Why Most Claude Code Skills Fail and How to Rebuild Them Using the Official Specification

Skill is a directory

A Skill must be a directory containing a required SKILL.md file and optional sub‑directories references/, assets/, and scripts/:

my-skill/
├── SKILL.md          # required – core command
├── references/       # optional – lazy‑loaded reference material
├── assets/           # optional – templates, images
└── scripts/          # optional – executable scripts

The references/ folder is loaded only when a file inside it is explicitly referenced. Placing large reference material there prevents the content from being injected into Claude’s context on every Skill call, saving tokens.

Three‑layer progressive loading

Level 1 (metadata): name and description are loaded at session start (≈100 tokens per Skill).

Level 2 (SKILL.md): the full command body is injected only when the Skill is invoked.

Level 3 (directory resources): files in references/, assets/, or scripts/ are read only when the Skill explicitly references them.

The description field is a routing rule, not a marketing blurb. Claude matches the first 250 characters of each description to decide whether to auto‑invoke the Skill. It must be concise, start with a verb, and state both what the Skill does and when it should trigger.

❌ description: A tool that helps write code.
✅ description: Generate a complete React component when the user mentions "create component", "write a page", or "add a feature module".

Frontmatter fields (12 optional keys, grouped into four categories)

Identification : name, description, argument-hint.

Trigger control : disable-model-invocation (prevent Claude auto‑calling), user-invocable (hide from user), paths (glob patterns for file‑based activation).

Execution : context, agent, allowed-tools, model, effort.

Other : hooks (Skill‑level lifecycle hooks) and shell (shell used for pre‑processing, default bash).

Example frontmatter (comments translated to English):

# Identification
name: write-tweet               # ≤64 characters, lower‑case, hyphens
description: |
  Generate a tweet from supplied material. Triggers when the user says "write tweet", "post tweet", or "help me write one".
argument-hint: "[tweet content or link]"

# Trigger control
disable-model-invocation: false  # false = Claude may auto‑call
user-invocable: true            # true = user can call manually
paths: "*.md, src/**/*.ts"      # only activate when matching files are processed

# Execution
context: fork                   # run in isolated sub‑agent
agent: "general-purpose"        # agent type
allowed-tools: Read Write Edit  # tools granted without further permission checks
model: sonnet                   # override model for this Skill
effort: medium                  # effort level

# Other
shell: bash                     # shell for pre‑processing commands

Context modes: fork vs inline

By default a Skill runs inline , inheriting the full conversation history and consuming the main token budget. Setting context: fork runs the Skill in an isolated sub‑agent, which does not inherit the main dialogue history and therefore protects the primary session from token exhaustion.

Use fork when the Skill’s command contains all information needed for the task (e.g., large code‑base refactoring, batch operations). Use inline when the Skill must rely on prior conversation context (e.g., “continue the feature we just discussed”).

Rule of thumb: if the instruction is self‑contained, choose fork ; if it depends on earlier dialogue, choose inline .

Description token budget

All Skill descriptions share a single context budget. The default budget is 1 % of the model’s context window. For Claude Sonnet (200 K token window) this equals 2 000 tokens. If you have 20 Skills, each description is effectively limited to about 100 tokens (≈75 Chinese characters). Moreover, the list view truncates each description to the first 250 characters, so the essential trigger information must appear within that limit.

Include the core trigger condition (verb + trigger phrase) within the first 250 characters.

Start with a verb and avoid filler text such as “this Skill helps you…”.

Shell pre‑processing (dynamic context injection)

The shell field enables execution of a command before the Skill body is sent to Claude. Use the syntax !`<command>` to run the command, capture its output, and substitute the placeholder.

Current Git status:
!`git status --short`

This makes a Skill dynamic: it can read package.json to infer the project’s tech stack, list recently modified files, or fetch the current branch name, turning a static shortcut into a full‑featured workflow.

Key takeaways

Skill is a directory, not a single file; keep large reference material in references/ to avoid unnecessary token consumption.

The description field is the routing rule – keep it under 250 characters, start with a verb, and state both the action and the trigger phrase.

Understand the three‑layer loading model: metadata at session start, command body on invocation, resources on demand.

Choose context: fork for heavyweight, self‑contained tasks; use inline when the Skill needs prior conversation context.

Leverage shell pre‑processing to create dynamic Skills that adapt to the current repository state.