Skill实战指南：告别仅写提示词

很多新手会把 Skill 理解成一个 SKILL.md 文件，这个理解并不完整。按照 Agent Skills 的标准结构，一个 Skill 的核心确实是 SKILL.md，但它还可以同时包含脚本、参考资料、模板、静态资源和其他辅助文件。官方规范中给出的典型结构是：SKILL.md 负责元信息和核心指令，scripts/ 用于存放可执行代码，references/ 用于存放参考文档，assets/ 用于存放模板或资源文件。

一个更贴近真实研发场景的目录可以这样设计：

.claude/skills/
└── queue-debugging/
    ├── SKILL.md
    ├── stuck-jobs.md
    ├── dead-letters.md
    ├── retry-storms.md
    ├── consumer-lag.md
    └── scripts/
        └── collect_queue_metrics.py

这种结构的优势在于：SKILL.md 只承载最核心的触发条件、流程入口和安全边界；具体排查步骤拆分到多个子文件；重复执行的命令、检测逻辑、格式转换则放到脚本里。Agent 在执行任务时，不必一次性读取所有内容，而是根据当前问题逐步加载所需文件。

例如，排查队列消费延迟时，Agent 先读取 SKILL.md 判断任务类型，再根据错误现象读取 consumer-lag.md，最后按需运行 collect_queue_metrics.py。这比把所有内容写进一个超长提示词更稳定，也更符合工程文档维护习惯。

在多模型接入场景中，如果团队需要统一管理 Claude、OpenAI、DeepSeek 等接口，也可以将 koalaapi 作为 API 中转接入方案之一，用于集中配置模型调用入口，减少不同 SDK 和接口格式带来的重复对接成本。

二、Skill 的核心机制：渐进式上下文加载

Skill 最重要的设计原则是“渐进式披露”（Progressive Disclosure）。Anthropic 官方解释过，Agent 启动时通常只加载每个 Skill 的 name 和 description，用于判断当前任务是否可能触发该 Skill；只有当任务匹配时，才会读取完整的 SKILL.md；如果还需要更多细节，再继续读取引用文件或执行脚本。

这套机制解决了一个非常实际的问题：上下文窗口有限，不能把所有团队文档一次性塞给模型。Skill 的正确写法不是“越全越好”，而是让 Agent 先看到最关键的入口信息，再按需深入。

一个基础 SKILL.md 可以这样写：

---
name: queue-debugging
description: Use this skill when debugging stuck, slow, delayed, failing, or retrying queue workers, including dead-letter queues, consumer lag, retry storms, and job backlog incidents.
---

# Queue Debugging Skill

Use this skill to diagnose queue worker incidents.

## Workflow

1. Identify the symptom:
   - stuck jobs
   - consumer lag
   - dead-letter growth
   - retry storm
2. Read the matching reference file:
   - stuck jobs: `stuck-jobs.md`
   - dead letters: `dead-letters.md`
   - retry storm: `retry-storms.md`
   - consumer lag: `consumer-lag.md`
3. Collect metrics before changing anything.
4. Do not restart workers or purge queues without human confirmation.
5. Summarize findings using the incident report template.

## Safety rules

- Never delete queue messages automatically.
- Never increase retry concurrency without approval.
- Always include evidence before suggesting rollback.

这里的重点不是写得华丽，而是写得明确。Agent 需要知道“什么时候用这个 Skill”“第一步做什么”“哪些行为不能自动执行”“需要读取哪些文件”。

三、九大分类：从研发到运维的 Skill 体系

结合官方实践和真实团队场景，Skill 可以按以下九类建设：

第一类：库与 API 参考。 记录内部 SDK、CLI、私有 API、第三方服务的特殊用法。例如某个内部支付接口虽然 HTTP 状态码返回 200，但业务状态仍可能失败，这类规则必须写进 Skill，否则 Agent 很容易套用通用经验。

第二类：产品验证。 用于执行自动化验收，例如用 Playwright 检查注册流程、用测试账号验证支付链路、用脚本确认页面关键元素是否出现。它的价值不只是“生成代码”，而是让 Agent 形成“写完之后必须验证”的闭环。

第三类：数据分析。 沉淀数据仓库表结构、字段口径、Grafana 面板、Datadog 查询方式和指标解释规则。很多数据问题不是 SQL 写错，而是口径理解错，Skill 可以把这些约定固化下来。

第四类：业务自动化。 用于生成站会纪要、周报、复盘、工单摘要、客户回访记录等重复性文本工作。相比通用提示词，Skill 可以固定输出结构、术语和信息优先级。

第五类：代码脚手架与模板。 用于生成新服务、新模块、数据迁移脚本、API handler、测试文件等，让代码结构符合团队规范，而不是每次由模型自由发挥。

第六类：代码质量与评审。 沉淀代码风格、审查要点、安全检查项、测试覆盖要求。例如要求所有数据库查询使用参数化写法、所有外部错误信息不得泄露内部堆栈。

