Every time you open Claude and ask it to create a Word document, build a data analysis pipeline, or write presentation slides — something invisible happens first. Claude scans a directory of skills, finds the most relevant one, reads it, and only then starts working.

This system is called Claude Skills. It is one of the most underappreciated features in the entire Claude ecosystem. And once you understand how it works, you will see why it changes everything about how you build AI-powered workflows.

“Skills are how Claude learns domain-specific workflows without retraining. They are runtime instructions, not model weights.”

What Is a Skill?

A skill is a directory containing a SKILL.md file (and optionally supporting assets, scripts, and reference documents). When Claude starts handling a request, it reads the name and description of every available skill. If a description matches the current task, Claude loads the full SKILL.md body and follows its instructions.

Think of it like a context-sensitive manual. When a carpenter picks up a dovetail saw, they know exactly how to use it — not because they memorised every detail about every tool upfront, but because they learned the right technique for the right moment. Skills work the same way for Claude.

The Three-Layer Loading System

Skills use progressive disclosure — Claude never loads everything at once. There are three distinct layers, each loaded only as needed:

This is elegant engineering. Layer 1 is tiny — just enough for Claude to decide whether a skill applies. Layer 2 gives full instructions once relevant. Layer 3 provides deep reference material only when needed, keeping context usage lean.

Anatomy of a Skill Directory

A skill is a folder with a predictable structure. Here is the full layout:

Only SKILL.md is required. Everything else is optional and only loaded when the skill itself explicitly references it.

Inside SKILL.md — The Configuration Fields

The file starts with a YAML frontmatter block (between — delimiters), followed by markdown instructions. Here is every supported field:

KEY INSIGHTThe description field is the most important part of any skill. Claude decides whether to load your skill based solely on this field — the body never loads unless the description matches. Write it with real triggers, real contexts, and a slight “push” to combat under-triggering.

A Minimal Skill — Step by Step

Let’s build a real skill from scratch. Imagine you regularly need to convert raw PostgreSQL query results into nicely formatted Markdown reports. Here is how to package that as a skill.

Step 1 — Create the directory

mkdir pg-report-skill
cd pg-report-skill
touch SKILL.md

Step 2 — Write the frontmatter

---
name: pg-report
description: |
  Converts raw PostgreSQL query results into formatted Markdown reports
  with tables, summary stats, and query metadata. Use whenever the user
  pastes SQL output, mentions "format this query result", or wants to
  turn database output into a readable report or document. Also trigger
  when user asks to summarise a dataset from a .csv or .tsv that looks
  like a DB export.
---

TIP: WRITE THE DESCRIPTION LIKE A TRIGGER RULESETNotice how the description lists multiple phrasings (“pastes SQL output”, “format this query result”, “summarise a dataset”). This breadth is intentional — Claude uses fuzzy matching, so covering several natural phrasings dramatically improves trigger reliability.

Step 3 — Write the skill body

# PostgreSQL Report Formatter
## What this skill does
Formats raw PostgreSQL tabular output into clean Markdown reports.
## Required output sections
1. A ## Summary block: row count, column count, date range (if present)
2. A ## Data block: full Markdown table with aligned columns
3. A ## Observations block: 3-5 key insights from the data
## Formatting rules
- Numeric columns: right-align, add thousand separators
- Date columns: format as YYYY-MM-DD
- NULL values: render as `—` (em dash), never blank
- Column headers: Title Case
## Example input

id | user_name | total_orders | revenue —-+———–+————–+——— 1 | alice | 12 | 4500.00 2 | bob | 3 | 890.50

## Example output
### Summary
- **Rows:** 2  |  **Columns:** 4  |  **Total revenue:** $5,390.50
### Data
| ID | User Name | Total Orders | Revenue |
|----|-----------|-------------:|--------:|
|  1 | Alice     |           12 | $4,500.00 |
|  2 | Bob       |            3 |   $890.50 |

Step 4 — Add a reference file (optional)

If your skill needs to handle multiple database types — PostgreSQL, MySQL, SQLite — you can create a references/ folder and have the skill body instruct Claude to load the right one:

In your SKILL.md body, you then write:

