Creating Effective Skills

Creating Effective Skills

Guide for creating agent skills that follow Claude's official best practices.

Core Principles

Concise is Key: The context window is shared. Only add what Claude doesn't already know. Default assumption: Claude is already very smart.

Progressive Disclosure: Skills load in three levels:

1. Metadata (~100 tokens) - always loaded
2. SKILL.md body (100 lines, include table of contents at top.

Organize by domain when appropriate:

skill/
├── SKILL.md
└── references/
    ├── domain_a.md
    └── domain_b.md

Avoid: deeply nested references, duplicate information, generic file names.

Step 8: Create Test Scenarios (Optional)

Ask the user: "Would you like to create test scenarios for this skill? Test scenarios enable automated evaluation with /evaluating-skills-with-models to measure skill quality across different models (sonnet, opus, haiku)."

If the user agrees, create tests/scenarios.md for self-evaluation:

## Scenario: [Name]

**Difficulty:** Easy | Medium | Hard | Edge-case

**Query:** User request that triggers this skill

**Expected behaviors:**

1. [Action description]
   - **Minimum:** What counts as "did it"
   - **Quality criteria:** What "did it well" looks like
   - **Haiku pitfall:** Common failure mode for smaller models
   - **Weight:** 1-5 (importance)

**Output validation:** (optional)
- Pattern: `regex`
- Line count: `< N`

Why this format: Binary pass/fail doesn't differentiate models. Quality-based scoring reveals capability differences.

Step 9: Define allowed-tools

After completing SKILL.md and references, identify which tools the skill uses:

1. Review SKILL.md and reference files for tool usage
2. List tools that need pre-approval (e.g., Bash(git status:*), WebSearch, Skill(other-skill))
3. Add allowed-tools field to frontmatter if needed

---
name: skill-name
description: ...
allowed-tools: "Bash(git status:*) Bash(git diff:*) WebSearch"
---

This field is experimental but helps agents pre-approve tool access.

Important considerations:

• Read, Glob are already allowed by default - do not include
• Edit, Write are destructive - do not pre-approve
• Be as specific as possible with Bash subcommands
• Good: Bash(git status:*) Bash(git diff:*) Bash(git log:*)
• Avoid: Bash(git:*) (too broad, includes destructive operations like git push --force)

Anti-Patterns

❌ Windows-style paths (scripts\file.py) ❌ Too many options without a default ❌ Time-sensitive information ❌ Inconsistent terminology ❌ Deeply nested references ❌ Vague instructions

References

Progressive Disclosure: [references/progressive-disclosure.md](references/progressive-disclosure.md) - Detailed patterns and examples

Degrees of Freedom: [references/degrees-of-freedom.md](references/degrees-of-freedom.md) - Guidance on appropriate freedom levels

Workflows and Validation: [references/workflows-and-validation.md](references/workflows-and-validation.md) - Creating workflows with validation and feedback loops

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: taisukeoe
• Source: taisukeoe/agentic-ai-skills-creator
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.