技能大师

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

关于技能

技能是模块化、独立的包,通过提供专业知识、工作流程和工具来扩展 Claude 的能力。将它们视为特定领域或任务的“入门指南”——它们将 Claude 从通用智能体转变为配备了任何模型都无法完全拥有的程序知识的专业智能体。

提供什么技能

专业工作流程 - 针对特定领域的多步骤过程 工具集成 - 使用特定文件格式或 API 的说明 领域专业知识 - 公司特定的知识、模式、业务逻辑 捆绑资源 - 用于复杂和重复任务的脚本、参考和资产

技能类型

根据指导克劳德工作的方式,技能分为两种类型。

程序技巧

当任务需要严格的步骤顺序并且顺序很重要时使用。第 2 阶段取决于第 1 阶段的正确完成。跳过或重新排序步骤会破坏工作流程。示例:代码编写(计划 → TDD → 审查)、项目规划(面试 → 功能 → 路线图)、技术规范规划。这些技能有明确的阶段,每个阶段后都有检查点,以在继续之前验证完成情况。

信息技能

在没有严格执行顺序的情况下提供方法、知识或指南时使用。代理阅读相关章节并将其应用于实际情况。不存在“第一阶段必须在第二阶段之前完成”的情况——各部分是独立的。示例:安全审核员(检查什么)、测试(何时使用哪种测试类型)、公司信息(领域知识)、数据库模式。这些技能将内容组织成具有决策框架的逻辑部分(如果是/否),以帮助代理选择适用的内容。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@pavel-molyanov · 未声明许可证
上下文用量评级
较高消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Skill Creator

## About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

### What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

## Skill Types

There are two types of skills based on how they guide Claude's work.

### Procedural Skills

Use when the task requires a strict sequence of steps where order matters. Phase 2 depends on Phase 1 completing correctly. Skipping or reordering steps would break the workflow.

Examples: code-writing (Plan → TDD → Review), project-planning (Interview → Features → Roadmap), tech-spec-planning.

These skills have explicit phases with checkpoints after each phase to verify completion before proceeding.

**Creating a procedural skill?** Read [procedural-skills.md](references/procedural-skills.md) — phase structure, checkpoints, verification patterns.

### Informational Skills

Use when providing methodology, knowledge, or guidelines without a strict execution order. The agent reads relevant sections and applies them to the situation. There's no "Phase 1 must complete before Phase 2" — sections are independent.

Examples: security-auditor (what to check), testing (when to use which test type), company-info (domain knowledge), database-schemas.

These skills organize content into logical sections with decision frameworks (YES if / NO if) to help the agent choose what applies.

**Creating an informational skill?** Read [informational-skills.md](references/informational-skills.md) — section organization, knowledge structure.

## 1. Discovery

For new skills or major changes — run discovery interview:
- What problem does the skill solve?
- What phrases should trigger it?
- What should the skill NOT do?
- Concrete usage examples

**When running user interview**, read [interview-guide.md](references/interview-guide.md) — process overview, example questions for each phase, handling "I don't know" answers.

**Checkpoint:** Requirements gathered. Problem, triggers, scope, and examples documented.

## 2. Skill Structure

### Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

### Frontmatter

**`name`** (required):
- kebab-case (lowercase, hyphens)
- ≤64 characters
- Unique identifier

**`description`** (required):
- Third person ("Analyzes code...", NOT "I analyze...")
- Include both WHAT the skill does AND WHEN to use it
- ≤1024 characters

#### Description Best Practices

Claude uses description to decide when to auto-invoke the skill. Be specific and include key terms.

**Template:**
```yaml
description: |
  [What the skill does — be specific, include key terms]

  Use when: [trigger conditions — specific phrases users say]
```

**Rules:**
1. **Be specific** — Include key terms that match user requests
2. **List trigger phrases** — Real phrases users actually say (5-10 phrases)
3. **Include variations** — "техспек" AND "составь тз" (different ways to say same thing)

**Bad:**
```yaml
description: This skill helps with documents. Use when user wants to work with docs.
```
Why bad: Vague phrases ("work with docs"), no specific triggers.

