福生无量摸鱼天尊

logo
福生无量摸鱼天尊

skills系列：（一）coding未来的管中窥豹

2026/01/09
78
0

0. 现有的就是最好的

由于claude code的Opus和sonnet过于昂贵，其实codex也能用skills，这里推荐用codex的skills，只需要把https://github.com/obra/superpowers/tree/main/skills 里所有的文件夹搬到.codex的skills文件夹里即可。很多人吹嘘skills是什么黑科技，在我看来其实就是两个思路交错产生的结果：

  1. 减少token消耗，复用之前的思路

  2. 格式化输入输出，减少幻觉

也正是如此，产生了2.1当中的三种想法。这个技术不稀奇，是由于大模型固有缺陷带来的，只是个trick，希望各位理性看待。

1. Skill and Subagent

在专注 coding 的场景里，很多工作其实是“固定套路”：比如 code review、写 commit message、排查 CI 失败、生成变更摘要、跑一套团队约定的检查清单等这些都可以被抽象成可自动化的流程。

Skill 的价值就在于：把这种“可重复的、可流程化的环节”从一次性的 prompt 里抽出来，变成一个可组合、可扩展、可移植的能力模块，让 agent 像搭积木一样把能力拼起来，而不是每次都从零“临场发挥”。

更具体地说，Skill 不是一句提示词，而是一个有序文件夹：里面包含指令（核心通常写在 SKILL.md）、可执行脚本、以及参考资源（规范、模板、示例等）。

代理在执行任务时，会先基于 Skill 的“名字/描述”进行匹配，在任务需要时再动态发现并加载该文件夹内容（而不是一开始就把全部资料塞进上下文）。因此 Skill 能把你的经验打包成可复用资源，扩展 Claude 的能力，把通用代理“定制化”为符合你需求的专用代理。

1) Skills 和 Subagent 的关系

Skills 是“可复用的工作说明书/工具包”，Subagent 是“带独立上下文和权限的专职同事”。

Skills也就是Agent Skills的核心是 SKILL.md（YAML 元数据 + Markdown 指令），还可以带脚本/参考资料等。Claude Code 会基于 description 自动发现并应用。

