Back to Details

effective-agent-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Skills: A Complete Guide

Agent Skills：完整指南

A consolidated reference on what agent skills are, why they exist, how they work, and how to write effective ones.
本文整合介绍了Agent技能是什么、存在的意义、工作原理以及如何编写有效的Agent技能。

1. What agent skills are

1. 什么是Agent技能

An Agent Skill is a folder containing a 
SKILL.md
file (YAML frontmatter + markdown instructions), plus optional subfolders for scripts, references, and assets that the agent loads on demand.
my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files
Skills are an open standard (agentskills.io), originally created by Anthropic and adopted by OpenAI Codex, Cursor, Gemini CLI, Microsoft Agent Framework, Google ADK, and 40+ other agent products. The core folder and 
SKILL.md
format are portable, but optional behavior such as invocation control can be client-specific.
Agent Skill是一个包含
SKILL.md
文件（YAML前置元数据+Markdown说明）的文件夹，还可按需包含用于脚本、参考资料和资源的可选子文件夹。
my-skill/
├── SKILL.md          # 必填：元数据 + 说明文档
├── scripts/          # 可选：可执行代码（CLI、验证器、辅助工具）
├── references/       # 可选：仅在需要时加载的详细文档
└── assets/           # 可选：模板、字体、静态文件
技能是一种开放标准（agentskills.io），最初由Anthropic创建，后被OpenAI Codex、Cursor、Gemini CLI、Microsoft Agent Framework、Google ADK及40多款其他Agent产品采用。核心文件夹和
SKILL.md
格式具备可移植性，但调用控制等可选行为可能因客户端而异。

2. Why this abstraction exists

2. 该抽象概念存在的意义

Base LLMs are generalists. Real work requires procedural knowledge, organizational context, and repeatable workflows. Every prior alternative had a failure mode:
ApproachProblem
Stuff it into the system promptAlways loaded → context bloat at scale
Re-paste instructions each sessionNo version control, no consistency
Fine-tuningSlow, expensive, opaque, vendor-locked
MCP servers aloneGive the agent tools but no workflows for using them
Skills solve four problems at once:
  • Context efficiency — instructions load only when relevant
  • Repeatability — multi-step procedures become auditable workflows
  • Composability — multiple skills combine at runtime per task
  • Portability — same files work across vendors and surfaces
Mental model: skills are to LLMs what man pages, runbooks, and team handbooks are to engineers — reference material loaded into working memory only when the task demands it.
基础LLM是通用型模型，但实际工作需要流程知识、组织上下文和可重复的工作流。以往的所有替代方案都存在缺陷：
方法问题
塞进系统提示词始终加载→大规模场景下上下文膨胀
每次会话重复粘贴说明无版本控制，缺乏一致性
微调速度慢、成本高、不透明、受供应商锁定
仅使用MCP服务器为Agent提供工具，但未给出使用工具的工作流
技能可同时解决四大问题：
  • 上下文效率 —— 仅在相关时加载说明
  • 可重复性 —— 多步骤流程成为可审计的工作流
  • 可组合性 —— 运行时可根据任务组合多个技能
  • 可移植性 —— 相同文件可跨供应商和平台使用
思维模型：技能对于LLM而言，就像手册、运行手册和团队指南对于工程师的意义——仅在任务需要时才加载到工作内存中的参考资料。

3. How they work — progressive disclosure

3. 工作原理——渐进式披露

