Agent Skills
2026 AI 智能体最热的新范式

一、Skills 诞生的核心问题:专业知识如何沉淀

在 2024-2025 年的「Agent 军备竞赛」里,业界普遍认识到一个关键问题:

Agent 本身已经足够通用,但真正稀缺的是被整理、被固化、能反复调用的专业流程。

过去我们试图通过 Prompt 教 AI 做事,但 Prompt 有三大根本缺陷:

• 一次性:每次对话都要重新粘贴,跨会话不保留。
• 不可审计:散落在聊天记录,无法代码审查、版本管理。
• 能力错配:写 Prompt 在调措辞,真正的专业知识被「精确措辞」掩盖。

Skills 的解法是把 Prompt 升级为资产:可版本控制、可团队共享、可工具调用、可持续迭代。一个 Skill 就是一个装着「专业流程」的文件夹。

1.1 一个类比:瑞士军刀 vs 食谱 vs 岗位 SOP

1.2 Skills vs MCP vs Plugin vs Prompt

1.3 Skills × MCP:完整的 Agent 架构

Skills 与 MCP 是互补关系,不是替代:

Powerful Agent = MCP Tools(连接外部世界) + Skill(沉淀专业流程) + Memory(跨会话记忆) + Model(推理能力)

在 Claude Code 2.1.3+ 版本中,Anthropic 进一步把 commands 和 skills 合并为统一的概念 —— 都叫 Skill,只是触发方式不同(自动 vs 手动 /skill-name)。这是 Skills 走向统一生态的关键一步。

二、SKILL.md 完整规范:文件夹、YAML、正文

一个 Skill 的标准结构:

2.1 YAML Frontmatter:必填与可选字段

---
# === 必填字段 ===
name: python-code-reviewer          # Skill 名称(kebab-case,≤64 字符)
description: |                      # Skill 描述 - 最重要!
  对 Python 代码进行 OWASP 安全审查 + PEP8 风格检查 +
  性能反模式检测。当用户说"审查"、"review"、"检查代码"、
  "code review" 时使用。适用:Python 3.10+。
  不适用:其他语言(用对应的 review skill)。

# === 推荐字段 ===
license: Apache-2.0                 # 许可证
compatibility: Requires python>=3.10, git  # 环境依赖
allowed-tools: Read Bash(git:*) Grep    # 预授权工具,安全隔离
metadata:                           # 自定义元数据
  author: devops-team
  version: "1.2.0"
  category: code-review

# === 可选高级字段 ===
when_to_use: "审查 PR 或审计遗留代码时"   # 补充触发条件
argument-hint: "[file-path]"             # 斜杠命令参数提示
disable-model-invocation: false          # 是否禁止自动触发
user-invocable: true                     # 是否出现在 / 菜单
model: claude-sonnet-4-5                 # 指定模型
context: fork                            # 在子代理中执行
---  # YAML frontmatter 结束分隔符

2.2 Markdown 正文:必含的 4 个部分

# Skill 标题

## Instructions                         <-- 核心执行步骤(必填)
按以下顺序执行:
1. 读取目标文件
2. 运行安全扫描
3. 按严重程度分类输出

## Examples                             <-- 输入输出示例
输入: ...
输出: ...

## Guidelines                           <-- 风格 / 约束 / 边界
- 忽略 auto-generated 文件
- 对 test 文件降低严格度

## Troubleshooting                      <-- 失败处理(可选)
- 如果 git 不可用,提示用户安装

2.3 命名规范与常见坑(踩过!)

2.4 description 字段:Skill 的「SEO 关键词」

description 决定了 90% 的自动触发准确率。差的描述会让 Skill 永不触发或乱触发。三个核心要素:

1. 做什么:明确说明 Skill 的功能
2. 什么时候用:适用场景 + 触发关键词
3. 不适用:显式排除相近场景,降低误触发

# ❌ 差:太模糊,无法路由
description: 代码审查

# ⚠️ 一般:有动作但缺触发词
description: 对代码进行审查,检查问题

# ✅ 好:WHO + WHEN + 关键词 + 边界
description: |
  对 Python 代码进行 OWASP 安全审查,检查注入漏洞、硬编码凭证、
  资源泄漏、性能反模式。当用户说"审查"、"review"、"检查代码"、
  "code review"、"audit" 时使用。适用:Python 3.10+。
  不适用:其他语言(用对应的 review skill)、格式化(用 formatter)。

