ByteWatcher

03 - Skills 设计

4分钟阅读

03 - Skills 设计

Skill 是什么

官方描述是”按需加载的知识与工作流”：描述符常驻上下文，完整内容按需加载。和”保存的 Prompt”差别挺大的。

渐进式披露

Claude Code 团队内部反复强调 “progressive disclosure”——不是让模型一次性看到所有信息，而是先获得索引和导航，再按需拉取细节：

  • SKILL.md 负责定义任务语义、边界和执行骨架
  • supporting files 负责提供领域细节
  • 脚本 负责确定性收集上下文或证据

推荐的目录结构：

.claude/skills/
└── incident-triage/
    ├── SKILL.md
    ├── runbook.md
    ├── examples.md
    └── scripts/
        └── collect-context.sh

三种 Skill 模式

类型一：检查清单型（质量门禁）

发布前跑一遍，确保不漏项：

---
name: release-check
description: Use before cutting a release to verify build, version, and smoke test.
---
## Pre-flight (All must pass)
- [ ] `cargo build --release` passes
- [ ] `cargo clippy -- -D warnings` clean
- [ ] Version bumped in Cargo.toml
- [ ] CHANGELOG updated
- [ ] `kaku doctor` passes on clean env
 
## Output
Pass / Fail per item. Any Fail must be fixed before release.

类型二：工作流型（标准化操作）

配置迁移高风险，显式调用 + 内置回滚步骤：

---
name: config-migration
description: Migrate config schema. Run only when explicitly requested.
disable-model-invocation: true
---
## Steps
1. Backup: `cp ~/.config/kaku/config.toml ~/.config/kaku/config.toml.bak`
2. Dry run: `kaku config migrate --dry-run`
3. Apply: remove `--dry-run` after confirming output
4. Verify: `kaku doctor` all pass
 
## Rollback
`cp ~/.config/kaku/config.toml.bak ~/.config/kaku/config.toml`

类型三：领域专家型（封装决策框架）

运行时出问题时让 Claude 按固定路径收集证据，不要瞎猜：

---
name: runtime-diagnosis
description: Use when kaku crashes, hangs, or behaves unexpectedly at runtime.
---
## Evidence Collection
1. Run `kaku doctor` and capture full output
2. Last 50 lines of `~/.local/share/kaku/logs/`
3. Plugin state: `kaku --list-plugins`
 
## Decision Matrix
| Symptom | First Check |
|---|---|
| Crash on startup | doctor output → Lua syntax error |
| Rendering glitch | GPU backend / terminal capability |
| Config not applied | Config path + schema version |
 
## Output Format
Root cause / Blast radius / Fix steps / Verification command

描述符优化

每个启用的 Skill，描述符常驻上下文，优化前后差距很大：

# 低效（~45 tokens）
description: |
  This skill helps you review code changes in Rust projects.
  It checks for common issues like unsafe code, error handling...
  Use this when you want to ensure code quality before merging.
 
# 高效（~9 tokens）
description: Use for PR reviews with focus on correctness.

关键原则：描述要让模型知道”何时该用我”，而不是”我是干什么的”。

disable-auto-invoke 策略

频率策略
高频（>1 次/会话）保持 auto-invoke，优化描述符
低频（<1 次/会话）disable-auto-invoke，手动触发
极低频（<1 次/月）移除 Skill，改为文档

有副作用的 Skill 要显式设置 disable-model-invocation: true，不然 Claude 会自己决定要不要跑。

反模式

  • 描述过短：description: help with backend（任何后端工作都能触发）
  • 正文过长：几百行工作手册全塞进 SKILL.md 正文
  • 一个 Skill 覆盖 review、deploy、debug、docs、incident 五件事
  • 有副作用的 Skill 允许模型自动调用

Prev: 02 - 上下文管理 | Next: 04 - 工具设计哲学

反向链接