---
id: gh-skill-best-practices
name: "skill-best-practices"
url: https://skills.yangsir.net/skill/gh-skill-best-practices
author: dboeckli
domain: ai-skill-platform-ecosystem
tags: ["skill-development", "skill-standardization", "documentation", "ai-agent", "developer-tools"]
install_count: 6500
rating: 4.50 (120 reviews)
github: https://github.com/dboeckli/ai-agent-skills/tree/master/.claude/skills/skill-best-practices
---

# skill-best-practices

> 指导创建、结构化与改进 AI 技能（SKILL.md）的规范型技能：涵盖用例分类、目录与 frontmatter 编写、触发描述设计、正文模板、YAML 与 CLI 校验以及触发测试迭代。当开发者新建技能、评审既有技能或排查「不触发／过度触发／指令被忽略」等问题时，此技能能显著缩短调试周期并提升技能质量。

**Stats**: 6,500 installs · 4.5/5 (120 reviews)

## Before / After 对比

### 触发调试从反复试错到一次成型

**Before**:

没有规范指引时，开发者只能凭感觉写 description，技能经常不触发或误触发，需要反复修改措辞、来回测试十几次，仍不确定何时才算稳定。

**After**:

该 Skill 给出 WHAT+WHEN 描述模板、负向触发词写法与 10–20 条测试查询的验收标准，把触发调试变成可度量的流程，一次迭代即可达到稳定触发。

| Metric | Before | After | Change |
|---|---|---|---|
| 触发调试耗时 | 90分钟 | 15分钟 | -83% |
| 描述改写轮次 | 8轮 | 2轮 | -75% |
| 相关查询触发率 | 55% | 92% | +37% |

### SKILL.md 结构校验从人工猜测到脚本把关

**Before**:

目录名、文件名大小写、frontmatter 的块标量写法、子键缩进等细节容易踩坑，提交后才发现命令行工具识别不到，只能回头逐项排查。

**After**:

此技能提供统一的正文模板与本地／远程校验脚本，先校验再提交，把格式类问题挡在提交之前，技能可被正确列出与加载。

| Metric | Before | After | Change |
|---|---|---|---|
| 格式校验失败率 | 40% | 5% | -88% |
| 排查格式问题耗时 | 45分钟 | 8分钟 | -82% |
| 技能被正确识别比例 | 70% | 98% | +40% |

### 技能评审有据可依

**Before**:

评审一个既有技能时缺乏统一尺度，只能凭印象说「感觉不太清楚」，反馈零散且难以落地，评审与修改之间来回拉扯。

**After**:

该 Skill 按 PASS／WARN／FAIL 逐项检查名称、描述长度、正文长度、示例与排错章节，输出可直接执行的改进清单，评审一次到位。

| Metric | Before | After | Change |
|---|---|---|---|
| 单次评审耗时 | 60分钟 | 15分钟 | -75% |
| 可落地改进项比例 | 45% | 90% | +100% |
| 评审返工次数 | 3次 | 1次 | -67% |

## Readme

---

# Skill Best Practices

Reference: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

## Instructions

### Step 1: Identify your use case category

Determine which type of skill you're building:

- **Document & Asset Creation** — consistent output (docs, designs, code)
- **Workflow Automation** — multi-step processes with consistent methodology
- **MCP Enhancement** — workflow guidance on top of MCP tool access

Define 2–3 concrete use cases before writing anything (see Planning section below).

### Step 2: Create the folder and SKILL.md

- Name the folder in kebab-case (e.g. `my-skill-name`)
- Create exactly `SKILL.md` (case-sensitive) inside it
- Write YAML frontmatter with `name` and `description` (see Technical requirements)

### Step 3: Write the description — this is the most critical part

The description controls when Claude loads your skill. It must include:

- **WHAT** the skill does
- **WHEN** to use it (specific trigger phrases)
- Optional: negative triggers ("Do NOT use for...")

See "Writing effective descriptions" for good/bad examples.

### Step 4: Write the body instructions

Follow the recommended template: `## Instructions` → numbered steps → `## Examples` → `## Troubleshooting`.
Be specific and actionable. Move detailed docs to `references/` and link to them.

### Step 5: Update CLAUDE.md and README.md

After creating or modifying any skill in this repository, always update the skill tables in both files:

- `CLAUDE.md` — skill table under "Included Skills" (Trigger column: one-line description of when it fires)
- `README.md` — skill table under "Enthaltene Skills" (Beschreibung column: German one-liner)

Both files must stay in sync. This step is mandatory and must not be skipped.

Also invoke the `cc-best-practices` skill when working on skills in this repository to ensure context and session management follow project standards.

### Step 6: Validate YAML and skills CLI compatibility

Run the validation script from the repository root before testing or committing:

```bash
bash .claude/skills/skill-best-practices/scripts/validate-skills.sh
```

Fix any `FAIL` lines before continuing. Common issues:

- `description` uses block scalar (`>` or `|`) → replace with a quoted single-line string
- Sub-keys under a parent mapping key not indented → add two-space indent

After pushing, also run the remote check to confirm `npx skills add --list` finds all skills:

```bash
bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote
```

### Step 7: Test triggering and functional behavior

Run 10–20 test queries. Target: skill triggers on ~90% of relevant queries and never on unrelated topics.
Iterate on the description until triggering is reliable (see Testing approach).

### Step 7: Iterate based on signals

- Undertriggering → add more trigger phrases to description
- Overtriggering → add negative triggers, narrow scope
- Instructions ignored → move critical steps to top, use explicit language

---

## Examples

### Example 1: Building a new skill from scratch

User says: "Help me create a skill that plans sprints in Linear"

Actions:

1. Identify category: Workflow Automation + MCP Enhancement
2. Define use case: trigger = "plan sprint", "create sprint tasks"; steps = fetch Linear status → analyze velocity → create tasks
3. Create folder `linear-sprint-planner/SKILL.md`
4. Write description: "Manages Linear sprint planning workflows. Use when user says 'plan sprint', 'create sprint tasks', or 'set up iteration'."
5. Write step-by-step instructions with Linear MCP tool calls
6. Test with 10 trigger phrases; adjust description if skill doesn't auto-load

Result: Functional skill that auto-triggers on sprint planning requests and executes the full workflow without user re-explaining the steps each time.

### Example 2: Reviewing an existing skill

User says: "Review my SKILL.md and suggest improvements"

Actions:

1. Read the SKILL.md frontmatter — check name (kebab-case?), description (WHAT + WHEN? under 1024 chars? trigger phrases present?)
2. Check body — is it under 5,000 words? Are instructions specific and actionable? Is there a Troubleshooting section? Examples?
3. Simulate triggering — would the description cause Claude to load this skill for the right queries?
4. Report findings as: PASS / WARN / FAIL per criterion

Result: Prioritized list of improvements with specific fixes for each issue.

### Example 3: Troubleshooting a skill that doesn't trigger

User says: "My skill never loads automatically, I always have to invoke it manually"

Actions:

