Skip to content

Commit 85d6b03

Browse files
SummerSecSummerSec
authored
Update why-personal-agent-skills-repo.md
1 parent 6cd17bb commit 85d6b03

1 file changed

Lines changed: 162 additions & 35 deletions

File tree

‎2026/why-personal-agent-skills-repo.md‎

Lines changed: 162 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@ tags:
33
- blog-comments
44

55
---
6-
76
# 模型人人都能用，什么才是你能带走的？我的答案是一个可进化的SKILL库
87

98
> 你花几十小时调教出来的 AI 工作流，换个工具就没了？这篇文章聊聊怎么把它变成可积累、跨平台、能自我进化的资产。
@@ -19,17 +18,17 @@ A developer sitting at a desk with multiple AI agent interfaces floating around
1918

2019
## 先聊一个不舒服的现实
2120

21+
<!--
22+
插图 prompt:
23+
A developer standing at a crossroads/fork in the road, looking uncertain. Behind them, a fading office building with a "company" sign dissolving into particles. In front of them, multiple diverging paths leading to different destinations (startup, freelance, new company). The developer carries only a small glowing backpack (representing portable skills). Around the paths, AI tool logos float like road signs changing rapidly. Style: slightly melancholic but hopeful atmosphere, muted colors with the glowing backpack as focal point, editorial illustration style, metaphorical.
24+
-->
25+
2226

2327

2428
AI 时代有一个残酷的事实：**谁也无法保证你明天还在这家公司。**
2529

2630
当 AI 能完成越来越多的工作，团队在缩编，岗位在重组。你今天在 A 公司用 Cursor 写代码，明天可能在 B 公司用 Claude Code，后天可能自己出来单干。
2731

28-
<!--
29-
插图 prompt:
30-
A developer standing at a crossroads/fork in the road, looking uncertain. Behind them, a fading office building with a "company" sign dissolving into particles. In front of them, multiple diverging paths leading to different destinations (startup, freelance, new company). The developer carries only a small glowing backpack (representing portable skills). Around the paths, AI tool logos float like road signs changing rapidly. Style: slightly melancholic but hopeful atmosphere, muted colors with the glowing backpack as focal point, editorial illustration style, metaphorical.
31-
-->
32-
3332
![不确定的现实](./images/uncertain-reality.png)
3433

3534
在这种不确定性下，什么是你真正能带走的？
@@ -197,7 +196,7 @@ agents-dev → 我在开发 AI 工具本身
197196

198197
<!--
199198
插图 prompt:
200-
A central glowing SKILL.md document in the middle, with 6 arrows radiating outward to different platform logos/icons arranged in a circle: Claude Code (anthropic style), Cursor (cursor logo style), Codex CLI (openai style), OpenClaw(Clawfish style), OpenCode, Hermes(Hermes style). Each arrow passes through a thin "adapter layer" (shown as a small translating prism/filter). Style: hub-and-spoke diagram, clean lines, dark background with glowing connections, tech/network aesthetic.
199+
A central glowing SKILL.md document in the middle, with 6 arrows radiating outward to different platform logos/icons arranged in a circle: Claude Code (anthropic style), Cursor (cursor logo style), Codex CLI (openai style), OpenClaw, OpenCode, Hermes. Each arrow passes through a thin "adapter layer" (shown as a small translating prism/filter). Style: hub-and-spoke diagram, clean lines, dark background with glowing connections, tech/network aesthetic.
201200
-->
202201