第七类：CI/CD 与部署。 记录 CI 失败排查、构建缓存清理、PR 合并前检查、版本回滚步骤等流程。这类任务步骤固定、风险较高，非常适合用 Skill 固化。

第八类：故障处理手册。 按照“现象—排查步骤—证据—结论—处置建议”的逻辑组织报警处理流程，例如队列积压、数据库连接池耗尽、缓存击穿、接口 5xx 激增等。

第九类：基础设施运维。 管理资源清理、依赖升级、日志归档、成本排查等任务。需要特别注意，高危操作必须加入人工确认规则，不能让 Agent 自动执行删除、扩容、重启等动作。

四、专业编写原则：只写模型不知道的东西

Skill 最大的误区，是把它写成“通用最佳实践大全”。例如“代码要清晰”“异常要处理”“注意安全”这类内容，模型本来就知道，写进去只会占用上下文资源。Agent Skills 的最佳实践也强调，Skill 应聚焦模型不知道的项目特定规则、边界条件、工作流和常见错误，而不是解释 HTTP、数据库迁移、PDF 等通用概念。

更有价值的内容应该是：

## Gotchas

- The `users` table uses soft deletes. Always add:
  `WHERE deleted_at IS NULL`.

- The billing service uses `accountId`, while the auth service uses `uid`.
  They refer to the same internal user identity.

- The `/health` endpoint only checks whether the web server is alive.
  Use `/ready` to verify database and queue connectivity.

- A 200 response from the payment provider does not mean payment succeeded.
  Always check `business_status == "SUCCESS"`.

这类“项目特有坑点”才是 Skill 的核心价值。每当 Agent 犯错、工程师纠正、线上故障复盘时，都应该把对应经验补充到 Skill 中。Skill 的建设不是一次性写完，而是像测试用例和运维手册一样持续演进。

五、描述字段决定 Skill 是否会被正确触发

description 不是写给人看的简介，而是写给 Agent 的触发条件。官方文档明确指出，Agent 通常在启动时只读取 name 和 description，因此描述字段承担了判断是否加载 Skill 的关键职责；过窄会导致该触发时不触发，过宽会导致无关任务误触发。

错误写法：

description: 提升队列排查效率的工具

这个描述太泛，Agent 很难知道什么时候调用。

更好的写法：

description: Use this skill when debugging stuck, slow, delayed, failing, or retrying queue workers, including dead-letter queues, consumer lag, retry storms, and job backlog incidents.

这个描述覆盖了用户可能使用的不同表达方式：stuck、slow、delayed、failing、retrying、dead-letter、lag、backlog。实际优化时，可以准备一组触发测试用例。官方建议构造约 20 条查询，其中 8—10 条应该触发，8—10 条不应该触发，并且每条查询可以运行 3 次，用触发率观察描述是否稳定。

示例测试文件：

[
  {
    "query": "The order queue has 30k pending jobs and workers look alive. Help me diagnose it.",
    "should_trigger": true
  },
  {
    "query": "Write a Python script to sort a list of numbers.",
    "should_trigger": false
  },
  {
    "query": "Dead-letter messages increased after yesterday's deployment. What should I check?",
    "should_trigger": true
  }
]

如果一个 Skill 经常误触发，就说明描述太宽；如果经常漏触发，就说明描述没有覆盖真实用户表达。

六、文件结构：让 SKILL.md 保持轻量

大型 Skill 不应该把所有细节都写进 SKILL.md。Agent Skills 最佳实践建议：当 Skill 变大时，应把详细参考资料拆到独立文件，并在主文件中明确说明何时读取。文档中还给出建议：SKILL.md 尽量控制在 500 行、5,000 tokens 以内，核心思想是让主文件只承载每次执行都需要的内容。

推荐结构：

queue-debugging/
├── SKILL.md
├── references/
│   ├── stuck-jobs.md
│   ├── dead-letters.md
│   ├── retry-storms.md
│   └── consumer-lag.md
├── scripts/
│   └── collect_queue_metrics.py
└── assets/
    └── incident-report-template.md

在 SKILL.md 中不要写“更多内容见 references”，而要写清楚触发条件：

## Reference loading rules

- If jobs are pending but consumers are running, read `references/consumer-lag.md`.
- If dead-letter messages are increasing, read `references/dead-letters.md`.
- If retries spike after deployment, read `references/retry-storms.md`.
- If jobs remain locked for more than 15 minutes, read `references/stuck-jobs.md`.

这样 Agent 才知道什么时候读取哪个文件。

七、脚本：把不稳定推理变成确定性执行

Skill 不只是文档，也可以包含脚本。Anthropic 官方文章提到，某些操作更适合传统代码执行，因为脚本具备确定性和可重复性，例如解析文件、校验格式、提取字段、生成报告等。

比如队列排查中，可以把指标采集写成脚本：

# scripts/collect_queue_metrics.py
import json
import subprocess
from datetime import datetime

QUEUES = ["orders", "payments", "notifications"]

