Anthropic Skills Format: Description Triggers & Progressive Disclosure

Anthropic skills format centers on SKILL.md: YAML front matter plus a markdown body that teaches Claude when and how to perform a specialized job. The description field is the trigger surface hosts scan before they load a skill. Progressive disclosure keeps heavy docs and scripts out of the first context load until the task needs them. This guide explains the anthropic skills format without inventing private APIs.

You leave with trigger writing rules, folder layout habits, a release-notes skeleton, testing steps, and an FAQ for the same day. Draft at https://promptmake.net/skills. Guest users get about three runs per day; free accounts about five. You own install and Claude Code testing.

What anthropic skills are in practice

Agent Skills are instruction packages Anthropic documents for Claude products that support skill discovery. In Claude Code, skills typically live in configured directories as folders containing SKILL.md and optional assets. Claude reads front matter to decide relevance, then follows the body and linked files.

Skills are not a replacement for application code, CI, or security policy. They teach the agent how you want recurring tasks handled: doc templates, review checklists, release note shape, or internal API conventions. One skill, one primary job.

As of mid-2026, public Anthropic materials emphasize concrete descriptions, imperative instructions, and splitting large references into separate files. Verify directory conventions and field names on Anthropic's current skills documentation before you automate installs.

SKILL.md anatomy: front matter and body

Front matter is YAML between --- delimiters. Common public fields include name and description. Name is a short identifier. Description lists tasks and phrases that should activate the skill. The body uses markdown headings and numbered steps.

Do not paste secrets, live tokens, or customer PII into SKILL.md. Document required environment variables by name only. Point to internal wikis for values.

Description triggers: how Claude picks a skill

Think of description as a search ad for the skill. Include verbs (audit, scaffold, summarize), artifacts (OpenAPI, CHANGELOG, SKILL.md), and scope boundaries (TypeScript packages under /packages). Avoid generic "helps with coding" lines.

When two skills overlap, users see wrong loads or missed loads. Narrow descriptions and add "Do not use for …" in the body. Maintain a human index in CLAUDE.md listing skills and owners.

Progressive disclosure: entry file stays thin

SKILL.md should fit the entry role: when to use, steps overview, output contract, links to references/, templates/, and scripts/. Claude opens deeper files only when the task requires them. This saves context for repo files and chat.

Anti-pattern: 2,000 lines of policy in SKILL.md. Pattern: 200 lines plus references/policy.md linked twice with clear headings.

Supporting files and scripts

Scripts can validate, format, or fetch when Claude Code execution allows. Templates give copy-paste starting points. Examples show good and bad outputs. Keep filenames stable; link with relative paths from SKILL.md.

Review scripts for destructive commands before merge. Require explicit user confirmation in the body for deletes, force pushes, and production deploys.

Folder layout example (conceptual)

my-skill/SKILL.md, my-skill/references/style.md, my-skill/templates/report.md, my-skill/scripts/lint.sh. Exact roots depend on your Claude Code skill path settings. Confirm on Anthropic docs rather than treating blog paths as gospel.

Writing anthropic skills that pass review

Corporate reviewers ask: triggers, blast radius, secrets, ownership, tests. Supply a test log: three prompts that should load, two that should not, and one real weekly task outcome.

Match team language in descriptions. If engineers say "cut a release branch," include that phrase, not only "semantic versioning assistant."

Output contract and fences

State required sections in every output. State refusals: no legal advice, no invented citations, no file deletes without confirmation. Unknown rules beat silent invention when docs are missing.

Versioning and changelog

Bump a short CHANGELOG in the skill folder when triggers change. Teammates need to know why a skill stopped loading old phrases. Date the last Claude Code test in README or CLAUDE.md.

Drafting on PromptMake /skills

Open https://promptmake.net/skills Claude tab or /claude-skill-generator. Paste a rough job paragraph. Edit description until five real requests would match. Move supporting content to reference file placeholders instead of inline bloat.

