Inside a skill — SKILL.md, references, examples, the loading protocol

At a glance

Learning objectives

• Describe the SKILL.md schema and the directory layout convention
• Evaluate a skill's objectives before you trust it
• Install a registry skill and inspect its files

What you need

• An agent host that supports the Agent Skills format
• A repeatable review you currently do by hand
• [object Object]

Steps

1. A skill is a SKILL.md file with front-matter (name, description, version), plus references/, scripts/, and examples/ directories that an agent loads on demand. (from ref-agent-skills )
2. The specification covers the SKILL.md schema, the directory layout convention, and the agent loading protocol. (from ref-agent-skills )
3. The format is portable across compatible agents — it is what this platform's Skill object is modelled on. (from ref-agent-skills )
4. Read a real one — the mcp-tool-contract-auditor skill ships SKILL.md, references/blast-radius.md and examples/audit.md. (from skill-mcp-tool-contract-auditor )
5. Judge a skill by its objectives — read a tool schema and predict its side effects, classify tools by blast radius, write a least-privilege MCP configuration. (from skill-mcp-tool-contract-auditor )
6. Install it and compare the layout with yours — npx de-agent-platform add mcp-tool-contract-auditor. (from skill-mcp-tool-contract-auditor )

Check yourself

• You can say what belongs in SKILL.md front-matter versus the references/ directory.
• The auditor's three objectives each name an observable behavior — read, classify, write — not a topic.

Worked example

SKILL.md
references/blast-radius.md
examples/audit.md

A SKILL.md file with front-matter (name, description, version), plus
references/, scripts/, and examples/ directories that an agent loads
on demand. Covers the SKILL.md schema, the directory layout convention,
and the agent loading protocol.

npx de-agent-platform add mcp-tool-contract-auditor

Sourced from

• Agent Skills (open format)
• MCP Tool Contract Auditor

Security scan

Last sweep 2026-10-24: 0 finding(s), 0 marked as examples.

Common gotchas

• A skill loads on demand under the agent loading protocol — it is not always in context.
• references/, scripts/ and examples/ are convention directories from the layout spec — keep them if you want portable skills.
• A skill's objectives should be observable behaviors — read, classify, write — not topics.

Production considerations

• Model your SKILL.md on a registry skill — mcp-tool-contract-auditor shows the SKILL.md + references + examples layout.
• Write to the spec, not to one agent — the format is portable across compatible agents.

Diagram

skill anatomy
   |
   |- SKILL.md --> front-matter (name, description, version)
   |
   |- references/ --> deeper docs loaded on demand
   |
   |- scripts/ + examples/ --> runnable checks
   |
   |- loading protocol --> loaded on demand, portable across agents

Registry stats