Skill Authoring

AI Agent Skills Best Practices

Design and development guide for AI agent skills, including Claude Code skills and MCP tools. Contains 46 rules across 8 categories, prioritized by impact to guide skill creation, review, and optimization.

When to Apply

• Creating new Claude Code skills or MCP tools
• Writing or reviewing SKILL.md metadata and descriptions
• Optimizing skill trigger reliability
• Structuring content for progressive disclosure
• Testing skill activation and behavior
• Designing tool interfaces for agent workflows

Core Principles

1. Descriptions drive activation. Claude selects skills based on description matching against user intent. Include specific capabilities, trigger keywords, and negative cases. A skill with a vague description activates inconsistently or never.

2. Front-load critical instructions. Claude may truncate long content. Place non-negotiable rules in the first 100 lines. Bury important constraints at the end and they get ignored.

3. Progressive disclosure saves tokens. Load detailed content only when needed. A 2000-line skill wastes context on every activation. Structure as: SKILL.md (overview) → references/ (details) → scripts/ (execution).

4. Test activation, not just execution. A skill that works perfectly but never triggers provides zero value. Test with real user phrases, synonyms, and edge cases before deployment.

5. One skill per domain. Overlapping skills create activation conflicts. Split by clear boundaries (language, framework, workflow stage) with distinct trigger keywords.

Rule Categories

Quick Reference

1. Skill Metadata Design (CRITICAL)

• meta-name-format - Use lowercase hyphenated skill names
• meta-name-hyphen-boundaries - Never start or end names with hyphens
• meta-name-no-consecutive-hyphens - Avoid consecutive hyphens in names
• meta-name-uniqueness - Ensure skill names are globally unique
• meta-required-frontmatter - Include all required frontmatter fields
• meta-allowed-frontmatter-fields - Use only allowed frontmatter fields
• meta-frontmatter-yaml-syntax - Use valid YAML frontmatter syntax
• meta-name-length - Keep skill names under 64 characters
• meta-directory-match - Match skill name to directory name

2. Description Engineering (CRITICAL)

• desc-specific-capabilities - Name specific capabilities in description
• desc-trigger-keywords - Include user trigger keywords in description
• desc-third-person-voice - Write descriptions in third person
• desc-length-optimization - Optimize description length for discovery
• desc-avoid-vague-terms - Avoid vague terms in descriptions
• desc-differentiate-similar-skills - Differentiate similar skills with distinct triggers
• desc-include-negative-cases - Include negative cases for precision

3. Content Structure (HIGH)

• struct-header-hierarchy - Use consistent header hierarchy
• struct-instructions-first - Put critical instructions early in content
• struct-imperative-instructions - Write instructions in imperative mood
• struct-code-blocks-with-language - Specify language in code blocks
• struct-line-limit - Keep SKILL.md under 500 lines
• struct-single-responsibility - One skill per domain
• project-conventions - Preserve repository-specific skill conventions

4. Trigger Optimization (HIGH)

• trigger-slash-command-aliases - Include slash command aliases in description
• trigger-file-type-patterns - Include file type patterns in description
• trigger-workflow-stages - Reference workflow stages in description
• trigger-error-patterns - Include error patterns in debugging skills
• trigger-synonym-coverage - Cover synonyms and alternate phrasings

5. Progressive Disclosure (MEDIUM-HIGH)

• prog-three-level-disclosure - Implement three-level progressive disclosure
• prog-one-level-deep-links - Limit reference links to one level deep
• prog-scripts-execute-not-read - Execute scripts instead of reading code
• prog-lazy-load-examples - Lazy load examples and reference material
• prog-mutual-exclusion - Separate mutually exclusive contexts

6. MCP Tool Design (MEDIUM)

• mcp-tool-naming - Use clear action-object tool names
• mcp-parameter-descriptions - Document all tool parameters
• mcp-error-messages - Return actionable error messages
• mcp-tool-scope - Design single-purpose tools
• mcp-allowed-tools - Use allowed-tools for safety constraints
• mcp-idempotent-operations - Design idempotent tool operations

7. Testing and Validation (MEDIUM)

• test-trigger-phrases - Test skill activation with real user phrases
• test-edge-cases - Test skills with edge case inputs
• test-negative-scenarios - Test that skills do NOT trigger on unrelated requests
• test-instruction-clarity - Test instructions with fresh context

8. Maintenance and Distribution (LOW-MEDIUM)

• maint-semantic-versioning - Use semantic versioning for skill releases
• maint-changelog - Maintain a changelog for skill updates
• maint-plugin-packaging - Package skills as plugins for distribution
• maint-audit-security - Audit skills before installing from external sources

Creating Rules

Copy assets/templates/_template.md and follow the frontmatter schema:

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---

Reference files use the pattern: references/{prefix}-{slug}.md

References

• skills-ref specification
• Anthropic Engineering: Agent Skills
• Claude Code Skills Documentation
• Anthropic Skills Repository
• MCP Best Practices
• Prompt Engineering Guide: LLM Agents
• Claude Skills Deep Dive

Skill Authoring

This curated skill mirrors SKILL.md. When maintaining it, keep the guidance focused on skill metadata, descriptions, triggers, progressive disclosure, MCP tools, validation, and distribution.

Rule Title Here

1-3 sentences explaining WHY this matters. Focus on the impact and consequences.