三、渐进式披露机制(Progressive Disclosure)

Skills 的杀手级设计 —— 3 层按需加载,让 Agent 拥有 100 个 Skill 也不撑爆上下文。

3.1 三层架构图解

3.2 Token 经济性:为什么 100 个 Skill 都不卡?

3.3 行业实测收益

• Token 节省:14-80%(任务相关度越低,节省越多)
• 错误率降低:复杂任务中 ~35%(有 TDD 约束的场景)
• 月度任务效率:Anthropic 内部团队提升 ~40%
• 文档处理长任务:Token 消耗降低 60-80%

3.4 SKILL.md 大小写敏感 —— 最大的坑

这是 Claude Code 用户最常犯的错误。文件必须精确叫 SKILL.md(全大写),以下全部不会生效且不会报错:

• skill.md - 小写 s,无效
• SKILL.MD - 全大写扩展名,无效
• Skill.md - 首字母大写,无效

在 macOS/Linux 默认大小写不敏感的文件系统上,你可能创建了 skill.md,push 到 Linux CI 才发现问题。务必在 git status 时检查文件名。

四、创建 Skill 的完整流程

4.1 五步法

1. 用 skill-creator 自动创建:Anthropic 官方「元技能」,对话式生成 SKILL.md。
2. 写 SKILL.md:YAML frontmatter + Markdown 主体。
3. 加 scripts/:把确定性操作封装为脚本(数据抓取、格式转换、API 查询)。
4. 加 references/:补充按需读取的详细文档(API 参考、边界案例)。
5. 测试 → 评估 → 优化:用真实任务验证触发率,迭代 description。

4.2 一个真实可用的完整 Skill:python-code-reviewer

下面这个 Skill 演示了从目录结构到 SKILL.md 完整内容,可以直接拿去用。

SKILL.md 内容:

---
name: python-code-reviewer
description: |
  对 Python 代码进行 OWASP Top 10 安全审查 + PEP8 风格检查 +
  性能反模式检测。输出按 CRITICAL / HIGH / MEDIUM / LOW 分级。
  当用户说"审查"、"review"、"代码检查"、"audit"、"pr 评审"时使用。
  适用:Python 3.10+。
  不适用:其他语言(用对应的 review skill);格式化(用 formatter)。
license: Apache-2.0
compatibility: Requires python>=3.10, git
allowed-tools: Read Grep Glob Bash(git diff:*)
metadata:
  author: ai-kb-team
  version: "1.0.0"
  category: code-review
---  # YAML frontmatter 结束分隔符

# Python Code Reviewer

## Instructions

按以下顺序执行:

### Phase 1:收集变更
1. 运行 `git diff --name-only origin/main...HEAD` 找出变更文件
2. 过滤出 `*.py` 文件
3. 跳过 auto-generated(`*_pb2.py`、`*_pb2_grpc.py`)

### Phase 2:安全审查
运行 `python scripts/check_security.py <file>`,重点检查:
- SQL 注入风险(字符串拼接)
- 硬编码密钥/凭证
- 不安全的反序列化(pickle / eval)
- 缺少输入验证的 HTTP handler

### Phase 3:风格与性能
参考 `references/owasp-checklist.md`,逐项检查:
- 错误处理是否使用具体异常类型
- 是否使用 context manager 管理资源
- 是否有 N+1 查询反模式

### Phase 4:输出报告
按以下格式输出:

| 级别 | 文件:行 | 问题 | 修复建议 |
| --- | --- | --- | --- |

## Examples

输入:对 src/api/users.py 进行 review

输出:
- [CRITICAL] src/api/users.py:42 - SQL 注入:使用字符串拼接构造查询
  → 建议:改用参数化查询 `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`
- [HIGH] src/api/users.py:78 - 硬编码 API key
  → 建议:从环境变量读取 `os.environ["API_KEY"]`

## Guidelines

- 忽略 test 文件的 style 问题(只检查安全和正确性)
- 对 `__init__.py` 降低严格度
- 单文件超过 20 个问题时分批输出

## Troubleshooting

- 如果 git 不可用,提示用户安装 git
- 如果 Python 版本 < 3.10,提示不兼容

配套的 scripts/check_security.py:

#!/usr/bin/env python3
"""Python 代码安全静态扫描 - Python Code Reviewer 配套脚本"""
from pathlib import Path