## Database-specific rules
Detect which database produced the output from syntax clues.
- If `||` concatenation → read references/sqlite.md
- If `AUTO_INCREMENT` → read references/mysql.md
- Default → read references/postgres.md

Claude will read only the relevant file, keeping the context window lean and responses accurate.

Real-World Example: The Built-in DOCX Skill

Claude ships with several built-in skills. The docx skill is a great example of production-quality configuration. Here is its description field, distilled:

description: |
  Use this skill whenever the user wants to create, read, edit, or
  manipulate Word documents (.docx files). Triggers include: any
  mention of 'Word doc', 'word document', '.docx', or requests to
  produce professional documents with formatting like tables of
  contents, headings, page numbers, or letterheads. Also use when
  extracting content from .docx files, inserting images, performing
  find-and-replace, working with tracked changes, or converting
  content into a polished Word document.

Notice the pattern: the description is almost a checklist. Every plausible user phrasing that should trigger the skill is listed. This is intentional — Claude has a natural tendency to under-trigger skills, so descriptions are deliberately thorough.

WARNING: AVOID GENERIC DESCRIPTIONS

A description like “Helps with documents” will rarely trigger. Claude needs enough specificity to distinguish your skill from general knowledge. Name the exact task, the exact file types, and the exact user phrases that should activate it.

The Progressive Disclosure Principle

The most important architectural decision in skill design is knowing what goes where. The three-layer rule is simple:

1. Description = triggering logic only

Never put instructions in the description. It exists solely to help Claude decide whether to load the skill. Keep it focused on “when to use” language, not “how to do”.

2. SKILL.md body = core workflow

Put the main instructions, output format rules, required sections, formatting guidelines, and examples here. Target under 500 lines. If you need more, move deep content into reference files.

3. References + scripts = deep knowledge

Detailed documentation, database-specific rules, platform-specific templates, and executable scripts go in subfolders. The SKILL.md body tells Claude when to read them.

Writing Descriptions That Actually Trigger

The description field is the hardest part to get right. Here is a battle-tested template:

description: |
  [What the skill does in one sentence].
  Use this skill when: [scenario A], [scenario B], [scenario C].
  Also trigger when the user [natural phrase], [natural phrase],
  or mentions [keyword / file type / tool name].
  Do NOT use for [explicit exclusion to avoid false positives].

And a concrete example for a “Java Code Review” skill:

description: |
  Reviews Java source files for correctness, performance, thread
  safety, and style — producing structured inline feedback.
  Use whenever the user shares Java code and asks for review,
  feedback, improvements, or a PR review. Also trigger on phrases
  like "check my code", "what's wrong here", or "how can I improve
  this" when the code is Java. Trigger on .java files even without
  an explicit review request.
  Do NOT use for Kotlin, Scala, or general architecture questions
  without code attached.

When Skills Use Scripts

For deterministic or repetitive transformations — file conversions, data extraction, package generation — skills can include executable scripts. Claude reads the script path from the SKILL.md body, runs it via the bash tool, and uses the output.

The built-in docx skill, for example, uses a Python script to write .docxfiles using the python-docx library. The skill body contains step-by-step instructions for calling the script correctly — Claude follows them at runtime.

## Creating a DOCX file
1. Generate Python code using python-docx from the template at
   scripts/create_doc.py
2. Run: python scripts/create_doc.py output.docx
3. Copy result to /mnt/user-data/outputs/
4. Present to user with present_files tool

Testing Your Skill

Before deploying, write 5–10 test prompts that should trigger your skill, and 3–5 that should not. Run Claude with the skill installed and check whether it loads correctly.

Good test prompts for a “pg-report” skill:

# Should trigger:
"Here's my query result, can you format it nicely?"
"Turn this SQL output into a report"
"I exported this CSV from my database, summarise it"
# Should NOT trigger:
"How do I write a JOIN query?"
"What is normalisation in databases?"

PRO TIP: QUANTITATIVE EVALUATIONIf you are building skills at scale, the skill-creator meta-skill includes an automated optimization loop. It splits your test set 60/40 (train/held-out), runs Claude against each case multiple times, proposes description improvements, and iterates up to 5 rounds — outputting the best-performing description with before/after scores.

