Claude Code技能系统架构与SKILL.md文件解析

1. Claude Code技能系统架构解析Claude Code的技能系统采用模块化设计通过SKILL.md文件定义核心功能配合hooks和subagents实现复杂工作流。整个架构包含三个关键层级技能定义层每个技能都是独立目录包含SKILL.md必需和可选的支持文件执行控制层通过hooks实现生命周期管理支持pre/post执行逻辑运行环境层可选择在主会话或subagent中运行技能典型技能目录结构如下my-skill/ ├── SKILL.md # 主指令文件 ├── hooks/ # 生命周期钩子 │ ├── pre-exec.sh # 执行前脚本 │ └── post-exec.sh # 执行后脚本 ├── scripts/ # 辅助脚本 │ └── validator.py # 自定义验证逻辑 └── examples/ # 示例文件 └── demo-output.md # 预期输出样本2. SKILL.md文件深度解析2.1 文件结构规范SKILL.md采用YAML frontmatterMarkdown的混合格式--- name: code-review description: 执行代码审查并生成改进建议 context: fork agent: Review allowed-tools: Read Grep --- ## 审查标准 1. 代码应符合项目编码规范 2. 关键路径需有错误处理 3. 公共API必须包含文档注释 ## 审查流程 !git diff main # 动态注入变更内容2.2 核心元数据字段字段名必需说明description是技能的功能描述用于自动触发判断disable-model-invocation否设为true时仅允许手动触发allowed-tools否技能运行时自动授权的工具列表context否设为fork时在子代理中运行agent否指定子代理类型Explore/Review/Plan等经验提示description字段应包含常见触发短语如代码审查、检查代码质量等提高自动匹配准确率3. 动态能力注入机制3.1 实时命令执行使用!command语法实现预处理## 变更记录 !git log -n 3 --prettyformat:%h %s执行流程Claude Code拦截!标记的命令在本地环境执行命令用输出结果替换原始标记将处理后的内容发送给Claude3.2 参数化技能调用支持多种参数传递方式位置参数/rename-file old_name.txt new_name.txt在技能中通过$0、$1引用命名参数需在frontmatter声明arguments: [oldname, newname]使用时通过$oldname、$newname引用4. 子代理(Subagents)集成方案4.1 子代理类型选择代理类型适用场景工具权限Explore代码探索与研究只读工具(Read/Grep等)Review代码审查与质量分析读静态分析工具Plan复杂任务分解全工具但需确认4.2 子代理集成示例--- name: security-scan description: 执行安全漏洞扫描 context: fork agent: Review allowed-tools: Read Grep Semgrep --- ## 扫描标准 1. 检查SQL注入风险 2. 验证输入过滤 3. 检测敏感信息泄露 !find . -name *.py -o -name *.js5. 生产环境实用技巧5.1 技能调试方法使用/debug-skill命令查看技能加载过程在技能开头添加DEBUG区块!-- DEBUG -- 当前参数$ARGUMENTS 工作目录${CLAUDE_PROJECT_DIR} !-- ENDDEBUG --5.2 性能优化建议对大型技能使用懒加载[详细规范](spec.md) !-- 点击时才加载 --动态内容分块处理!-- CHUNK:重要配置 -- 数据库连接配置应加密存储 !-- ENDCHUNK --5.3 企业级部署方案中央技能库配置// .claude/settings.json { skillRepositories: [ https://intra.example.com/claude-skills ] }技能权限控制// 企业策略配置 { skillPermissions: { deploy: [devops], db-migrate: [dba] } }6. 典型问题排查指南问题现象可能原因解决方案技能未自动触发description字段不够明确添加更多触发关键词动态命令未执行缺少执行权限检查allowed-tools配置子代理无输出未设置context: fork确保frontmatter包含正确配置参数传递失败包含特殊字符使用引号包裹参数我在实际项目中发现当技能涉及文件操作时明确指定${CLAUDE_PROJECT_DIR}比使用相对路径更可靠。特别是在monorepo项目中子目录技能经常需要回溯到项目根目录访问共享配置。