203202
![多平台分发架构](./images/multi-platform.png)
@@ -253,7 +252,7 @@ AI Agent 平台的规范在快速演进。技能库如果是一座孤岛，很
253252
```gitmodules
254253
[submodule "claude-plugins-official"]
255254
path = claude-plugins-official
256-
url = git@github.com:anthropics/claude-plugins-official.git
255+
url = https://github.com/anthropics/claude-plugins-official.git
257256

258257
[submodule "context7"]
259258
path = context7
@@ -270,34 +269,173 @@ git submodule update --remote
270269

271270
Anthropic 更新了 Skill 规范？新增了 frontmatter 字段？调整了加载机制？不用去翻 changelog，不用猜"官方现在推荐怎么写"——直接看 `claude-plugins-official/` 目录里的最新代码。
272271

273-
### 一个真实的例子：frontmatter 的演进
272+
### 一个真实的例子：Skill 规范在快速生长
273+
274+
最早期的 Claude Code Skill 长这样，朴素到只有两个字段：
275+
276+
```yaml
277+
---
278+
name: my-skill
279+
description: "..."
280+
---
281+
```
282+
283+
能跑，但能力非常有限。它就是一段挂着名字的 prompt。
274284

275-
早期的 Claude Code Skill 只支持 `name` 和 `description` 两个字段。但官方后来陆续加入了一系列精细化控制：
285+
然后官方在短短一年内不断给它加新字段。今天一个完整的 Skill frontmatter 可能是这样：
276286

277287
```yaml
278288
---
279289
name: my-skill
280290
description: "..."
281-
# ↓ 这些全是后来才加入的新能力
282-
disable-model-invocation: true # 禁止 AI 自动调用，只能用户手动触发
283-
user-invocable: false # 纯背景知识，不暴露为命令
284-
allowed-tools: [Read, Grep] # 预批准安全工具，减少确认弹窗
285-
context: fork # 用子 Agent 执行，隔离上下文
286-
argument-hint: "<file-path>" # 支持用户直接传参
291+
when_to_use: "..." # 补充触发场景，帮 AI 更准判断
292+
argument-hint: "<file-path>" # 自动补全时的参数提示
293+
arguments: [issue, branch] # 命名位置参数
294+
disable-model-invocation: true # 禁止 AI 自动调用
295+
user-invocable: false # 不出现在 / 菜单
296+
allowed-tools: [Read, Grep] # 预批准工具,减少确认弹窗
297+
model: claude-opus-4-7 # 这个 Skill 指定模型
298+
effort: high # 指定思考强度
299+
context: fork # 子 Agent 隔离执行
300+
agent: Explore # 选择子 Agent 类型
301+
paths: ["src/**/*.ts"] # 只在编辑特定路径时激活
302+
hooks: { ... } # 绑定生命周期 hook
287303
---
288304
```
289305

290-
每个新字段都解决一个具体的痛点：
306+
字段数量翻了 6 倍多。每一个都对应一个真实的工程痛点：
291307

292308
| 字段 | 解决什么问题 |
293309
|------|-------------|
294-
| `disable-model-invocation` | 危险操作（删文件、部署）不能让 AI 自己决定执行 |
295-
| `user-invocable: false` | 编码规范这种背景知识不需要出现在命令列表里 |
296-
| `allowed-tools` | 只读操作不用每次都弹确认框 |
297-
| `context: fork` | 长任务用子 Agent 跑，不污染主对话 |
298-
| `argument-hint` | 让用户可以 `/skill <参数>` 直接传参 |
310+
| `when_to_use` | description 装不下完整触发场景，单独一栏专门写触发短语 |
311+
| `argument-hint` / `arguments` | 让 Skill 像命令一样接收参数（详见下一节）|
312+
| `disable-model-invocation` | 危险操作（部署、删除）不能让 AI 自己决定 |
313+
| `user-invocable: false` | 背景知识不需要出现在 `/` 菜单里 |
314+
| `allowed-tools` | 只读操作不用每次弹确认框 |
315+
| `model` / `effort` | 不同任务用不同算力（写文章用强模型，琐事用快模型）|
316+
| `context: fork` + `agent` | 长任务隔离到子 Agent，不污染主对话 |
317+
| `paths` | 只在编辑相关文件时才进入候选，节约注意力 |
318+
| `hooks` | Skill 自己绑定生命周期事件，做自动化预处理 |
319+
320+
**这还只是 Claude Code 一个平台的现状。** 其它平台还在各自演进。规范从"一段带名字的 prompt"长成了一个可编程的运行时。你不持续跟踪，写出的 Skill 就停留在最初版本，能跑，但用不上现在的能力。
321+
322+
### 新增能力一：参数传递，让 Skill 不只是静态文档
323+
324+
Skill 从"挂名 prompt"变成"动态命令"，靠的是这一步。Skill 内容里可以用占位符引用用户传入的参数：
325+
326+
```yaml
327+
---
328+
name: migrate-component
329+
description: 在框架之间迁移组件
330+
arguments: [component, from, to]
331+
---
332+
333+
把 $component 组件从 $from 迁移到 $to。
334+
保留所有现有行为和测试。
335+
```
336+
337+
用户输入：
338+
339+
```
340+
/migrate-component SearchBar React Vue
341+
```
342+
343+
Skill 内容被实时渲染成"把 SearchBar 组件从 React 迁移到 Vue"。
344+
345+
可用的占位符有这么几类：
346+
347+
- `$ARGUMENTS` — 所有参数拼成一个字符串
348+
- `$ARGUMENTS[0]` / `$0` — 按位置访问第一个参数（shell 风格引号，多词用引号包起来）
349+
- `$component` — 在 `arguments` 里声明的命名参数
350+
- `${CLAUDE_SESSION_ID}` — 当前会话 ID，做日志或会话级文件
351+
- `${CLAUDE_SKILL_DIR}` — Skill 自己所在的目录，引用同目录脚本必备
352+
353+
**Skill 不再是固化的指令，而是能接收上下文的可复用模板。** 一个 `/migrate-component` 配三个参数就能处理无数种迁移场景，不用为每对框架各写一个 Skill。
354+
355+
### 新增能力二：调用控制，谁来触发这个 Skill？
356+
357+
默认情况下，你和 AI 都可以触发任何 Skill。但有些 Skill 你只想自己手动触发（比如部署），有些你只想让 AI 在后台用（比如背景知识）。两个字段控制这件事：
358+
359+
| frontmatter 配置 | 用户能调用 | AI 能自动调用 | 加载到上下文的内容 |
360+
|------------------|------------|----------------|--------------------|
361+
| 默认 | ✅ | ✅ | description 常驻，body 调用时加载 |
362+
| `disable-model-invocation: true` | ✅ | ❌ | **description 完全不进上下文**，body 用户触发时加载 |
363+
| `user-invocable: false` | ❌ | ✅ | description 常驻，body 调用时加载 |
299364

300-
**如果你不跟踪官方，你可能还在用最原始的方式写 Skill。** 能跑，但远没有用上平台的全部能力。
365+
举两个例子：
366+
367+
```yaml
368+
# 部署 Skill：必须用户手动触发，AI 不能擅自决定
369+
---
370+
name: deploy
371+
disable-model-invocation: true
372+
---
373+
```
374+
375+
```yaml
376+
# 遗留系统知识：AI 需要在相关时引用，但不是给用户的命令
377+
---
378+
name: legacy-auth-context
379+
user-invocable: false
380+
---
381+
```
382+
383+
第二种特别值得注意：`disable-model-invocation` 不仅禁止 AI 调用，**还会把这个 Skill 的 description 从 AI 上下文里完全移除**。这是一个减压阀。把那些"重要但用得不频繁"的 Skill 标成手动触发，它们就不再占用 AI 的注意力预算。
384+
385+
---
386+
387+
### 顺便聊一下：Skill 多了真的会爆 context 吗？
388+
389+
写到这里我猜你心里有个疑问：**"如果我攒了几十上百个 Skill，AI 的上下文是不是被 description 撑爆了？"**
390+
391+
合理担心。但平台已经替你想了很多。说几个具体机制：
392+
393+
**1. 默认只加载 description，不加载正文。**
394+
你装了 50 个 Skill，进入上下文的只是 50 行简短描述（每条上限 1,536 字符）。Skill 正文只在被触发时才进入对话，一个 800 行的 SKILL.md 平时一个 token 都不占。
395+
396+
**2. 描述预算是动态的，按模型上下文窗口的 1% 自动分配。**
397+
Opus 4.7 有 200K 上下文，默认描述预算就是 2K 字符。预算不够时，**用得最少的 Skill 描述会先被砍掉**，常用 Skill 保留完整。可以用 `skillListingBudgetFraction` 调整这个百分比，或者用 `/doctor` 命令检查当前预算够不够。
398+
399+
**3. 用 `paths` 字段做按需激活。**
400+
`paths` 字段让 Skill 只在你编辑特定路径的文件时才进入候选：
401+
402+
```yaml
403+
---
404+
name: react-conventions
405+
paths: ["src/components/**/*.tsx"]
406+
---
407+
```
408+
409+
不编辑 React 文件时，这个 Skill 完全不出现。这就把"我有 100 个 Skill"变成了"任何时刻只有十几个相关的 Skill 在视野里"。
410+
411+
**4. 用 `skillOverrides` 在 settings 里手动调权重。**
412+
413+
```json
414+
{
415+
"skillOverrides": {
416+
"legacy-context": "name-only", // 只显示名字，不显示描述
417+
"deploy": "off" // 完全隐藏
418+
}
419+
}
420+
```
421+
422+
保留 Skill 在仓库里，但在当前项目里把它们"折叠"，既不丢，也不占 token。
423+
424+
**5. Auto-compaction 会替你保留最近用过的能力。**
425+
长对话被压缩时，最近调用过的 Skill 会自动重新挂载，每个保留前 5,000 token，总预算 25,000 token。你不会因为对话变长而失去刚用过的能力。
426+
427+
---
428+
429+
**结论：放心写 Skill。** 真正需要克制的不是 Skill 总数，而是这几条工程纪律：
430+
431+
- 不要把 SKILL.md 写到 500 行以上（深度内容放 `references/`，让 AI 按需加载）
432+
- 把 description 写准，让 AI 一眼能筛掉无关的
433+
- 给"重要但用得不频繁"的加上 `disable-model-invocation` 或 `user-invocable: false`
434+
- 给"只在特定路径相关"的加上 `paths`
435+
436+
这些都是平台给你的减压阀。用上它们，你的技能库可以放心从 20 个长到 200 个，上下文不会被撑爆，AI 的判断也不会被淹没。
437+
438+
**所以与其纠结要不要少写几个 Skill，不如把精力花在跟踪官方规范上。** 平台每加一个字段，往往就是在给你多一种"既要又要"的解法。不跟踪，Skill 一多就会越用越焦虑；跟踪了，你会发现每个焦虑场景官方都准备了对应的开关。
301439

302440
### 分层架构：官方是地基，个人是建筑
303441

@@ -368,18 +506,7 @@ git log --oneline skills/git-commit-pr/
368506

369507
<!--
370508
插图 prompt:
371-
A vertical funnel/filter diagram with 4 distinct layers, each progressively narrower.
372-
Top layer (widest): "Marketplace" — 4 colorful plugin boxes with brief labels floating in a wide open space.
373-
Second layer: "Plugin" — one plugin box opened, revealing 3-4 small skill cards inside.
374-
Third layer: "Skill" — a single SKILL.md document unfolding, showing its header and structure.
375-
Bottom layer (narrowest): "References" — detailed code snippets and script files loading on demand, shown as thin glowing threads being pulled in.
376-
377-
Between each layer, a semi-transparent filter/membrane with a "pass/block" visual — some items pass through (glowing), others stay above (dimmed).
378-
379-
On the left side, a vertical arrow labeled "context usage" decreasing from top to bottom. On the right side, a vertical arrow labeled "relevance" increasing from top to bottom.
380-
381-
Style: clean infographic, dark background with soft gradients, each layer has a distinct accent color (blue → teal → green → gold), minimalist geometric shapes, professional data visualization aesthetic, no text clutter, the funnel shape should feel elegant not cramped.
382-
509+
A two-panel layout. Left panel shows a single SKILL.md with "progressive disclosure" concept (layers peeling back). Right panel shows the same concept scaled up to repository level: multiple plugin boxes, each containing skills, user only pulling what they need. A visual parallel/mirror between the two panels showing "same principle, different scale". Style: clean split-panel infographic, mirror/fractal aesthetic, left side micro-scale, right side macro-scale, minimalist, professional.
383510
-->
384511

385512
![设计哲学](./images/design-philosophy.png)

0 commit comments

Comments
 (0)