SECRET_PATTERNS = [
    (r'(?i)(api[_-]?key|secret|password|token)\s*=\s*["\'][^"\']+["\']', 'Hardcoded credential'),
    (r'(?i)aws_[a-z]+_key\s*=\s*["\'][^"\']+["\']', 'Hardcoded AWS key'),
]

SQL_INJECTION_PATTERNS = [
    (r'execute\s*\(\s*["\'].*%s.*["\']', 'SQL string formatting'),
    (r'execute\s*\(\s*["\'].*\+.*\)', 'SQL string concatenation'),
    (r'\.raw\s*\(\s*["\'].*\+', 'Django raw SQL with concatenation'),
]

UNSAFE_PATTERNS = [
    (r'\beval\s*\(', 'Use of eval()'),
    (r'\bexec\s*\(', 'Use of exec()'),
    (r'pickle\.loads?\s*\(', 'Unsafe deserialization'),
    (r'subprocess\.[A-Za-z_]+\([^)]*shell\s*=\s*True', 'Shell injection risk'),
]

def scan_file(path: Path) -> list:
    findings = []
    content = path.read_text(encoding='utf-8', errors='ignore')
    for pattern, desc in SECRET_PATTERNS + SQL_INJECTION_PATTERNS + UNSAFE_PATTERNS:
        for match in re.finditer(pattern, content):
            line_no = content[:match.start()].count('\n') + 1
            findings.append({'line': line_no, 'issue': desc, 'snippet': match.group(0)[:80]})
    # AST 检查:except 裸用
    try:
        tree = ast.parse(content)
        for node in ast.walk(tree):
            if isinstance(node, ast.ExceptHandler) and node.type is None:
                line_no = getattr(node, 'lineno', 0)
                findings.append({'line': line_no, 'issue': 'Bare except clause', 'snippet': 'except:'})
    except SyntaxError:
        pass
    return findings

def main():
    if len(sys.argv) < 2:
        print('Usage: check_security.py <file_or_dir>', file=sys.stderr)
        sys.exit(1)
    target = Path(sys.argv[1])
    files = [target] if target.is_file() else list(target.rglob('*.py'))
    for f in files:
        findings = scan_file(f)
        for fnd in findings:
            print(f"[SECURITY] {f}:{fnd['line']} - {fnd['issue']}")
            print(f"    {fnd['snippet']}")
    sys.exit(0)

if __name__ == '__main__':
    main()

五、5 大设计模式(基于实战经验)

Anthropic 内部沉淀 + 社区共识总结出的 5 个高频 Skill 设计模式。

5.0 Skill 完整生命周期(从发现到执行)

执行流程:用户输入 → Agent 比对 Layer 1 元数据 → 命中则加载 Layer 2 正文 → 正文里引用到 Layer 3 references → 可选 scripts 由 Agent 决定调用(脚本代码不进入上下文!)→ 返回结果。

5.1 顺序工作流编排(Sequential Workflow)

场景:客户入职、产品上线、订单处理等多步流程。

模式:把固定步骤固化到 Skill 中,每步作为检查点。

# 客户入职流程
## Steps
1. 创建账户(调 create_account MCP)
2. 设置支付方式(调 stripe MCP)
3. 发送欢迎邮件(调 sendgrid MCP)
4. 同步到 CRM(调 salesforce MCP)
5. 创建项目管理空间(调 notion MCP)

## Guidelines
- 任一步失败立即停止,记录错误到 audit log
- 步骤间等待 ≤ 5 秒
- 完成后自动通知销售团队

5.2 多 MCP 协调(Multi-MCP Coordination)

场景:跨系统数据流转,典型如「设计转开发」。

模式:Skill 定义转换规则,MCP 负责连接。

# 设计转开发
## Workflow
1. 从 Figma MCP 读取设计稿
2. 提取设计 token(颜色/字体/间距)
3. 在 Linear MCP 创建对应 ticket
4. 同步到 GitHub MCP 仓库 issues
5. Slack MCP 通知前端团队
6. 在 Drive MCP 存储设计资产

## Coordination
- 失败重试:同一 MCP 调用最多 3 次
- 跨 MCP 数据传递用 JSON

5.3 迭代式优化(Iterative Refinement)

场景:报告生成、内容创作、数据分析等需要多轮改进的任务。

