直接答案
Skills 复用知识与流程，Subagents 隔离调查或专业任务；两者解决的问题不同。
这篇内容解决什么问题
帮助团队把成熟用法沉淀为可维护扩展，同时控制上下文和权限。
先判断需要 Skill 还是 Subagent
Skill 是可按需加载的领域知识或重复工作流，适合 API 规范、发布流程和固定排查步骤。Subagent 是拥有独立上下文和工具集合的代理，适合读取大量文件、专业审查或并行调查。
仅需要实时外部系统时使用 MCP，必须在生命周期确定执行时使用 Hooks。不要为一个短提示创建整套扩展。
创建一个最小项目 Skill
项目 Skill 位于 .claude/skills/<name>/SKILL.md。frontmatter 至少提供清晰名称和描述，让 Claude 能判断何时加载；正文给出项目特有规则、步骤和验证方式。
描述应说明触发场景，正文只保留执行所需内容。大段参考资料可以拆到 Skill 目录内的其他文件，由 Claude 按需读取。
---
name: api-conventions
description: 在新增或修改本项目 REST API 时使用
---
# API conventions
- URL 路径使用 kebab-case。
- 列表端点必须支持分页。
- 修改接口后运行 `pnpm test api` 和 `pnpm typecheck`。把有副作用的工作流设为手动触发
Skill 可以描述从读取 Issue 到测试和创建 PR 的完整流程。具有发布、提交或外部写入副作用的 Skill，应避免被模型仅凭相似语义自动触发。
使用手动调用后，参数通过 $ARGUMENTS 进入工作流。脚本仍需权限审批，Skill 本身不会绕过 Claude Code 的安全规则。
---
name: fix-issue
description: 修复指定 GitHub Issue
disable-model-invocation: true
---
修复 Issue：$ARGUMENTS
1. 用 `gh issue view` 读取问题。
2. 写复现测试并修复根因。
3. 运行受影响测试和 lint。
4. 展示 diff，等待确认后再创建 PR。为专业审查创建自定义 Subagent
自定义 Subagent 放在 .claude/agents/，frontmatter 定义名称、描述、模型和可使用工具。它在独立上下文中工作，最终把精炼结果返回主会话。
工具权限应按任务最小化。只做代码审查的代理通常需要 Read、Grep、Glob，只有确实要运行验证时才增加受限 Bash。
---
name: security-reviewer
description: 审查当前改动中的可利用安全问题
tools: Read, Grep, Glob
model: opus
---
检查认证绕过、注入、秘密泄漏和不安全数据处理。
只报告能影响正确性或安全边界的问题，提供文件位置和利用路径，
不要提出纯风格重构。
把调查和独立复核委派给 Subagents
适合委派的任务应有明确问题、范围和返回格式，例如定位 token refresh 路径，或只按 PLAN.md 审查当前 diff。主代理不必接收子代理读过的所有文件。
实现后的独立审查使用新上下文，可以减少代理为自己方案辩护的倾向。但审查提示要限制为真实正确性问题，避免为了产出发现而过度设计。
使用一个子代理调查 auth 模块如何刷新 token，并找出可复用测试工具；
返回文件路径、调用链和不确定项，不要修改代码。
实现完成后，再用新子代理按 PLAN.md 审查当前 diff，
只报告影响需求、正确性或安全的缺口。测试、审查并控制扩展成本
Skill 与 Subagent 文件应进入代码审查，并用代表性任务验证是否触发正确、是否遵守工具边界。描述太宽会误触发，正文太长会增加上下文。
子代理拥有独立上下文，但仍会消耗 token，并可能并行修改文件。默认让调查代理只读；需要并行编辑时使用独立 worktree 并明确文件所有权。
- 为每个扩展写清维护者、用途和验证任务。
- 删除重复、过期或模型已能可靠完成的说明。
- 外部写操作仍保留权限与人工确认。
- 用
/context和执行记录核对实际加载与调用。
官方来源与核验范围
本文以公开官方文档为事实依据；命令和配置可能随客户端版本变化，执行前请同时核对对应来源。
查看技术核验方法