Back to Details

skill-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Writing

技能编写

Before you start

开始之前

Ask yourself: is a skill the right tool? A skill encodes reusable, domain-specific knowledge that an agent lacks on its own. If the task is a one-off, a simple prompt handles it better. Push back when a skill request is really a script, a config file, or a one-time instruction.
When the user's intent is clear, proceed directly. When it is ambiguous, clarify with targeted questions:
  • What task or domain does this cover?
  • What specific use cases should it handle?
  • Does it need scripts, or instructions alone?
  • What source material exists (docs, runbooks, code reviews, past conversations)?
Ground the skill in real expertise - internal docs, actual incident reports, code review patterns. A skill synthesized from project-specific material outperforms one built from generic knowledge.
先问自己：用技能解决当前问题是否是合适的选择？技能是对Agent本身不具备的、可复用的领域特定知识的编码。如果是一次性任务，使用简单的提示词处理效果更好。如果所谓的技能请求本质上只是一个脚本、配置文件或者一次性指令，应该拒绝这类需求。
当用户意图明确时可直接推进工作，若意图模糊，可通过针对性问题澄清：
  • 该技能覆盖的任务或领域是什么？
  • 它需要处理哪些具体的使用场景？
  • 它是否需要脚本支持，还是仅靠指令就足够？
  • 现有的参考材料有哪些（文档、运行手册、代码评审记录、过往对话）？
技能要基于真实的专业知识构建：内部文档、实际事故报告、代码评审模式等。基于项目特定材料合成的技能，效果远优于基于通用知识构建的技能。

Structure

结构

skill-name/
├── SKILL.md          # Required: frontmatter + instructions
├── scripts/          # Optional: deterministic, reusable logic
├── references/       # Optional: detailed docs loaded on demand
└── assets/           # Optional: templates, schemas, static resources
skill-name/
├── SKILL.md          # 必需：前置元数据 + 指令内容
├── scripts/          # 可选：确定性、可复用的逻辑
├── references/       # 可选：按需加载的详细文档
└── assets/           # 可选：模板、 schema、静态资源

SKILL.md

SKILL.md

Frontmatter

前置元数据

yaml
---
name: lowercase-hyphenated    # Must match directory name, max 64 chars
description: What it does and when to use it. Max 1024 chars.
license: MIT                  # Optional
compatibility: Requires X     # Optional, only if environment-specific
allowed-tools: Bash Read      # Optional, experimental
---
yaml
---
name: lowercase-hyphenated    # 必须和目录名一致，最长64个字符
description: 技能的用途和适用场景，最长1024个字符
license: MIT                  # 可选
compatibility: Requires X     # 可选，仅适用于特定环境的场景
allowed-tools: Bash Read      # 可选，实验性功能
---

Description

描述字段

The description carries the entire triggering burden. The agent sees only 
name
and 
description
at startup.
  • First sentence: what the skill does.
  • Second sentence: "Use when [specific triggers]."
  • Include keywords the user might say, even indirect ones.
  • Be pushy about when to activate - list contexts explicitly.
  • Stay under 1024 characters.
描述字段承担了全部的触发职责，Agent在启动时仅能看到
name
和
description
两个字段。
  • 第一句：说明技能的作用
  • 第二句：格式为「当[具体触发条件]时使用」
  • 包含用户可能会提到的关键词，哪怕是间接相关的也可以加入
  • 明确触发时机，清晰列出适用场景
  • 字数控制在1024字符以内

Body

正文内容

Write what the agent would get wrong without this skill. Skip what it already knows.
  • Lead with the core workflow. Put edge cases and advanced content in 
    references/
    .
  • Keep 
    SKILL.md
    under 500 lines and 5000 tokens.
  • Use procedures over declarations: teach how to approach a class of problems, not what to produce for one instance.
  • Provide defaults, not menus. Pick one tool/approach, mention alternatives briefly.
  • Add a gotchas section for environment-specific facts that defy reasonable assumptions.
只写没有这个技能时Agent会出错的内容，跳过Agent已经掌握的知识。
  • 开头先讲核心工作流，边缘 case 和进阶内容放在
    references/
    目录下
  • 控制
    SKILL.md
    内容在500行、5000 token 以内
  • 优先写操作流程而非规则声明：教Agent如何处理一类问题，而不是针对单个场景要输出什么内容
  • 提供默认方案而非选项列表：选定一种工具/实现方式，简要提及替代方案即可
  • 增加陷阱说明模块，记录不符合常规认知的环境特定注意事项

Writing style

写作风格

Follow the agent-communication guidelines:
  • Lead with the answer. Reasoning follows only when it aids the next step.
  • One sentence beats three. Cut filler, preamble, transitions.
  • Write in affirmative form. State what to do, not what to avoid.
  • Every token costs context, money, and human attention. Earn each one.
  • Use hyphens or commas instead of em dashes.
