技能创造演练
- 作者仓库星标 201
- 作者仓库 claude-skills
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @rampstackco · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
并非所有事情都应该成为技能。运行此测试: 签名应该是一项技能 · 签名不应该是 您重复相同的工作流程 5 次以上。 · 你用过一次。输出受益于一致的结构。 · 每个输出都是定制的。该任务有一个明确的触发器(问题形状、文件类型、域)。 · 该任务已经成为每次对话的一部分。
在写任何东西之前,先问一下:这个技能应该什么时候加载?具体一点。写下应该触发它的确切短语或情况。示例:“当用户要求提供创意简介、启动文档或项目简介时。” “当用户上传 CSV 并想要进行表格分析时。” “当用户询问‘我如何对 X 进行排名’、‘我应该添加模式’或任何与 SEO 相关的内容时。”
这是你的技能中最重要的一句话(或两句话)。描述就是克劳德在系统提示中看到的内容,决定是否加载技能。好的描述有 4 个部分:它的作用(一句话,面向行动)。何时使用它(触发短语或情况)。带有“当......时也触发”的边缘情况(捕获不太明显的情况)。
一致的结构使技能可读、可维护且对 AI 友好。以下模式适用于大多数技能:并非每个技能都需要每个部分。有些技能纯粹是如何操作并跳过“框架”。有些技能非常注重示例,并添加“示例”部分。使用该结构作为起点,根据需要进行调整。
参考文献是渐进式披露的第二层。它们是在克劳德阅读时加载的,而不是默认加载的。使用参考: 长清单(包含 100 项的审核清单)。带有工作示例的模板。针对特定场景的详细剧本。
技能第一次不会起作用。计划迭代。测试清单: [ ] 触发测试:在新的对话中,写下触发短语。技能有负载吗?如果不是,说明描述太狭窄或错误。 [ ] 边缘情况测试:编写应通过“也触发时...”子句触发的内容。会火吗? [ ] 误报测试:写一些接近但实际上不相关的内容。该技能是否可以避免加载?如果总是加载,则说明您的描述过于宽泛。
A walkthrough for designing, writing, and maintaining your own Claude Skills. Covers when a skill is the right shape for your problem, how to write a description that actually triggers, how to structure SKILL.md and references, and how to test and iterate.
## When to use
- You catch yourself writing the same prompt or instructions repeatedly.
- You want to package a workflow or framework for reuse.
- An existing skill of yours is not triggering when it should.
- You are publishing skills for others to use.
- You want to teach Claude a domain-specific way of working.
- You are reviewing a skill someone wrote and need a quality bar.
## When NOT to use
- For one-off prompts (just write the prompt).
- For information that should live in system context, not progressive disclosure.
- For changing Claude's general behavior across all conversations (use Claude.ai settings or system prompts, not skills).
- For replacing tool calls (skills are instructions, not tools).
## Required inputs
- The task or workflow you want to encode.
- The audience: who will trigger this skill, in what kind of conversation.
- Existing artifacts: prompts you have used, docs you have written, examples of good output.
## The framework: how skills work
A Skill is a folder with a `SKILL.md` file. The SKILL.md has YAML frontmatter (name and description) and a body with instructions. It can also include reference files, scripts, or templates that get loaded when needed.
The key property: **progressive disclosure**. Claude does not read every skill on every turn. The skill description lives in the system prompt. The SKILL.md body and references load only when the skill is triggered. This is what lets a user have hundreds of skills without polluting context.
What this means for you:
- The **description** is everything for triggering. Get it right or the skill never loads.
- The **SKILL.md body** is for the workflow itself.
- The **references** are for content that does not need to be in every invocation: long checklists, templates, examples, deep reference material.
## Workflow
### Phase 1: Decide if a skill is the right shape
Not everything should be a skill. Run this test:
| Sign it should be a skill | Sign it should not be |
| --- | --- |
| You repeat the same workflow 5+ times. | You used it once. |
| The output benefits from a consistent structure. | Each output is bespoke. |
| The task has a clear trigger (a question shape, a file type, a domain). | The task is part of every conversation already. |
| The instructions exceed 200 words. | A one-line system instruction would do. |
| Templates or reference material would help. | Pure prose is enough. |
| Other people might benefit from the same workflow. | Only relevant to your single project. |
If most of your answers are in the left column, build a skill. Otherwise, use a saved prompt or a system instruction.
### Phase 2: Define the trigger
Before writing anything, ask: when should this skill load?
Be concrete. Write down the exact phrases or situations that should trigger it. Examples:
- "When the user asks for a creative brief, kickoff doc, or project brief."
- "When the user uploads a CSV and wants tabular analysis."
- "When the user asks 'how do I rank for X', 'should I add schema', or anything SEO-related."
- "When the user mentions they want to pick a vendor or compare tools."
The trigger is your description's job. If you cannot articulate the trigger crisply, the skill will not load reliably.
### Phase 3: Write the description
This is the most important sentence (or two) in your skill. The description is what Claude sees in the system prompt to decide whether to load the skill.
Good descriptions have 4 parts:
1. **What it does** (one sentence, action-oriented).
2. **When to use it** (the trigger phrases or situations).
3. **Edge cases** with "Also triggers when..." (catches less obvious situations).
4. **Useful for...** (audience or use cases, helps disambiguation).
Bad description:
> "Helps with SEO."
Why it fails: vague, no trigger phrases, will not fire when the user actually needs it.
Good description:
> "Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, asks 'why is this page not ranking', or shares a URL and asks what is wrong with it. Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits."
Why it works: specific actions, multiple trigger phrases, edge cases, audience clarity.
### Phase 4: Structure the SKILL.md body
A consistent structure makes skills readable, maintainable, and AI-friendly. The pattern below works for most skills:
```
---
name: [your-skill-name]
description: [your description]
---
[One-sentence purpose statement]
## When to use
[Bulleted list of trigger situations]
## When NOT to use
[Bulleted list, ideally redirecting to sibling skills]
## Required inputs
[What Claude needs from the user to run this skill]
## The framework
[The durable IP: the model, the steps, the dimensions, the layers]
## Workflow
[Numbered steps Claude follows]
## Failure patterns
[Common mistakes to avoid or push back on]
## Output format
[What the deliverable looks like]
## Reference files
[List of files in the references/ folder with descriptions]
```
Not every skill needs every section. Some skills are pure how-to and skip "framework". Some skills are heavy on examples and add an "Examples" section. Use the structure as a starting point, adapt as needed.
### Phase 5: Add references for what does not belong in SKILL.md
References are the second tier of progressive disclosure. They load when Claude reads them, not by default.
Use references for:
- Long checklists (a 100-item audit checklist).
- Templates with worked examples.
- Detailed playbooks for specific scenarios.
- Reference material like spec links, glossaries, decision tables.
- Anything over 100 lines that not every invocation needs.
Each reference should be standalone. A reader (or Claude) should be able to use it without reading the SKILL.md first, given the context the skill provides.
Naming patterns that work:
- `references/[noun]-template.md` for templates.
- `references/[noun]-checklist.md` for checklists.
- `references/[noun]-playbook.md` for end-to-end runbooks.
- `references/example-[scenario].md` for worked examples.
Reference your reference files from the SKILL.md "Reference files" section with a one-line description of each.
### Phase 6: Test and iterate
Skills do not work the first time. Plan to iterate.
Testing checklist:
- [ ] Trigger test: in a fresh conversation, write the trigger phrase. Does the skill load? If not, the description is too narrow or wrong.
- [ ] Edge case test: write something that should trigger via the "Also triggers when..." clause. Does it fire?
- [ ] False positive test: write something close but not actually relevant. Does the skill avoid loading? If it always loads, your description is too broad.
- [ ] Output test: run the skill on a real task. Is the output what you expected?
- [ ] Length test: is the SKILL.md staying under 250 lines? Are references under 400 lines? If not, split or trim.
After testing, common fixes:
- Skill not triggering → broaden the description, add explicit phrases, add "Also triggers when..."
- Skill triggering too often → narrow the description, add "Do not trigger when...", be more specific about audience.
- Output is generic → add a clearer framework or workflow with more specifics.
- Reference is overwhelming → split into multiple references, keep each focused.
## Deep dive: description anatomy
The description is hard to get right. Here is the formula in detail.
### Sentence 1: What it does
Lead with the verb. Be specific.
- Good: "Audit on-page SEO."
- Bad: "Help with SEO things."
### Sentence 2: When to use it
State the primary triggers. Use phrases users would actually say.
- Good: "Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks 'why is this page not ranking'."
- Bad: "Use for SEO improvements."
### Sentence 3: "Also triggers when..."
Catch the secondary triggers and edge cases.
- Good: "Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup."
- Bad: (omitted)
### Sentence 4: Useful for...
Explain audience or scope to help with disambiguation.
- Good: "Useful for both individual page reviews and small-batch audits."
- Bad: (omitted)
If your skill description is one sentence, it is probably not specific enough.
## Deep dive: worked example
Imagine you keep writing technical post-mortem documents and want to skill-ify it.
**Step 1: Decide it's a skill.** You write 5+ post-mortems a year, output benefits from consistency, others on the team would use it. Yes, build a skill.
**Step 2: Trigger.** "When the user wants to write a post-mortem, retrospective, or after-action report. When an incident has happened and we are reviewing what went wrong."
**Step 3: Description.**
> "Write a structured post-mortem after an incident, outage, or significant project failure. Use when the user mentions post-mortem, retrospective, after-action report, RCA, or asks 'why did this go wrong' after an incident. Also triggers when the user wants to capture lessons learned from a launch, project miss, or incident debrief. Useful for technical incidents, project retros, and team learning reviews."
**Step 4: SKILL.md body.** Use the standard structure. Required inputs (timeline, impact, contributors). The framework (Five Whys, contributing factors, action items). Workflow (gather facts, draft, review, distribute). Failure patterns (blame, vague action items, no follow-up).
**Step 5: References.** A `post-mortem-template.md` with the document structure and a `facilitator-checklist.md` for running the post-mortem meeting.
**Step 6: Test.** Trigger on "we had an outage yesterday, can you help me write the post-mortem?" Should fire. Trigger on "what is a post-mortem?" Should probably also fire. Trigger on "let's review the quarter". Should not fire (this is a different kind of retro).
You iterate until the triggers fire correctly, then ship.
## Failure patterns
- **Description too narrow.** The skill never fires because your description requires exact phrases the user does not say.
- **Description too broad.** The skill fires constantly, including for unrelated tasks.
- **No trigger phrases.** The description describes what the skill does but not when to load it. Triggering is unreliable.
- **SKILL.md too long.** A 1,000-line SKILL.md defeats the purpose of progressive disclosure. Split into references.
- **References that duplicate SKILL.md.** If a reference repeats what the body says, prune one.
- **No "When NOT to use".** Skills that overlap with sibling skills get loaded ambiguously. Cross-reference siblings explicitly.
- **No examples.** A framework without a worked example is hard to apply. Include at least one in the reference material.
- **Optimizing for one example.** A skill written around your single use case fails at adjacent ones. Generalize.
- **No iteration.** Shipping a skill once and never revisiting it. Skills decay. Audit yearly.
- **Branding or product-specific assumptions in a public skill.** Skills meant to be general should not hardcode your stack. Public skills teach methodology (frameworks, decision criteria, taxonomies, anti-patterns); implementation specifics (specific page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. See [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md) for the full discipline and the user-outcome reasons it matters.
## Output format
When using this skill to create another skill, deliver:
1. **Trigger analysis**: a short list of phrases and situations that should fire the skill.
2. **Description draft**: the 2-4 sentence description for the YAML frontmatter.
3. **SKILL.md body**: the full body of the skill, following the standard structure.
4. **Reference plan**: a list of reference files to create with one-line descriptions.
5. **First reference file**: at least one reference written end to end as a starting point.
6. **Test plan**: 3-5 test prompts that should trigger the skill, plus 2-3 that should not.
## Reference files
- [`references/skill-template.md`](references/skill-template.md): A blank SKILL.md template with annotated section guidance, ready to copy and fill in.
- [`references/description-cookbook.md`](references/description-cookbook.md): A library of description patterns with worked examples for common skill types (audits, templates, frameworks, walkthroughs).
- [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md): What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. The audit pattern and the authoring checklist for keeping skills methodology-pure.
按说明文件中的顺序排列。
何时使用
何时不使用
所需的输入
框架:技能如何发挥作用
第 1 阶段:确定技能的形状是否正确
文件/命令 -> references/[noun]-template.md · references/[noun]-checklist.md · references/[noun]-playbook.md · references/example-[scenario].md · post-mortem-template.md · facilitator-checklist.md · references/methodology-vs-implementation.md · references/skill-template.md
内容校验值 -> 6719fcbd115d
当前原文的自动摘译,尚未人工审校。
何时使用
您发现自己重复写相同的提示或说明。您想要打包工作流程或框架以供重用。您现有的技能没有在应该触发的时候触发。您正在发布技能供其他人使用。您想教克劳德一种特定于领域的工作方式。
何时不使用
对于一次性提示(只需写下提示)。对于应该存在于系统上下文中的信息,而不是渐进式披露。用于更改 Claude 在所有对话中的一般行为(使用 Claude.ai 设置或系统提示,而不是技能)。用于替换工具调用(技能是指令,而不是工具)。
所需的输入
您要编码的任务或工作流程。观众:谁会在什么样的对话中触发这个技能。现有的工件:您使用过的提示、您编写的文档、良好输出的示例。
框架:技能如何发挥作用
技能是一个包含
SKILL.md文件的文件夹。 SKILL.md 具有 YAML frontmatter(名称和描述)和带有说明的正文。它还可以包括在需要时加载的参考文件、脚本或模板。关键属性:渐进式披露。克劳德并不是每回合都会读所有技能。技能描述位于系统提示符中。仅当技能被触发时,SKILL.md 正文和引用才会加载。这使得用户可以在不污染上下文的情况下拥有数百种技能。