Guests about three runs per day on skills paths; free accounts about five. PromptMake does not push to Anthropic or run Claude Code. See claude-code-skills-guide for install and terminal testing detail.

Common format mistakes

Mistake 1: Missing or vague description triggers.

Mistake 2: Essay-length SKILL.md with no linked references.

Mistake 3: Overlapping skills in one repo.

Mistake 4: Secrets in examples.

Mistake 5: No negative trigger tests.

Mistake 6: Treating blog examples as private Anthropic APIs.

Worked example: release-notes skill skeleton

Below is a conceptual SKILL.md shape you can adapt. Replace paths and triggers with your repo language.

Front matter name: release-notes. Description: "Use when the user asks for release notes, changelog draft, or version bump summary from git history. Covers conventional commits and GitHub compare links. Do not use for legal filings or customer support macros."

Body opening: When to use / when not to use. Steps: (1) ask for tag range or commit span, (2) group commits by type, (3) draft user-facing bullets, (4) list breaking changes separately. Output contract: Version, Date, Highlights, Breaking, Contributors link. Fences: never invent issue numbers; mark Unknown when git log empty.

Linked files: references/commit-types.md for house conventions, templates/CHANGELOG-section.md for paste shape. Scripts optional: scripts/collect-commits.sh documented with "run only after user confirms range."

After draft on https://promptmake.net/claude-skill-generator, move files into your skill folder, install per Anthropic docs, and run triggers: "write release notes for 1.4.0" should load; "rewrite support email" should not.

Reviewer questions your skill README should answer

Who owns updates? What repos may this skill touch? What scripts run network or delete commands? When was it last tested in Claude Code? Where do secrets live (answer: not in SKILL.md)?

Teams that answer these in README pass security review faster than teams that only paste SKILL.md into chat.

Anthropic skills vs other standing config

CLAUDE.md holds repo-wide defaults every session may see. Skills load on trigger for specialized jobs. Custom GPT Instructions load every chat with that GPT. Gemini Gem Instructions load every chat with that Gem. Pick one home for each rule to avoid conflicts.

When the same policy appears in CLAUDE.md and SKILL.md, Claude may double-weight or contradict. Prefer CLAUDE.md for universal git rules and SKILL.md for release-notes-specific steps. Link between them instead of duplicating paragraphs.

Progressive disclosure in practice: three file tiers

Tier 1 is SKILL.md under roughly 250 lines: triggers, step overview, output contract, links. Tier 2 is references/: policy, examples, long tables. Tier 3 is scripts/ and templates/: executable or paste-ready assets loaded only when the user task needs them.

When Claude opens Tier 2, the user should already match Tier 1 triggers. Do not hide critical safety rules only in references/. Fences belong in SKILL.md even if examples live elsewhere.

When to split versus merge files

Split when a section exceeds what you would skim in one screen, when policy updates monthly but steps stay stable, or when non-technical reviewers must edit references without touching triggers. Merge when the skill is tiny and splitting adds navigation friction only.

Name files by purpose: references/api-style.md not references/misc.md. Future you and Claude both retrieve faster.

Testing description triggers without guesswork

Build a trigger matrix spreadsheet: rows are user phrases, columns are skills, cells are should-load yes/no. Run the matrix after every description edit. Export results to your skill README as "last verified" with date.

Paraphrase tests matter because teammates rarely type your internal jargon. Include typos only if you truly want fuzzy match; otherwise keep descriptions precise.

Soft draft triggers on https://promptmake.net/claude-skill-generator, then harden in the repo. Generator text is a starting point, not production triggers until matrix tests pass.

Maintaining anthropic skills when models and repos change

Schedule a quarterly retest even if the skill "worked last quarter." Model updates shift trigger behavior. Repo moves break relative paths in SKILL.md links. Deprecate skills with a one-line banner in CLAUDE.md pointing to the replacement folder.

