skill-best-practices

# Workflow Patterns for Skills

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

## Choosing: Problem-first vs. Tool-first

- **Problem-first:** User describes an outcome → skill orchestrates the right MCP calls in sequence
- **Tool-first:** User has MCP access → skill teaches optimal workflows and best practices

## Pattern 1: Sequential Workflow Orchestration

Use when: Users need multi-step processes in a specific order.

```
## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)
```

Key techniques:

- Explicit step ordering with numbered steps
- Document dependencies between steps
- Validation gate at each stage
- Rollback instructions for failures

## Pattern 2: Multi-MCP Coordination

Use when: Workflows span multiple services.

```
### Phase 1: Design Export (Figma MCP)
1. Export design assets
2. Generate design specifications

### Phase 2: Asset Storage (Drive MCP)
1. Create project folder
2. Upload all assets

### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links
```

Key techniques:

- Clear phase separation per service
- Explicit data passing between MCPs
- Validation before moving to next phase
- Centralized error handling section

## Pattern 3: Iterative Refinement

Use when: Output quality improves with iteration.

```
### Initial Draft
1. Fetch data via MCP
2. Generate first draft

### Quality Check
1. Run validation: `scripts/check_report.py`
2. Identify issues: missing sections, formatting errors

### Refinement Loop
1. Fix each issue
2. Re-validate
3. Repeat until quality threshold met
```

Key techniques:

- Explicit quality criteria (not "good enough")
- Validation scripts for deterministic checks
- Define the stop condition clearly

## Pattern 4: Context-Aware Tool Selection

Use when: Same outcome, different tools depending on context.

```
### Decision Tree
1. Check file type and size
2. Determine storage:
   - Large files (>10MB): cloud storage MCP
   - Collaborative docs: Notion/Docs MCP
   - Code files: GitHub MCP

### Execute
- Call appropriate MCP tool
- Explain choice to user
```

Key techniques:

- Explicit decision criteria
- Fallback options for each branch
- Transparency about which tool was chosen and why

## Pattern 5: Domain-Specific Intelligence

Use when: Skill adds specialized knowledge beyond tool access.

```
### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
3. Document compliance decision

### Processing
IF compliance passed → call payment MCP tool
ELSE → flag for review, create compliance case

### Audit Trail
- Log all checks
- Record decisions
- Generate audit report
```

Key techniques:

- Embed domain rules in explicit logic (IF/ELSE, not vague language)
- Compliance/validation before action
- Comprehensive audit documentation
- Clear governance (who reviews flagged cases)

#!/usr/bin/env bash
# Validate SKILL.md frontmatter for npx skills CLI compatibility.
#
# Usage:
#   bash validate-skills.sh           # local YAML check only
#   bash validate-skills.sh --remote  # local check + npx skills add --list
#
# Exit codes: 0 = all ok, 1 = errors found

set -euo pipefail

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SKILLS_DIR="$REPO_ROOT/.claude/skills"
REMOTE=false
errors=0

[[ "${1:-}" == "--remote" ]] && REMOTE=true

frontmatter() { awk '/^---$/{n++; if(n==2)exit; next} n==1{print}' "$1"; }

for skill_md in "$SKILLS_DIR"/*/SKILL.md; do
    [[ -f "$skill_md" ]] || continue
    skill="$(basename "$(dirname "$skill_md")")"
    fm="$(frontmatter "$skill_md")"
    fail=false

    output="$(printf '%s' "$fm" | python3 -c '
import sys, yaml
content = sys.stdin.read()
try:
    data = yaml.safe_load(content) or {}
except yaml.YAMLError as e:
    print(str(e).replace(chr(10), " "))
    sys.exit(1)
name = data.get("name", "")
desc = str(data.get("description", ""))
if not name:
    print("missing required field: name")
    sys.exit(1)
if not desc:
    print("missing required field: description")
    sys.exit(1)
if len(desc) > 1024:
    print("WARN description is " + str(len(desc)) + " chars (limit: 1024)")
' 2>&1)" || {
        echo "FAIL  $skill — $output"
        fail=true
        errors=$((errors + 1))
    }

    if ! $fail; then
        while IFS= read -r line; do
            [[ "$line" == WARN* ]] && echo "WARN  $skill — ${line#WARN }"
        done <<< "$output"
        echo "OK    $skill"
    fi
done

echo ""
[[ $errors -eq 0 ]] && echo "Local: all skills valid" || echo "Local: $errors error(s) found"

if $REMOTE; then
    REPO_URL="$(git -C "$REPO_ROOT" remote get-url origin 2>/dev/null || true)"
    [[ -z "$REPO_URL" ]] && { echo "error: no git remote 'origin' found" >&2; exit 1; }
    echo ""
    echo "Remote: npx skills add --list $REPO_URL"
    echo ""
    _tmp="$(mktemp -d)"
    trap 'rm -rf "$_tmp"' EXIT
    TMPDIR="$_tmp" npm_config_cache="$_tmp/cache" \
        npx --yes --package=skills skills add --list "$REPO_URL" 2>&1 \
        | sed 's/\x1b\[[0-9;]*[mGJhls?]//g; s/\r//g' \
        | grep -E "(Skipped|Found [0-9]|Available Skills|  [a-z])" || true
fi

exit $((errors > 0))

---
name: skill-best-practices
description: "Guide for creating, structuring, and improving Claude skills (SKILL.md). Use when building a new skill, reviewing an existing skill, writing SKILL.md frontmatter, defining trigger conditions, troubleshooting skill problems (not triggering, over-triggering, instructions not followed), or planning skill distribution. When working on any skill in this repository: also load the cc-best-practices skill, and always update both CLAUDE.md and README.md skill tables after any skill change. Do NOT use for general Claude Code configuration or hook setup."
---

---

# 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