Packaging and Sharing Skills

A finished skill can be packaged into a .skill file for distribution. Anyone can install it by dropping the file into their skills directory. The package script handles archiving:

python -m scripts.package_skill path/to/pg-report-skill/
# → outputs pg-report-skill.skill

The Bigger Picture

Skills are not just a convenience feature. They are the mechanism by which Claude becomes domain-aware without retraining. A legal firm can build a contract-review skill. A data team can build a dashboard-generation skill. A game studio can build a Godot export skill. Each one runs inside the same Claude — just with different runtime instructions.

The architecture is deliberately modular. Skills compose. A single request might trigger the pdf-reading skill to extract content, then the docx skill to write the output. Each stays in its lane, and Claude orchestrates.

“You don’t teach Claude new tricks by changing the model. You teach it by writing better skills.”

For solo developers and small teams, this is genuinely powerful. You can codify your best workflows once, as a skill, and they run reliably on every request — without prompting, without repetition, and without hoping Claude happens to “know” your preferred format.

Start small. Pick one workflow you repeat every week. Write a 30-line SKILL.md. Test it on five prompts. Then iterate. That is all it takes to start building your own personalised AI toolkit.

RESOURCESThe skills discussed in this article — including docx, pdf, pptx, xlsx, and skill-creator — are built into Claude’s computer-use environment. You can explore them at /mnt/skills/public/ in any Claude session with computer use enabled.

The Agentic Loop (How Claude Actually Thinks)

Before anything else, you need to understand what makes Claude Code different from your IDE’s autocomplete. Autocomplete guesses the next word. Claude Code runs a loop — it gathers context, takes action, verifies results, then repeats until the task is done. Think of it less like a text editor feature and more like a developer who works asynchronously while you make coffee.

The loop has three phases that blend together depending on the task:

The loop adapts to what you ask. A question might only hit phase 1. A bug fix cycles through all three phases multiple times. A full feature might chain dozens of tool calls before Claude surfaces for air. You’re part of the loop too — you can interrupt at any point with Ctrl+C and steer it in a different direction.

THE HONEST SUMMARY

Claude Code is basically a language model with access to your entire computer strapped to it. It can read everything, run anything you could run from a terminal, and it just keeps going until it either finishes the task or you tell it to stop. This is either exhilarating or terrifying depending on how much you trust your test coverage.

Sessions & How Claude Remembers (Or Doesn’t)

Here’s the thing about Claude: every session starts with a completely blank memory. No recollection of last week’s chat. No memory of that convention you mentioned. Tabula rasa. Every. Single. Time. If you don’t explicitly persist knowledge, it’s gone when the session closes.

This isn’t a bug — it’s how LLMs work. But Claude Code gives you two mechanisms to work around it:

How a session actually starts

When you run claude in a directory, here’s what happens in the first few seconds before you’ve typed anything:

1. **Settings load (all scopes)**Global ~/.claude/settings.json → project .claude/settings.json → local .claude/settings.local.json. Scalar settings use the most specific value; array settings (like permissions) merge across all scopes.
2. MCP servers connectAll configured MCP servers from .mcp.json and ~/.claude.json start up. Tool schemas are deferred and load on demand. If a server fails to connect, Claude continues without it — it just loses those tools.
3. CLAUDE.md files load into contextOrg-level → user-level (~/.claude/CLAUDE.md) → project-level (./CLAUDE.md) → local (./CLAUDE.local.md). Plus your ~/.claude/MEMORY.md auto memory. All of this costs context window tokens immediately.
4. Plugins activateAll enabled plugins load their skills, hooks, MCP servers, and settings. Run /reload-plugins to activate changes mid-session.
5. Session is readyYou see the prompt. Everything above has already happened. Claude now has your project context and is ready to work.

CONTEXT WINDOW BUDGET

Everything loaded at startup costs tokens before you type a single character. A bloated CLAUDE.md, a dozen MCP servers, and a large MEMORY.md can eat a significant chunk of your context window. Run /status to see current token usage. Use /compact when a session gets long.

The .claude Directory — Every Folder Explained

