Skill 结构
Skill 是以SKILL.md 为入口的能力包，遵循 Agent Skills 格式。启动时主要加载名称和描述，模型判断相关后再读取完整指令，减少不必要的上下文占用。
创建 Skill
保存为~/.stepcode/agent/skills/api-review/SKILL.md：
references/checklist.md 中编写项目审查清单，然后运行 /reload，使用 /skill:api-review。包含辅助脚本的 Skill 可能执行本地命令，只加载可信来源。
references/checklist.md 可使用以下内容：
调用
enableSkillCommands 默认启用，将 Skill 注册为 /skill:<名称>。参数以 User: <参数> 追加到 Skill 内容后。
模型根据 description 判断何时读取 Skill，不一定会自动读取。需要明确执行某项工作流时，请使用斜杠命令；设置 disable-model-invocation: true 可关闭自动发现入口。
复用其他工具的 Skills
~/.codex/skills 等非默认目录需要加入 skills 数组；Claude 和 Step 目录会自动发现，不必重复加入。加入后无需复制文件。使用前检查其中引用的命令、路径、模型能力和工具名称，避免沿用其他工具专属的行为假设。
子代理的定义和调用见Agent 与 subagent。
存放位置
优先级从高到低如下：
项目
.agents/skills/ 和 .claude/skills/ 的发现会向上查找到 Git 根。上述目录自动发现，不必重复加入 skills 数组；~/.codex/skills 等非默认目录仍需使用 config.toml 的 skills 数组显式指定。
资源包的安装与分发见插件与 Packages。
文件格式
目录结构
SKILL.md 中使用相对路径引用包内资料。scripts/ 和 references/ 是可选目录。
Frontmatter 字段
校验规则
大写、首尾连字符、连续连字符和超长名称会告警但仍加载；缺少description 不加载；重名保留第一个并告警。未知 frontmatter 字段忽略。
为跨工具复用，建议按标准修正全部命名和长度问题。Skill 的工具声明不能替代 Step Code 的权限控制。