The architectural core. Three-stage loading:
Level 1 — Discovery (~100 tokens per skill, always in context): Only 
name
+ 
description
from frontmatter are injected into the system prompt at startup. Agent knows the skill exists and when it applies. You can install dozens of skills with negligible overhead.
Level 2 — Activation (<5,000 tokens, loaded on match): When the user's request matches a skill's description, the agent reads the full 
SKILL.md
body into context.
Level 3 — Execution (unbounded, on demand): The agent reads referenced files (
references/foo.md
) or runs scripts (
scripts/validate.py
) only as needed. Scripts can execute without their source being loaded into context at all.
This is why bundled content has no practical limit. Files don't consume tokens until accessed.
这是架构核心，分为三个加载阶段：
阶段1 —— 发现（每个技能约100 tokens，始终在上下文中）： 仅将前置元数据中的
name
+
description
注入启动时的系统提示词。Agent知道该技能存在以及适用场景。你可以安装数十个技能，且几乎不会产生额外开销。
阶段2 —— 激活（少于5000 tokens，匹配时加载）： 当用户请求与技能的描述匹配时，Agent会将完整的
SKILL.md
内容读取到上下文中。
阶段3 —— 执行（无限制，按需加载）： Agent仅在需要时才读取参考文件（
references/foo.md
）或运行脚本（
scripts/validate.py
）。脚本可在源代码未加载到上下文的情况下执行。
这就是为什么捆绑内容没有实际限制——文件在被访问前不会消耗tokens。

4. SKILL.md anatomy

4. SKILL.md结构解析

markdown
---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---
markdown
---
name: skill-name
description: 该技能的功能及适用场景。包含用户可能使用的触发短语。
---

Skill Name

技能名称

Quick start

快速入门

[Minimal working example]
[最小可用示例]

Workflow

工作流

[Step-by-step procedure with checklists]
[带检查清单的分步流程]

Output format

输出格式

[What the user/agent should expect back]
[用户/Agent预期的返回内容]

Advanced

进阶内容

[Link to references/ for rarely-needed detail]

