Skill Best Practices

This guide covers best practices for creating effective AI skills, based on the agentskills.io specification and Anthropic's official guidance.

Key Principle: Claude is already very smart. Only add context that Claude doesn't have—your company's specific conventions, proprietary workflows, or domain knowledge.

SKILL.md Structure

Required Frontmatter

Per the agentskills.io specification, only two fields are required in SKILL.md frontmatter:

---
name: reviewing-code
description: Reviews code for quality and security issues. Use when examining PRs or auditing codebases.
---

Name Field

1-64 characters maximum
Lowercase alphanumeric and hyphens only
No leading, trailing, or consecutive hyphens
Must match the parent directory name
Use gerund form (verb + -ing) for better discoverability:
- ✅ reviewing-code, processing-pdfs, analyzing-security
- ❌ code-reviewer, pdf-tool, security

Description Field

1-1024 characters maximum
WHAT + WHEN format: Explain what the skill does AND when to use it
Third-person voice: "Reviews code..." not "I review code..."
Include relevant keywords for discovery

Good descriptions:

✅ "Extracts text and tables from PDF documents. Use when working with PDF files that need parsing."
✅ "Generates comprehensive test suites for code. Use when creating unit tests or improving coverage."

Avoid:

❌ "I help you review code" (first-person)
❌ "PDF processing tool" (no WHEN clause)
❌ "This skill is useful for..." (verbose)

Optional Frontmatter Fields

license - License name (max 500 characters)
compatibility - Environment requirements (max 500 characters)
metadata - Key-value pairs for custom properties
allowed-tools - Pre-approved tools (experimental)

Keep It Concise

500-Line Limit: The agentskills.io specification recommends keeping SKILL.md under 500 lines. This prevents context window bloat and ensures Claude loads your skill efficiently.

Progressive Disclosure

Skills use a progressive disclosure architecture to minimize token usage:

Level 1 - Metadata (~100 tokens): Name and description are pre-loaded at startup. Claude uses this to determine when a skill is relevant.
Level 2 - Instructions (<5000 tokens): Full SKILL.md content loads when the skill is activated.
Level 3 - Resources (on-demand): Files inreferences/ and scripts/ load only when needed.

Move Details to References

If your skill needs extensive documentation, move it to references/:

my-skill/
├── SKILL.md              # Core instructions (<500 lines)
├── references/
│   ├── patterns.md       # Detailed patterns (loaded on-demand)
│   ├── examples.md       # Extended examples
│   └── api-reference.md  # API documentation
└── scripts/
    └── helper.py         # Executable scripts

Effective Instructions

Be Specific, Not Generic

Claude already knows general programming concepts. Focus on what makes YOUR skill unique:

❌ Too Generic

"Review code for bugs and issues. Look for common problems. Suggest improvements."

✅ Specific

"Check for SQL injection in database queries. Verify all user input is parameterized. Flag any string concatenation in SQL statements."

Provide Feedback Loops

Build in validation steps so Claude can verify its work:

## Instructions

1. Generate the test file
2. Run `python scripts/validate.py` to check syntax
3. If validation fails, fix the issues and re-validate
4. Only mark complete when validation passes

Include Examples

Concrete input/output examples help Claude understand the expected behavior:

## Examples

### Example: Security Review
User: "Check this login function for vulnerabilities"

Expected behavior:
1. Identify SQL injection risk in the query
2. Suggest parameterized queries
3. Note missing rate limiting
4. Recommend secure password hashing

Scripts and Execution

Use Scripts for Deterministic Operations

Bundle scripts in scripts/ for operations that don't require LLM reasoning:

File format conversion
Data validation
Syntax checking
API calls with fixed parameters

Note: Scripts are executed by the AI agent using its tools (like Bash). The agent reads the script output, but the script code itself doesn't consume context tokens. This is more efficient for deterministic operations.

Script Best Practices

Include clear --help output
Return structured output (JSON preferred)
Handle errors gracefully with clear messages
Document dependencies in skill metadata

Testing Your Skill

Test with Multiple Models

Per Anthropic's guidance, test your skill with different Claude models:

Claude Haiku: Fast, affordable. If your skill works here, it's well-structured.
Claude Sonnet: Balanced performance. Most common production use.
Claude Opus: Most capable. Handles complex reasoning.

A skill that only works on Opus might have instructions that are too vague.

Iterate Based on Real Usage

Start with minimal instructions
Test with real tasks
Add guidance only when Claude makes mistakes
Remove guidance that doesn't improve results

Security Considerations

Skills Can Be Dangerous

Skills can instruct AI agents to run commands, read files, and make network requests. Malicious skills could:

Exfiltrate environment variables (API keys, secrets)
Install backdoors
Modify git configuration
Access sensitive files

For Skill Authors

Never hardcode secrets or credentials
Avoid dangerous shell patterns (curl | bash)
Don't access sensitive paths unless necessary
Document any permissions your skill requires
Keep scripts focused and auditable

For Skill Users

Read SKILL.md before installing
Prefer verified publishers
Check community signals (downloads, reviews)
Pin versions for critical workflows
Use aster audit to scan installed skills

Common Mistakes

❌ Including time-sensitive information

Don't reference "latest version" or specific dates. Skills should be timeless.

❌ Over-explaining obvious things

Claude knows how to write code, use git, and follow common patterns. Only explain what's unique.

❌ Deep reference chains

Keep references one level deep. Don't create references that reference other references.

❌ Putting everything in SKILL.md

Move detailed documentation to references/. Keep SKILL.md under 500 lines.

Quick Reference

Aspect	Recommendation
Naming	Gerund form (`reviewing-code`)
Description	WHAT + WHEN, third-person
SKILL.md length	<500 lines
Instructions	<5000 tokens recommended
References	One level deep only
Testing	Haiku → Sonnet → Opus
Frontmatter	Only `name` + `description` required