mcpField
S
skill-structure

skill-structure

github.com/majesticlabs-devAgent 工作流5046 次安装7 周前更新
代码仓库

关于 skill-structure

介绍 Claude Code 中 Skill 与命令文件的组织方式，涵盖命名、目录布局、调用控制和 frontmatter，适合构建及维护 Skill 的开发者。

主要功能

  1. 01Skill 与命令的关系
  2. 02命名和目录约定
  3. 03frontmatter 字段参考
  4. 04调用控制
  5. 05参数与上下文注入
  6. 06验证清单

适用场景

  1. 01选择命令文件或 Skill 目录
  2. 02组织包含参考资料的 Skill
  3. 03配置自动调用或用户调用
  4. 04检查 Skill 是否符合命名和文件限制

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/majesticlabs-dev/majestic-marketplace --skill skill-structure

安装后在 Claude Code 中输入/skill-structure确认已加载。

详细介绍

技能结构

命令与技能已合并

自定义斜杠命令和技能是同一回事。.claude/commands/review.md 中的文件和 .claude/skills/review/SKILL.md 中的技能都会创建 /review。现有的 .claude/commands/ 文件仍可正常使用。技能新增了：用于存放支持文件的目录、用于控制调用方式的 frontmatter，以及自动加载上下文的功能。

如果技能和命令同名，则优先使用技能。

何时使用哪种类型：

类型适用场景
命令文件（commands/name.md）简单的单文件工作流，无需支持文件
技能目录（skills/name/SKILL.md）需要参考资料、背景知识或渐进式披露

命名规则

规则示例
格式kebab-case，小写，1-64 个字符
模式^[a-z][a-z0-9]*(-[a-z0-9]+)*$
必须匹配目录名称完全一致

正确/错误示例：

正确错误原因
stimulus-coderMySkill不允许大写字母
tdd-workflowskill_helper不允许使用下划线
pdf-processing-invalid不能以连字符开头
seo-contentskill--bad连字符不能连续出现

目录结构

扁平结构（大多数技能）
plugins/majestic-rails/skills/stimulus-coder/SKILL.md
-> name: stimulus-coder
-> invoked as: Skill("stimulus-coder")
嵌套结构（分类技能）
plugins/majestic-rails/skills/dhh-coder/SKILL.md
-> name: dhh-coder
-> invoked as: Skill("dhh-coder")

要点：

  • name 字段仅为最终技能名称（不是完整路径）
  • 目录名称必须与 name 完全一致
  • 使用嵌套目录对相关技能分组（ceo/、fundraising/、research/）

渐进式披露

对于复杂技能，可拆分为多个文件：

my-skill/
+-- SKILL.md (overview, <500 lines)
+-- references/
|   +-- patterns.md (detailed patterns)
|   +-- examples.md (extended examples)
+-- scripts/
    +-- helper.py (utility scripts)

规则：

  • 参考文件最多嵌套一层（SKILL.md 引用 reference.md，不再深入）
  • 脚本无需加载到上下文即可执行
  • 让 SKILL.md 专注于导航和核心内容
  • 子目录仅限：scripts/、references/、assets/

Frontmatter

核心字段
---
name: skill-name              # Matches directory, defaults to dir name if omitted
description: What it does...  # Recommended, max 1024 chars
allowed-tools: Read Bash      # Optional, space-delimited
---
所有字段参考
字段必填描述
name否小写字母、数字、连字符（最多 64 个字符）。默认为目录名称。
description建议填写说明其功能以及使用时机。最多 1024 个字符。
argument-hint否自动补全时显示的提示。示例：[issue-number]
disable-model-invocation否true = Claude 无法自动加载。适用于手动工作流。默认值：false
user-invocable否false = 在 / 菜单中隐藏。适用于背景知识。默认值：true
allowed-tools否无需权限提示即可使用的工具。示例：Read, Bash(git *)
model否haiku、sonnet 或 opus
context否使用 fork 在隔离的子 Agent 上下文中运行
agent否context: fork 时使用的子 Agent 类型：Explore、Plan、general-purpose 或自定义类型
描述模板
[What it does]. Use when [trigger contexts]. Triggers on [specific keywords].

规则：

  • 最多 1024 个字符
  • 使用第三人称（“Processes...”而非“I process...”）
  • 包含用户自然会说出的触发关键词

调用控制

Frontmatter用户可调用Claude 可调用加载时机
（默认）是是描述始终位于上下文中，调用时加载完整内容
user-invocable: false否是描述始终位于上下文中，相关时加载

选择指南：

  • 背景知识（约定、领域上下文）-> user-invocable: false
  • 其他所有内容 -> 使用默认值（用户和模型都可以调用）

注意： 避免使用 disable-model-invocation: true。具有副作用的命令/技能应通过确认步骤（AskUserQuestion）处理，而不是完全禁止模型调用。

动态功能

参数

使用 $ARGUMENTS 接收用户输入。如果内容中未包含该变量，则会自动追加参数。

---
name: fix-issue
---
Fix GitHub issue $ARGUMENTS following our coding standards.

单个参数：$ARGUMENTS[0]，或使用简写 $0、$1、$2。

动态上下文注入

!`command` 语法会在内容传递给 Claude 之前运行 shell 命令：

## Context
- Current branch: !`git branch --show-current`
- PR diff: !`gh pr diff`

命令会立即执行；其输出会替换占位符。

子 Agent 执行

添加 context: fork，即可在隔离环境中运行（不包含对话历史）：

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...

工具访问权限

所需工具示例用例
Read, Grep, Glob在代码库中搜索模式
Bash(git *)仅执行 Git 操作
Bash(gh *)执行 GitHub CLI 操作
WebFetch获取外部文档
无纯知识／指导

限制

  • SKILL.md： 最多 500 行
  • 名称： 最多 64 个字符
  • 描述： 最多 1024 个字符

验证清单

  • 名称与目录名称完全一致
  • 名称符合模式 ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
  • 描述少于 1024 个字符，并包含触发关键词
  • 使用标准 Markdown 标题（而非 XML 标签）
  • SKILL.md 少于 500 行
  • 如果技能有副作用，使用 AskUserQuestion 进行确认
  • 如需特定工具，设置 allowed-tools
  • 不包含角色设定陈述或署名
  • 子目录仅限：scripts/、references/、assets/
  • 已通过实际使用进行测试

评论

支持 Markdown