Claude Code Skills: Why Less Is More and How to Build the Right Ones

By James Aspinwall, co-written by Alfred Pennyworth (my trusted AI) — March 5, 2026, 15:07

A recent video breaks down what Claude Code skills actually are, why most people use them wrong, and how to build a small, high-quality library that works reliably. The core argument: stop installing hundreds of marketplace skills. Build 20–30 good ones instead. Here’s the full breakdown.

What a Skill Actually Is

A skill is not a fancy system prompt. It’s a folder with step-by-step instructions on how to create something valuable — effectively a standard operating procedure (SOP) for the agent.

A standard skill folder contains:

skill.md — The core file. YAML front matter (name, description) at the top, process instructions in the body. This is the SOP: what to do, in what order, what good output looks like, what to avoid.
Reference files — Large knowledge bases, examples, templates. A marketing skill might have a 139-item catalog of marketing ideas in a separate file, only loaded when needed.
Scripts — Executable code (Python, etc.) called from the skill instructions with arguments passed in. Used for things like image generation or file manipulation.
Assets — Example outputs, style guides, artifacts that show Claude how results should look.

The key insight is separation of concerns. Process lives in skill.md. Knowledge lives in reference files. Execution lives in scripts. When something goes wrong, you know where to look.

Progressive Disclosure: The Architecture That Makes It Work

Claude doesn’t load all your skills into context at once. It uses progressive disclosure — the right information at the right time.

Layer 1 — Always loaded: Only the YAML front matter (name and description) of each installed skill. This is the “menu” Claude scans to decide which skill is relevant. It’s a few lines per skill.

Layer 2 — Loaded on activation: When Claude decides a skill matches the task, it loads the full skill.md body — the process instructions.

Layer 3 — Loaded on demand: Reference files and assets are pulled in only when the process explicitly tells Claude to use them. The skill says “now read the title-ideas reference” at the step where titles matter, not at the beginning.

This is the “point, don’t dump” pattern. An SEO content writer skill might have one reference file for title ideation and another for content structure. The process file tells Claude which reference to pull depending on the current step.

This architecture means you can install many skills without bloating context — because Claude only sees names and descriptions until it needs more.

Skills as a New Software Layer

Here’s where it gets interesting beyond mechanics.

When Anthropic launched Co-Work and its plugins feature (bundles of skills, agents, hooks, and commands) in early 2026, markets reacted sharply. An estimated $285 billion was wiped off large software companies like Intuit, Adobe, and Salesforce as investors realized that an AI agent with the right skills could replace parts of multiple paid tools.

SaaS isn’t dead, but the valuation model is broken:

A lead generation skill replaces parts of a traditional outreach stack.
A content creation skill replaces a standalone copywriting product.
An SEO skill replicates chunks of what Ahrefs or Surfer do.

Skill marketplaces are exploding. SkillsMap has over 280,000 skills indexed from GitHub. SkillHub offers more than 7,000 AI-evaluated skills. Platforms like Stripe, Cloudflare, and Vercel ship their own skills that interact with their APIs directly — a Stripe “best practices” skill lets Claude read Stripe docs and reason about integration from within the agent.

The thesis: anyone can install generic skills, but encoding your own domain expertise, brand voice, and processes into custom skills creates durable value. That’s the defensible moat — not having skills, but having the right skills built properly.

Why More Skills Is Usually Worse

This is the section most people need to hear.

The activation problem: Claude decides which skill to use by scanning the name and description of every available skill. More skills means a noisier menu. Anthropic’s documentation states a roughly 15,000-character limit for the entire available-skills list. Stuffing it with hundreds of skills consumes valuable context and can lead to truncation and overlap.

The overlap problem: Multiple SEO skills, multiple writing skills, multiple deployment skills — they compete with each other. Claude sometimes picks one, sometimes another, yielding inconsistent behavior.

The monolith problem: Many marketplace skills cram all knowledge into a single skill.md with no reference files. When output is bad, you can’t tell if the process is wrong or the knowledge is outdated, and you can’t update them independently.

The numbers: In a test measuring skill activation rates, with a basic setup and weak description, Claude only activated the intended skill about 20% of the time. Even with good hooks and well-tuned descriptions, the best rate was around 84% — roughly one in five attempts still failed. With four or five skills. Now imagine hundreds.

The recommendation: maintain roughly 20–30 well-isolated, carefully described skills tightly aligned to your workflows. A curated set will dramatically outperform a huge generic collection in both reliability and output quality.

Where to Get Skills

Three sources, each with trade-offs:

1. Anthropic’s Official Skills

Good exemplars of robust architecture. Primarily focused on document transformation (PDF, DOCX). Install via:

npx skills add @anthropic/pdf

Add -g for global availability across all projects.

2. Community Marketplaces (SkillsMap, SkillHub)

Browse by category, use case, or role. Everything you could want is there. But exercise caution: blindly installing large bundles creates activation conflicts, quality issues, and debugging headaches. Many community skills don’t follow best-practice architecture — everything crammed into one file, no separate references.

3. Your Own Custom Skills

This is where the real value lives. Only you have your specific domain expertise, process details, and brand voice. The secret isn’t having the most skills — it’s having the right skills, built to a consistent convention.

How to Build Skills: The Framework

The video recommends using a “skill builder” meta-skill that creates other skills according to the recommended pattern:

Process instructions in skill.md — clear, ordered steps with human-in-the-loop decision points.
Reference knowledge in separate files — pointed to by skill.md using the “point, don’t dump” approach.
Scripts only when you need actual code execution — kept separate from process and knowledge.

Install the meta-skill:

npx skills add @glittercowboy/agent-skill

Add -d local for project-only installation, omit for global.

Once installed, prompt Claude to “create a skill” and it follows the convention automatically instead of inventing ad-hoc layouts.

Debugging and Iteration

The separated architecture makes debugging straightforward:

Skill doesn’t follow the process correctly? Fix skill.md (process).
Skill lacks information or misinterprets context? Add or update reference files (knowledge).
Skill needs to execute something it can’t? Add a script (execution).

Start simple. Use front matter as the concise summary Claude sees. Put your deep expertise and brand nuance into references. Add scripts gradually as needed.

What This Means for Us

At WorkingAgents, this maps directly to how we think about agent access control. Skills are organized expertise that plug into Claude Code. But expertise without boundaries is dangerous:

A skill that can read Stripe docs should not also have access to your production database.
A skill that generates marketing content should not be able to deploy to your website.
A skill builder meta-skill should not have access to modify other skills in production.

The keycard model applies here too. Each skill should operate with the minimum permissions needed for its task. Progressive disclosure isn’t just about context management — it’s a security pattern. Load only what’s needed, when it’s needed, with only the access required.

Skills are the building blocks of the agentic economy. Build fewer. Build better. Build them with guardrails.

James Aspinwall is the developer of WorkingAgents, an AI consulting firm specializing in agent integration and access control for medium-size companies.