def run(cmd: str) -> str:
    result = subprocess.run(
        cmd,
        shell=True,
        capture_output=True,
        text=True,
        timeout=15
    )
    if result.returncode != 0:
        raise RuntimeError(result.stderr)
    return result.stdout.strip()

def main():
    report = {
        "collected_at": datetime.utcnow().isoformat(),
        "queues": {}
    }

    for queue in QUEUES:
        pending = run(f"queue-cli stats {queue} --field pending")
        failed = run(f"queue-cli stats {queue} --field failed")
        consumers = run(f"queue-cli stats {queue} --field consumers")

        report["queues"][queue] = {
            "pending": int(pending),
            "failed": int(failed),
            "consumers": int(consumers)
        }

    print(json.dumps(report, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

再在 SKILL.md 中约束 Agent：

## Metrics collection

Before recommending any fix, run:

```bash
python scripts/collect_queue_metrics.py

Use the output as evidence. Do not suggest restarting workers unless the metrics show consumers are missing or stuck.

这样做的好处是，Agent 不需要凭空猜测队列状态，而是先收集证据，再基于数据推理。

## 八、为 Skill 增加轻量记忆

部分 Skill 适合保留历史执行记录，例如站会总结、故障复盘、版本发布记录、客户问题跟踪等。最简单的方式是在 Skill 目录下维护一个日志文件：

```text
standup-summary/
├── SKILL.md
├── standups.log
└── assets/
    └── summary-template.md

追加日志的 Python 示例：

from datetime import datetime

def append_log(content: str):
    with open("standups.log", "a", encoding="utf-8") as f:
        f.write(f"\n--- {datetime.now().isoformat()} ---\n")
        f.write(content.strip())
        f.write("\n")

不过需要注意，记忆文件不应保存敏感数据，例如密钥、客户隐私、未脱敏订单信息等。对于团队环境，建议明确哪些日志可以进入仓库，哪些只能保存在本地或内部系统。

九、团队分发策略：小团队进仓库，大团队走插件化

对于小团队，最简单的方式是把 Skill 放进项目仓库，例如：

project-root/
└── .claude/
    └── skills/
        ├── queue-debugging/
        ├── code-review/
        └── release-checklist/

这样所有成员拉取代码后都能获得同一套 Skill，适合项目规范强、团队人数少、迭代速度快的场景。

对于大型团队，更推荐建立内部 Skill 仓库或插件市场。Anthropic 的公开 Skills 仓库也采用了类似“示例集合”的方式，覆盖创意设计、技术开发、企业沟通、文档处理等不同场景，并说明每个 Skill 都是独立文件夹，包含 SKILL.md、指令和元数据。

大型团队可以采用三步流程：

1. 新 Skill 先进入沙箱目录，由少数成员试用。
2. 通过真实任务验证触发率、输出质量和安全边界。
3. 通过 PR 合并到内部 Skill 集合，并标注适用项目、负责人和版本号。

这样可以避免每个人都维护一套不同的 Skill，也能防止未经审计的脚本被大范围使用。

十、安全边界：Skill 越强，审计越重要

Skill 可以给 Agent 新能力，也可能带来新风险。Anthropic 官方安全建议明确提到，应只从可信来源安装 Skill；对于不可信来源，应审计其中的文件、依赖、脚本和外部网络连接指令，避免恶意 Skill 导致数据外泄或非预期操作。

团队落地时，至少要建立以下规则：

• 所有脚本必须经过代码审查；
• 禁止在 Skill 中写入明文密钥；
• 高风险命令必须要求人工确认；
• 删除、回滚、重启、扩容等操作不得自动执行；
• Skill 目录应纳入版本控制，便于追踪修改历史；
• 每个 Skill 应有 owner，负责维护和更新。

一个安全提示可以直接写进 SKILL.md：

## Human approval required

You must ask for human approval before:
- deleting data
- purging queues
- restarting production services
- changing retry concurrency
- applying database migrations
- rolling back deployments

这类规则简单但非常重要。Agent 越接近真实生产环境，越需要清晰边界。

十一、总结：Skill 是团队经验工程化，而不是提示词堆叠

Skill 的真正价值，不是让提示词写得更长，而是把团队的隐性经验变成可复用的工程资产。它能沉淀内部 API 用法、代码审查规则、CI/CD 流程、故障处理手册、数据分析口径和业务自动化模板，让 Agent 在执行任务时不再依赖临时猜测。

专业的 Skill 体系应该具备五个特征：结构清晰、触发准确、内容克制、可验证、可审计。SKILL.md 负责入口和核心规则，参考文件负责细节，脚本负责确定性执行，日志负责连续性，评估用例负责持续优化。

对于开发者和团队而言，搭建 Skill 不应从“大而全的平台”开始，而应从一个具体痛点开始：一次队列故障、一个 PR 审查流程、一套发布检查清单、一个数据分析模板。每解决一个真实问题，就把经验沉淀进 Skill。长期来看，这些小型经验包会逐渐组成团队自己的 Agent 能力库，让 AI 真正贴合业务规范，而不是停留在通用回答层面。