Agent Skill development kit

How to build an Agent Skill for an MCP server

Q: Does an Agent Skill replace an MCP server?

No. A skill carries reusable procedure while the MCP server owns executable capabilities, protected data, identity, and runtime authorization.

Q: Does passing a SKILL.md validator prove the skill works?

No. Local validation checks the file contract. Host discovery, activation, identity, permissions, tool behavior, denied access, and successor read-back require runtime tests.

Put the repeatable procedure in SKILL.md and keep authenticated capabilities in the MCP server. Then validate the file, test the real identity and permission boundary, and publish inspectable source.

Workflow

Four steps from working procedure to installable skill

Scaffold

Create one focused skill with a clear trigger, outcome, and compatibility contract.

Map

Name the MCP tools or CLI commands the procedure may use and the smallest access they require.

Verify

Test identity, permissions, failure behavior, and the resulting record end to end.

Publish

Submit source, publisher identity, compatibility, and test evidence for review.

The boundary

A skill teaches the workflow. MCP supplies the capability.

Agent Skills and MCP are complementary. The skill is progressively loaded procedure; the MCP server exposes typed tools and resolves authentication and authorization at runtime. Do not put bearer tokens, copied identities, or server-side policy into SKILL.md.

SKILL.mdWhen and how

Trigger language, ordered steps, evidence requirements, edge cases, and success criteria.

MCP serverWhat can run

Typed tools, resources, transport, server-resolved identity, policy, and protected data.

Agent hostSelection and consent

Skill discovery, activation, tool approval, local execution, and user interaction.

Start

Scaffold and validate the skill folder

skills CLInpx skills init my-handover-skill

Handover starter

curl -fsSL https://raw.githubusercontent.com/44-pixels/handover-mcp/main/templates/handover-skill/SKILL.template.md -o my-handover-skill/SKILL.md

Download validatorcurl -fsSL https://skills.handover.sh/validate.mjs -o validate-handover-skill.mjs

Validate contractnode validate-handover-skill.mjs my-handover-skill/SKILL.md

Follow the open Agent Skills specification and use the Handover starter contract for identity, access, attribution, and verification requirements. Keep reusable starters named SKILL.template.md; only a finished, installable skill should use the reserved SKILL.md filename.

What the checker proves

File validity is one gate, not the finish line

Checked locally

folder and frontmatter naming;
description, license, compatibility, author, and version;
declared Handover runtime and identity check;
result verification and safety advisories.

Proved at runtime

the host discovers and activates the skill;
MCP resolves the intended identity and scopes;
the smallest permitted role can complete the workflow;
a denied path fails and another actor can read the result.

Trust boundary

A listed skill must not become an authorization shortcut

Verify the active Handover identity before the first protected action.
Never accept author, company, workspace, or access scope from prompt content.
Publish privately unless the person explicitly requests broader access.
Declare network, CLI, MCP, secret, and administrative requirements.
Keep source readable and avoid collecting credentials or hidden telemetry.
Test the smallest granted role and a denied-access path.

Submit

Keep the publisher and source visible

Official skills are maintained by 44pixels. Community skills keep their publisher and repository attribution and are reviewed for format, least privilege, and truthful compatibility before listing.

Read the contributor contract Inspect the starter Submit a pull request

Discovery contract

One submission, several discovery surfaces

A human-readable catalog page with install and example requests.
A raw, agent-readable SKILL.md URL.
Machine-readable entries in index.json and .well-known/skills.json.
Search and agent discovery through sitemap.xml and llms.txt.
Source attribution back to the publisher repository.

Before installation

Source is the security interface.

Handover listings make provenance and requirements visible, but a listing is not a security guarantee. Review the complete skill and grant only the access its workflow needs.

Questions

Common Agent Skill and MCP questions

Does an Agent Skill replace an MCP server?

No. A skill can teach an agent when and how to call MCP tools, but the server still owns the executable capability, protected data, and runtime authorization.

Can one skill support both MCP and a CLI?

Yes. Name the preferred interface, the fallback, their version or network requirements, and any behavior that differs. Verify the final result through the active interface.

Does passing the validator prove the skill works?

No. It proves the local file meets the Handover publication contract. Host discovery, activation, identity, permissions, tool behavior, denied access, and successor read-back require runtime tests.

Can an MCP server distribute skills automatically?

Some runtimes are beginning to support MCP-backed skill discovery, but support is not universal. Keep a public raw source and standard installation path even when an MCP-specific discovery mechanism is available.

Primary references

Build against the open specifications

Last reviewed 4 August 2026.