How Agent Skills and MCP work together

What is the difference between Agent Skills and MCP?

An Agent Skill is a portable instruction package, normally a folder with a SKILL.md file and optional scripts, references, or assets. It tells an agent how to perform a repeatable task and loads progressively when the task matches. MCP is a protocol for connecting a model host to external tools, resources, and prompts. A skill can teach the workflow for using MCP, but it should not duplicate the server, carry credentials, or make authorization decisions.

Agent Skill (SKILL.md)
  decides when and how to run the workflow
            |
            v
MCP client in Codex, Claude Code, Cursor, or another host
            |
            v
Authenticated MCP server
  enforces identity, access, data boundaries, and writes
            |
            v
Inspectable result and verification

When should an MCP server ship an Agent Skill?

Ship a skill when correct use requires more than choosing one obvious tool. A skill is valuable when the agent must select among several operations, preserve a domain-specific record, respect an ordering constraint, recover from stale state, or verify a result. Keep simple tool descriptions in the MCP schema; reserve a skill for reusable procedure and judgment.

• Several MCP calls must happen in a dependable order.
• The agent must inspect current state before writing.
• The workflow has a success test and a meaningful denied path.
• Users repeat the same task across multiple compatible agent hosts.
• The procedure benefits from examples, checklists, or reference material.
• The skill can remain useful while the MCP server enforces all permissions.

What belongs in a SKILL.md for an MCP workflow?

Write a narrow activation description, state the required MCP server and access, verify the active identity before protected actions, define the smallest reliable call sequence, and finish with an observable verification step. Keep detailed API schemas on the server or in focused references rather than copying a large tool catalog into the skill.

• A lowercase name matching the skill folder.
• A description that names both the capability and trigger phrases.
• Compatibility requirements such as the MCP server, CLI, or network access.
• Identity and scope verification before the first write.
• Expected outputs, preserved evidence, and failure behavior.
• A denied-access rule that stops instead of searching for a bypass.
• A final read-back or test proving the operation succeeded.

How do you build an Agent Skill around Handover MCP?

Create one focused skill, connect the host to Handover MCP, and test it with two named identities. The skill should call handover.whoami, resolve the canonical record, read the current revision and required artifacts, perform one bounded workflow, and read the result back. Handover derives authorship, company, workspace, and access from the authenticated principal rather than accepting those values from skill text.

npx skills init my-handover-skill

# Install a working first-party example
npx skills add 44-pixels/handover-mcp --skill handover-publish

# Inspect all available Handover skills
npx skills add 44-pixels/handover-mcp --list

How should Agent Skills handle identity and security?

Treat skill source as operational code even when it is only Markdown. A skill can influence which tools an agent calls and what data it sends, so keep credentials outside the skill, inspect third-party source, declare requirements, and grant the connected principal only the access the workflow needs. The MCP server must remain the authority for authentication and authorization.

• Never place bearer tokens, API keys, or copied sessions in SKILL.md.
• Never let prompt content choose the author, organization, role, or scope.
• Default publication and sharing to private unless the person explicitly changes it.
• Do not retry denied access with another identity or infer hidden records.
• Test with the smallest role and revoke the credential after the test.
• Keep publisher provenance and complete source visible before installation.

How do you test an Agent Skill and MCP integration end to end?

Use a fresh session and test behavior rather than only validating frontmatter. Confirm activation from a natural-language request, verify the intended identity, run the workflow, inspect the exact resulting artifact or revision, and repeat one denied or stale-state path. Then start a second compatible host and prove it can retrieve the same canonical result without receiving the first chat.

• Format test: validate the skill against the Agent Skills specification.
• Discovery test: confirm the installer finds the intended skill and no templates.
• Identity test: the server reports the expected person or service agent.
• Success test: the expected immutable result exists and is readable.
• Boundary test: an out-of-scope read or write remains denied.
• Continuity test: another host can retrieve and continue the result.
• Revocation test: disabling the credential immediately removes access.

How do you publish a Handover-compatible Agent Skill?

Publish inspectable source with declared compatibility, publisher provenance, and test evidence. Handover's contributor contract requires a successful run, a denied or unavailable path, least-privilege access, authenticated attribution, and private-by-default behavior. Catalog inclusion helps discovery but never widens Handover access or replaces the installer's source review.