Subagents是Claude Code 的自定义子代理，其核心是.claude/agents/*.md（或 ~/.claude/agents/），文件里是 YAML frontmatter（name/description/tools/model/…）+ Markdown 系统提示词。

重要细节：Subagent 默认不继承主对话的 Skills。你需要在 subagent 配置里显式写 skills:，它会把这些 Skills 的完整内容注入到 subagent 启动时的上下文。

2. skills流水线的好手

Skill 的本体：文件夹 = 指令 + 脚本 + 资源。在 Claude Code 里，最小形态就是一个包含 SKILL.md 的目录，SKILL.md 的 name / description 用来让 Claude 判断何时触发。

1) 渐进式披露

这里就不得不提到skill的“渐进式披露”：Skill 不要求把所有内容一次性注入上下文：可以把关键步骤留在 SKILL.md，把详尽规范拆到其他文件，需要时才读取。这让 Skill 能携带“几乎无限”的资料而不挤爆上下文窗口。

Skill 之所以“能装很多知识却不爆上下文”，靠的是三层加载模型：

  • Level 1：元数据（永远加载）
    启动时只加载每个 Skill 的 name + description（相当于目录卡片/索引）。Claude 只知道“有哪些技能”和“什么时候用”。

  • Level 2：指令正文（触发才加载）
    当你的请求匹配 description，Claude 才会去读取 SKILL.md 的正文，把流程化的“怎么做”读进上下文。

  • Level 3：资源与代码（需要时才访问/执行）
    SKILL.md 可以链接更多文档（规范、API 说明、模板），也可以带脚本；Claude 只在需要时才读这些文件，并且脚本可以直接执行（只把输出带回上下文），做到“可靠、可重复、低 token”。

而恰巧这三个步骤，可以被抽象成以下三种想法：

  • Discovery（发现）：启动时只加载每个 Skill 的 name/description（快、轻量）。

  • Activation（激活）：当请求命中 description，Claude 会提示要使用该 Skill，你确认后才把完整 SKILL.md 读进上下文。

  • Execution（执行）：按 Skill 指令做事，按需读更多文件或运行脚本。

这里最关键的其实是description，它决定了claude会不会用这个skills。

2) Skills和Subagent的考虑

我曾经试过用多Subagent和Skills组合搭配试图造出一个软件开发团队，但是我发现写出来的代码千篇一律，非常垃圾。我试图scaling它，发现无论往里灌多少种可能性，总会出现写出来的代码灵活性不够，且输出代码有bug，最后我仔细思考了一下，发现是我的规格化workflow把agent的plan给限制死了，所以我认为一个好的skills不是替代一个团队或者替agent去plan或者do somethion，不是给每个团队的成员编排任务，而是辅助每个subagent的plan执行的更顺畅，用更少的LLM call。

比如说我们写一个文档的subagent，我想做到的是：

  • “我想加一个用户认证功能” → writing 应自动生成/更新 docs/PRD_v0.1.md

  • “这个功能怎么做比较稳？给我两三个方案” → 自动生成/更新 docs/Feasibility_v0.1.md

  • “功能实现完了，补一份开发文档，告诉我怎么跑怎么测” → 自动生成/更新 docs/DevDoc_v0.1.md

那么我们如何写subagent呢？

  • 把它当成“岗位说明书”。

  • name/description 要能让 Claude 自动路由命中（写清它什么时候该被用、解决什么问题、产物是什么）

  • 再用几条硬规则钉住边界（能改哪些文件/不能做什么、输出必须落盘还是可直接回话、最多问几次澄清、遇到阻塞怎么交接）

  • 关键是把输入→产出写成可执行契约：例如“读 PRD + repo 现状 → 输出 .claude/handoff/<task_id>/plan.md + 5 条风险 + 下一步建议”，并明确“只回路径+摘要”。

  • 这样它既可替换（换人也按同一口径交付），又不容易越界或发散。

目录结构如下：

<repo>/
├── docs/
│   ├── PRD_v0.1.md
│   ├── Feasibility_v0.1.md
│   └── DevDoc_v0.1.md
└── .claude/
    ├── agents/
    │   └── writing.md
    ├── skills/
    │   ├── doc-router/SKILL.md
    │   ├── prd-writer/SKILL.md
    │   ├── feasibility-writer/SKILL.md
    │   └── devdoc-writer/SKILL.md
    └── handoff/
        └── <task_id>/
            ├── state.json
            ├── writing_log.md
            ├── prd_notes.md
            ├── feasibility_notes.md
            └── devdoc_notes.md

Subagent最重要的有三点：

A) description 写成路由器

在YAML frontmatter的部分，有name（subagent 的“唯一标识”）、description（自动路由的“召唤咒语”）和skills（给这个角色的“工具箱”）。

其中写好description的要点：一句话说明什么时候用（触发场景）+ 做什么（任务类型）+ 产物落哪（文件路径）+ 禁止做什么（边界）。如：

---
name: writing
description: >
  Documentation specialist. Use proactively when the user describes a feature in natural language, asks for a PRD/spec,
  feasibility/options analysis, or wants dev/implementation documentation. Always write docs to docs/** and handoffs to
  .claude/handoff/**. Never modify source code.
skills:
  - doc-router
  - prd-writer
  - feasibility-writer
  - devdoc-writer
---

CLARIFY POLICY
- Ask at most 3 clarification questions if absolutely needed for correctness.
- Otherwise proceed with best-effort and list assumptions explicitly in the doc.

CHANGELOG
- Every doc must have a final "## Changelog" section.
- Each update append a timestamp line and 3–8 bullets of changes.

B) HARD RULES写好边界

写清楚写入范围 + 输出格式 + 状态落盘。

You are the documentation owner.

HARD RULES
- Only create/edit files under: docs/** and .claude/handoff/**.
- Never modify source code files.
- Output is file-first: write the full doc(s) to disk, then reply with only:
  - artifact_path(s)
  - 3–8 bullet summary
  - open questions (<= 5)
- Maintain per-task state and log:
  - .claude/handoff/<task_id>/state.json
  - .claude/handoff/<task_id>/writing_log.md

写好要点：

  1. 写入范围（只能写 docs/handoff）= 防越权

  2. 输出形式（file-first + 摘要）= 防上下文爆炸

  3. 状态与日志（state.json/log.md）= 可追踪、可增量

C) ROUTING + ID/VERSION 路由策略和标识

版本和路由控制一次只更新一个主文档，并保证可增量续写。

ROUTING
- Each turn, run the routing logic in doc-router and pick ONE primary doc to update:
  - PRD OR Feasibility OR DevDoc
- You may add a tiny cross-link line to the other docs, but do not rewrite multiple major docs in one turn.

TASK ID / VERSION
- task_id:
  - If user provides one, use it.
  - Else infer from existing .claude/handoff/*/state.json recent entries.
  - Else generate: T<YYYYMMDD>_<HHMM>_<nn>.