模式:Skill 包含「生成 → 检查 → 修正」循环。

# 报告生成
## Steps
1. 基于数据生成初稿
2. 运行 scripts/check_quality.py 检查
3. 找出不达标章节
4. 重新生成(仅修改不达标部分)
5. 最多 3 轮迭代
6. 达标后输出最终报告

## Quality Check
- 数据准确性(每条结论必须可追溯)
- 章节完整性(必须覆盖 5 个核心维度)
- 引用规范(数据来源必须标注)

5.4 情境感知工具选择(Context-Aware Tool Selection)

场景:文件存储、内容管理等需要根据情境选择存储方式的任务。

模式:Skill 中定义「条件 → 工具」映射,Agent 自动决策。

# 智能文件存储
## Decision Tree
- 文件 > 100MB ──→ 云存储(MCP: AWS S3)
- 协作文档 ──→ Notion(MCP: Notion)
- 代码片段 ──→ GitHub Gist(MCP: GitHub)
- 临时数据 ──→ 本地 /tmp
- 敏感数据 ──→ 加密存储(MCP: 1Password)

## Triggers
- "保存这个文件" ──→ 根据文件类型自动选择
- "归档" ──→ 强制 S3
- "分享给团队" ──→ Notion

5.5 领域专用智能(Domain-Specific Intelligence)

场景:金融合规、医疗诊断、法律审查等垂直领域。

模式:Skill 封装行业知识 + 法规 + 最佳实践,结合领域 MCP。

# 金融合规检查
## Workflow
1. 拉取交易数据(MCP: 银行 API)
2. 匹配制裁名单(MCP: OFAC 数据库)
3. 司法管辖检查(本地规则库)
4. 风险评分计算
5. 人工审核触发(高风险时)
6. 审计日志生成

## Compliance
- 每步必须可审计
- 任何高风险操作需要人工确认
- 完整记录到 SOC2 合规系统

5.6 5 大设计模式速查图

六、Anthropic Skills 设计 10 大黄金原则

2026 年初,Anthropic 在《Lessons from building Claude Code: how we use Skills》文章中首次公开内部方法论,核心是 10 条原则:

1. 不要写显而易见的内容。Claude 已经会编码、读代码,Skill 只写「让模型偏离默认解法的信息」。frontend-design skill 就刻意写「避免 Inter 字体和紫色渐变」,强制改变模型的默认审美。
2. 构建陷阱区(Gotchas)。Skill 中最重要的不是规则,是「真实踩坑记录」。例:「数据表是 append-only,必须取最高版本行,不是最新 created_at」「staging 环境即使 webhook 失败也返回 200,要从 payment_events 判断真实状态」。
3. 文件夹分层 + 渐进式披露。SKILL.md 保持 < 500 行,详细内容拆到 reference.md / stuck-jobs.md / assets/ / scripts/。AI 按需读取,精简上下文。
4. 避免过度约束(不要 railroading)。Skill 不应变成执行手册。只定义目标与约束,不规定每一步。Slack standup skill 只定义「输出目标」,不规定逐步生成流程。
5. 支持私有化配置 + 交互式初始化。用 config.json 统一管理 Slack channel、API endpoint。当配置缺失时,通过 AskUserQuestion 工具引导用户补全。
6. description 是路由信号,不是文档。description 不是给开发者看的说明,而是 Claude 用于任务路由的识别信号。必须包含:做什么 + 触发词(babysit、standup、review、debug)+ 适用边界。
7. 引入持久化记忆,实现持续演化。用 ${CLAUDE_PLUGIN_DATA} 作为稳定存储路径,记录执行历史。例:standup-post skill 维护 standups.log,让模型对比历史变化生成差异化结果。
8. 固化脚本,让模型专注决策。所有确定性操作(数据抓取、格式转换、API 查询)都不应由模型重复生成,而应封装为 scripts/。data-science skill 提供 helper functions,让 Claude 直接组合调用。
9. 使用 on-demand hooks,不要全局 hooks。hooks 只在 Skill 调用期间生效。例:/careful 拦截 rm -rf、DROP TABLE、git push -f;/freeze 限制编辑范围。
10. 技能联动,实现能力复用。Skill 之间可形成依赖、组合调用。例:CSV 生成 Skill 可直接调用文件上传 Skill,实现从数据生成到输出分发的一体化流程。