Incorrect (what's wrong with this approach):

# Bad example with comments explaining the cost

Correct (what's right about this approach):

# Good example with comments explaining the benefit

When NOT to use this pattern:

• Exception 1
• Exception 2

Reference: Reference Title

Sections

This file defines all sections, their ordering, impact levels, and descriptions. The section ID (in parentheses) is the filename prefix used to group rules.

---

1. Skill Metadata Design (meta)

Impact: CRITICAL Description: Metadata determines skill discovery and selection. Poor names or descriptions mean the skill is never triggered, rendering all other optimizations worthless.

2. Description Engineering (desc)

Impact: CRITICAL Description: The description field is the primary signal for LLM skill selection. Vague descriptions cause wrong triggers or missed activations, making skills unreliable.

3. Content Structure (struct)

Impact: HIGH Description: How SKILL.md content is organized affects instruction clarity and execution accuracy. Poor structure causes misinterpretation and inconsistent results.

4. Trigger Optimization (trigger)

Impact: HIGH Description: Keywords and patterns that activate skills reliably. Missing trigger terms mean missed opportunities to help users.

5. Progressive Disclosure (prog)

Impact: MEDIUM-HIGH Description: Loading minimal context first and expanding as needed prevents context exhaustion and improves token efficiency across multi-step workflows.

6. MCP Tool Design (mcp)

Impact: MEDIUM Description: Model Context Protocol tool naming, descriptions, and parameter design affect tool discoverability and correct usage by LLMs.

7. Testing and Validation (test)

Impact: MEDIUM Description: Verifying skills work correctly across diverse scenarios catches issues before deployment and ensures consistent behavior.

8. Maintenance and Distribution (maint)

Impact: LOW-MEDIUM Description: Versioning, distribution, and long-term maintenance patterns ensure skills remain usable and discoverable over time.

Avoid Vague Terms in Descriptions

Generic words like "helps", "manages", "handles", and "works with" trigger on too many unrelated requests. Use precise action verbs that match specific user intents.

Incorrect (vague verbs cause over-triggering):

---
name: data-helper
description: Helps with data. Works with various data formats and manages data operations.
---
# "Helps with data" - triggers on ANY data mention
# "Works with" - matches everything
# "Manages" - too generic
# User asks about database schema - wrong skill activates

Correct (precise verbs limit scope):

---
name: csv-parser
description: Parses CSV files into structured data, validates column types, and converts to JSON or database records. This skill should be used when importing CSV data or converting spreadsheet exports.
---
# "Parses CSV" - specific format and action
# "validates column types" - specific operation
# "converts to JSON" - concrete output
# Only triggers on actual CSV work

Replace vague terms:

Reference: Anthropic Engineering: Agent Skills

Differentiate Similar Skills with Distinct Triggers

When multiple skills cover overlapping domains, use distinct trigger terms to ensure the right skill activates. Overlapping descriptions cause unpredictable behavior—sometimes one skill wins, sometimes the other.

Incorrect (overlapping descriptions cause conflicts):

# skills/excel-export/SKILL.md
---
name: excel-export
description: Works with Excel files and data export
---

# skills/data-analysis/SKILL.md
---
name: data-analysis
description: Analyzes data and exports to Excel
---
# Both mention "Excel" and "data"
# User says "export to Excel" - which skill wins?
# Unpredictable activation on every request

Correct (distinct trigger domains):

# skills/excel-export/SKILL.md
---
name: excel-export
description: Exports query results and datasets to Excel spreadsheets with formatting. This skill should be used when the user wants to create Excel reports or download data as .xlsx files.
---

# skills/data-analysis/SKILL.md
---
name: data-analysis
description: Analyzes datasets using statistical methods, generates insights, and creates visualizations. This skill should be used when the user wants to explore data, find patterns, or create charts.
---
# "Excel reports" vs "explore data"
# ".xlsx files" vs "create charts"
# Clear separation of concerns

Disambiguation strategies:

• Use different file formats as triggers
• Reference different workflow stages (create vs. analyze)
• Mention different output types (spreadsheet vs. visualization)

Reference: Claude Code Skills Docs

Include Negative Cases for Precision

For skills with narrow scope, mention what the skill does NOT do. This prevents Claude from activating the skill for superficially similar but actually different requests.

Incorrect (no boundaries, over-activates):

---
name: unit-test-generator
description: Generates tests for code. This skill should be used when the user wants to test their code.
---
# "test their code" matches integration tests
# "test their code" matches E2E tests
# "test their code" matches manual testing requests
# Skill activates but can't help with these cases

Correct (explicit boundaries prevent wrong activation):

---
name: unit-test-generator
description: Generates unit tests for individual functions with mocks and assertions. This skill should be used when writing unit tests or testing isolated functions. This skill does NOT handle integration tests, E2E tests, or load testing.
---
# Clear positive: "unit tests", "isolated functions"
# Clear negative: "does NOT handle integration tests"
# User asking for E2E tests won't trigger this skill

When to add negative cases:

• Skill name suggests broader capability than actual scope
• Common confusion with related but different skills
• Frequently asked to do things outside scope

Pattern:

This skill does NOT {out-of-scope action 1} or {out-of-scope action 2}.

Reference: Anthropic Engineering: Agent Skills

Optimize Description Length for Discovery

The skills-ref validator enforces a 1024-character maximum for descriptions. Additionally, descriptions are loaded into context at startup, so efficiency matters. Target 150-300 characters for optimal balance between trigger coverage and token usage.

Incorrect (too short, misses triggers):

---
name: pdf-processing
description: Handles PDFs.
---
# 12 characters - too vague
# No trigger keywords
# Misses most user requests

Incorrect (exceeds 1024-character limit):

---
name: pdf-processing
description: This comprehensive PDF processing skill handles all aspects of PDF document management including but not limited to text extraction using OCR and native text parsing, table extraction with structure preservation, form filling for both AcroForms and XFA forms, document merging and splitting, page manipulation including rotation and reordering, image extraction and conversion, PDF to image conversion supporting PNG JPEG and TIFF formats, compression and optimization, digital signature verification, and metadata extraction. This skill should be used whenever the user needs to work with PDF files in any capacity including reading extracting converting manipulating or creating PDF documents. Additionally this skill supports batch processing of multiple PDF files, automated workflows for document processing pipelines, and integration with external services for enhanced functionality including cloud storage providers and document management systems...
---
# skills-ref validate ./skills/pdf-processing/
# Error: description cannot exceed 1024 characters

Correct (optimal length with key triggers):

---
name: pdf-processing
description: Extract text and tables from PDFs, fill forms, merge documents, and convert to images. This skill should be used when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# 213 characters - includes key capabilities
# Covers main trigger keywords
# skills-ref validate ./skills/pdf-processing/
# Validation passed

Validation command:

# Check description length
skills-ref read-properties ./skills/my-skill/ | jq '.description | length'
# Should be <= 1024

Reference: skills-ref validator

Name Specific Capabilities in Description

List concrete actions the skill performs, not abstract categories. Claude matches user requests against these specific capabilities. Generic descriptions cause missed activations or wrong triggers.

Incorrect (abstract category, no specific actions):

---
name: document-helper
description: Helps with documents
---
# "Helps with documents" matches nothing specific
# User says "extract text from this PDF" - skill doesn't trigger
# User says "fill out this form" - skill doesn't trigger

Correct (lists specific extractable capabilities):

---
name: pdf-processing
description: Extract text and tables from PDF files, fill interactive forms, merge multiple PDFs, and convert PDFs to images. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# Each action is a concrete trigger point
# "extract text from PDF" matches "Extract text"
# "fill out this form" matches "fill interactive forms"

Capability naming patterns:

• Use verbs: Extract, Fill, Merge, Convert, Generate, Analyze
• Include objects: text, tables, forms, images, data
• Mention formats: PDF, Excel, JSON, Markdown

Reference: Anthropic Engineering: Agent Skills

Write Descriptions in Third Person

Use "This skill should be used when..." rather than "Use this skill when...". Third person helps Claude reason about skill applicability as an external resource rather than a direct command.

Incorrect (imperative voice):

---
name: code-review
description: Use this skill to review code for security issues. Run it on PRs before merging.
---
# Imperative voice reads as instruction to Claude
# Mixes skill description with usage commands
# Less clear when skill applies vs. direct instructions

Correct (third person declarative):

---
name: code-review
description: Reviews code for security vulnerabilities, performance issues, and style violations. This skill should be used when reviewing PRs, auditing codebases, or checking for bugs before deployment.
---
# Third person describes what skill does
# Clear separation: what it does vs. when to use it
# Claude reasons about applicability more accurately

Pattern to follow: 1. First sentence: What the skill does (verb phrase) 2. Second sentence: "This skill should be used when..." (triggers)

Reference: Anthropic Engineering: Agent Skills

Include User Trigger Keywords in Description

Add phrases users actually say when requesting the skill's functionality. Claude performs semantic matching between user input and skill descriptions. Missing keywords mean missed activations.

Incorrect (technical terms only):

---
name: git-workflow
description: Manages git operations including commits, branches, and merges using best practices.
---
# User says "push my changes" - no match for "push"
# User says "create a PR" - no match for "PR" or "pull request"

Correct (includes natural user phrases):

---
name: git-workflow
description: Manages git operations including commits, branches, and merges. Use when the user wants to commit changes, push code, create a PR, open a pull request, or review git history.
---
# "push my changes" matches "push code"
# "create a PR" matches "create a PR"
# "open pull request" matches "open a pull request"

Keyword research technique: 1. Write down 10 ways users might ask for this feature 2. Include synonyms (PR/pull request, commit/save changes) 3. Include command names users might type (/commit, /pr) 4. Test with real user queries

Reference: Claude Code Skills Docs

Audit Skills Before Installing from External Sources

Before installing skills from external sources, review their contents for security risks. Skills can execute arbitrary code, access files, and make network requests. Malicious skills can exfiltrate data or compromise systems.

Incorrect (blind trust):

# Found skill on random GitHub repo
/plugin add github:unknown-user/cool-skills

# Installed without review
# Skill contains hidden backdoor
# Exfiltrates code to external server

Correct (security audit before install):

# Security Audit Checklist

## Before Installing: github:org/skill-package

### 1. Source Review
- [ ] Repository has clear ownership
- [ ] Maintained by known organization
- [ ] Has meaningful commit history
- [ ] Not a fork of suspicious origin

### 2. Code Review
- [ ] No obfuscated code
- [ ] No network calls to unknown hosts
- [ ] No file access outside expected scope
- [ ] No credential harvesting patterns

### 3. Permission Review
- [ ] allowed-tools restricts capabilities appropriately
- [ ] No unnecessary Bash access
- [ ] No Write access if read-only expected

### 4. Script Audit
- [ ] scripts/ directory contents reviewed
- [ ] Dependencies from trusted sources
- [ ] No eval() or exec() on user input

Red flags to watch for:

Reference: Anthropic Engineering: Agent Skills

Maintain a Changelog for Skill Updates

Keep a CHANGELOG.md file documenting all changes between versions. Users need to understand what changed before updating, especially for breaking changes.

Incorrect (no changelog):

skill-directory/
├── SKILL.md
└── metadata.json  # version: "3.0.0"

# User on v2.0.0 sees v3.0.0 available
# No information about what changed
# No warning about breaking changes
# Updates blindly, skill breaks their workflow

Correct (changelog with all versions):

skill-directory/
├── SKILL.md
├── metadata.json
└── CHANGELOG.md

# Changelog

All notable changes to this skill are documented here.

## [3.0.0] - 2024-02-01

### Breaking Changes
- Output format changed from JSON to YAML
- Minimum Node.js version is now 18

### Added
- Support for TypeScript type generation

### Fixed
- Handle circular references in schemas

## [2.1.0] - 2024-01-15

### Added
- New `--dry-run` flag for preview mode

### Changed
- Improved error messages for invalid inputs

## [2.0.0] - 2024-01-01

### Breaking Changes
- Renamed `generate` command to `create`

### Added
- Batch processing support

Changelog sections:

Reference: Keep a Changelog

Package Skills as Plugins for Distribution

When distributing skills beyond a single project, package them as Claude Code plugins. Plugins provide versioned installation, automatic updates, and proper dependency management.

Incorrect (manual file sharing):

# Installation Instructions

1. Clone this repo
2. Copy the `skills/` directory to `~/.claude/skills/`
3. Restart Claude Code
4. To update, re-clone and re-copy

# Users must manually manage files
# No version tracking
# Updates overwrite customizations
# Dependencies not managed

Correct (plugin packaging):

my-skills-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── api-generator/
│   │   └── SKILL.md
│   └── test-runner/
│       └── SKILL.md
└── README.md

// .claude-plugin/plugin.json
{
  "name": "my-skills",
  "version": "1.0.0",
  "description": "Collection of development skills",
  "skills": {
    "auto-discover": true
  }
}

# Installation

/plugin add github:myorg/my-skills-plugin

Plugin benefits:

Reference: Claude Code Plugins

Use Semantic Versioning for Skill Releases

Track skill versions using semantic versioning (MAJOR.MINOR.PATCH). This allows users to understand update impact and pin to known-working versions when needed.

Incorrect (no versioning or arbitrary versions):

{
  "name": "api-generator",
  "version": "latest"
}

# No way to know what changed
# Can't pin to specific version
# Breaking changes surprise users
# No rollback path

Correct (semantic versioning):

{
  "name": "api-generator",
  "version": "2.1.0"
}

# CHANGELOG.md

## [2.1.0] - 2024-01-15
### Added
- Support for GraphQL endpoints

## [2.0.0] - 2024-01-01
### Changed
- BREAKING: Changed output format from JSON to YAML
- BREAKING: Renamed 'endpoint' parameter to 'path'

## [1.2.3] - 2023-12-15
### Fixed
- Handle paths with special characters

Version increment rules:

Breaking changes include:

• Changing output format
• Renaming required parameters
• Removing capabilities
• Changing default behavior

Reference: Semantic Versioning

Use allowed-tools for Safety Constraints

Restrict which tools a skill can use via the allowed-tools frontmatter field. This prevents accidental file modifications during read-only operations or unintended command execution.

Incorrect (no tool restrictions):

---
name: code-analyzer
description: Analyzes code for quality issues
---

# Code Analyzer

Analyze the codebase and report issues...

# Skill has access to all tools
# Claude might edit files while "analyzing"
# Claude might run commands to "check" things
# Unintended side effects possible

Correct (explicit tool restrictions):

---
name: code-analyzer
description: Analyzes code for quality issues
allowed-tools: Read, Grep, Glob
---

# Code Analyzer

Analyze the codebase and report issues...

# Only read-only tools available
# Cannot edit files during analysis
# Cannot execute arbitrary commands
# Safe by design

Common restriction patterns:

Wildcard syntax:

• Bash(git:*) - Only git commands
• Bash(npm:*) - Only npm commands
• Bash(python scripts/*.py) - Only specific scripts

Reference: Claude Code Skills Docs

Return Actionable Error Messages

When MCP tools fail, return error messages that explain what went wrong and how to fix it. Generic errors leave Claude unable to recover, causing repeated failures or giving up entirely.

Incorrect (generic error messages):

{
  "error": {
    "code": -1,
    "message": "Operation failed"
  }
}

# "Operation failed" - what operation? why?
# Claude has no information to self-correct
# User sees "I encountered an error"
# No path forward

Correct (actionable error with guidance):

{
  "error": {
    "code": 422,
    "message": "Invalid date format",
    "details": {
      "field": "start_date",
      "received": "2024-1-5",
      "expected": "ISO 8601 format (YYYY-MM-DD)",
      "example": "2024-01-05"
    }
  }
}

# Identifies exact field with problem
# Shows what was received
# Explains expected format
# Provides working example
# Claude can retry with corrected value

Error message components:

Reference: MCP Best Practices

Design Idempotent Tool Operations

Design MCP tools so calling them multiple times with the same input produces the same result. Claude may retry failed calls, and network issues can cause duplicate requests. Non-idempotent tools create inconsistent state.

Incorrect (non-idempotent increment):

// Tool: increment_counter
async function incrementCounter(counterId: string): Promise<number> {
  const counter = await db.get(counterId)
  counter.value += 1
  await db.save(counter)
  return counter.value
}

# User asks to increment counter
# Claude calls tool, network timeout
# Claude retries (same request)
# Counter incremented twice!
# Value is now 2 instead of 1

Correct (idempotent set with request ID):

// Tool: set_counter
async function setCounter(
  counterId: string,
  value: number,
  requestId: string
): Promise<number> {
  const existing = await db.getByRequestId(requestId)
  if (existing) {
    return existing.value  // Already processed
  }

  await db.save({ counterId, value, requestId })
  return value
}

# User asks to set counter to 5
# Claude calls tool, network timeout
# Claude retries with same requestId
# Tool detects duplicate, returns existing value
# Counter is exactly 5

Idempotency strategies:

Reference: MCP Best Practices

Document All Tool Parameters

Every MCP tool parameter needs a clear description, type, and constraints. Missing documentation causes Claude to guess parameter values, leading to API errors and failed tool calls.

Incorrect (minimal parameter documentation):

{
  "name": "search_users",
  "inputSchema": {
    "type": "object",
    "properties": {
      "q": {"type": "string"},
      "n": {"type": "integer"},
      "s": {"type": "string"}
    }
  }
}

# "q" - query? queue? what format?
# "n" - number of what? max? min?
# "s" - sort? status? string of what?
# Claude guesses wrong values

Correct (full parameter documentation):

{
  "name": "search_users",
  "description": "Searches users by name, email, or role",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search term to match against user name, email, or role"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of results to return (1-100, default 20)",
        "minimum": 1,
        "maximum": 100,
        "default": 20
      },
      "sort_by": {
        "type": "string",
        "description": "Field to sort results by",
        "enum": ["name", "email", "created_at", "last_login"],
        "default": "name"
      }
    },
    "required": ["query"]
  }
}

# Clear parameter names
# Descriptions explain purpose and format
# Constraints prevent invalid values
# Defaults reduce required inputs

Reference: MCP Specification

Use Clear Action-Object Tool Names

Name MCP tools with a verb-object pattern that describes exactly what the tool does. Claude selects tools based on name matching, so unclear names cause wrong tool selection or missed opportunities.

Incorrect (vague or noun-only names):

{
  "tools": [
    {"name": "data", "description": "Handles data operations"},
    {"name": "processor", "description": "Processes things"},
    {"name": "helper", "description": "Helps with tasks"}
  ]
}

# "data" - data what? get? set? delete?
# "processor" - process what? how?
# Claude can't determine when to use these

Correct (verb-object pattern):

{
  "tools": [
    {"name": "get_user_profile", "description": "Retrieves user profile data by user ID"},
    {"name": "update_user_settings", "description": "Updates user account settings"},
    {"name": "delete_user_session", "description": "Invalidates and removes user session"}
  ]
}

# "get_user_profile" - clear action (get) and object (user_profile)
# "update_user_settings" - precise operation
# Claude matches user request to correct tool

Naming patterns:

Reference: MCP Best Practices

Design Single-Purpose Tools

Each MCP tool should do one thing well. Multi-purpose tools with many optional parameters confuse Claude's tool selection and increase the chance of incorrect usage.

Incorrect (multi-purpose tool with mode parameter):

{
  "name": "manage_users",
  "description": "Creates, updates, deletes, or retrieves users",
  "inputSchema": {
    "type": "object",
    "properties": {
      "action": {
        "type": "string",
        "enum": ["create", "update", "delete", "get", "list"]
      },
      "user_id": {"type": "string"},
      "user_data": {"type": "object"},
      "filters": {"type": "object"}
    }
  }
}

# 5 actions with different required parameters
# Claude must understand modal behavior
# Easy to pass wrong combination
# Error messages complex to generate

Correct (separate tools for each action):

{
  "tools": [
    {
      "name": "create_user",
      "description": "Creates a new user account",
      "inputSchema": {
        "properties": {
          "name": {"type": "string", "description": "User's full name"},
          "email": {"type": "string", "description": "User's email address"}
        },
        "required": ["name", "email"]
      }
    },
    {
      "name": "get_user",
      "description": "Retrieves user profile by ID",
      "inputSchema": {
        "properties": {
          "user_id": {"type": "string", "description": "User's unique identifier"}
        },
        "required": ["user_id"]
      }
    },
    {
      "name": "delete_user",
      "description": "Permanently deletes a user account",
      "inputSchema": {
        "properties": {
          "user_id": {"type": "string", "description": "User's unique identifier"}
        },
        "required": ["user_id"]
      }
    }
  ]
}

# Each tool has clear purpose
# Required parameters obvious
# Claude selects correct tool directly
# Simpler error handling per tool

Reference: MCP Best Practices

Only Use Allowed Frontmatter Fields

SKILL.md frontmatter must only contain recognized fields. The skills-ref validator enforces a strict allowlist and rejects skills with unexpected fields. This ensures forward compatibility and prevents silent failures.

Allowed fields:

Incorrect (unknown field):

---
name: code-review
description: Reviews code for quality issues
author: John Doe
version: 1.0.0
---
# Validation error: unexpected fields
# skills-ref validate ./skills/code-review/
# Error: Unexpected fields in frontmatter: author, version

Correct (only allowed fields):

---
name: code-review
description: Reviews code for quality issues, security vulnerabilities, and performance problems. Use when reviewing PRs or auditing code.
license: MIT
metadata:
  author: John Doe
  version: 1.0.0
---
# Valid: custom data goes in metadata field
# skills-ref validate ./skills/code-review/
# Validation passed

Migration guide:

Reference: skills-ref validator

Match Skill Name to Directory Name

The name field in frontmatter must exactly match the containing directory name. The skills-ref validator enforces this constraint using Unicode normalization (NFKC) to compare names.

Incorrect (name does not match directory):

skills/
└── pdf-tools/           # Directory name
    └── SKILL.md

---
name: pdf-processing     # Different from directory!
description: Handles PDF files
---
# skills-ref validate ./skills/pdf-tools/
# Error: Name must match the skill directory name

Correct (name matches directory exactly):

skills/
└── pdf-processing/      # Directory name
    └── SKILL.md

---
name: pdf-processing     # Matches directory
description: Handles PDF files
---
# skills-ref validate ./skills/pdf-processing/
# Validation passed

Unicode normalization:

The validator uses NFKC normalization, so these would match:

• caf\u00e9 (precomposed) matches cafe\u0301 (decomposed)
• Compatibility characters are normalized

Benefits:

• Passes skills-ref validation
• Reliable discovery across all platforms
• Simple mental model: directory = skill name

Reference: skills-ref validator

Use Valid YAML Frontmatter Syntax

YAML frontmatter must start on line 1 with ---, use spaces (not tabs), and close with ---. Invalid syntax causes the entire skill to fail silently—no error message, just non-functional skill.

Incorrect (tabs instead of spaces cause parsing failure):

---
name:	pdf-processing
description:	Processes PDF files
---
# Tab characters (\t) instead of spaces
# YAML parser fails silently
# Skill never loads despite being in correct directory

Correct (spaces after colons, proper delimiters):

---
name: pdf-processing
description: Processes PDF files for text extraction and form filling.
---
# Space after colon, no tabs
# Valid YAML parses correctly

Common syntax errors:

• Using tabs instead of spaces
• Missing space after colon (name:value vs name: value)
• Unescaped special characters in strings
• Missing closing --- delimiter
• Frontmatter not starting on line 1

Validation command:

# Check YAML syntax before committing
head -20 SKILL.md | python -c "import yaml, sys; yaml.safe_load(sys.stdin)"

Reference: YAML 1.2 Specification

Use Lowercase Hyphenated Skill Names

The skill name must use lowercase letters, digits, and hyphens only. The skills-ref validator enforces this constraint and rejects names with uppercase letters, spaces, or special characters.

Incorrect (mixed case causes validation failure):

---
name: PDF-Processing
description: Handles PDF files
---
# skills-ref validate ./skills/PDF-Processing/
# Error: Name must be lowercase

Incorrect (spaces not allowed):

---
name: pdf processing tool
description: Handles PDF files
---
# skills-ref validate ./skills/pdf processing tool/
# Error: Name can only contain letters, digits, and hyphens

Correct (lowercase with hyphens):

---
name: pdf-processing
description: Handles PDF files
---
# Directory: skills/pdf-processing/SKILL.md
# skills-ref validate ./skills/pdf-processing/
# Validation passed

Allowed characters:

• Lowercase letters (a-z)
• Digits (0-9)
• Hyphens (-)
• Unicode letters for i18n support

Benefits:

• Passes skills-ref validation
• Consistent discovery across Windows, macOS, and Linux
• Valid URL slugs for plugin marketplaces

Reference: skills-ref validator

Never Start or End Names with Hyphens

Skill names cannot start or end with hyphens. The skills-ref validator explicitly checks for this and rejects names with leading or trailing hyphens. This ensures consistent URL slugs and programmatic access patterns.

Incorrect (leading hyphen):

---
name: -pdf-processor
description: Processes PDF files
---
# Validation error: name cannot start with hyphen
# skills-ref validate ./skills/-pdf-processor/
# Error: Name cannot start or end with hyphens

Incorrect (trailing hyphen):

---
name: pdf-processor-
description: Processes PDF files
---
# Validation error: name cannot end with hyphen
# skills-ref validate ./skills/pdf-processor-/
# Error: Name cannot start or end with hyphens

Correct (no boundary hyphens):

---
name: pdf-processor
description: Processes PDF files
---
# Valid: hyphens only between words
# skills-ref validate ./skills/pdf-processor/
# Validation passed

Validation command:

# Install skills-ref (Python 3.11+)
pip install skills-ref

# Validate skill directory
skills-ref validate ./skills/my-skill/

Reference: skills-ref validator

Keep Skill Names Under 64 Characters

The skills-ref validator enforces a 64-character maximum for skill names. Names exceeding this limit cause validation failure and cannot be published or distributed.

Incorrect (exceeds 64-character limit):

---
name: enterprise-customer-relationship-management-data-synchronization-toolkit
description: Syncs CRM data
---
# 74 characters - exceeds limit
# skills-ref validate ./skills/enterprise-customer-...
# Error: Name cannot exceed 64 characters

Correct (concise name under limit):

---
name: crm-sync
description: Synchronizes enterprise CRM data across platforms. Use when importing, exporting, or reconciling customer records.
---
# 8 characters - well under limit
# skills-ref validate ./skills/crm-sync/
# Validation passed

Naming strategy:

• Use common abbreviations (CRM, API, DB)
• Omit redundant words (tool, helper, utility)
• Focus on the action, not the domain
• Target 15-30 characters for optimal readability

Validation command:

# Check name length before creating skill
echo -n "my-skill-name" | wc -c  # Should be <= 64

# Or validate the full skill
skills-ref validate ./skills/my-skill/

Reference: skills-ref validator

Avoid Consecutive Hyphens in Names

Skill names cannot contain consecutive hyphens (--). The skills-ref validator rejects names with double or multiple consecutive hyphens. This prevents ambiguous word boundaries and ensures clean URL slugs.

Incorrect (double hyphen):

---
name: pdf--processor
description: Processes PDF files
---
# Validation error: consecutive hyphens not allowed
# skills-ref validate ./skills/pdf--processor/
# Error: Name cannot contain consecutive hyphens

Incorrect (multiple consecutive hyphens):

---
name: enterprise---crm---sync
description: Syncs enterprise CRM data
---
# Validation error: triple hyphens not allowed
# Ambiguous word boundaries

Correct (single hyphens only):

---
name: pdf-processor
description: Processes PDF files
---
# Valid: single hyphens between words
# skills-ref validate ./skills/pdf-processor/
# Validation passed

Common causes:

• Find-and-replace errors when renaming
• Copy-paste from URLs with encoded characters
• Automated slug generation without normalization

Prevention pattern:

// Normalize skill names before creating directories
function normalizeSkillName(name) {
  return name
    .toLowerCase()
    .replace(/[^a-z0-9-]/g, '-')
    .replace(/-+/g, '-')  // Collapse consecutive hyphens
    .replace(/^-|-$/g, ''); // Remove boundary hyphens
}

Reference: skills-ref validator

Ensure Skill Names Are Globally Unique

Skill names must be unique within each scope (project, user, plugin). When names collide, higher-priority scopes silently override lower ones. Users see unpredictable behavior without any error.

Incorrect (generic name collides with common plugins):

---
name: utils
description: General utility functions
---
# Collides with utils from anthropic/skills plugin
# Your skill silently overrides or gets overridden

Correct (prefixed name avoids collisions):

---
name: acme-deployment-utils
description: ACME Corp deployment utility functions
---
# Unique namespace prevents collisions
# Clear ownership when multiple plugins installed

Priority order (highest wins): 1. Enterprise managed settings 2. Personal (~/.claude/skills/) 3. Project (.claude/skills/) 4. Plugin-provided skills

When NOT to use prefixes:

• Official Anthropic skills that define the standard
• Project-only skills never distributed externally

Reference: Agent Skills - Claude Code Docs

Include All Required Frontmatter Fields

Every SKILL.md must have valid YAML frontmatter with name and description fields. The skills-ref validator requires both fields and rejects skills with missing or empty values.

Incorrect (missing description field):

---
name: code-review
---
# skills-ref validate ./skills/code-review/
# Error: description is required

Incorrect (empty name):

---
name: ""
description: Reviews code for quality issues
---
# skills-ref validate ./skills/code-review/
# Error: name must be non-empty

Correct (all required fields present):

---
name: code-review
description: Reviews code for quality issues, security vulnerabilities, and performance problems. Use when reviewing PRs, auditing code, or checking for bugs.
---

# Code Review Instructions
...
# skills-ref validate ./skills/code-review/
# Validation passed

Field requirements (per skills-ref):

Validation command:

skills-ref validate ./skills/my-skill/
# Or extract properties as JSON
skills-ref read-properties ./skills/my-skill/

Reference: skills-ref validator

Lazy Load Examples and Reference Material

Keep examples and reference material in separate files, loading them only when users ask for examples. Most interactions don't need examples, so loading them by default wastes tokens.

Incorrect (examples embedded in SKILL.md):

# API Generator

## Instructions
Generate REST API endpoints following these patterns...

## Examples

### Example 1: User CRUD

// 50 lines of user API example

### Example 2: Product Catalog

// 50 lines of product API example

### Example 3: Order Processing

// 50 lines of order API example

[... 10 more examples ...]

# 650+ lines of examples in main file
# ~1300 tokens loaded every activation
# User just wants to generate one endpoint
# Examples rarely referenced

Correct (examples in separate file):

# API Generator

## Instructions
Generate REST API endpoints following these patterns...

## Examples
For implementation examples, see [examples.md](examples.md).

Quick reference:
- User CRUD: `examples.md#user-crud`
- Product Catalog: `examples.md#products`
- Order Processing: `examples.md#orders`

# Core file stays under 100 lines
# ~200 tokens on activation
# Examples loaded only when requested
# Quick reference enables targeted loading

What to lazy load:

• Code examples (especially multiple examples)
• API reference documentation
• Error code listings
• Configuration option catalogs
• Template collections

Reference: Anthropic Engineering: Agent Skills

Separate Mutually Exclusive Contexts

When a skill supports multiple distinct scenarios that never overlap, put each in its own reference file. This prevents loading Python documentation when the user needs JavaScript, or AWS docs when they need Azure.

Incorrect (all scenarios in one file):

# Cloud Deployment

## AWS Deployment
[200 lines of AWS-specific instructions]

## Azure Deployment
[200 lines of Azure-specific instructions]

## GCP Deployment
[200 lines of GCP-specific instructions]

# User deploys to AWS
# All 600 lines loaded
# 400 lines (Azure + GCP) completely irrelevant
# Wastes ~800 tokens

Correct (separate files per scenario):

cloud-deployment/
├── SKILL.md
├── aws.md
├── azure.md
└── gcp.md

# SKILL.md

## Deployment Instructions

1. Determine target cloud provider
2. Load provider-specific guide:
   - AWS: [aws.md](aws.md)
   - Azure: [azure.md](azure.md)
   - GCP: [gcp.md](gcp.md)
3. Follow provider-specific steps

# User deploys to AWS
# Only aws.md loaded (200 lines)
# Zero irrelevant content
# Saves ~400 tokens

Mutual exclusion patterns:

Reference: Anthropic Engineering: Agent Skills

Limit Reference Links to One Level Deep

SKILL.md can link to reference files, but those files should not link to further files. Multi-level chains (A→B→C→D) cause recursive loading, context explosion, and Claude losing track of where information came from.

Incorrect (multi-level reference chains):

# SKILL.md
See [config.md](config.md) for configuration options.

# config.md
For authentication, see [auth.md](auth.md).

# auth.md
For OAuth details, see [oauth.md](oauth.md).

# oauth.md
For token refresh, see [tokens.md](tokens.md).

# 4 levels deep
# Claude follows chain, loading each file
# Context fills with partially relevant content
# Original question context pushed out

Correct (flat reference structure):

# SKILL.md
## Configuration
See [config.md](config.md) for all configuration options.

## Authentication
See [auth.md](auth.md) for authentication setup.

# config.md (NO further links)
## All Configuration Options
[Complete config documentation, no outgoing links]

# auth.md (NO further links)
## Authentication
[Complete auth documentation including OAuth and tokens]

# Single level of references
# Each reference file is self-contained
# Claude loads exactly what's needed

Reference file guidelines:

• Self-contained: Include all relevant information
• No outgoing links: Don't reference other skill files
• Focused: One topic per reference file

Reference: Claude Code Skills Docs

Execute Scripts Instead of Reading Code

Place executable scripts in scripts/ directory and have Claude run them rather than reading code into context. Script execution uses zero context tokens while delivering the same results.

Incorrect (reading script into context):

# SKILL.md

## Data Processing

Read the processing script and follow its logic:

scripts/process.py - 200 lines

import pandas as pd import json

def process_data(input_file, output_format): df = pd.read_csv(input_file)

... 180 more lines of processing logic

return result

Use this logic to process user's data.

# 200 lines of code in context
# ~400 tokens consumed
# Claude tries to mentally execute code
# Error-prone and slow

Correct (execute script, describe interface):

# SKILL.md

## Data Processing

Process data using the bundled script:

python scripts/process.py --input data.csv --format json

**Arguments:**
- `--input`: Input CSV file path
- `--format`: Output format (json, csv, markdown)
- `--output`: Optional output file (defaults to stdout)

The script handles data validation, transformation, and formatting.

# ~10 lines describing interface
# ~20 tokens consumed
# Script executes with full capability
# Results returned directly

When to read vs. execute:

Reference: Claude Code Skills Docs

Implement Three-Level Progressive Disclosure

Structure skill content across three disclosure levels: metadata at startup, full SKILL.md when activated, and supplementary files when needed. This prevents context exhaustion while enabling deep functionality.

Incorrect (everything in one file):

# PDF Processor

## Instructions
[50 lines of core instructions]

## Complete API Reference
[500 lines of API documentation]

## All File Format Details
[300 lines of format specs]

## Every Example
[400 lines of examples]

# 1250+ lines loaded on first activation
# ~2500 tokens consumed immediately
# Most content never used in typical session

Correct (three-level disclosure):

pdf-processor/
├── SKILL.md           # Level 2: Core instructions (~100 lines)
├── api-reference.md   # Level 3: Loaded when API help needed
├── formats.md         # Level 3: Loaded for format questions
└── examples.md        # Level 3: Loaded when examples requested

# Level 1: SKILL.md frontmatter (always loaded)
---
name: pdf-processor
description: Extract text, tables, and forms from PDFs.
---

# Level 2: SKILL.md body (loaded on activation)

## Quick Start
Extract text with `extractText(pdf)`. For advanced API options,
see [api-reference.md](api-reference.md).

## Supported Formats
PDF 1.0-2.0 supported. For format details,
see [formats.md](formats.md).

Disclosure levels:

Reference: Anthropic Engineering: Agent Skills

dot-skills Project Conventions

This project extends the base Anthropic skill specification with additional conventions for internal consistency and contributor workflows. Understanding these deviations helps when creating skills for different contexts.

Standard Anthropic Skill Structure

The official Anthropic skill specification requires only:

skill-name/
├── SKILL.md          (required - main skill file)
├── scripts/          (optional - executable utilities)
├── references/       (optional - supporting documentation)
└── assets/           (optional - templates, examples)

dot-skills Extended Structure

This project adds:

skill-name/
├── SKILL.md          (required - skill entry point)
├── metadata.json     (extension - project metadata)
├── references/
│   ├── _sections.md  (extension - category definitions)
│   └── *.md          (standard - rule files)
└── assets/templates/ (standard - templates)

Extension files explained:

When Creating Skills for Distribution

If creating a skill for distribution outside dot-skills:

• Follow only the standard Anthropic specification
• Include only SKILL.md and essential bundled resources
• Avoid README.md, AGENTS.md, and project-specific metadata

If creating a skill within dot-skills:

• Follow the extended structure for consistency
• Use the reference frontmatter schema with impact levels
• Include _sections.md for category organization

Reference File Frontmatter Schema

dot-skills uses structured frontmatter in reference files:

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact statement
tags: prefix, technique, related-concepts
---

This schema is project-specific and not required by the Anthropic specification.

Reference: Anthropic Skill Creator

Specify Language in Code Blocks

Always include language identifiers in fenced code blocks. Claude uses these to determine execution context and syntax rules. Missing identifiers cause parsing ambiguity and execution errors.

Incorrect (no language specified):

## Example Usage

` ` `
const result = await extractText(pdf)
console.log(result)
` ` `

Run the script:

` ` `
python scripts/process.py --input file.pdf
` ` `

# First block: Is it JavaScript? TypeScript? Node?
# Second block: Is it bash? Should Claude execute it?
# Ambiguous execution context

Correct (language specified for each block):

## Example Usage

` ` `typescript
const result = await extractText(pdf)
console.log(result)
` ` `

Run the script:

` ` `bash
python scripts/process.py --input file.pdf
` ` `

# TypeScript: Claude knows syntax rules and types
# Bash: Claude knows this is a shell command
# Clear execution context for each block

Common language identifiers:

• typescript, javascript, python, bash, go, rust
• yaml, json, toml for configuration
• markdown for documentation examples
• diff for showing changes

Reference: CommonMark Specification

Use Consistent Header Hierarchy

Use markdown headers to create clear section hierarchy. Claude parses headers to understand document structure. Skipped levels or inconsistent usage causes parsing confusion and instruction misinterpretation.

Incorrect (skipped levels, inconsistent hierarchy):

# PDF Processing

#### Quick Start
Some quick instructions...

## Advanced Usage
More detailed usage patterns...

##### Edge Cases
Edge case handling...

# H1 → #### H4 (skipped 2, 3)
## H2 → ##### H5 (skipped 3, 4)
# Claude can't determine section relationships

Correct (sequential hierarchy, consistent structure):

# PDF Processing

## Quick Start
Some quick instructions...

## Advanced Usage
More detailed usage patterns...

### Edge Cases
Edge case handling...

# H1 (document title)
## H2 (main sections)
### H3 (subsections)
# Clear parent-child relationships

Recommended structure:

# Skill Title (H1 - only one)

## Section 1 (H2 - major sections)

### Subsection 1.1 (H3 - details)

## Section 2 (H2 - next major section)

Reference: CommonMark Specification

Write Instructions in Imperative Mood

Use direct commands like "Extract text" rather than passive constructions like "Text should be extracted". Imperative mood creates unambiguous instructions that Claude executes consistently.

Incorrect (passive and conditional language):

# PDF Processor

## Instructions
Text could be extracted from the PDF if needed. Users may request
tables to be parsed. It would be good to validate the output format.
Forms may need to be filled based on user requirements.

# "could be", "may want", "would be good", "may need"
# All introduce ambiguity about when to act
# Claude may or may not perform these actions

Correct (direct imperative commands):

# PDF Processor

## Instructions
1. Extract all text from the PDF document
2. Parse tables and preserve their structure
3. Validate output format before returning
4. Fill form fields when the user provides values

# "Extract", "Parse", "Validate", "Fill"
# Clear commands with no ambiguity
# Claude executes each instruction

Transform passive to imperative:

Reference: Prompt Engineering Guide

Put Critical Instructions Early in Content

Place the most important instructions in the first 500 lines of SKILL.md. Context windows can truncate long documents, and Claude weighs earlier content more heavily. Burying critical instructions causes inconsistent behavior.

Incorrect (critical rules buried at the end):

# Code Generator

## Introduction
This skill generates code...

## History
The evolution of code generation...

## Supported Languages
We support Python, JavaScript, TypeScript...

## Examples
Here are 50 examples...

## IMPORTANT: Security Rules
Never generate code that accesses /etc/passwd...
Never include API keys in generated code...

# Security rules at line 800+
# May be truncated or deprioritized
# Critical rules applied inconsistently

Correct (critical rules early, details later):

# Code Generator

## Security Rules (MUST FOLLOW)
- Never generate code that accesses system files
- Never include credentials or API keys
- Always sanitize user inputs in generated code

## Quick Start
Generate code by describing what you need...

## Supported Languages
Python, JavaScript, TypeScript...

## Detailed Examples
[Examples can safely be truncated]

# Security rules in first 20 lines
# Always loaded and prioritized
# Examples safely truncated if needed

Reference: Anthropic Engineering: Agent Skills

Keep SKILL.md Under 500 Lines

The main SKILL.md file should stay under 500 lines. Longer files consume excessive tokens when loaded and may trigger context management. Move detailed content to referenced files.

Incorrect (monolithic 2000+ line file):

# API Generator

## Instructions
[100 lines of core instructions]

## Complete API Reference
[500 lines of OpenAPI spec]

## All Error Codes
[300 lines of error documentation]

## Full Examples
[800 lines of example code]

## Changelog
[300 lines of version history]

# 2000+ lines loaded on every activation
# ~4000 tokens consumed immediately
# Most content rarely needed

Correct (core file with references):

# API Generator

## Instructions
[100 lines of core instructions]

## API Reference
For complete API documentation, see [api-reference.md](api-reference.md)

## Error Handling
For error codes, see [errors.md](errors.md)

## Examples
For usage examples, see [examples.md](examples.md)

# 150 lines in main file
# ~300 tokens on activation
# Details loaded only when needed

File splitting strategy:

Reference: Claude Code Skills Docs

One Skill per Domain

Each skill should handle one coherent domain. Multi-purpose skills have vague descriptions that trigger incorrectly and grow unwieldy over time. Split into focused skills.

Incorrect (kitchen-sink skill):

---
name: developer-tools
description: Helps with development tasks including code review, testing, deployment, documentation, and database management.
---

# Developer Tools

## Code Review
[200 lines]

## Testing
[200 lines]

## Deployment
[200 lines]

## Documentation
[200 lines]

## Database
[200 lines]

# Description triggers on any dev task
# 1000+ lines loaded when any feature needed
# Changes to one domain risk breaking others

Correct (focused skills per domain):

skills/
├── code-review/SKILL.md     # 150 lines
├── test-runner/SKILL.md     # 150 lines
├── deployment/SKILL.md      # 150 lines
├── doc-generator/SKILL.md   # 150 lines
└── db-migration/SKILL.md    # 150 lines

Each with focused description:

---
name: code-review
description: Reviews code for security vulnerabilities, performance issues, and style violations. This skill should be used when reviewing PRs or auditing code.
---

# Each skill loads only when needed
# Precise activation for each domain
# Independent evolution and maintenance

Reference: Anthropic Engineering: Agent Skills

Test Skills with Edge Case Inputs

Test skills with unusual but valid inputs: empty files, very large files, special characters, unicode, missing optional data. Edge cases expose instruction gaps that cause production failures.

Incorrect (only happy path tested):

# CSV Parser - Test Results

## Tests Run
1. Standard CSV file (10 rows, 5 columns) ✓

## Deployed

# User uploads empty CSV - skill crashes
# User uploads 100MB CSV - timeout
# User uploads CSV with emojis in headers - parsing error
# User uploads TSV file - wrong delimiter
# 4 production failures from untested cases

Correct (edge cases covered):

# CSV Parser - Test Results

## Standard Cases
1. Standard CSV (10 rows, 5 columns) ✓
2. Large CSV (10,000 rows) ✓

## Edge Cases
3. Empty file (0 rows) ✓ - Returns "No data found"
4. Headers only (0 data rows) ✓ - Returns headers list
5. Single column ✓
6. Unicode in headers (日本語, emoji) ✓
7. Quoted fields with commas ✓
8. TSV file (tab-separated) ✗ - Added delimiter detection

## Error Cases
9. Binary file (not CSV) ✓ - Returns "Invalid format"
10. Malformed CSV (inconsistent columns) ✓ - Reports row errors

## Instructions Updated
- Added: "Detect delimiter automatically (comma, tab, semicolon)"
- Added: "Handle unicode characters in all fields"
- Added: "For empty files, report 'No data found' instead of error"

Common edge cases to test:

Reference: Anthropic Engineering: Agent Skills

Test Instructions with Fresh Context

Test your skill at the start of a new conversation, without any prior context. Instructions that seem clear after extensive development may be ambiguous to Claude seeing them for the first time.

Incorrect (tested only in development context):

# Code Formatter - SKILL.md

## Instructions
Format the code using the settings we discussed.
Apply the rules from the configuration.
Use the standard approach for this project.

# During development, these made sense
# New conversation: "what settings?"
# New conversation: "what configuration?"
# New conversation: "what standard approach?"
# Claude has no context for these references

Correct (self-contained instructions):

# Code Formatter - SKILL.md

## Instructions
Format code using Prettier with these settings:
- printWidth: 100
- tabWidth: 2
- singleQuote: true
- trailingComma: 'es5'

## Process
1. Read the target file
2. Apply Prettier formatting
3. Write formatted output back
4. Report changes made

## Default Behavior
If no specific style requested, use the Prettier defaults above.

# All context self-contained
# No references to "previous discussion"
# No "as mentioned before"
# Works in any conversation

Testing checklist:

• [ ] Start new Claude Code session
• [ ] Trigger skill with simple request
• [ ] Verify Claude follows instructions without asking clarifying questions
• [ ] Check output matches expected format
• [ ] Repeat with 3 different simple requests

Reference: Anthropic Engineering: Agent Skills

Test That Skills Do NOT Trigger on Unrelated Requests

Verify your skill does NOT activate for superficially similar but actually unrelated requests. Over-triggering skills frustrate users and waste context on irrelevant instructions.

Incorrect (no negative testing):

---
name: python-debugger
description: Helps debug Python code and fix errors.
---

# Positive tests pass - activates on Python errors
# No negative testing done
# User asks "what Python version do I have?" - debugger activates
# User asks "recommend Python books" - debugger activates
# User asks "Python vs JavaScript?" - debugger activates
# Skill over-triggers on any Python mention

Correct (negative scenarios tested):

# Negative Test Results

## Should NOT Trigger

1. "what Python version do I have?"
   - Result: Triggered ✗
   - Fix: Added "errors", "bugs", "exceptions" as required context

2. "recommend Python books"
   - Result: Did not trigger ✓

3. "Python vs JavaScript comparison"
   - Result: Did not trigger ✓

4. "write a Python function to sort a list"
   - Result: Triggered ✗
   - Fix: Added "This skill does NOT write new code"

5. "explain how Python decorators work"
   - Result: Did not trigger ✓

## Updated Description
description: Debugs Python errors, traces exceptions, and fixes bugs in Python code. This skill should be used when encountering Python errors, tracebacks, or exceptions. This skill does NOT write new Python code or explain Python concepts.

Negative test categories:

Reference: Anthropic Engineering: Agent Skills

Test Skill Activation with Real User Phrases

Before deploying a skill, test it with 10+ real user phrases to verify it activates correctly. Write down how users actually ask for this functionality, then verify each phrase triggers the skill.

Incorrect (no activation testing):

---
name: api-docs
description: Generates API documentation
---

# Deployed without testing
# User says "create swagger spec" - doesn't trigger
# User says "write OpenAPI" - doesn't trigger
# User says "document my endpoints" - doesn't trigger
# 3 of 4 common requests fail

Correct (systematic phrase testing):

# Activation Test Plan

## Test Phrases (should trigger)
1. "generate API docs" ✓
2. "create swagger spec" ✗ - Added "Swagger" to description
3. "write OpenAPI definition" ✗ - Added "OpenAPI" to description
4. "document my endpoints" ✓
5. "create API reference" ✗ - Added "API reference" to description
6. "/api-docs" ✓
7. "help me document this REST API" ✓
8. "I need documentation for my API" ✓

## Negative Tests (should NOT trigger)
1. "what does this API do?" ✗ (should not trigger - this is a question)
2. "call the API" ✗ (should not trigger - this is execution)

## Updated Description
description: Generates API documentation, Swagger specs, OpenAPI definitions, and API reference pages. This skill should be used when creating API docs, documenting endpoints, or writing API reference.

Testing process: 1. Write 10+ phrases users might say 2. Test each in Claude Code 3. Note which fail to trigger 4. Update description with missing keywords 5. Retest until all pass

Reference: Anthropic Engineering: Agent Skills

Include Error Patterns in Debugging Skills

For skills that help diagnose or fix errors, include common error message patterns in the description. Claude can then activate the skill when users paste error messages.

Incorrect (no error patterns):

---
name: typescript-debugger
description: Helps debug TypeScript code and resolve type issues.
---

# User pastes "Type 'string' is not assignable to type 'number'"
# Skill doesn't recognize this as its domain
# User must explicitly request TypeScript help

Correct (common error patterns included):

---
name: typescript-debugger
description: Resolves TypeScript compilation errors and type mismatches. This skill should be used when encountering type errors like "is not assignable to type", "Property does not exist", "Cannot find name", or TS error codes (TS2322, TS2339, TS2304).
---

# User pastes "Type 'string' is not assignable to type 'number'"
# Matches "is not assignable to type"
# Skill automatically activates to help

Error pattern strategies:

• Include exact error message substrings
• Reference error code prefixes (TS, E, ERRNO)
• Mention common symptom descriptions
• Include stack trace patterns if relevant

Reference: Anthropic Engineering: Agent Skills

Include File Type Patterns in Description

When a skill processes specific file types, mention those extensions and formats. Claude uses file context to select appropriate skills, so explicit file type mentions improve activation accuracy.

Incorrect (no file types mentioned):

---
name: spreadsheet-analyzer
description: Analyzes data and generates reports from spreadsheets.
---

# User has .xlsx file open - skill doesn't know
# User mentions "Excel file" - might trigger
# User mentions ".csv" - doesn't trigger
# File context not leveraged

Correct (explicit file types in description):

---
name: spreadsheet-analyzer
description: Analyzes data from Excel (.xlsx, .xls) and CSV files, generating statistical reports and visualizations. This skill should be used when working with spreadsheet files, Excel documents, or CSV data exports.
---

# User has .xlsx file - skill knows it applies
# User mentions "CSV" - skill triggers
# File context enables smart activation

File type patterns to include:

Reference: Claude Code Skills Docs

Include Slash Command Aliases in Description

When users might invoke your skill explicitly via slash command, mention that command in the description. This helps Claude recognize explicit invocations and provides discoverability.

Incorrect (no slash command mention):

---
name: commit-helper
description: Creates well-formatted git commits following conventional commit standards.
---

# User types "/commit" - skill doesn't trigger
# User types "use the commit skill" - might work
# Explicit invocation path is broken

Correct (includes slash command reference):

---
name: commit-helper
description: Creates well-formatted git commits following conventional commit standards. This skill should be used when the user wants to commit changes, types /commit, or asks to create a commit message.
---

# User types "/commit" - skill triggers
# User types "commit my changes" - skill triggers
# Both invocation paths work

Common slash command patterns:

• /commit - Git operations
• /review - Code review
• /test - Test running
• /deploy - Deployment
• /docs - Documentation generation

Reference: Claude Code Skills Docs

Cover Synonyms and Alternate Phrasings

Users describe the same task in many ways. Include synonyms, abbreviations, and alternate phrasings to maximize trigger coverage. Missing synonyms mean missed opportunities to help.

Incorrect (single phrasing only):

---
name: api-documentation
description: Generates API documentation for REST endpoints.
---

# "document my API" - triggers
# "create swagger docs" - doesn't trigger (Swagger not mentioned)
# "write OpenAPI spec" - doesn't trigger (OpenAPI not mentioned)
# "API reference" - doesn't trigger

Correct (synonyms and alternates included):

---
name: api-documentation
description: Generates API documentation, Swagger specs, and OpenAPI definitions for REST endpoints. This skill should be used when creating API docs, API reference documentation, Swagger documentation, or OpenAPI specifications.
---

# "document my API" - triggers
# "create swagger docs" - triggers (Swagger mentioned)
# "write OpenAPI spec" - triggers (OpenAPI mentioned)
# "API reference" - triggers (reference mentioned)

Synonym research process: 1. List 5-10 ways users might describe the task 2. Include industry jargon and casual terms 3. Add common abbreviations (API, DB, UI, PR) 4. Include tool names (Swagger, Postman, Jest) 5. Test with real user queries

Reference: Claude Code Skills Docs

Reference Workflow Stages in Description

Mention the workflow stage where your skill applies. Users often describe tasks in terms of workflow position ("before deploying", "after writing tests"). Stage references improve activation timing.

Incorrect (no workflow context):

---
name: code-linter
description: Checks code for style issues and potential bugs.
---

# User says "before I commit" - skill doesn't know
# User says "after making changes" - skill doesn't know
# Workflow timing unclear

Correct (workflow stages referenced):

---
name: code-linter
description: Checks code for style issues and potential bugs. This skill should be used before committing changes, during code review, or when preparing a PR for merge.
---

# User says "before I commit" - skill activates
# User says "review before merging" - skill activates
# Workflow-aware activation

Common workflow stage phrases:

Reference: Anthropic Engineering: Agent Skills