What is the folder structure for a Claude Skill?

A Claude Skill directory must be kebab-cased and contain a required SKILL.md file, with optional folders for scripts/, references/, and assets/.

How does progressive disclosure reduce token costs?

By only loading Level 1 YAML metadata by default and only fetching Level 2 (SKILL.md) and Level 3 (linked files) when relevant, Claude reduces unnecessary context bloating, often saving up to 50% in tokens.

Mastering Claude Skills: The 33-Page Blueprint for AI Infrastructure

Sunday, February 15, 2026 — Anthropic has released a 33-page technical manual that fundamentally redefines the developer's role in the AI ecosystem. The guide, "The Complete Guide to Building Skills for Claude," moves beyond prompt engineering into the realm of AI Infrastructure.

The Anatomy of a Claude Skill

A Claude Skill is no longer just a text block; it is a structured directory that follows a strict naming convention. For Claude to recognize and utilize a skill, it must be contained within a kebab-case folder (e.g., `git-workflow-manager/`) with the following hierarchy:

📁 your-skill-name/
├── 📄 SKILL.md (Required, Case-Sensitive)
├── 📁 scripts/ (Optional: .py, .sh for validation)
├── 📁 references/ (Optional: API docs, guides)
└── 📁 assets/ (Optional: Templates, icons)

YAML Frontmatter Specifications

The `SKILL.md` file must begin with a YAML block. This block is the "Level 1" metadata that Claude's system prompt loads globally to decide when to trigger the full skill.

name: Must match the folder name exactly.
description: Max 1,024 characters. Must avoid XML tags and explicitly state trigger conditions (e.g., "Use when user requests a technical security audit").
allowed-tools: A security-first field to whitelist only specific MCP tools this skill can invoke.

Progressive Disclosure: The 50% Token Saver

The architectural breakthrough in this guide is the three-level disclosure system. This ensures Claude stays focused and cost-efficient by only loading what is necessary.

Level 1: Global

YAML metadata is always in context. Tells Claude when to wake up.

Level 2: Active

Full `SKILL.md` body is loaded only when triggered. Contains the core "how-to".

Level 3: On-Demand

Linked files in `references/` are read by Claude only if the task requires deep-dive data.

Impact: Anthropic benchmarks show that for complex project creation, this system reduced clarifies from 15 to 2 and slashed token consumption from 12,000 to 6,000.

The 5 Orchestration Patterns

Anthropic codifies five specific design patterns for building reliable AI agents:

1. Sequential Workflow Orchestration

Rigid, multi-step processes like customer onboarding or CI/CD pipelines.

Key Technique: Implement "Rollback Instructions" in your `SKILL.md` to define what Claude should do if step 3 fails after step 2 succeeds.

2. Multi-MCP Coordination

Workflows spanning multiple services (e.g., Figma -> Drive -> Linear -> Slack).

Key Technique: Use "Phase Separation" markers. Explicitly tell Claude to validate data from MCP-A before passing it to MCP-B.

3. Iterative Refinement

For high-stakes outputs where the first draft is never the final.

Key Technique: Define "Stopping Conditions" (e.g., "Stop after 3 iterations or when the validation script returns 0 errors").

4. Context-Aware Tool Selection

Dynamic decision-making based on file types or sizes.

Key Technique: Decision Matrices. Provide Claude with clear criteria (e.g., "If file > 5MB, use AWS S3; otherwise, use local storage").

5. Domain-Specific Intelligence

Embedding logic (like financial compliance) before tool calls.

Key Technique: "Pre-flight Compliance Checks." Force Claude to run a logic check in a linked script before authorizing a payment MCP tool call.

Production-Grade Reliability

Programmatic Validation

Vague instructions like "Double check your work" are deprecated. The guide mandates Programmatic Validation. Developers should include scripts in the `scripts/` folder and instruct Claude to run them. Example:

"Before finalizing the PR, run `python scripts/validate_lint.py` and resolve all Level 1 warnings."

Success Metrics (The 90/0 Rule)

Anthropic suggests tracking three primary KPIs for your Skills:

Skill Trigger Rate: Target 90%+ accuracy on relevant user queries.
API Call Success Rate: Target 0 failed API calls per workflow.
Token Efficiency: Measure context reduction compared to "Mega-Prompts."

Getting Started: The 'skill-creator'

To accelerate adoption, Anthropic provides the skill-creator meta-skill. By enabling it, you can prompt Claude: "Use skill-creator to architect a multi-agent skill for our HIPAA-compliant data pipeline."

Pro Tip: Skill Context Management

Keep your individual `SKILL.md` under 5,000 words. If you exceed this, offload detailed documentation to `references/` or split the skill into a "Skill Pack" to maintain high reasoning performance and low latency.

Internal Integration: When drafting your `SKILL.md` files, use ByteNotes to manage version control and collaborative editing before deploying to your MCP server environment.

Sources: Anthropic Official Technical Resources | Inspired by community discussion on r/ClaudeAI