Version SKILL.md changes in git like code. Pull requests for skills should include the trigger matrix diff: which phrases were added or removed and why. Reviewers reject drive-by description edits without tests.

When Anthropic publishes format tweaks, diff their examples against your front matter. Update field names once per release note, not ad hoc in every skill separately. A shared internal template repo reduces drift.

Router, reference, and workflow skill shapes

Anthropic public examples cluster into three shapes teams reuse. Router skills classify input then branch: ticket versus email versus doc request. Reference skills apply a stable spec: glossary tables, API field naming, commit type lists. Workflow skills run phased checklists: plan, execute, verify with explicit stop rules.

Pick one primary shape per folder. Mixing router and workflow in one SKILL.md without clear headings confuses both reviewers and hosts. If you need both, use the body to say which section runs first and link branch-specific references.

Router skills need the widest description triggers because users arrive with varied phrasing. Reference skills need precise artifact names in description: OpenAPI, CHANGELOG, terminology table. Workflow skills need phase verbs: draft, review, ship, audit.

Mapping shapes to progressive disclosure

Routers stay thin in SKILL.md: classification steps plus links to references/router-branches.md if branches multiply. References live almost entirely in references/ with SKILL.md acting as index. Workflows keep numbered steps in SKILL.md but move examples to examples/ and long policy to references/.

Guest users on PromptMake get about three skill generations per day without signup. Free registration raises the cap to about five per day on the skills path. Quotas stay separate from /text and /image. Use generation for scaffolding, then spend review time on triggers and file splits.

Copy-paste SKILL.md front matter patterns

Pattern A (doc skill): description mentions "API docs," "OpenAPI," "endpoint summary," and "not for production deploys." Pattern B (review skill): description mentions "pull request," "diff review," "security checklist," and "not for release notes." Pattern C (content skill): description mentions "blog draft," "SEO outline," "house style," and "not for legal contracts."

Keep patterns disjoint. Overlap between A and B causes double loads during "summarize this PR for the changelog" requests. Split skills or narrow descriptions when overlap appears in testing.

Body bodies should open with imperative verbs: "Read," "List," "Draft," "Refuse." Passive openings slow Claude down and read like policy PDFs. Link to references instead of quoting them inline.

Before merge, ask a teammate to run two prompts cold without telling them which skill should load. If they cannot predict which skill activated from the transcript, your description triggers need another edit pass. Repeat until prediction matches reality.

Archive retired skills in a deprecated/ folder with a one-line reason and replacement path. Deleting folders without a trail confuses git history and onboarding docs.

FAQ

What is the anthropic skills format?

It is the SKILL.md pattern Anthropic documents for Agent Skills: YAML front matter with at least name and description, plus a markdown body and optional supporting files loaded progressively.

What belongs in the description field?

Concrete tasks, user phrases, artifacts, and scope boundaries that should cause Claude to load the skill. It is the main trigger surface. Update it when users report missed activations.

What is progressive disclosure in skills?

Keep SKILL.md as a thin entry point. Put long policy, examples, and templates in linked files Claude reads only when needed. This preserves context for code and chat.

Can PromptMake write anthropic skills format for me?

It drafts SKILL.md text on https://promptmake.net/skills. You edit, add files, install per Anthropic docs, and test in Claude Code. No automatic publish.

How is this different from claude code skills guide?

That guide focuses on Claude Code workflow, testing loops, and team rollout. This page focuses on format mechanics: triggers, disclosure, and file anatomy.

Do skills replace CLAUDE.md?

No. CLAUDE.md often holds repo-wide rules. Skills hold specialized playbooks loaded on trigger. Both can coexist; avoid duplicating conflicting instructions.

How do I start today?

Write one repeating job in three sentences. Generate SKILL.md on /claude-skill-generator. Add one reference file. Run positive and negative prompts in Claude Code before sharing the folder.