How to Build and Use Claude Code Skills Like the 1%
Most developers treat Claude Code skills like a buffet — install hundreds from community marketplaces and hope for better output. The opposite approach works. This tutorial covers the architecture behind skills, demonstrates how progressive disclosure keeps context lean, and presents a framework for building a small, curated set that outperforms a bloated one.
*Understand what a skill actually is. A skill is a folder containing a required SKILL.md file and optional supporting directories: scripts/, references/, and assets/. The SKILL.md functions as a standard operating procedure — it tells Claude what to do, in what order, what good output looks like, and what to avoid. Supporting files supply the knowledge and tooling behind the process.
*Learn the three-layer skill architecture. Every skill operates across three layers: YAML front matter at the top of SKILL.md (a name and trigger description), the SKILL.md body (process instructions), and linked reference files (the knowledge base). Each layer serves a distinct purpose and loads at a different time.
*Grasp progressive disclosure. Claude does not ingest an entire skill when a conversation starts. Only the YAML front matter — name and description — enters the initial prompt. The SKILL.md body loads when Claude determines the skill is relevant. Linked files load only when SKILL.md explicitly directs Claude to read them.
*Examine a real skill. The Marketing Ideas skill by Cory Haynes demonstrates the architecture in practice. Its YAML front matter lists trigger phrases like “marketing ideas,” “growth ideas,” and “marketing strategies.” The body instructs Claude to check for a product marketing context file, then suggest three to five relevant ideas with implementation details.
*Install a community skill locally. Run npx skills add targeting the skill repository, use the -skill flag to specify the exact skill name, and add the local installation flag to place it in your project’s .claude/skills/ directory.
Warning: this step may differ from current official documentation —
see the verified version below.
*Apply the “point, don’t dump” principle. Keep SKILL.md concise. The Marketing Ideas skill lists category summaries in the body but stores all 139 tactics in a separate reference file. Claude reads that file only when a specific category becomes relevant, preventing unnecessary context bloat.
*Use multiple reference files strategically. The SEO Content Writer skill loads title-formulas.md during title ideation and content-structure-templates.md during content creation. Each file enters context only at its relevant phase rather than all at once.
*Bundle executable scripts for automation. Skills can include Python scripts that Claude runs with arguments. An image generation skill keeps its SKILL.md minimal — just instructions on when to call generate_image.py with specific prompts — while the script handles execution logic outside of context.
*Adopt the 1% framework. Start sourcing from Anthropic’s official skills, then browse SkillsMP (280,000+ skills) and Skill Hub (7,000+ AI-evaluated skills) — but resist mass-installing. Claude imposes a 15,000-character limit on skill descriptions in its initial context. Overlapping triggers cause skill cannibalization and unpredictable selection. Five to ten purpose-built, curated skills consistently outperform hundreds of generic installs.
How does this compare to the official docs?
Anthropic’s own skill-building guide covers the same architecture but includes specifications and conventions worth verifying against the patterns demonstrated here.
0 Comments