PART 03 — PHASE 2

What a skill actually is.

A folder-based package led by SKILL.md. It can also contain scripts, templates, references, and resources that Claude loads or uses as needed. Today we separate package structure from runtime permissions.

10–15 Min Claude Your Brain

Reviewed 31 August 2026. This structure follows Anthropic's current Agent Skills overview. The instruction-only example is deliberately small; third-party packages require every-file and dependency review.

Part 1: Required entry point, optional package files

The package entry point is SKILL.md. Its YAML frontmatter identifies and describes the skill; the Markdown body contains instructions. The same directory may include scripts, templates, references, and resources. Inspect referenced and unreferenced files alike: dormant content can become reachable after an update.

1
SKILL.md: YAML metadata plus Markdown instructions. Name and description support discovery; the body defines the workflow and boundaries.
2
Optional files: scripts, templates, references, and other resources. Their code, dependencies, licenses, data flows, and required permissions are part of the review.

Part 2: A real skill, line by line

Below is an educational, instruction-only caption skill. “Safe” is not a permanent property: validate it in your environment, with synthetic content and no secrets, before use.

  caption-writer / SKILL.md
--- name: caption-writer description: Draft short-form social captions when asked for a caption, hook, or social post; do not use for articles, private replies, account access, or publishing. --- # Voice - Short sentences. Under 14 words each. - One idea per line — no filler. - End with a question or a CTA. - Never use emojis unless asked. # Workflow 1. Ask which platform (IG, LinkedIn, X). 2. Ask the single most important point. 3. Draft three options. Label them 1, 2, 3. 4. Ask which direction to tighten. # Examples Prompt: "Caption for LinkedIn about a fictional product update." 1. "One less manual step. The fictional Acme demo now exports drafts in one click." 2. "We simplified the demo workflow. Which repetitive step should the fictional Acme team test next?"
Frontmatter — lines 1–4

The --- delimiters mark YAML metadata. name identifies the skill and description helps Claude decide relevance. Follow the current schema and test discovery rather than assuming a description will always activate.

Why description matters

Claude uses skill metadata during discovery. Describe the task and trigger boundaries precisely, including when the skill should not apply. Similar skills can conflict, so test both intended activation and near-miss prompts.

The rules — the "how"

Clear steps and boundaries can improve consistency, but instructions are not enforcement. Use runtime permissions and application controls for security, then evaluate representative, edge, and adversarial prompts.

Examples — the "so-what"

Examples can clarify intended output. Use synthetic or rights-cleared examples, exclude personal and client data, and test whether they introduce unwanted imitation, bias, or overfitting.

Part 3: How Claude actually loads it

Skills use progressive disclosure: metadata supports discovery, the relevant SKILL.md instructions can then be loaded, and supporting resources can be accessed as needed. This reduces context use; it does not sandbox the package or prove that only one skill will influence a task.

Simplified skill discovery and loading flow A user request is compared with skill descriptions, relevant instructions are loaded, and Claude produces a draft output. Actual selection can vary and should be tested. YOU ASK "caption for LinkedIn" CLAUDE SCANS DESCRIPTIONS commit-helper — "writes git..." caption-writer — "short-form captions..." seo-audit — "technical SEO..." debugging — "root-cause..." match: caption-writer ✓ LOADS THE BODY caption-writer rules ✓ short sentences ✓ one idea per line ✓ end with CTA ✓ no emojis OUTPUT "Hiring?..."
Core Concept

Description is a discovery contract. State the intended task, trigger cues, exclusions, and output—not marketing claims. Then test activation empirically. Spend effort according to observed failures across metadata, instructions, supporting files, permissions, and application controls.

Too broad: "Helps with writing." It does not define task or boundaries, so activation may be inconsistent.

More testable: "Draft short-form social captions when the user asks for a caption, hook, or social post; do not use for long-form articles or private-message replies." This specifies outputs, cues, and exclusions, but still needs evaluation.

← Part 2 — Red Flags Part 4 — Establishing trust →