Claude Code: The Anatomy of a Skill

A Claude Code skill is more than what is inside the file.

Skills are not a flat list of instructions sitting in one folder. They have types and scopes. They sit in different locations depending on their purpose. And the relationship between skills and your documentation layer is not optional - it is what makes the whole system work.

This post breaks that architecture down - clearly.

The relationship that makes skills work

Before the structure, one framing matters more than anything else.

Every skill system rests on two layers that serve different functions:

/docs

Source of Truth

Truth without action is passive.

/skills

Source of Action

Action without truth is chaos.

Your /docs folder holds the standards - design decisions, architecture rules, how things should be built. It is prescriptive and passive. The agent reads it. It does not execute from it.

Your skills are where action lives. They take the standards in your docs and turn them into procedures - specific, executable, repeatable.

A skill without docs is an agent that acts without grounding.

Docs without skills are standards with no way to apply them.

Skills are the hands of your system. Docs are the mind. Neither works well without the other.

What a skill actually is

This distinction is worth making explicit, because the word “prompt” gets used for both:

A prompt is a one-time instruction. You write it now, for this task, in this session. When the conversation ends, it is gone. It does not improve over time unless you manually refine it.

A skill is a repeatable process. It is written once, stored in a specific location, and available to Claude every time that task comes up - regardless of session, regardless of context. It version-controls your expertise. It compounds.

The rule for when to build a skill is simple: when a task becomes repetitive, you turn it into a skill.

The trigger is repetition. The first time you do something, write a prompt. The second time, notice the pattern. The third time, build a skill.

Two types of skills

Claude Code has two distinct categories of skills. They serve different purposes and operate at different levels.

Built-in skills: the exploration layer

Built-in skills give Claude visibility into your project. They are the tools Claude uses to understand what it is working with before it acts.

Examples

ls - see the file structure
read_file - inspect file contents
grep - search across files

This layer is exploration - not execution. Claude uses these to orient itself - to understand the project, locate relevant files, confirm assumptions before doing anything.

Builders often overlook the importance of this layer because it is invisible. Claude is using these tools constantly in the background. The quality of the exploration layer directly affects how well Claude understands the task before it starts.

Custom skills: the orchestration layer

Custom skills give Claude control over your environment. These are the skills you build - specific to your project, your stack, your standards.

Examples

deploy_to_staging - safely push code through your deployment process
audit_accessibility - check UI compliance against your design standards
generate_api_types - create type-safe APIs from your schema

This layer is orchestration - turning insight into action. Where built-in skills help Claude understand, custom skills help Claude execute. The quality here depends entirely on how well the skills are designed.

Built-in skills are given.

Custom skills are earned - they reflect the work you have put into encoding your procedures.

Three scopes, three locations

Skills in Claude Code are not all stored in the same place. Where a skill lives determines when it is available - and what it applies to. There are three scopes.

Global skills

Location: ~/.claude/skills/ Activation: Always available - the “utility belt”

Global skills are foundational. They live in your home directory, not in any specific project, and they are available to Claude regardless of what project you are working in.

These are your personal standards and cross-project tools - the skills that apply everywhere. Formatting preferences, your personal workflow shortcuts, tasks you repeat across every project you touch.

Think of global skills as the things that belong to you as a builder, not to any single project.

Project skills

Location: /project-root/.claude/skills/ Activation: Loaded via the project root CLAUDE.md

Project skills are stack-specific. They live inside the project they belong to, and they are loaded when Claude reads the project’s CLAUDE.md at session start.

These are the skills that encode how this specific project works - its deployment process, its testing conventions, its design system audit procedure. Another project might have a deploy skill, but it would be a different one, with different logic, different checks, different targets.

Project skills travel with the codebase. When another developer clones the repo, they get the skills. When the project evolves, the skills evolve with it.

Local skills

Location: Inside specific project subfolders Activation: Triggered by location - Claude sees the local config and loads the relevant tools

Local skills are folder-specific. They activate based on where Claude is working within the project. If you have a /api folder with complex type generation logic, or a /components folder with its own audit requirements, a local skill can hold those procedures without affecting the project-wide skill set.

This scope is the most granular and the most often overlooked. It is most useful in large projects where different parts of the codebase have meaningfully different workflows.

How the scopes work together

The three scopes stack. When Claude starts working, it has access to all three - global skills for your personal toolkit, project skills for this codebase, and local skills for the specific folder being worked in.

Local Folder-specific tools. Loaded by location.

Project Stack-specific tools. Loaded via CLAUDE.md.

Global Foundational tools. Always available.

When the same skill name exists at multiple scopes, the more specific scope wins. A local skill overrides a project skill with the same name. A project skill overrides a global one. This is how you maintain consistent defaults while allowing specific overrides where needed.

Where to start

If you are building your skills layer for the first time, the scope hierarchy gives you a natural build order.

Start with global skills - the personal tools and preferences that travel with you everywhere. These are the fastest to build and immediately useful.

Then build project skills for the work you repeat most often in your current project. Deployment, testing, component generation - whatever your high-frequency tasks are.

Local skills come last, and only when a specific part of the codebase genuinely needs a different set of procedures from the rest.

Do not build the full skills architecture before you need it. Build the skill when the task becomes repetitive. The structure will emerge from the actual work.

The SKILL.md Starter at AOL 4 gives you a working example - a real code review skill with each section annotated - so you can see what a finished skill looks like before you write your own.

The AI Setup Snapshot includes your AOL layer depth - including how much of the skills infrastructure you currently have in place and what adding the next layer would look like in practice.

This series started with why skills exist and where they fit in the orchestration stack. It covered how to design them well enough to hold up at scale. This post walked through the specific structure Claude Code uses to organize and activate them.

The architecture is straightforward once you see the full picture. The work is in building the skills themselves - one repeated task at a time.

Blueprint

Lead Scraper Blueprint

Extract leads from any directory automatically. Runs on a schedule, deduplicates itself, drops output into your pipeline.

Get the blueprint →