Frontmatter constraints:
- `name` is lowercase, hyphens only, 1–64 chars, **exactly matches the parent folder name**
- Avoid `<` and `>` in frontmatter (they can inject into the system prompt)
- Invalid YAML silently prevents loading
- **Never put `: ` (colon + space) inside an unquoted `description`** — strict YAML parsers (e.g. Pi's) reject it as a nested mapping ("Nested mappings are not allowed in compact mappings"), even though lenient parsers (Claude Code) accept it. If the text needs a mid-sentence colon, single-quote the whole value and double any inner apostrophes: `description: 'Differentiator: finds gaps in David''s knowledge.'`
[链接至references/中的罕见场景细节]

前置元数据约束：
- `name`为小写，仅使用连字符，长度1-64个字符，**必须与父文件夹名称完全匹配**
- 前置元数据中避免使用`<`和`>`（它们可能注入到系统提示词中）
- 无效YAML会静默阻止加载
- **切勿在未加引号的`description`中使用`: `（冒号+空格）**——严格的YAML解析器（如Pi的解析器）会将其视为嵌套映射（“紧凑映射中不允许嵌套映射”），即使宽松的解析器（Claude Code）接受这种写法。如果文本需要句中冒号，请将整个值用单引号括起来，并将内部的撇号加倍：`description: 'Differentiator: finds gaps in David''s knowledge.'`

Manual-only invocation is client-specific

仅手动调用为客户端特定功能

disable-model-invocation: true
is not part of the core Agent Skills specification. It is a client extension supported by Claude Code and VS Code/Copilot. In those clients, put it in 
SKILL.md
frontmatter to prevent automatic invocation while keeping explicit invocation available.
OpenAI Codex uses a separate file at 
agents/openai.yaml
inside the skill:
yaml
policy:
  allow_implicit_invocation: false
For a manual-only skill shared across Claude Code, VS Code/Copilot, and Codex, include both configurations. Never assume a client-specific frontmatter field works in every Agent Skills implementation; verify each target client's documentation and test implicit invocation in each runtime.
disable-model-invocation: true
不属于核心Agent Skills规范。它是Claude Code和VS Code/Copilot支持的客户端扩展。在这些客户端中，将其放入
SKILL.md
前置元数据可防止自动调用，同时保留显式调用功能。
OpenAI Codex使用技能内部的独立文件
agents/openai.yaml
：
yaml
policy:
  allow_implicit_invocation: false
若要在Claude Code、VS Code/Copilot和Codex之间共享仅手动调用的技能，请同时包含两种配置。切勿假设客户端特定的前置元数据字段适用于所有Agent Skills实现；请验证每个目标客户端的文档，并在每个运行时测试隐式调用。

5. Two design philosophies

5. 两种设计理念

Skills tend to fall into one of two patterns. Both are valid; they solve different problems.
技能通常属于以下两种模式之一，两者均有效，可解决不同问题。

Pattern A — Capability primitives (tool wrappers)

模式A——能力原语（工具封装）

The skill is a thin wrapper over a deterministic CLI or script. Logic lives in code. SKILL.md teaches the agent how to invoke it.
  • Adds: new capabilities (search, email, browser, API access)
  • Reliability via: shell tools, not prompts
  • Typical length: 30–80 lines, mostly command examples
  • Use when: the bottleneck is "the agent can't do X"
技能是对确定性CLI或脚本的轻量封装。逻辑存在于代码中，SKILL.md指导Agent如何调用它。
  • 新增功能：新能力（搜索、邮件、浏览器、API访问）
  • 可靠性来源：Shell工具，而非提示词
  • 典型长度：30-80行，主要为命令示例
  • 适用场景：瓶颈在于“Agent无法完成X”

Pattern B — Process primitives (cognitive disciplines)

模式B——流程原语（认知规范）

The skill encodes a methodology the agent should follow. Pure prompt engineering — no scripts needed.
  • Adds: structured workflows (TDD, code review, design alignment, debugging loops)
  • Reliability via: explicit procedure, checklists, validation loops
  • Use when: the bottleneck is "the agent's output quality or process is bad"
A mature setup uses both. Pattern A gives the agent better tools. Pattern B gives it better methods for using them.
技能编码了Agent应遵循的方法论。纯提示词工程——无需脚本。
  • 新增功能：结构化工作流（TDD、代码审查、设计对齐、调试循环）
  • 可靠性来源：明确的流程、检查清单、验证循环
  • 适用场景：瓶颈在于“Agent的输出质量或流程不佳”
成熟的配置会同时使用两种模式。模式A为Agent提供更好的工具，模式B为Agent提供使用工具的更好方法。

6. How to write effective skills — do this

6. 如何编写有效的技能——正确做法

Description as routing contract

将描述作为路由契约

The description is the only thing the agent sees before deciding to load the skill. If your skill doesn't trigger, the description is wrong 95% of the time, not the body.
Include three elements:
  1. What the skill does (one phrase)
  2. When to use it (trigger phrases, situations)
  3. Differentiator vs related skills (prevents routing conflicts)
Pattern: 
"X via Y. Use for [situations]. [Differentiator: no Z required / faster than W / handles edge case V]."
Never summarize the full workflow in the description. If the description contains a step-by-step summary of how the skill works, the agent tends to follow that summary and skip loading the body. Describe what and when, never how. The description answers "should I open this skill now?" — not "what are the steps?"
描述是Agent决定是否加载技能前唯一能看到的内容。如果你的技能未触发，95%的原因是描述有误，而非内容本身。
描述需包含三个要素：
  1. 功能：技能能做什么（一句话）
  2. 场景：何时使用（触发短语、适用情境）
  3. 差异化：与相关技能的区别（避免路由冲突）
模板：
"通过Y实现X。适用于[场景]。[差异化：无需Z/比W更快/处理边缘场景V]。"
切勿在描述中总结完整工作流。如果描述包含技能工作原理的分步摘要，Agent往往会遵循该摘要而跳过加载内容。描述要说明“是什么”和“何时用”，绝不要说明“怎么做”。描述回答的是“我现在应该打开这个技能吗？”——而非“步骤是什么？”

Keep SKILL.md lean

保持SKILL.md精简

  • Beyond a certain length, you're usually encoding logic that should be in a script or referenced file
  • 超过一定长度后，你通常是在编码应放入脚本或参考文件的逻辑

Bash-first, prose-second

优先使用Bash，其次是文字说明

Concrete command examples with inline comments beat prose explanations. The agent pattern-matches on syntax. Show, don't describe.
带内联注释的具体命令示例优于文字解释。Agent会基于语法进行模式匹配。要展示，不要描述。

Push determinism into code

将确定性逻辑移入代码

Anything fragile, repetitive, or where variation is a bug → script. Use markdown only for tasks requiring judgment.
任何脆弱、重复或变异会导致错误的内容→编写脚本。仅将需要判断的任务用Markdown编写。

Match strictness to task fragility (degrees of freedom)

根据任务脆弱性匹配严格程度（自由度）

Scale instruction rigidity to how costly a wrong move is:
  • Loose natural-language heuristics when many approaches are valid (e.g. code review).
  • Pseudocode or templates when there's a preferred pattern but variation is acceptable (e.g. report format).
  • Exact scripts and strict step lists when the workflow is fragile, error-prone, or consistency-critical (e.g. migrations, document patching).
根据错误操作的代价调整指令的严格性：
  • 宽松的自然语言启发法：当多种方法均有效时（如代码审查）。
  • 伪代码或模板：存在首选模式但允许变异时（如报告格式）。
  • 精确脚本和严格步骤列表：当工作流脆弱、易出错或一致性要求高时（如迁移、文档补丁）。

Build validation loops

构建验证循环

The single biggest output quality improvement: state a verify → fix → re-verify loop explicitly.
  • Document skills: visual QA pass before delivery
  • Code skills: tests pass + zero type errors before completion
  • Data skills: schema validation before output
提升输出质量的最有效方法：明确说明“验证→修复→重新验证”循环。
  • 文档技能：交付前进行视觉QA检查
  • 代码技能：测试通过+零类型错误后再完成
  • 数据技能：输出前进行 schema 验证

State-check before action

行动前检查状态

Don't assume setup is done. Instruct the agent to verify state, then branch:
First check if X is configured: [command]
If not, walk the user through setup: [steps]
不要假设已完成设置。指导Agent验证状态，然后分支处理：
首先检查X是否已配置：[命令]
若未配置，引导用户完成设置：[步骤]

Just-in-time loading with explicit pointers

按需加载并使用明确指向

Tell the agent exactly when to read each referenced file:
For standard cases, follow the steps below.
For [specific edge case], read references/edge-cases.md first.
明确告知Agent何时读取每个参考文件：
标准场景请遵循以下步骤。
针对[特定边缘场景]，请先阅读references/edge-cases.md。

Keep references one level deep

保持参考文件仅一层深度

Link referenced files directly from SKILL.md. Never build chains (SKILL.md → advanced.md → details.md → actual.md) — the agent may preview nested files only partially and miss critical instructions. Add a table of contents to any reference file longer than 100 lines.
直接从SKILL.md链接参考文件。切勿构建链式链接（SKILL.md → advanced.md → details.md → actual.md）——Agent可能仅部分预览嵌套文件，从而错过关键说明。对于超过100行的参考文件，添加目录。

Document output formats

记录输出格式

If your script returns structured data, show the agent what it looks like. Enables reliable downstream parsing.
如果你的脚本返回结构化数据，请向Agent展示其格式。确保下游解析的可靠性。

Defer to --help for completeness

借助--help获取完整信息

List the 80% common operations in SKILL.md. Tell the agent to run 
tool --help
for the rest. Keeps SKILL.md small without losing functionality.
在SKILL.md中列出80%的常用操作。告知Agent运行
tool --help
获取其余内容。在不损失功能的前提下保持SKILL.md精简。

Compose primitives, don't bundle workflows

组合原语，而非捆绑工作流

One skill = one capability or one discipline. Resist bundling concerns into "the X workflow." Multiple small skills combine at runtime; one large skill is rigid.
一个技能=一项能力或一种规范。不要将多个关注点捆绑成“X工作流”。多个小技能可在运行时组合；一个大技能则过于僵化。

Cite established principles when applicable

适用时引用既定原则

If your skill encodes a known engineering methodology (TDD, DDD, red-green-refactor), name the source. Gives the agent a coherent model to align with and gives users a way to verify the design.
如果你的技能编码了已知的工程方法论（TDD、DDD、红-绿-重构），请注明来源。为Agent提供一致的模型以对齐，同时为用户提供验证设计的途径。

Persistent artifacts for cross-session memory

持久化工件实现跨会话记忆

Skills can write to repo-level files (CONTEXT.md, ADRs, decision logs) that future agent sessions read. This is how you fight the "agents have no memory" problem at the architecture level.
技能可写入仓库级文件（CONTEXT.md、ADRs、决策日志），供未来Agent会话读取。这是在架构层面解决“Agent无记忆”问题的方法。

7. What not to do — anti-patterns

7. 切勿做的事——反模式

Don't re-teach what the model already knows

不要重复教授模型已掌握的知识

Every line in SKILL.md should provide context the model doesn't already have. No Python syntax tutorials. No "what is git." Challenge every paragraph.
SKILL.md中的每一行都应提供模型不具备的上下文。无需Python语法教程，无需“什么是git”。质疑每一段内容。

Don't include human-facing docs

不要包含面向人类的文档

No README.md, no CHANGELOG.md, no INSTALLATION_GUIDE.md inside the skill folder. Skills are for agents.
技能文件夹内不要放README.md、CHANGELOG.md、INSTALLATION_GUIDE.md。技能是为Agent设计的。

Don't write vague descriptions

不要编写模糊的描述

  • Bad: "A helpful skill for documents"
  • Good: "Fill PDF form fields, extract form data, flatten completed PDFs. Use when the user mentions PDF forms, fillable forms, or programmatic field population."
  • 错误示例：“一款对文档有帮助的技能”
  • 正确示例：“填充PDF表单字段、提取表单数据、扁平化已完成的PDF。当用户提及PDF表单、可填写表单或程序化字段填充时使用。”

Don't bundle library code

不要捆绑库代码

If you need a parsing library, install via npm/pip. Don't paste source into the skill.
如果需要解析库，请通过npm/pip安装。不要将源代码粘贴到技能中。

Don't write monolithic mega-skills

不要编写单体巨型技能

If one skill does design + planning + implementation + testing + deployment, you've built a framework, not a skill. Split it.
如果一个技能同时负责设计+规划+实现+测试+部署，你构建的是框架，而非技能。请拆分它。

Don't assume the agent will infer

不要假设Agent会自行推断

Be explicit about every step that matters.
  • Bad: "Then deploy it."
  • Good: "Run 
    npm run deploy:staging
    and wait for HTTP 200 from /healthz before reporting success."
对所有重要步骤都要明确说明。
  • 错误示例：“然后部署它。”
  • 正确示例：“运行
    npm run deploy:staging
    ，等待/healthz返回HTTP 200后再报告成功。”

Don't write style-only variants

不要编写仅风格差异的变体

A skill that just changes tone or formatting belongs in user preferences or a system prompt, not a skill.
仅更改语气或格式的技能应放入用户偏好或系统提示词，而非技能中。

Don't ignore failure modes

不要忽略故障模式

For every workflow step that can fail, document what failure looks like and what to do. Happy-path-only skills break in production.
对于工作流中可能失败的每一步，记录故障表现及应对措施。仅包含理想路径的技能在生产环境中会失效。

Don't include time-sensitive information

不要包含时效性信息

"As of Q4 2024..." rots fast. Fetch live data via script or omit.
“截至2024年第四季度……”这类内容会很快过时。通过脚本获取实时数据或省略此类信息。

Don't use absolute paths

不要使用绝对路径

Always relative. Forward slashes regardless of OS. Use runtime placeholders for skill-directory references.
始终使用相对路径。无论操作系统如何，均使用正斜杠。使用运行时占位符引用技能目录。

Don't trust unfamiliar skills

不要信任陌生技能

Skills can execute arbitrary code and steer agent behavior. A malicious skill is a data exfiltration vector. Audit 
scripts/
for unexpected network calls, file access outside expected scope, or hidden instructions in references. Watch for typosquatted skill names. Sandbox execution environments.
技能可执行任意代码并引导Agent行为。恶意技能是数据泄露的载体。审核
scripts/
中的意外网络调用、超出预期范围的文件访问或参考资料中的隐藏指令。警惕拼写相似的技能名称。使用沙箱执行环境。

8. Authoring workflow

8. 编写工作流

  1. Identify the gap. Run your agent on real tasks. Where does it consistently fail or need re-prompting? That's a skill candidate.
  2. Decide the pattern. Capability primitive (need new tools) or process primitive (need better methodology)?
  3. Draft the description first. What + when + differentiator. Read it back: would the agent know when to fire it?
  4. Write the smallest body that works. Add only when testing reveals gaps.
  5. Move detail to references/ once SKILL.md grows too long.
  6. Test triggering. Ask the agent something the skill should handle without invoking it explicitly. If it doesn't fire, fix the description.
  7. Test execution. Invoke explicitly. If output is wrong, fix the body.
  8. Adversarial test. Have another LLM ask: "What edge cases break this skill?" Patch the gaps.
  9. Version control. Treat skills as code. Tag, branch, review.
  1. 识别缺口。让Agent处理实际任务。它在哪里持续失败或需要重新提示？这就是技能的候选场景。
  2. 确定模式。是能力原语（需要新工具）还是流程原语（需要更好的方法论）？
  3. 先编写描述。包含功能+场景+差异化。回头读一遍：Agent会知道何时触发它吗？
  4. 编写最小可行内容。仅在测试发现缺口时添加内容。
  5. 当SKILL.md过长时，将细节移至references/。
  6. 测试触发。向Agent提出技能应处理的问题，但不明确调用它。如果未触发，修改描述。
  7. 测试执行。显式调用技能。如果输出错误，修改内容。
  8. 对抗性测试。让另一个LLM提问：“哪些边缘场景会破坏此技能？”修复缺口。
  9. 版本控制。将技能视为代码进行标记、分支和审查。

9. Testing and debugging

9. 测试与调试

  • "Which skill did you use?" — ask the agent post-task. Fastest routing debug.
  • Routing fails → description problem. Add specific trigger phrases.
  • Execution fails → body problem. Add explicit steps, examples, or validation.
  • Skills snapshot at session start. Edits during a session require a restart.
  • Test against the weakest model you'll deploy on. Stronger models forgive vague skills; weaker models expose them.
  • Run an eval suite. A handful of representative prompts that should and shouldn't trigger the skill, with expected outputs.
  • “你使用了哪个技能？” —— 任务完成后询问Agent。这是最快的路由调试方法。
  • 路由失败→描述问题。添加具体的触发短语。
  • 执行失败→内容问题。添加明确的步骤、示例或验证。
  • 技能在会话开始时快照。会话期间的编辑需要重启。
  • 针对你将部署的最弱模型进行测试。更强的模型会容忍模糊的技能；更弱的模型会暴露这些问题。
  • 运行评估套件。包含一组代表性提示词，其中一部分应触发技能，一部分不应，并定义预期输出。

10. Composition

10. 组合性

Skills compose at runtime — the agent loads multiple skills as needed for a single task. Design for this:
  • One skill = one concern. Resist bundling.
  • Define interfaces between skills. If skill A produces artifacts that skill B consumes, document the shape.
  • Use a repo-level config substrate. A shared file (e.g., AGENTS.md, CONTEXT.md, settings.json) that multiple skills read and write coordinates them without explicit handoffs.
  • Loops over menus. A coordinated set of skills forming a workflow (align → spec → build → verify → refactor) drives adoption far better than an unrelated catalog of capabilities.
技能可在运行时组合——Agent可针对单个任务按需加载多个技能。为此进行设计：
  • 一个技能=一个关注点。避免捆绑。
  • 定义技能间的接口。如果技能A生成的工件供技能B使用，请记录其格式。
  • 使用仓库级配置基底。一个共享文件（如AGENTS.md、CONTEXT.md、settings.json），多个技能可读写该文件，无需显式交接即可协调工作。
  • 菜单式循环。一组协调的技能形成工作流（对齐→规范→构建→验证→重构），比无关的能力目录更能推动采用。

11. Security checklist

11. 安全检查清单

Before installing any third-party skill:
  • Read every file in the folder
  • Audit 
    scripts/
    for outbound network calls, file access outside expected scope, command execution
  • Check references for prompt injection ("ignore previous instructions...")
  • Verify the skill name isn't typosquatting a popular one
  • Run in a sandboxed environment first
  • Pin to a specific version/commit, not 
    latest
安装任何第三方技能前：
  • 阅读文件夹中的所有文件
  • 审核
    scripts/
    中的出站网络调用、超出预期范围的文件访问、命令执行
  • 检查参考资料中是否存在提示注入（“忽略之前的指令……”）
  • 验证技能名称是否模仿了热门技能的拼写
  • 先在沙箱环境中运行
  • 固定到特定版本/提交，而非
    latest

12. Ship checklist

12. 发布检查清单

Before publishing a skill:
  • Frontmatter 
    name
    matches folder name
  • Description includes what + when + differentiator
  • Description includes likely user trigger phrases
  • No human-facing docs inside the skill folder
  • No time-sensitive information
  • Relative paths only
  • State-check before action where applicable
  • Validation loop documented
  • Output format documented if relevant
  • Tested with weak and strong models
  • Tested for both correct triggering and correct execution
  • Skill does one thing
  • Composes cleanly with related skills
  • Version controlled
发布技能前：
  • 前置元数据
    name
    与文件夹名称匹配
  • 描述包含功能+场景+差异化
  • 描述包含可能的用户触发短语
  • 技能文件夹内无面向人类的文档
  • 无时效性信息
  • 仅使用相对路径
  • 适用时行动前检查状态
  • 记录了验证循环
  • 相关情况下记录了输出格式
  • 针对弱模型和强模型进行了测试
  • 测试了正确触发和正确执行
  • 技能仅负责一件事
  • 可与相关技能顺畅组合
  • 已进行版本控制

13. First principles, compressed

13. 核心原则精简版

  1. The description routes; the body executes. Get both right independently.
  2. Tokens are scarce; files are cheap. Push detail out of context until it's needed.
  3. Determinism comes from code; judgment comes from prompts. Put each in its right place.
  4. One skill, one concern. Composition beats bundling.
  5. Agents have no memory. Use persistent artifacts to give them one.
  6. The model knows a lot. Don't re-teach. Only add what's missing.
  7. Validate before completing. Self-correction loops dominate output quality.
  8. Skills are code. Version, test, audit, and review them as such.
  1. 描述负责路由；内容负责执行。确保两者都正确。
  2. Tokens稀缺；文件廉价。将细节移出上下文，直到需要时再加载。
  3. 确定性来自代码；判断来自提示词。将两者放在合适的位置。
  4. 一个技能，一个关注点。组合优于捆绑。
  5. Agent无记忆。使用持久化工件为其提供记忆。
  6. 模型掌握大量知识。不要重复教授。仅添加缺失的内容。
  7. 完成前先验证。自我校正循环对输出质量影响最大。
  8. 技能即代码。像对待代码一样进行版本控制、测试、审核和审查。