The .claude/ folder is Claude Code’s configuration home in your project. There’s also ~/.claude/ in your home directory for global settings. Here’s the complete layout with every file and folder you’ll actually encounter:

COMMIT STRATEGY

Everything marked committed should go in Git so your whole team gets the same Claude setup. Everything marked gitignored is personal — Claude automatically adds settings.local.json to your global Git ignore. Add CLAUDE.local.md to your project’s .gitignore manually.

CLAUDE.md — The Full Story

You’ve heard about CLAUDE.md. Everyone mentions it. But few people explain the entire system behind it, which has four separate scope levels that load in a specific order:

They load in that order — managed first, local last. More specific scopes appear later in the context window, giving them higher effective priority.

What to actually put in CLAUDE.md

The golden rule: add something to CLAUDE.md when Claude makes the same mistake a second time. Here’s a battle-tested example for a Spring Boot project:

SIZE MATTERS

Target under 200 lines per CLAUDE.md. Longer files still load fully but adherence drops. If it’s getting long, split topic-specific rules into .claude/rules/ files and skills for complex procedures — they load conditionally and save your context window.

Auto Memory (MEMORY.md)

This is the magical part most people miss. Claude can write its own notes — automatically. When you correct Claude, it optionally remembers that correction for next session in ~/.claude/MEMORY.md. The first 200 lines or 25KB load at the start of every session.

Enable it with /memory in session or toggle it in settings. Then: tell Claude something once, it remembers it forever (until you delete the entry). This is how you get a Claude that feels like it’s been on your team for months.

settings.json — The Enforcement Layer

There’s a critical distinction most people miss: CLAUDE.md is guidance Claude reads.settings.json is configuration Claude Code enforces. One is a polite suggestion. The other is a locked door.

Settings live in .claude/settings.json (project/team) and .claude/settings.local.json(personal overrides). Here’s what you can configure:

ALLOW VS DENY PRECEDENCE

Deny rules always win over allow rules. If you allow Bash(kubectl *) and deny Bash(kubectl delete *), the delete command is blocked. Patterns support wildcards — Bash(npm test *)matches any command starting with npm test.

rules/ — Scoped Instructions That Load On Demand

Once your CLAUDE.md hits 200 lines, start splitting it into .claude/rules/. Rules are Markdown files that can load conditionally based on which files Claude is working with — only when it reads a file that matches the rule’s path pattern. This keeps your global context lean while ensuring Claude gets the right rules at the right time.

THE REAL POWER

A rule file without paths: frontmatter loads every session like CLAUDE.md. A rule WITH paths:only loads when Claude reads a matching file. This means your Kafka rules don’t eat context window during a CLAUDE.md update, and your migration rules only appear when Claude actually opens a migration file.

skills/ — Your Custom Slash Commands

Skills are reusable prompts you or Claude can invoke by name using /skill-name. Think of them as saved workflows — things you do repeatedly that are more than a one-liner but less than a custom tool. You write the instructions once in a SKILL.md, and invoke it whenever you need it.

Now you type /db-migrate and Claude walks through all seven steps. No more explaining the process from scratch every time. Skills also accept arguments via $ARGUMENTS:

Usage: /review-pr 127 — Claude reviews MR #127 with your exact conventions baked in.

SKILLS VS COMMANDS

You may see references to .claude/commands/ in older docs — this is the same mechanism as skills. For new workflows, use skills/ instead: same /name invocation, plus you can bundle supporting files alongside the SKILL.md.

Hooks — The Automation Engine

Hooks are shell commands that fire automatically at specific points in Claude’s lifecycle. They’re deterministic — they always run when triggered, regardless of what Claude decides. This is the difference between “please format the file” (Claude might forget) and “PostToolUse hook runs Spotless” (it definitely happens).

Available hook events

PreToolUseFires before any tool call. Can block execution (exit 2). Use to protect files or validate commands.

PostToolUseFires after a tool completes. Perfect for auto-formatting files after Claude edits them.

NotificationFires when Claude needs your input. Desktop notification so you don’t stare at the terminal.

SessionStartFires when a session begins. Inject additional context, set environment, run setup scripts.

