Claude Code Agent Skills 升级：从 Slash 命令到带 YAML Frontmatter 的结构化技能包

Agent Skills 升级：从 Slash 命令到带 YAML Frontmatter 的技能包

本文是「Claude 企业级工程实战手册」专栏第 09 篇。Skills 比 Slash 命令更强大：带元数据、支持动态加载、可以隔离上下文、有文件组织结构。

为什么升级到 Skills

特性	传统 Slash 命令	Agent Skills
元数据	无	YAML Frontmatter（名称、描述、触发条件）
动态加载	每次全量加载	按文件路径或话题自适应加载
上下文隔离	共享主会话上下文	`context: fork` 独立子上下文
工具权限	继承全部权限	可精确控制允许/禁止的工具
文件组织	单个 .md 文件	多文件目录结构（脚本、模板、参考文档）

Skills 目录结构

.claude/skills/security-auditor/
├── SKILL.md          ← 主文件：YAML Frontmatter + 指令内容
├── templates/
│   └── vulnerability_report.md   ← 漏洞报告模板
├── scripts/
│   └── extract_pr_diff.py        ← 辅助脚本
└── reference/
    ├── owasp_top10.md            ← OWASP 安全基准
    └── pci_dss_v4.md             ← PCI-DSS v4.0 标准

完整 SKILL.md 实现

安全审计 Skill

---
name: security-auditor
description: 专门审查核心数据库、交易网关和会话凭证敏感路径的变更，防范 SQL 注入及 PCI-DSS 违规风险。
when_to_use: 当用户提出审查代码安全性、检查依赖库合规性，或讨论涉及 financial、payment、crypt、database、auth 关键字时自动加载。
user-invocable: true
allowed-tools:
  - Read
  - Glob
  - Grep
disallowed-tools:
  - Write
  - Bash
  - Edit
paths:
  - "src/payments/**/*.py"
  - "src/database/**/*.py"
  - "src/auth/**/*.py"
arguments: [target_scope]
argument-hint: 输入待审查的目标目录或文件路径（如 src/payments/）
effort: high
context: fork
---

# 安全审查技能指令

你目前在独立的子 Agent 中运行（`context: fork`）。
你已失去 Write、Bash、Edit 工具权限——这是防止误操作的设计。

## 审计步骤

1. 使用 `Read` 和 `Glob` 检索 `$target_scope` 下的所有 Python 文件
2. 依据 `reference/owasp_top10.md` 中的安全定义，逐行排查：
   - SQL 注入风险（直接字符串拼接）
   - 权限绕过漏洞
   - 敏感数据明文存储
   - 弱密码学算法使用
3. 发现漏洞时，使用 `templates/vulnerability_report.md` 格式输出报告
4. 评估结束后，直接向主 Agent 汇报结果，不做多余解释

代码审查 Skill

---
name: code-review
description: 以高级工程师视角对 PR 变更进行全面代码审查。
when_to_use: 当用户说"审查代码"、"review PR"、"check my changes" 时触发。
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Glob
effort: high
---

# 代码审查技能

获取当前 PR 变更：
```bash
git diff main...HEAD --name-only
git diff main...HEAD

以高级工程师视角审查上述变更，按以下维度评估：

安全性 🔴：SQL 注入、XSS、权限漏洞、敏感数据泄露
性能 🟡：N+1 查询、不必要的全表扫描、同步阻塞
业务逻辑 🟡：边界情况处理、错误处理完整性
测试覆盖 🔵：新功能是否有对应测试

输出格式：

🔴 必须修复

（每条附具体文件行号和修复建议）

🟡 建议修复

（每条附理由）

🔵 可选优化

（简短列举）

总体评价

（2-3 句话的综合评估）


### 生产事故处理 Skill

```yaml
---
name: incident-response
description: 快速分析生产事故，提供止血方案和根本原因分析。
when_to_use: 当用户说"生产出问题"、"线上报错"、"事故"、"incident" 时触发。
user-invocable: true
allowed-tools:
  - Bash
  - Read
effort: xhigh
---

# 生产事故处理技能

获取最近错误日志：
```bash
# Kubernetes 环境
kubectl logs -n prod deployment/api --since=30m | grep -E "ERROR|CRITICAL" | tail -100

# 本地日志
tail -500 /var/log/app/error.log | grep -E "ERROR|CRITICAL"

分析日志并输出：

1. 症状描述（1-2 句）

2. 根本原因（最可能的 1-2 个）

3. 立即止血（5 分钟内可执行的操作）

4. 永久修复（代码层面的根本修复）

5. 防止复发（监控告警 / 测试用例建议）

优先级原则：速度 > 完美，先止血再根治。


---

## 使用方式

```bash
# 方式一：用户手动触发
/project:security-auditor src/payments/

# 方式二：Claude 自动识别（when_to_use 匹配）
用户：帮我检查一下 payments 模块的安全性
Claude：[自动加载 security-auditor skill]

# 方式三：编程方式创建（Claude Code SDK）
# 在 CI 中自动触发审查

迁移指南：从 Slash 命令迁移到 Skills

# 旧的方式（~/.claude/commands/review.md）
# 直接在文件里写 Markdown 指令

# 新的方式（.claude/skills/code-review/SKILL.md）
# 带 YAML Frontmatter 的结构化目录

# 迁移步骤
mkdir -p .claude/skills/code-review
mv ~/.claude/commands/review.md .claude/skills/code-review/SKILL.md
# 在文件顶部添加 YAML Frontmatter

下一篇：10. CI/CD 集成与团队规模化适配

专栏导航 · Claude 企业级工程实战手册

⬅️ 上一篇：08. Claude Code 三阶段工作流：Plan Mode → 并行子 Agent → 物理验收标准 ➡️ 下一篇：10. Claude Code 工程实战：GitHub Actions 质量门控 + Compaction 防御 + 团队规模化

本专栏共 14 篇，系统覆盖 Claude 模型选型 / Prompt 工程 / Claude Code 工作流 / API 高级用法 / MCP / RAG / AI 安全合规全链路。欢迎收藏：Claude 企业级工程实战手册