**Good:**
```yaml
description: |
  Manage .claude/skills/project-knowledge/ docs: create, check, update.

  Use when: "заполни документацию", "создай документацию", "проверь документацию", "обнови документацию"
```
Why good: Specific actions, concrete trigger phrases.

**How to gather trigger phrases:**
1. Think: "What would I actually say to invoke this skill?"
2. Ask: "How would different users phrase this request?"
3. Include: Common typos, informal variants, both Russian and English if applicable

#### Undertriggering Problem

Claude tends to undertrigger skills — not use them when they'd be useful. To combat this, make descriptions slightly "pushy": explicitly list contexts and keywords that should activate the skill, even non-obvious ones.

**Instead of:**
```yaml
description: How to build a dashboard to display data.
```

**Write:**
```yaml
description: |
  How to build a dashboard to display data. Use this skill whenever
  the user mentions dashboards, data visualization, internal metrics,
  or wants to display any kind of data, even if they don't explicitly
  ask for a "dashboard".
```

**Need argument-hint, disable-model-invocation, or model override?** Read [frontmatter-options.md](references/frontmatter-options.md) — optional fields and when to use each.

### Body

Every SKILL.md body consists of:
- **Core workflow** — main instructions that are always needed
- **Links to references** — for optional/detailed information
- Keep under 500 lines (otherwise → split to references)

**When defining output format**, read [output-patterns.md](references/output-patterns.md) — template pattern, examples pattern.

**Checkpoint:** SKILL.md created with frontmatter, body, and references. Skill structure complete.

### Bundled Resources

A skill contains only SKILL.md and these three optional directories — nothing else (no README, CHANGELOG, etc.).

#### Scripts (`scripts/`)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments

**Concrete example:** When building a `pdf-editor` skill for queries like "Help me rotate this PDF":
1. Rotating a PDF requires re-writing the same code each time
2. A `scripts/rotate_pdf.py` script solves this — write once, execute many times

**How to spot script candidates:** After running test cases, read the transcripts. If all test runs independently wrote similar helper code (e.g., each created a `create_docx.py`), that's a strong signal to bundle that script. Write once, use on every invocation.

#### References (`references/`)

Content needed in some execution paths, not all. If the skill branches (multiple operations, domains, modes) — each branch's details go to a reference. Content needed on every execution stays in SKILL.md.

**Example:** Task-management skill handles "create" and "edit". Each operation's workflow → separate reference. Task file format used by both → stays in SKILL.md.

- **No duplication**: Content lives in either SKILL.md or references, not both

**How to link references in SKILL.md:**

Embed references in workflow where they're logically needed. Two linking patterns, ranked by strength:

**Pattern A: Action-embedded (strong)** — the workflow step's action IS applying the reference content. The agent cannot complete the step without loading the file.

```markdown
3. Write tests following patterns from [testing-guide.md](references/testing-guide.md)
   (test structure, naming, what to skip)

4. Apply audit criteria from [principles.md](references/principles.md) to each file
   (code examples, obvious content, generic explanations)
```

Why it works: "follow patterns from X" or "apply criteria from X" makes the reference part of the action, not a separate read-then-do instruction.

**Pattern B: Condition + contents (basic)** — for optional references needed only in specific scenarios. Each link explains WHEN to read and WHAT's inside.

```markdown
**For tracked changes**, see [REDLINING.md] — revision marks, accept/reject.
**First time with docx-js?** Read [DOCX-JS.md] — setup, examples, pitfalls.
```

Use Pattern A for references that contain rules/patterns the agent must follow during a step. Use Pattern B for references that are only relevant in certain branches of the workflow.

**Anti-pattern: Resource catalog at end of file.** A passive list of references separated from the workflow. The agent reads the workflow top-down, gets instructions, and treats the catalog as optional appendix.

```markdown
❌ Bad — passive catalog (ignored):
## Resources
### references/structure.md
Complete description of all files...
### references/principles.md
Quality principles...

✅ Good — embed each reference into the workflow step where it's needed:
4. Apply audit criteria from [principles.md](references/principles.md) to each file
```

**Bad** (passive, no trigger):
- `Detailed guide: [X.md]`
- `See [X.md] for details`
- `Finance: [finance.md]` (no context why to read)