1. Read the description field — is it too generic? ("Helps with projects" won't work)
2. Check for missing trigger phrases — does it include words users would actually say?
3. Ask Claude: "When would you use the [skill name] skill?" — Claude quotes the description back; gaps become obvious
4. Rewrite description to add specific trigger phrases and retest

Result: Updated description with concrete triggers; skill auto-loads on relevant queries.

---

## What is a skill?

A skill is a folder containing:

- `SKILL.md` (required): Instructions in Markdown with YAML frontmatter
- `scripts/` (optional): Executable code (Python, Bash, etc.)
- `references/` (optional): Documentation loaded as needed
- `assets/` (optional): Templates, fonts, icons used in output

## Core design principles

**Progressive Disclosure** — three levels:

1. YAML frontmatter: always in system prompt; tells Claude _when_ to load the skill
2. SKILL.md body: loaded when relevant; full instructions
3. Linked files in `references/`: loaded on demand

**Composability** — skills work alongside others; don't assume exclusivity.

**Portability** — works identically across Claude.ai, Claude Code, and API.

---

## Planning: Start with use cases

Before writing, define 2–3 concrete use cases:

```
Use Case: <name>
Trigger: User says "<phrase>" or "<phrase>"
Steps:
  1. ...
  2. ...
Result: <expected outcome>
```

Ask yourself:

- What does the user want to accomplish?
- What multi-step workflow is required?
- Which tools are needed (built-in or MCP)?
- What domain knowledge should be embedded?

### Three skill categories

| Category                      | When to use                                           | Key techniques                                      |
| ----------------------------- | ----------------------------------------------------- | --------------------------------------------------- |
| **Document & Asset Creation** | Consistent, high-quality output (docs, designs, code) | Style guides, templates, quality checklists         |
| **Workflow Automation**       | Multi-step processes with consistent methodology      | Step-by-step with validation gates, iterative loops |
| **MCP Enhancement**           | Workflow guidance on top of MCP tool access           | Sequential MCP calls, embedded domain expertise     |

---

## Technical requirements

### File & folder naming

- Folder: **kebab-case** only (`notion-project-setup`) — no spaces, underscores, or capitals
- File: exactly **`SKILL.md`** (case-sensitive) — no variations
- No `README.md` inside the skill folder (put docs in `SKILL.md` or `references/`)

### YAML frontmatter

Minimal required format:

```yaml
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---
```

**`name`** (required):

- kebab-case, no spaces or capitals
- Must match folder name

**`description`** (required):

- MUST include BOTH: what the skill does AND when to use it (trigger conditions)
- Under 1024 characters
- No XML tags (`<` or `>`)
- Include specific trigger phrases users would actually say
- Mention file types if relevant

**Optional fields:**

```yaml
license: MIT
compatibility: "Requires Python 3.10+"
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name
```

**Security restrictions — forbidden in frontmatter:**

- XML angle brackets (`< >`)
- Names containing "claude" or "anthropic" (reserved)

---

## Writing effective descriptions

Structure: `[What it does] + [When to use it] + [Key capabilities]`

**Good examples:**

```yaml
# Specific and actionable
description: Analyzes Figma design files and generates developer handoff docs.
  Use when user uploads .fig files, asks for "design specs", "component
  documentation", or "design-to-code handoff".

# Includes trigger phrases
description: Manages Linear project workflows including sprint planning and
  task creation. Use when user mentions "sprint", "Linear tasks", or asks
  to "create tickets".
```

**Bad examples:**

```yaml
# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.
```

---

## Writing instructions (SKILL.md body)

Recommended structure:

```markdown
# Your Skill Name

## Instructions

### Step 1: [First Major Step]

Clear explanation of what happens.

### Step 2: ...

## Examples

### Example 1: [Common scenario]

User says: "..."
Actions:

1. ...
   Result: ...

## Troubleshooting

### Error: [Common error message]

**Cause:** Why it happens
**Solution:** How to fix
```

### Best practices for instructions

**Be specific and actionable:**

```
# Good
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues:
- Missing required fields (add to CSV)
- Invalid date formats (use YYYY-MM-DD)

# Bad
Validate the data before proceeding.
```

**Include error handling** — document common errors with cause and solution.

**Reference bundled resources clearly:**

```
Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
```

**Use progressive disclosure** — keep SKILL.md focused on core instructions; move detailed docs to `references/` and link to them. Keep SKILL.md under 5,000 words.

**For critical validations**, prefer a bundled script over language instructions — code is deterministic, language interpretation isn't.

---

## Testing approach

### 1. Triggering tests

Run 10–20 queries. Skill should trigger on ~90% of relevant queries and NOT trigger on unrelated topics.

```
Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"

Should NOT trigger:
- "What's the weather?"
- "Help me write Python code"
```

**Debugging:** Ask Claude "When would you use the [skill name] skill?" — it will quote the description back.

### 2. Functional tests

- Valid outputs generated
- API calls succeed
- Error handling works
- Edge cases covered

### 3. Performance comparison

Compare token count, tool calls, and back-and-forth messages with vs. without the skill.

**Pro tip:** Iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill.

---

## Troubleshooting

### Skill won't upload

| Error                     | Cause                      | Fix                                |
| ------------------------- | -------------------------- | ---------------------------------- |
| "Could not find SKILL.md" | Wrong filename             | Rename exactly to `SKILL.md`       |
| "Invalid frontmatter"     | YAML formatting            | Add `---` delimiters, close quotes |
| "Invalid skill name"      | Spaces or capitals in name | Use kebab-case                     |

### Skill doesn't trigger (undertriggering)

- Description too generic
- Missing trigger phrases users actually say
- Missing relevant file type mentions

**Fix:** Add more specific keywords and phrases to the description.

### Skill triggers too often (overtriggering)

Add negative triggers and narrow the scope:

```yaml
description: Advanced data analysis for CSV files. Use for statistical modeling,
  regression, clustering. Do NOT use for simple data exploration.
```

### Instructions not followed

1. **Too verbose** — keep concise, use bullet points, move details to `references/`
2. **Instructions buried** — put critical instructions at top, use `## Critical` headers
3. **Ambiguous language** — be explicit: "CRITICAL: Before calling X, verify: ..."
4. **Model laziness** — add to user prompts (more effective than SKILL.md): "Take your time, quality over speed, do not skip validation steps"

### Large context / slow responses

- Move detailed docs to `references/`
- Keep SKILL.md under 5,000 words
- Reduce simultaneous enabled skills (evaluate if you have more than 20–50)

---

## Workflow patterns

Five patterns cover most skill types: Sequential orchestration, Multi-MCP coordination, Iterative refinement, Context-aware tool selection, and Domain-specific intelligence.

For detailed examples and implementation templates for each pattern, consult `references/patterns.md`.

---

## Quick checklist

**Before you start:**

- [ ] Identified 2–3 concrete use cases
- [ ] Tools identified (built-in or MCP)
- [ ] Planned folder structure

**During development:**

- [ ] Folder named in kebab-case
- [ ] `SKILL.md` exists (exact spelling, case-sensitive)
- [ ] YAML frontmatter has `---` delimiters
- [ ] `name`: kebab-case, no spaces, no capitals
- [ ] `description` includes WHAT and WHEN
- [ ] No XML tags (`< >`) anywhere
- [ ] Instructions clear and actionable
- [ ] Error handling included
- [ ] Examples provided
- [ ] References clearly linked

**Repository sync (mandatory for this repo):**

- [ ] `CLAUDE.md` skill table updated
- [ ] `README.md` skill table updated
- [ ] `cc-best-practices` skill was loaded during this session
- [ ] `validate-skills.sh` run — no `FAIL` lines
- [ ] After push: `validate-skills.sh --remote` run — all skills found by `npx skills`

**Before upload:**

- [ ] Triggers on obvious tasks
- [ ] Triggers on paraphrased requests
- [ ] Does NOT trigger on unrelated topics
- [ ] Functional tests pass

**After upload:**

- [ ] Test in real conversations
- [ ] Monitor for under/over-triggering
- [ ] Iterate on description and instructions


---
*Source: https://skills.yangsir.net/skill/gh-skill-best-practices*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-skill-best-practices/markdown*