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.
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.
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.
SKILL.md: YAML metadata plus Markdown instructions. Name and description support discovery; the body defines the workflow and boundaries.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.
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.
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.
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 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.
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.
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.