七、Skills 生态(2025.10 - 2026.2 真实项目)

7.1 官方与规范

7.2 社区精选(均为真实 star 数,截至 2026 年初)

7.3 聚合与发现平台

八、跨平台支持全景(2026 年初)

2025-12-18 Agent Skills 成为开放标准后,主流 AI 编程工具密集适配,形成「一套 Skill,多平台运行」生态。

跨平台测试结果(2026 年初社区对比测试):Claude Code / Codex / Antigravity 在 4 个测试场景(hello-skill / format-boundary-trap / strict-json-trap / file-generation-trap)中全部满分,说明标准的兼容性已经达到生产可用水平。

九、Skills × MCP 协同:3 大企业场景

Powerful Agent = MCP Tools(能力) + Skill(标准作业程序) + Memory(跨会话记忆)

9.1 客户支持场景

Skill 职责:工单分级 SOP、自动回复模板、升级规则

MCP 职责:连接 Zendesk / Salesforce / Slack / Intercom

9.2 销售场景

Skill 职责:销售流程 SOP、BANT 评估、邮件跟进节奏

MCP 职责:Apollo / LinkedIn / HubSpot / Gmail

关键能力:从 ICP 定义 → 潜客挖掘 → 触达 → 资格认定 → 商机管理,全流程用 Skill 编排,MCP 提供实时数据。

9.3 研究场景

Skill 职责:研究方法论、信源分级、报告结构

MCP 职责:Brave Search / Exa / ArXiv / Notion / Zotero

关键能力:Skill 定义「什么问题用什么方法、产出什么结构」,MCP 提供实时数据流。两者解耦使同一 Skill 可应用到不同研究主题。

十、企业级落地:3 大场景 + 3 步实施法

10.1 3 大企业应用场景

10.2 实施 3 步法

1. 需求梳理与选型:从「每周至少做 2 次」的任务入手,识别可固化的 SOP,选型 Skill 框架(Superpowers / 自建 / 行业方案)。
2. 环境配置与权限:配置 MCP 集成、设置团队 Skill Registry、定义权限分级(读/写/网络)、准备审计日志。
3. 测试优化与监控:建立小规模评测集(50-100 题)、A/B 测试不同 description、监控触发准确率、持续迭代。

10.3 规模化的隐藏陷阱

UBC / Vector Institute / CIFAR 2026 年初的研究发现:当 Skill 库超过 50-100 个,Agent 的选择准确率会出现「相变」式下降 —— 因为模型的工作记忆存在物理极限(类似希克定律失效 + 认知负荷理论)。

6 条避坑指南:

1. 监控 Skill 库规模:50-100 是 GPT-4o 强度模型的「警戒线」
2. 最小化语义混淆:不要让 2 个 Skill 描述太相似(准确率暴跌 17-63%)
3. 大规模时分层:按领域分组 + Stage 1 选 Cluster + Stage 2 选具体 Skill
4. 投资 description 优化:description 是唯一触发线索,正文长度不影响选择
5. 为任务匹配模型:强模型(Claude Opus 4.5 / GPT-5)抗混淆能力更强
6. 考虑替代架构:超大规模时,部分回退到多 Agent(Multi-Agent + 路由)

十一、风险与最佳实践

11.1 安全风险

Anthropic 官方明确警告:恶意 Skill 可能:

• Prompt 注入:在 SKILL.md 中隐藏恶意指令
• 数据窃取:诱导 Agent 传输敏感信息到外部服务器
• 权限滥用:scripts/ 执行任意 shell 命令
• 外部网络调用:在 Skill 指令中引导 Agent 连接不可信地址

2025-2026 年社区已记录多起 Skills 投毒事件(尤其是不知名 AI trading bot 类仓库)。

11.2 防御性最佳实践

11.3 复杂度管理

不要做「万能助手」。把一个巨型 Skill 拆成多个专精 Skill,每个聚焦一件事。例:不要写「代码全流程 Skill」,而是分:code-reviewer / test-generator / refactor-helper / doc-writer。

理由:大模型「选择注意力」有物理上限(50-100 触发线索),多专精 Skill 反而比单一巨型 Skill 表现更好。

11.4 维护成本

Skill 是「活文档」,不是一次写完就完事。Anthropic 内部数据显示,最成功的 Skills 都不是一次设计完善的,而是:

• 最初几行简单说明
• 真实项目踩过的坑
• 持续补充新案例 / 规则 / 边界条件
• 最终成为生产工具

维护节奏建议:每 2 周回顾一次 Skill 使用数据(月度),每季度做一次系统性优化(添加/删除/合并)。

十二、学习资源与路径

12.1 必看官方资料

• Equipping agents for the real world with Agent Skills - Anthropic 官方工程博客,2025-10 首发
• Lessons from building Claude Code: how we use Skills - 2026 初首度公开内部 10 条方法论
• The Complete Guide to Building Skills for Claude - 32 页 PDF 完整开发指南
• Agent Skills 开放标准 - Specification v1.0 规范
• anthropics/skills - 官方仓库,16+ 官方 skill 可直接学习

12.2 课程与教程

• DeepLearning.AI:Agent Skills with Anthropic 短课程(Andrew Ng 主理)
• 中文教程:菜鸟教程 Agent Skills 章节
• Datawhale:agent-skills-with-anthropic 中文实战教程
• Awesome 系列:awesome-agent-skills、awesome-claude-skills

12.3 三级学习路径

🟢 入门(0-2 周)

1. 读 Skills 官方介绍,理解 3 层渐进式披露
2. 在 Claude Code 中输入 /skill 查看已有 Skill
3. 用 skill-creator 自动创建你的第一个 Skill
4. 读 3 个官方 skill 的源代码(pdf、webapp-testing、brand-guidelines)

🟡 进阶(2-8 周)

1. 为你的项目写 5-10 个专精 Skill
2. 学习 Superpowers 的 14 个核心 Skill(可读源码)
3. 研究 vercel-labs/agent-skills 的设计模式
4. 写一个有 scripts/ + references/ 的企业级 Skill
5. 接入 MCP,做 Skills × MCP 协同项目

🔴 高级(8 周+)

1. 研究 agentskills.io 规范,设计自定义字段
2. 构建跨平台兼容的 Skill,跨 Claude Code / Codex / Cursor 测试
3. 贡献到 anthropics/skills 或自建企业 Skill Registry
4. 研究 Skill 库扩容(50+ → 100+ → 200+)的「相变」问题,做分层路由优化
5. 将 MCP + Skills + Memory + 多 Agent 整合,构建企业级 Agent 平台

十三、关键数据看板(2026 年初)

十四、章节总结

• ✅ Skills是 2025-10 发布、2025-12-18 升级为开放标准的 Agent 全新范式,与 MCP 并列为 AI Agent 两大事实标准。
• ✅ 一个 Skill = 文件夹 + SKILL.md,必填 YAML(name + description),可选 scripts/、references/、assets/。
• ✅ 渐进式披露(3 层)是核心机制,让 100 个 Skill 也不撑爆上下文,Token 节省 14-80%。
• ✅ SKILL.md 大小写敏感(必须 SKILL.md),description 决定 90% 触发准确率。
• ✅ 5 大设计模式:顺序工作流 / 多 MCP 协调 / 迭代式优化 / 情境感知 / 领域专用。
• ✅ 10 条设计原则:不写显而易见内容、构建 Gotchas、避免 railroading、description 是路由信号、固化脚本、on-demand hooks 等。
• ✅ 生态:官方 anthropics/skills(100k+)+ 社区 superpowers(208k+)+ 14+ 优质仓库。
• ✅ 跨平台:27+ 平台原生支持(Claude Code / Codex / Cursor / Antigravity / Trae / CodeBuddy / VS Code Copilot)。
• ✅ Skills × MCP = 完整 Agent 架构,3 大企业场景(客户支持/销售/研究)。
• ✅ 扩容墙:50-100 个 Skill 是触发准确率的「相变点」,大规模需分层路由。
• ✅ 风险:恶意 Skill 可注入 / 窃取数据 / 滥用权限,必须用可信来源 + 审计 SKILL.md + allowed-tools 限制。

选型决策树

手把手创建一个生产级 Skill

这一节我们把前面讲的 SKILL.md 规范、YAML 字段、scripts/ 和 references/ 子目录全部走一遍 —— 从"我有一个想法"到"团队仓库里跑起来",完整复现一个生产级 code-review Skill 的诞生过程。所有文件约 250 行,按顺序复制粘贴就能跑。

1. 目标:我们要做什么 Skill

面向团队 Git 仓库,触发后自动:

• 加载 git diff 变更文件清单;
• 运行 scripts/lint.py 做静态检查 + 安全扫描;
• 对照 references/style-guide.md 用 LLM 给出改进建议;
• 在 PR 评论里贴出 Markdown 报告。

2. Step 1:用 skill-creator 聊需求

在 Claude Code 里直接说:

skill-creator 会反问几个澄清问题(目标用户、模型边界、副作用),回答完后直接生成 code-review/SKILL.md 草稿。

3. Step 2:手写 SKILL.md(成品)

---
name: code-review
description: 对当前 git diff 做静态检查 + 安全扫描 + 风格审查,生成可贴入 PR 的 Markdown 报告。当用户说「review」「审查」「看一下这个改动」时使用。
---

# Code Review Skill

对当前分支相对 main 的所有变更,运行静态检查 + 安全扫描 + LLM 风格审查,产出一份 PR 评论。

## 工作流

1. `git diff main...HEAD --stat` → 拿到变更文件列表
2. 对每个变更文件执行 `python scripts/lint.py <file>`
3. 读取 `references/style-guide.md` 与 `references/security-checklist.md`
4. 用 LLM 综合 lint 输出 + 文档规则,生成 Markdown 报告
5. 把报告写到 `report.md`,提示用户复制到 PR

## 何时不要使用

- 用户只想看某一行代码 → 直接 Read,不要触发
- 改动 < 5 行 → 直接口头点评
- 非代码文件(.md / .txt) → 跳过 lint,只做风格审查

## 输出格式

报告必须包含 3 个固定小节:**Lint 结果**、**安全问题**、**改进建议**。缺失任一节视为报告不完整。

4. Step 3:加 scripts/lint.py(Python 静态检查 + 安全扫描)

"""对单个 Python 文件做静态检查 + 安全扫描。

用法:
    python scripts/lint.py path/to/file.py

退出码:
    0 - 通过
    1 - 发现问题(报告写到 stderr)
"""
from __future__ import annotations

from pathlib import Path

# 简化的安全规则:常见漏洞关键词
SECURITY_PATTERNS = [
    (r"\beval\s*\(", "使用 eval 存在代码注入风险"),
    (r"\bexec\s*\(", "使用 exec 存在代码注入风险"),
    (r"pickle\.loads?\s*\(", "pickle 反序列化不可信数据有 RCE 风险"),
    (r"shell=True", "subprocess 启用 shell=True 需谨慎"),
    (r"password\s*=\s*['\"]", "疑似硬编码密码"),
    (r"\.format\s*\(\s*\*\*", "format(**kwargs) 可能泄露敏感字段"),
    (r"verify\s*=\s*False", "禁用 TLS 校验,中间人攻击风险"),
]


def check_security(source: str) -> list[str]:
    """扫描代码字符串,返回安全问题列表。"""
    issues = []
    for pattern, msg in SECURITY_PATTERNS:
        for m in re.finditer(pattern, source):
            line_no = source[: m.start()].count("\n") + 1
            issues.append(f"  L{line_no}: [SECURITY] {msg}")
    return issues


def check_ast(source: str) -> list[str]:
    """AST 级别检查:函数过长、参数过多、缺 docstring。"""
    issues = []
    try:
        tree = ast.parse(source)
    except SyntaxError as e:
        return [f"  L{e.lineno}: [SYNTAX] {e.msg}"]
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            n_lines = (node.end_lineno or node.lineno) - node.lineno + 1
            if n_lines > 80:
                issues.append(f"  L{node.lineno}: [STYLE] 函数 {node.name} 有 {n_lines} 行,建议拆分子函数")
            if len(node.args.args) > 6:
                issues.append(f"  L{node.lineno}: [STYLE] 函数 {node.name} 有 {len(node.args.args)} 个参数,建议用 dataclass")
            if not ast.get_docstring(node):
                issues.append(f"  L{node.lineno}: [STYLE] 函数 {node.name} 缺少 docstring")
    return issues


def main() -> int:
    if len(sys.argv) != 2:
        print("usage: lint.py <file>", file=sys.stderr)
        return 2
    path = Path(sys.argv[1])
    if not path.exists():
        print(f"file not found: {path}", file=sys.stderr)
        return 2
    source = path.read_text(encoding="utf-8")
    issues = check_ast(source) + check_security(source)
    if issues:
        print(f"=== {path.name}: {len(issues)} issue(s) ===", file=sys.stderr)
        for i in issues:
            print(i, file=sys.stderr)
        return 1
    print(f"=== {path.name}: OK ===")
    return 0


