技能写作
- 作者仓库星标 3,480
- 作者仓库 expect
- 领域
- 写作
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @millionco · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`
# Skill Writing
Skills are bundled instruction modules that load into an agent's context when activated. They are the highest-leverage mechanism for controlling agent behavior because they deliver focused instructions at the moment of relevance.
## The Iron Law
**No skill without a failing test first.** Before writing a skill, run a subagent on the target task WITHOUT the skill. Document what it gets wrong — the exact rationalizations, shortcuts, and skipped steps. Then write the skill addressing those specific failures. This is TDD applied to documentation.
| TDD Step | Skill Equivalent |
|---|---|
| RED | Run scenario without skill. Document what the agent does wrong. |
| GREEN | Write minimal skill addressing those specific failures. Verify agent now complies. |
| REFACTOR | Find new rationalizations the agent invents. Close loopholes. Re-test. |
## When to Create a Skill
**Create when:** the technique wasn't obvious, you'd reference it across projects, others would benefit, or the agent repeatedly fails without it.
**Don't create for:** one-off solutions, standard practices documented elsewhere, project-specific conventions (use CLAUDE.md), or mechanical constraints (enforce with linters/hooks instead).
## Core Principles
**Instructions are a finite budget.** Models reliably follow ~150 instructions. The system prompt burns ~50. Every instruction you add degrades compliance across ALL instructions. Be ruthless about what earns a slot.
**Peripheral positions get more attention.** First and last sections receive disproportionate attention. Bury a critical rule in the middle and it gets skipped.
**Specificity drives compliance.** "Consider running audits" gets ignored. "Call `accessibility_audit` before emitting `RUN_COMPLETED`" gets followed.
**Unconditional beats conditional.** "You MUST call X" works. "When appropriate, consider X" does not.
## Description Optimization
The `description` field controls when the skill activates. The agent reads it to decide: "Should I load this right now?" Describe **triggering conditions**, not workflow.
**Bad:** `description: A skill for TDD - write test first, watch it fail, write code`
**Good:** `description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently. Covers flaky tests, hanging tests, zombie processes.`
Checklist for descriptions:
- Start with "Use when..." focusing on triggering conditions
- Include specific symptoms and error messages the user would mention
- Include synonyms (timeout/hang/freeze, cleanup/teardown/afterEach)
- Name tools, commands, file types that signal relevance
- Max 500 characters. Under 200 for frequently-loaded skills
- Never summarize the skill's process — this causes agents to follow the description instead of loading the full skill
## Skill Structure
```
.agents/skills/<skill-name>/
SKILL.md # Required. Under 200 lines.
references/ # Optional. Heavy reference docs (100+ lines).
```
### Frontmatter
```yaml
---
name: kebab-case-name
description: Use when [triggering conditions]. Covers [symptoms, tools, keywords].
---
```
Use verb-first active naming: `creating-skills` not `skill-creation`, `condition-based-waiting` not `async-helpers`.
## Writing Instructions That Get Followed
### Lead with identity, then constraints
One-line role statement, then hard constraints immediately. Do not build up to them.
```markdown
# Browser Test Executor
You are executing adversarial browser tests against code changes.
REQUIRED for every test run:
1. Call accessibility_audit before completing
2. Call performance_metrics before completing
3. Call close to flush the session
```
### Use numbered checklists gated on completion
Numbered lists signal sequence and completeness. Tie them to whatever marks the task "done."
```markdown
Before marking the task complete, you MUST:
1. Run the linter
2. Run the type checker
3. Run the test suite
Do not skip any step. A skipped step is a failed task.
```
The trailing "do not skip" is not redundant — it closes the escape hatch.
### Name tools and commands exactly
Never "run the appropriate checks." Always `call accessibility_audit` or `run pnpm typecheck`.
### Put mandatory behaviors at the end
The last section is the last thing read before acting. Put the non-negotiable checklist there.
### One good example, one bad example
Examples are worth more than explanations.
```markdown
**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`
```
## Bulletproofing Against Rationalization
Agents invent reasons to skip rules. Anticipate and close every loophole explicitly.
**Close escape hatches:** After every mandatory rule, add: "No exceptions for 'just this once', 'it's simple enough', or 'I'll do it next time'."
**Build a rationalization table** from your RED phase testing. Every excuse the agent made becomes an explicit counter in the skill:
| Agent Says | Skill Responds |
|---|---|
| "This change is too small to test" | Every change gets tested. Size is not an exemption. |
| "I already verified manually" | Manual verification is not a substitute. Run the tool. |
| "The user didn't ask for this" | The skill requires it. User silence is not opt-out. |
**Create a red flags list:** "If you catch yourself thinking any of these, stop and follow the checklist."
## Anti-Patterns
| Pattern | Why It Fails |
|---|---|
| "Consider running X when appropriate" | Conditional + vague = ignored |
| Giant skill files (>200 lines) | Exceeds instruction budget, compliance drops |
| Duplicating CLAUDE.md rules | Burns budget twice for the same instruction |
| Listing every edge case | Show one example, not twenty — the agent infers the rest |
| "Be thorough" / "Be careful" | Vibes, not instructions. Say what "thorough" means concretely |
| Multi-paragraph justifications | The agent needs the rule, not the backstory. One sentence of "why" max |
| Critical rules in the middle | Middle-of-prompt blindspot. Move to top or bottom |
| Writing a skill without testing first | You don't know what failures to address. Delete it, start with RED. |
| Workflow-summarizing descriptions | Agent follows the summary instead of loading the full skill |
## Checklist: Before Shipping
- [ ] Tested without the skill first (RED phase) and documented failures
- [ ] Skill addresses those specific failures, not hypothetical ones
- [ ] Description starts with "Use when..." and lists triggering conditions, not workflow
- [ ] Under 200 lines total
- [ ] Mandatory behaviors in a numbered checklist at top or bottom
- [ ] Every tool/command named exactly — no "appropriate" or "relevant"
- [ ] No hedging ("consider", "when appropriate", "if needed")
- [ ] At least one good/bad example pair
- [ ] No duplication with CLAUDE.md or other skills
- [ ] Escape hatches closed with explicit "no exceptions" language
- [ ] Re-tested with the skill (GREEN phase) and agent now complies
章节与文件索引
按说明文件中的顺序排列。
铁律
何时创建技能
核心原则
描述优化
前题
文件/命令 -> accessibility_audit · RUN_COMPLETED · description · description: A skill for TDD - write test first, watch it fail, write code · creating-skills · skill-creation · condition-based-waiting · async-helpers
内容校验值 -> 7738592abfdb
当前原文的自动摘译,尚未人工审校。
铁律
没有先通过测试就没有技能。在编写技能之前,请在没有技能的情况下对目标任务运行子代理。记录它出错的地方——确切的合理化、捷径和跳过的步骤。然后编写解决这些特定故障的技能。这是应用于文档的 TDD。 TDD 步骤·技能等效红色·无需技能即可运行场景。记录代理人做错了什么。绿色 · 写出解决这些特定故障的最低限度的技能。验证代理现在是否符合要求。
何时创建技能
创建时间:该技术并不明显,您可以跨项目引用它,其他人会受益,或者代理在没有它的情况下反复失败。不要创建:一次性解决方案、其他地方记录的标准实践、特定于项目的约定(使用 CLAUDE.md)或机械约束(改为使用 linter/hooks 强制执行)。
核心原则
说明是有限的预算。模型可靠地遵循约 150 条指令。系统提示烧~50。您添加的每条指令都会降低所有指令的合规性。对赢得一席之地的事物要毫不留情。外围位置受到更多关注。第一部分和最后一部分受到了不成比例的关注。将一条关键规则埋在中间,它就会被跳过。特异性驱动合规性。 “考虑进行审核”被忽略。 “在发出
RUN_COMPLETED之前调用accessibility_audit”得到遵循。描述优化
description字段控制技能何时激活。代理阅读它并决定:“我应该立即加载它吗?”描述触发条件,而不是工作流程。不好:description: A skill for TDD - write test first, watch it fail, write code好:description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently. Covers flaky tests, hanging tests, zombie processes.前题
使用动词优先的主动命名:
creating-skills不是skill-creation,condition-based-waiting不是async-helpers。