**Good** (embedded in action or conditional):
- `3. Write tests following patterns from [testing-guide.md]` (action-embedded)
- `**Working with finance?** Read [finance.md] — P&L rules, ARR formulas` (conditional)
- `4. Apply criteria from [principles.md] to each file` (action-embedded)

#### Assets (`assets/`)

Files not intended to be loaded into context, but rather used within the output Claude produces.

- **When to include**: When the skill needs files that will be used in the final output
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate
- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context

**Concrete example:** When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app":
1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An `assets/hello-world/` template with boilerplate project files solves this — copy and customize

## 3. Writing Guidelines

### Concise is Key

The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.

**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

### Keep it Lean

Remove things that aren't pulling their weight. After running test cases, read the transcripts — not just the final outputs. If the skill is making the model waste time doing unproductive things, remove those parts of the skill.

Every instruction has a cost. If removing an instruction doesn't degrade results, it was dead weight.

### Generalize, Don't Overfit

Skills are used across many different prompts and contexts. When iterating on a skill based on test results, resist fiddly changes targeted at specific examples. Rather than oppressively constrictive rules, try branching out — use different metaphors, recommend different patterns of working. It's cheap to try and you might land on something better.

If a skill works only for its test cases, it's useless at scale.

### Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.

**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.

**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.

Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

### Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

1. **Metadata (name + description)** — Always in context (~100 words)
2. **SKILL.md body** — When skill triggers (<5k words)
3. **Bundled resources** — As needed by Claude (unlimited, scripts execute without reading)

Keep SKILL.md body under 500 lines. Split content into separate files when approaching this limit. When splitting, reference them from SKILL.md and describe clearly when to read them.

**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details into separate reference files.

**Pattern 1: High-level guide with references**

```markdown
# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features

**For form filling?** Read [FORMS.md](FORMS.md) — interactive fields, validation, PDF/A.

For complete API reference, see [REFERENCE.md](REFERENCE.md) — all methods with examples.
```

Claude loads FORMS.md or REFERENCE.md only when needed.

**Pattern 2: Domain-specific organization**

For skills with multiple domains, organize content by domain:

```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    └── product.md (API usage, features)
```

In SKILL.md, link each domain with description:

**When working with finance data**, read [finance.md](references/finance.md) — P&L rules, revenue calculations, ARR formulas.

For sales data analysis, see [sales.md](references/sales.md) — opportunity stages, pipeline calculations, account hierarchies.

**Working with product metrics?** Read [product.md](references/product.md) — API usage tracking, feature adoption, user segments.

**Pattern 3: Conditional details**

```markdown
# DOCX Processing

## Creating documents
Use docx-js for basic operations.

**First time with docx-js?** Read [DOCX-JS.md](DOCX-JS.md) — setup, examples, pitfalls.

## Editing documents
For simple edits, modify XML directly.

For tracked changes, see [REDLINING.md](REDLINING.md) — revision marks, accept/reject logic.
```

**Important guidelines:**
- Keep references one level deep from SKILL.md
- For files longer than 100 lines, include a table of contents at the top

### Writing Approach

Start by writing a draft, then look at it with fresh eyes and improve. Use theory of mind — make the skill general, not super-narrow to specific examples. Try to explain to the model why things are important in lieu of heavy-handed constraints.

### Positive over Negative

Default to positive instructions — they're followed more reliably. Rewrite negatives when the positive form fully conveys the meaning.

**Rewrite when positive form is sufficient:**
- "Don't use bullet points" → "Write in prose paragraphs"
- "Don't use var" → "Use const/let"

**Keep negatives for hard boundaries** where the positive rewrite loses the prohibition:
- Security: "Store secrets in .env" alone doesn't convey "never commit them to git" — you need both
- Irreversible damage: "Don't use `--force` on shared branches" — the cost of violation is high
- Disambiguation: "Use `Array.from()`, not spread for NodeList" — negative clarifies which similar option is wrong
- Scope limits: "This skill does not handle deployment" — defines boundary

**Test:** "Does the positive rewrite fully convey the prohibition?" If no → keep the negative + add motivation (WHY it matters).

### Explain the Why

Today's LLMs are smart. They have good theory of mind and when given a good harness can go beyond rote instructions. Try to explain the **why** behind everything you're asking the model to do. Even if user feedback is terse, try to actually understand the task and why the user wrote what they wrote, then transmit this understanding into the instructions.

