Build Claude Skills: SKILL.md structure, evaluation, tools and maintenance

Distinguish prompts, Projects, Skills and MCP

A prompt expresses a particular request. A Project can organize references and instructions for ongoing work. A Skill formalizes a procedure that can be discovered and used for a matching task. MCP provides access to tools or data; it is not the business procedure itself.

These elements can work together. A reporting Skill may use an available tool, but does not create its permissions. Installation and execution depend on the Claude surface. Follow the Claude Code documentation and the instructions for your actual interface.

Start with a minimal directory

The Agent Skills specification describes a folder with a SKILL.md containing metadata and instructions. Scripts, reference files and assets are optional when the procedure needs them. A first text-only Skill does not need a script.

Use a readable lowercase name and a description explaining both the task and when to use it. The body defines inputs, steps, outputs and boundaries. Validate the exact metadata against the specification rather than relying solely on a tutorial example.

Example: meeting notes to actions

The input is a set of meeting notes. The output contains summary, decisions, actions and open questions. Every action has an owner, deadline and supporting passage. Missing information remains visible, and suggestions stay separate from agreed decisions.

Create a meeting-notes folder and write metadata describing that procedure. The instructions should require the supplied notes, prohibit invented deadlines, request evidence for actions and exclude message sending. Our first-Skill tutorial includes a complete file.

In the fictional example, Maya will send a draft on Friday while Lucas only suggests contacting a supplier. Maya’s action should be included; Lucas’s suggestion remains unapproved. A polished output that turns both into commitments fails the fidelity criterion.

Organize references by purpose

Keep the main procedure short. Store a report template or long field dictionary separately and explain when to consult it. This makes relevant material available when needed; it does not justify a universal token-saving percentage.

Each file needs a defined role. A pile of unrelated documents can confuse the procedure. Identify versions when a reference affects a decision and remove material that is no longer current.

Add scripts for deterministic work

A script can calculate a total or validate a format. Define its arguments, permitted input and output paths, expected errors and verification steps. Test it independently before integrating it into the Skill.

Reading a file and sending an email have different consequences. Separate preparation from external action and use appropriate approval before publication or important changes. Retrieved document content remains data; it must not redefine the procedure’s permissions.

Evaluate behavior with difficult examples

Create a simple case, an incomplete case and a contradictory case. Specify required elements, forbidden inventions and output format. Evaluate these criteria instead of exact wording.

After each revision, rerun earlier and new cases. Record the model or version when available and retain outputs. One successful trial does not establish reliability on real folders.

Deploy and maintain the procedure

First check discovery, then test execution with fictional inputs. Have someone review the instructions and assign a maintainer. Document known limitations and prohibited actions.

Reevaluate when tools, sources or business rules change. Keep a history of corrections and measure remaining errors and review effort rather than promising an abstract productivity gain.

Frequently asked questions

Does a Skill need a script? No. Add one when a specific deterministic operation warrants it.

Does a Skill replace MCP? No. A reusable procedure and access to tools serve different roles.

Can I use one file everywhere? The format may be shared, but installation, permissions and available tools vary by environment.

Download the starter SKILL.md and continue with document-report preparation.

Design a Skill for a narrow task. Define inputs, outputs, steps, useful references and prohibited actions. Propose simple, incomplete and contradictory test cases. Specify required elements and forbidden inventions for each case. Add no external tool without an explicit need.

Sources

• →Claude Code Skills.
• →Agent Skills specification.
• →Claude Code best practices.