遵循agent-communication 规范：
  • 开头先给结论，只有当推理内容有助于推进下一步时再补充说明
  • 能用一句话说清就不要用三句，删掉冗余内容、开场白和过渡句
  • 用肯定句式表述，说明要做什么，而不是不要做什么
  • 每个token都会消耗上下文、成本和人的注意力，确保每部分内容都有价值
  • 用连字符或逗号代替破折号

Progressive disclosure

渐进式披露

  1. Frontmatter (~100 tokens): loaded at startup for all skills.
  2. SKILL.md body (<5000 tokens): loaded when the skill activates.
  3. References/scripts (as needed): loaded on demand.
Tell the agent when to load each file: "Read 
references/api-errors.md
if the API returns a non-200 status" beats "see references/ for details."
  1. 前置元数据（约100 token）：所有技能在Agent启动时就加载
  2. SKILL.md 正文（少于5000 token）：技能被触发时加载
  3. 参考文档/脚本（按需加载）：仅在需要时加载
要明确告知Agent何时需要加载对应文件：「如果API返回非200状态码，读取
references/api-errors.md
」的表述远优于「详情参考 references/ 目录」。

Scripts

脚本

Add a script when:
  • The operation is deterministic (validation, formatting, parsing).
  • The agent would reinvent the same logic each run.
  • Explicit error handling matters.
Script design:
  • Accept all input via flags, env vars, or stdin. No interactive prompts.
  • Include 
    --help
    with description, flags, and examples.
  • Write actionable error messages: what went wrong, what was expected, what to try.
  • Output structured data (JSON, CSV) to stdout, diagnostics to stderr.
  • Make scripts idempotent - agents retry.
  • Use inline dependency declarations (PEP 723 for Python, 
    npm:
    for Deno, 
    bundler/inline
    for Ruby).
满足以下条件时可以添加脚本：
  • 操作是确定性的（校验、格式化、解析）
  • 每次执行时Agent都需要重复实现相同逻辑
  • 需要明确的错误处理逻辑
脚本设计规则：
  • 所有输入通过参数、环境变量或者标准输入传递，不要使用交互式提示
  • 包含
    --help
    说明，提供功能描述、参数说明和使用示例
  • 输出可执行的错误信息：说明哪里出错了、预期结果是什么、可以尝试什么解决方案
  • 结构化数据（JSON、CSV）输出到标准输出，诊断信息输出到标准错误
  • 保证脚本幂等性，因为Agent可能会重试执行
  • 使用内联依赖声明（Python用PEP 723，Deno用
    npm:
    ，Ruby用
    bundler/inline
    ）

Library-shipped skills (TanStack Intent)

随库发布的技能（TanStack Intent）

When writing skills that ship inside an npm package, read references/intent.md for extended frontmatter fields, body conventions, validation rules, and packaging steps. Use 
npx @tanstack/intent@latest validate
to check compliance.
如果要编写随npm包发布的技能，请阅读references/intent.md了解扩展的前置元数据字段、正文规范、校验规则和打包步骤，使用
npx @tanstack/intent@latest validate
命令检查合规性。

Review checklist

评审检查清单

Before delivering, verify:
  • Description includes "Use when..." triggers and stays under 1024 chars
  • SKILL.md under 500 lines, focused on what the agent lacks
  • Directory name matches 
    name
    field (lowercase, hyphenated)
  • No time-sensitive information
  • Consistent terminology throughout
  • References one level deep from SKILL.md
  • Writing follows agent-communication style (concise, affirmative, earned tokens)
交付前请确认：
  • 描述包含「当...时使用」的触发条件，且字数在1024字符以内
  • SKILL.md 内容少于500行，聚焦于Agent不具备的知识
  • 目录名和
    name
    字段一致（小写、连字符分隔）
  • 没有包含时效性信息
  • 全文术语统一
  • 参考文件的引用层级不超过SKILL.md下一级
  • 写作符合Agent沟通风格（简洁、肯定、内容有价值）

After delivery

交付后

Present the draft to the user. Ask:
  • Does this cover your use cases?
  • Anything missing or unclear?
  • Should any section be more or less detailed?
Refine by running the skill against real tasks. Watch execution traces - if the agent wastes time on unproductive steps, the instructions are too vague or too numerous.
将草稿提交给用户，询问以下问题：
  • 是否覆盖了你的使用场景？
  • 有没有遗漏或者不明确的内容？
  • 有没有模块需要调整详细程度？
通过在真实任务中运行技能来迭代优化，观察执行链路：如果Agent在无效步骤上浪费时间，说明指令太模糊或者太冗余。