**Bad:** "Always return JSON format."
**Good:** "Return findings as JSON — orchestrator parses this automatically, invalid JSON crashes pipeline."

When explaining is impractical, keep the rule as-is. But default to reasoning over commanding.

### Avoid Emphasis Words

Words like CRITICAL, MANDATORY, NEVER, IMPORTANT, MUST are anti-patterns in skills.

**Why they don't work:**
- Every instruction in a skill is already important — if it wasn't, it shouldn't be there
- When everything is emphasized — nothing stands out
- Emphasis words signal poorly written instructions that need rewriting, not shouting

**What to do instead:**
- Write clear, specific instructions
- Explain why something matters (see "Explain the Why" above)
- Use structure (steps, checkpoints) to ensure compliance

If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag — reframe and explain the reasoning so that the model understands why the thing you're asking for is important.

**Hard limit:** Maximum one emphasis word per skill. Ideal: zero.

### Delegating Heavy Work

If skill has context-heavy tasks (reviews, research, validation):
- Keep each skill focused on a single methodology
- Delegate heavy subtasks to agents with fresh context
- Orchestrator calls agents → they work isolated → return results

**When to use subagents:**
- **Reviews** — code-reviewer, security-auditor, test-reviewer check work with fresh context
- **Research** — exploring codebase, reading documentation, searching information
- **Debugging** — isolated context for error diagnosis and root cause analysis
- **Validation** — checking schemas, formats, requirements compliance
- **Parallel tasks** — multiple independent investigations simultaneously
- **High-volume output** — tests, logs, reports that would bloat main context

**Two approaches:**

1. **Inline prompts** — for simple, one-off tasks (<50 lines):
   ```
   Use general-purpose/explore/plan subagent to find all TypeScript files importing {module}
   ```

2. **Skill + Agent pattern** — for complex, reusable tasks (>50 lines):
   - **Skill** holds methodology (WHAT to do, HOW to analyze)
   - **Agent** adds isolation + output format (runs in isolated context)
   - Agent uses `skills:` field to preload methodology
   - Reference by name: "Use `code-reviewer` agent"

**Key principle:** Keep detailed agent prompts out of SKILL.md. Large prompts bloat the skill and waste context. Store specialized agent definitions separately; the skill just invokes them.

**Delegating work to subagent?** Read [agents.md](references/agents.md) — inline prompts, dedicated agents, output contracts.

**Checkpoint:** Writing guidelines applied. Skill is concise, well-structured, references linked properly.

## 4. Validation

### Run skill-checker

After self-check — run validation:

```
Use skill-checker subagent to validate the skill at {path}.
If issues found → fix them → run skill-checker again.
```

skill-checker is defined in `~/.claude/agents/skill-checker.md` and has skill-master preloaded.

### Test the Skill

After creating or significantly updating a skill, suggest to the user to run skill-tester on it. skill-tester will design test cases, run them with and without the skill, test description triggering accuracy, and produce a report with specific improvement recommendations.

### Self-Check Before Validation

**Universal (all skills):**
- [ ] name in kebab-case, ≤64 chars
- [ ] description < 1024 chars, includes "Use when:" with trigger phrases
- [ ] SKILL.md < 500 lines
- [ ] All referenced files exist
- [ ] No extra docs (README, CHANGELOG)
- [ ] References contain only conditional content (not needed on every execution path)
- [ ] References linked as action steps or with condition + contents (no passive links, no resource catalogs at end of file)
- [ ] Defaults to positive instructions. Negatives only for hard boundaries (security, irreversible damage, disambiguation, scope limits) with motivation
- [ ] No emphasis words (CRITICAL, MANDATORY, NEVER) — max one allowed

**Identify skill type:** procedural or informational?

**If Procedural:**
- [ ] Has explicit phases with numbered steps
- [ ] Has checkpoints after each phase
- [ ] Has self-verification section at end
- [ ] Uses subagent verification for critical operations (if applicable)

**If Informational:**
- [ ] Sections organized by logic, not sequence
- [ ] Decision frameworks present (YES if / NO if) where applicable
- [ ] No forced sequential structure

**Functional (all skills):**
- [ ] Run skill-checker and fix all issues

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。