PreCompactFires before conversation compaction. Re-inject context that would otherwise be lost.

StopFires when Claude finishes a response. Useful for post-response validation or logging.

Practical examples for a Java/Spring Boot project

EXIT CODES MATTER

exit 0 = allow. exit 1 = warn Claude but let it continue. exit 2 = hard block — Claude gets told why and has to try something else. It’s the digital equivalent of a bouncer who also explains the dress code.

MCP — Connecting Claude to the World

Model Context Protocol (MCP) is an open standard for connecting AI to external tools. Without MCP, Claude can only see your filesystem and run terminal commands. With MCP, Claude can query your Jira board, check Sentry errors, read Slack messages, query your PostgreSQL database, and more — all without you copying and pasting anything.

THE MENTAL MODEL

MCP is how Claude gets a login to your tools. Without it: “here’s a pasted error from Sentry.” With it: “Claude, check what errors happened in prod in the last hour and correlate them with my recent commits.”

Three types of MCP servers

Project-scoped MCP (.mcp.json)

Put your team’s MCP servers in .mcp.json at the project root. This file gets committed to Git so everyone on the team gets the same tools:

User-scoped MCP (personal tools)

For tools only you need (not your team), use the –scope user flag. This writes to ~/.claude.json instead of .mcp.json:

CHANNELS: MCP THAT PUSHES TO CLAUDE

Normal MCP is pull — Claude queries a server when it needs something. Channels flip this: an MCP server pushes messages into your running session. This means Claude can react to CI results, monitoring alerts, or Slack messages while you’re doing something else. Enable with –channelsflag on startup.

Plugins — Package & Share Everything

Everything you’ve built — skills, hooks, MCP servers, rules — can be packaged into a plugin and shared with your team, your org, or the whole world. Plugins are just directories with a .claude-plugin/plugin.json manifest. They’re the difference between “config that lives in one project” and “config that lives everywhere.”

Standalone config vs plugins

Plugin structure

Installing a plugin

THE REAL VALUE

Your platform team builds a plugin once with all the Spring Boot conventions, Kafka rules, code review skills, and MCP servers your org uses. Every developer installs it once. Every project gets the same setup. No more “did you add the Flyway rules to your CLAUDE.md?” Slack messages.

Subagents — Claude Spawning Claude

This is the part where things get genuinely science-fiction. Subagents let Claude spin up other Claude instances to handle subtasks in parallel or in isolated contexts. The main Claude orchestrates; the subagents execute. Think distributed computing, but the workers are also AI and can also spawn more workers.

Subagents can maintain their own MEMORY.md too. Imagine a “database specialist” subagent that remembers every schema change it’s ever helped with. That’s the direction this is heading.

WHEN TO USE SUBAGENTS

For most day-to-day tasks, you don’t need subagents. They’re most useful when you have truly parallel workstreams (implement feature A and feature B simultaneously without conflicts), when you need a clean context for a specific task, or when you’re building automation pipelines that run without human interaction.

Complete Quick Reference

• .claude/settings.json — permissions + hooks + model config. Enforced, not just read.
• CLAUDE.md — persistent instructions. Team version in ./CLAUDE.md, personal in ~/.claude/CLAUDE.md.
• MEMORY.md — auto-written by Claude. Persists learnings across sessions (200 lines / 25KB limit).
• .claude/rules/ — conditional instruction files. Use paths: frontmatter to load only for relevant files.
• .claude/skills/ — custom /commands. Each skill = a folder with SKILL.md. Accepts $ARGUMENTS.
• hooks — deterministic automation. PreToolUse (block/allow), PostToolUse (format), Notification (alert).
• .mcp.json — team MCP servers (committed). ~/.claude.json for personal servers.
• Plugins — packaged, shareable bundles of skills + hooks + MCP + settings. Install with /plugin install.
• Subagents — parallel Claude instances for complex multi-track workflows. Three isolation levels.
• /init — always run first in a new project. Generates CLAUDE.md automatically.
• /compact — compresses long sessions. /clear = fresh start (CLAUDE.md reloads).
• /mcp — shows server status + tool count. /hooks — shows configured hooks. /memory — edit CLAUDE.md.