Interviewer's Skepticism: After Six Months with Claude Code, Do You Really Understand Skills?

What a skill really is

A skill is a folder, not a single markdown file. The folder must contain SKILL.md (the only required file) and can optionally include references/, scripts/, and assets/ sub‑folders. The SKILL.md front‑matter holds the name and a description, while the body provides step‑by‑step instructions, a “gotchas” list, and any auxiliary files.

deploy-service/
├── SKILL.md               # name, description, steps, gotchas
├── references/            # extra docs, API specs, troubleshooting
│   ├── api.md
│   └── troubleshooting.md
├── scripts/               # ready‑to‑run scripts
│   ├── smoke_test.sh
│   └── rollback.sh
└── assets/                # output templates
    └── release_note.md

Why the common misunderstanding?

Many think a skill is merely a markdown checklist. Anthropic’s blog calls this the biggest misconception. The description is not a human‑oriented summary; it is the trigger that Claude uses to decide whether to load the skill.

Nine functional categories

Library & API reference – e.g., internal billing library edge cases.

Product validation – e.g., headless browser tests that assert each step.

Data query & analysis – e.g., joining tables for conversion funnels.

Business process automation – e.g., one‑click daily report generation.

Code scaffolding – e.g., generating boilerplate with team conventions.

Code quality & review – e.g., a sub‑agent that performs adversarial review.

CI/CD & deployment – e.g., retrying flaky CI, resolving conflicts.

Runbook troubleshooting – e.g., step‑wise symptom investigation.

Infrastructure operations – e.g., guarded resource cleanup.

The most impactful category, according to internal data, is **product validation** – spending a week polishing a validation skill yields the biggest quality boost.

Progressive disclosure (the “directory‑only” model)

When a session starts, Claude receives a list containing only each skill’s name and description (max 250 characters). The full SKILL.md is fetched only when Claude decides the skill matches the current task. This three‑layer disclosure saves context tokens:

Directory view – name + description.

On‑demand load – full markdown.

Lazy load of referenced files – only when the skill explicitly reads them.

The skill list is limited to 1 % of the context window; each description is truncated to 250 characters, with an ellipsis added if longer.

Common pitfalls and how to avoid them

Too many skills – each skill consumes part of the 1 % budget; excess skills become invisible.

Overly long descriptions – characters beyond 250 are never seen, so crucial trigger phrases are lost.

Stating the obvious – “run tests after building” adds noise; only include information Claude cannot infer.

Railroading – overly prescriptive steps prevent Claude from adapting to unexpected situations.

The most valuable part of a skill is its “gotchas” list – concrete pitfalls that only a human who has hit the problem can describe. These signals let Claude avoid predictable failures.

Advanced capabilities

1️⃣ Memory inside a skill

Place a persistent file (plain text, JSON, or SQLite) inside the skill folder. Claude can read and append to it across sessions, enabling incremental reporting, stateful workflows, or configuration storage. The directory CLAUDE_PLUGIN_DATA provides a stable location that survives plugin upgrades.

2️⃣ Bundled scripts

Expose reusable functions in scripts/. Instead of writing boilerplate each time, Claude composes these functions on the fly, focusing on high‑level orchestration.

3️⃣ Temporary hooks

Declare a hook in the skill’s front‑matter; it registers only while the skill runs and is automatically deregistered at session end. Examples include a “careful” hook that blocks dangerous commands (e.g., rm -rf) and a “freeze” hook that prevents modifications outside a designated directory.

Team‑wide distribution

Two paths exist:

Repository distribution – place skills under .claude/skills in the codebase. Simple for small teams but incurs the 1 % budget for every developer.

Plugin marketplace – package skills as plugins, allowing each user to install only what they need, keeping context costs proportional to actual usage.

Anthropic’s internal workflow is organic: developers push skills to a sandbox repo, share them via Slack, and once a skill gains traction, they promote it to the official marketplace via a pull request.

Usage telemetry

A PreToolUse hook records every skill invocation (who, when, which skill). The aggregated data reveals:

Popular skills – worth dedicated maintenance.

Under‑triggered skills – likely suffer from poor descriptions; fixing the description closes the loop.

Without telemetry, a skill library becomes a stagnant “junk drawer”.

Key takeaways

Treat a skill as a fully equipped folder (scripts, memory, hooks), not just a document.

The first 250 characters of the description are the only thing Claude sees to decide activation; keep it concise and scenario‑focused.

If you can only perfect one type, focus on verification skills so Claude can automatically confirm its own output.