- version:
  - If user provides, use it (e.g., v0.2).
  - Else infer from docs filenames if present; otherwise default v0.1.

写好要点：

  • One primary doc per turn 是关键；否则 PRD/可行性/DevDoc 相互覆盖，版本漂移。

  • task_id 要可复用（能从 state.json 续写）

  • version 要可推断（从文件名/用户指令推断）

  • 规则要简单，避免每次都问用户

D) skills的的策略

  • description=触发条件 + 输出位置

---
name: prd-writer
description: "Turn user language into a PRD/spec with testable requirements and acceptance criteria. Output to docs/PRD_<version>.md."
user-invocable: true
---

  • 明确 scope / non-goals（防发散）

## Goal
Produce a PRD that is testable and scoped.

## Non-goals
Do not discuss implementation details beyond interfaces and constraints.

  • 固定输出契约（路径+结构）

## Outputs (mandatory)
- docs/PRD_<version>.md
- .claude/handoff/<task_id>/prd_notes.md

  • 步骤清单化（4–8 步）

## Steps
1) Extract goals + non-goals
2) Turn statements into atomic FR items (FR-01...)
3) Add acceptance criteria for each FR
4) Add work items (WI-01...) with DoD and test plan

  • DoD checklist + 失败策略（可验收、可持续跑）

## Checklist
- Every FR has acceptance criteria
- Scope and non-goals exist
- Open questions <= 5
- Has Changelog entry

## If ambiguous
- Ask at most 3 questions
- Otherwise write assumptions explicitly + list open questions

重点就在这里的steps，不要限制agent的plan，不然就会僵化输出，变得毫无作用

3. 一些比较好用的 Skills

我认为现有的已经足够好了：

  • anthropics/skills：官方示例与模板库，覆盖从文档到工程自动化的多类 Skill，适合照着抄结构

  • skill0：看似很厉害，其实挺水的

  • Superpowers：很流畅使用的一个库，很值得推荐

  • Agent-Skills-for-Context-Engineering：写完博客发了没几天就冒出来的上下文skills，挺有意思的

  • PRD-Taskmaster：相较于PRD Generator，我觉得更够反向提问是一个非常重要的过程

如果要我说，缺以下几个非常重要的skills：

  • 豪看的前端和正确的后端skills：在官方库里有两三个前端的skills，非常棒。关于前后端联调的skills倒是没见过

  • 数值正确性的skills：通常初始化的数据都是非常离谱的数据

  • 代码理解的skills：我还没看到能够把大代码库浓缩成高质量报告的skills

  • 记录过往报错的和正确执行的shell命令：很多人运行codex或者cc并不是在bash，而是cmd或者powershell，这时候命令往往不一样，这里总是会重复非常多次错误的shell命令

  • 记住用户喜欢代码或注释风格的skills：除非你不读代码，不然这个还是很重要的

  • 记住用户喜欢的输出形式的skills：这太重要了，谁都不想输出牛头不对马嘴，一点不合自己心意吧

  • 类似context engineering的固定证据链的skills：ABCD，下次我想问B到E，谁都不想多花时间和token去search和inference从B到D把

  • and so on~