if __name__ == "__main__":
    sys.exit(main())

5. Step 4:加 references/(团队规范文档)

两个 Markdown 文件,每个 30-50 行,内容真实可执行:

# references/style-guide.md

## 命名
- 变量 / 函数:`snake_case`;类:`PascalCase`;常量:`UPPER_SNAKE`
- 布尔变量前缀:`is_` / `has_` / `should_`
- 私有方法 / 属性:单下划线 `_` 开头

## 函数
- 单函数不超过 80 行
- 参数不超过 6 个,超过用 dataclass / pydantic model
- 必须有 docstring(Google 风格),首行一句话概括

## 错误处理
- 不要用裸 `except:`,必须指定异常类型
- 业务错误用自定义异常类,不要 `raise Exception("...")`
- 上层捕获后必须记录日志 + 上抛,不要吞掉

## 类型注解
- 公开函数 100% 加类型注解
- 内部工具函数推荐加,允许 `Any`
- 用 `from __future__ import annotations` 兼容低版本

# references/security-checklist.md

## 强制项(出现即 reject)
- `eval` / `exec` 调用
- `pickle.loads` 接收不可信数据
- SQL 字符串拼接(必须用参数化查询)
- 硬编码的密码 / API Key / Token
- 关闭 TLS 校验 (`verify=False`)
- `subprocess` 启用 `shell=True` 又拼接用户输入

## 警告项(出现需说明理由)
- 使用 `os.system` / `os.popen`
- 反射 / 动态 import 业务模块
- 反序列化用户上传的 JSON / YAML
- 日志里打印 request body / token

## 推荐做法
- 密钥从环境变量 / Vault 读取
- 用 `secrets` 模块生成随机数,不要用 `random`
- 数据库用 ORM 或参数化 SQL

6. Step 5:本地测试

cd code-review
# 写一个故意有问题的测试文件
cat > /tmp/bad.py << 'EOF'

def long_function(a, b, c, d, e, f, g, h):
    """短 docstring."""
    password = "admin123"
    eval("1+1")
    return a + b

def no_docstring():
    return 42
EOF

python scripts/lint.py /tmp/bad.py
echo "exit=$?"

预期输出(走 stderr,exit=1):

=== bad.py: 4 issue(s) ===
  L3: [STYLE] 函数 long_function 有 8 个参数,建议用 dataclass
  L9: [STYLE] 函数 no_docstring 缺少 docstring
  L5: [SECURITY] 疑似硬编码密码
  L6: [SECURITY] 使用 eval 存在代码注入风险

7. Step 6:发布到团队 Git 仓库

# 1. 推到团队公共仓库
git init
git add .
git commit -m "feat(skill): add code-review skill"
git remote add origin git@github.com:your-team/agent-skills.git
git push -u origin main

# 2. 在 Claude Code / Cursor 里把仓库注册为 Skill 来源
# Claude Code: claude config set skills.sources https://github.com/your-team/agent-skills
# Cursor: Settings → Features → Add Skill Source

# 3. 团队成员 reload,即可在对话中触发:
#    "用 code-review 审查当前分支"

8. 完整目录结构(产物)

code-review/
├── SKILL.md                     # YAML frontmatter + 工作流说明
├── scripts/
│   └── lint.py                  # 静态检查 + 安全扫描(70 行)
└── references/
    ├── style-guide.md           # 团队代码风格(40 行)
    └── security-checklist.md    # 安全审查清单(35 行)

9. 验证:在 Claude Code 里使用

新开会话,输入:

Claude 应当:

1. 读取 SKILL.md 理解工作流;
2. 运行 git diff main...HEAD --stat;
3. 对每个 .py 文件执行 python scripts/lint.py <file>;
4. 读取两个 references 文档;
5. 输出符合"输出格式"约束的 Markdown 报告(3 个固定小节齐全)。

如果 Claude 没有自动加载 Skill,在 ~/.claude/skills/ 下软链即可:

ln -s /path/to/agent-skills/code-review ~/.claude/skills/code-review

截图位置:Claude 输出的 PR 评论报告 → 复制成 report.md 即可,或贴到 GitHub PR 的 comment 框截图。