Prompts and skills
This page is for developers who build on the MCP server or connect a host to it. It lists the 16 prompts a host can offer its user and the 11 skills a model can load, what each takes, and when to use which.
Prompts and skills, compared
Both tell a model how to do a job with the server's tools. Neither runs anything on its own, and neither gives a caller more than its token and role allow.
| Prompts | Skills | |
|---|---|---|
| What it is | A short task, filled in with arguments, sent to the model as one user message | A longer guide to a whole job: steps, checkpoints, rules and how to recover from errors |
| Who starts it | The person, from the host's prompt menu or slash commands | The model, which reads it as a resource when a task needs it |
| How it is fetched | prompts/list, then prompts/get with arguments |
resources/read on a skill:// address |
| Changes anything | No. The tools it names do, under the usual contracts | No |
Prompts
The server lists every prompt to every signed-in caller. prompts/get answers one user message. For every prompt but follow, the message is the prompt's template with its arguments filled in. Every template opens with the server's short rules: drafts and versions, reading through resources, changing a draft with an expected revision, and never releasing without the person's say.
{"jsonrpc": "2.0", "id": 3, "method": "prompts/list", "params": {}} {
"jsonrpc": "2.0", "id": 4, "method": "prompts/get",
"params": {
"name": "add-guardrail",
"arguments": { "uri": "instruction://acme/support-agent", "risk": "a refund over €500 without a person" }
}
} {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "How instruction.md works, in short:\n- An instruction has one draft …\n\nTask: add a guardrail to instruction://acme/support-agent so that this never happens: a refund over €500 without a person.\n\n1. Read `instruction://acme/support-agent/draft`; find where it belongs. …"
}
}
]
} An argument that is not required has a default the template names, such as "the person's personal workspace". A required argument left out doesn't fail the request. The message then says which arguments are missing and asks the model to get them from the person and run the prompt again. A prompt name the server doesn't have doesn't fail either: its one message is "No such prompt.".
| Prompt | What it does | Arguments |
|---|---|---|
write-instructionWrite an instruction | Write a new instruction from what the person wants an agent to do, and save it as a draft for them to review. | intent (required): what the instruction should make an agent do, in the person's wordsworkspaceId (optional): where to create it (default: the personal workspace) |
propose-editPropose an edit | Change an instruction the governed way: read it, then make the change as suggestions (or directly, when you may and were asked to), never releasing it. | uri (required): instruction://<id|owner/name> to changeintent (required): what should change, in the person's words |
tighten-rulesTighten the rules | Make an instruction's rules precise and testable: vague words out, conditions and limits in, as suggestions. | uri (required): the instructionfocus (optional): which rules or section, if not all |
explain-ruleExplain a rule | Explain what one rule of an instruction makes an agent do, and where it could be misread. | uri (required): the instructionrule (required): the rule's words or its name |
write-sectionWrite a section | Write one new section of an instruction from a description, as a suggestion in place. | uri (required): the instructionabout (required): what the section coversafter (optional): the heading it follows, if not at the end |
add-guardrailAdd a guardrail | Add a NEVER rule for a risk the person names, as a suggestion. | uri (required): the instructionrisk (required): what must not happen |
make-exampleMake an example | Write a worked example for an instruction: a situation, what the agent should do, and why, as a suggestion. | uri (required): the instructioncase (optional): the situation the example shows |
fix-problemsFix problems | Fix what the language reader refuses or warns about in an instruction's draft, one problem at a time. | uri (required): the instruction |
convert-promptConvert a prompt | Turn a system prompt into an instruction: its rules become MUST, SHOULD and NEVER lines, saved as a new draft. | prompt (required): the system prompt's texttitle (optional): a name for the instruction |
prepare-releasePrepare a release | Summarize what changed since the latest version into a version message, check the draft, and say what releasing would change for the agents that follow it. | uri (required): the instruction |
answer-commentsAnswer comments | Read the open comment threads on an instruction and answer each one, changing the draft as suggestions where a comment asks for it. | uri (required): the instruction |
review-proposalReview a proposal | Review a proposal (a whole text offered back) against the instruction it targets: correctness, validity, who it affects; recommend approve or request changes. | instructionId (required): the instruction (ins_…)proposalId (required): the proposal (prp_…) |
explain-diffExplain a diff | Explain what changed between two versions of an instruction and what it means for the agents that follow it. | instructionId (required): the instruction (ins_…)from (required): a version (v3, ver_…), a ref, or draftto (required): a version, a ref, or draft |
create-from-intentCreate from intent | Create a new instruction from a goal, starting from a template when one fits, and save it as a draft. | intent (required): what the instruction should make an agent doworkspaceId (optional): where to create it |
adapt-for-agentAdapt for an agent | Adapt an instruction for a specific agent or host without changing the original: fork it, adjust the copy, keep its origin. | uri (required): the instruction to adaptagent (required): the target agent or host (agentd, Claude Code, Cursor, a CI job…) |
followFollow an instruction | Take an instruction as this conversation's instructions: its delivered text (the version its ref names now, with its includes and its parameters' defaults), which you follow from here on. | uri (required): the instruction to follow: instruction://owner/name, with @ref (stable, latest) or @v3 for one version |
The prompts that change an existing instruction tell the model to make the change as suggestions. propose-edit lets it edit the draft directly only when the caller may and the person asked for that. The prompts that make a new instruction (write-instruction, convert-prompt, create-from-intent) save it as a draft, and adapt-for-agent forks one. None of them releases a version. prepare-release writes the version message and asks the person whether to release. The release itself is instructions_publish, which asks to confirm. See Contracts.
The follow prompt
follow is not filled from a template. The server reads the instruction as the caller, with the caller's permission, and answers its delivered text: the version its ref names now, with its includes and its parameters' defaults in. The read is recorded like any other read.
uritakesinstruction://owner/name,owner/name, or either with@stable,@latestor@v3. Without a ref it is the instruction's default ref.- The text comes wrapped in an
<instruction>element with its address, version and digest, the same digest the hooks andinstruction://currentgive. - An instruction the caller can't read answers
not_found, as a read does. An emptyurianswersvalidation.
{
"description": "acme/support-agent v7",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "These are the instructions you follow in this conversation, from instruction.md: acme/support-agent v7 (signed). Follow them from here on; they replace any earlier version of them.\n<instruction uri=\"instruction://acme/support-agent@stable\" version=\"v7\" digest=\"sha256:…\">\n# Support agent\n…\n</instruction>"
}
}
]
} The prompt gives the conversation the version as it is when it runs. A host that doesn't subscribe to resources doesn't hear of a new version afterwards: run the prompt again, or set up following.
How hosts show prompts
- Claude Code lists each prompt as a slash command named after the server it was added as: with
claude mcp add instruction-md …, the follow prompt is/mcp__instruction-md__follow instruction://acme/support-agent. See Claude Code. - Codex reaches the server through the
instruction mcpbridge, because it doesn't speak MCP 2026-07-28 by default. To follow an instruction in Codex, use its hooks: see Codex. - The stdio servers pass the prompts on.
instruction mcplists the server's prompts once you are signed in. With--follow, or a project's.instruction/follow.json, its ownfollowtakes the place of the server's, anduribecomes optional: it defaults to the followed instruction.instruction-mcplists the server's prompts as they are. See instruction-mcp. - Other hosts differ. A host with no prompt menu can still call the same tools; the prompts only save the person typing the task.
Skills
A skill is a Markdown file, SKILL.md, with front matter that says when to use it, and sometimes reference files beside it. The server serves each as a resource. The index lists them all with each file's digest and size:
{"jsonrpc": "2.0", "id": 5, "method": "resources/read", "params": {"uri": "skill://instruction-md/index.json"}} {
"version": 1,
"skills": [
{
"name": "instruction-md-basics",
"description": "Start here before using any instruction.md tool. What instru…",
"uri": "skill://instruction-md/instruction-md-basics/SKILL.md",
"resources": [
{
"uri": "skill://instruction-md/instruction-md-basics/SKILL.md",
"digest": "sha256:…",
"size": 8772,
"mimeType": "text/markdown"
}
]
},
…
]
} {"jsonrpc": "2.0", "id": 6, "method": "resources/read", "params": {"uri": "skill://instruction-md/releasing-and-rolling-back/SKILL.md"}} The addresses are skill://instruction-md/<name>/SKILL.md and skill://instruction-md/<name>/reference/<file>. The server has no skills/list or skills/get method: read the index, then the files.
| Skill | When to load it | For | Files |
|---|---|---|---|
instruction-md-basics | Start here before using any instruction.md tool. What instruction.md is (versioned instructions for AI agents, served over MCP), its model (draft, suggestions, comments, checkpoints, versions, latest, roles), how to find tools and read through resources, the revision and confirmation rules every change follows, and what each error means. | an assistant acting for a person, an agent that follows an instruction, an agent that writes instructions, a coding agent, a CI pipeline | skill://instruction-md/instruction-md-basics/SKILL.md |
writing-instructions | Write a new instruction for an AI agent from what a person wants it to do — "write an instruction for our support agent", "set up rules for the coding agent". Interviews for purpose and limits, starts from a template, writes rules, guardrails and examples in the language publishing accepts, validates until clean, previews what the agent will receive, and saves the draft. | an assistant acting for a person, an agent that writes instructions, a coding agent | skill://instruction-md/writing-instructions/SKILL.mdskill://instruction-md/writing-instructions/reference/language.md |
improving-an-instruction | Change an existing instruction safely — "make the refund rules stricter", "add a rule about tone", "fix the problems", "rename it". Reads the draft and what others have pending, makes precise edits rather than rewriting, proposes them as suggestions when the person can't edit directly or others are working on it, validates, and shows the diff. | an assistant acting for a person, an agent that writes instructions, a coding agent | skill://instruction-md/improving-an-instruction/SKILL.md |
releasing-and-rolling-back | Release a new version of an instruction to the agents that follow it, roll back to an earlier version, move a ref such as stable, or revoke a harmful version — "ship it", "publish the changes", "roll back to v6", "promote to stable", "v5 leaked a key, kill it". Checks for problems and pending suggestions first, writes the version message, asks the person to confirm before agents switch, and checks adoption after. | an assistant acting for a person, a CI pipeline | skill://instruction-md/releasing-and-rolling-back/SKILL.md |
release-gates-in-ci | Release an instruction from a CI pipeline behind gates — validate the changed file, write it to the draft, run the checks, release it to canary, and let stable follow once it has stood and passed. "Publish instructions from GitHub Actions", "only ship checked versions", "canary then stable", "why didn't stable move?". Also sets up the gates on the refs, which a person does once. | a CI pipeline, an assistant acting for a person | skill://instruction-md/release-gates-in-ci/SKILL.md |
following-instructions | For an AI agent or agent runtime that runs with an instruction from instruction.md as its operating context — bind to a version or ref, read and verify it, apply it at a safe moment, report what you applied, stay current when a new version is released, and hold the last good version when something is wrong. | an agent that follows an instruction, an agent that writes instructions, a coding agent | skill://instruction-md/following-instructions/SKILL.md |
converting-a-prompt | Turn an existing system prompt into an instruction — "make this prompt an instruction", "import our support bot's prompt", "convert this". Converts its rules into MUST, SHOULD and NEVER lines, shows the result before anything is created, creates the instruction from it, and checks it. | an assistant acting for a person, an agent that writes instructions, a coding agent | skill://instruction-md/converting-a-prompt/SKILL.md |
reviewing-changes | Review what others propose on an instruction — "what's waiting for me", "review the suggestions", "answer the comments", "accept Maria's change". Reads the pending suggestions and comment threads, explains each against the released text, and settles them only as the person decides. | an assistant acting for a person | skill://instruction-md/reviewing-changes/SKILL.md |
sharing-and-access | Share an instruction or change who can use it — "share it with Priya", "let the support team edit it", "make it public", "who can see this?", "ask for edit access", "make my own copy". Reads who has access, changes grants and visibility with the server's confirmation shown to the person, answers access requests, and asks for access or forks when the person can only read. | an assistant acting for a person | skill://instruction-md/sharing-and-access/SKILL.md |
connecting-an-agent | Connect an agent so it follows an instruction — "hook our support bot up to the refund rules", "give the agent a credential", "is the agent on the latest version?", "pause that agent". Issues the agent's credential, shows how it signs in and binds to the instruction, and checks from the instruction's side that it follows and applies the latest version. | an assistant acting for a person, a coding agent | skill://instruction-md/connecting-an-agent/SKILL.md |
administering-an-org | Run an organization — "invite Tom", "make Priya an admin", "create a workspace for the support team", "what's our policy on public instructions?", "add our GitHub skills repo", "only let instructions use our approved MCP servers", "who changed this and when?", "export the audit log". Manages members, invitations, workspaces and roles, the organization's policy and integrations, and its audit trail, asking first where the server does. | an assistant acting for a person | skill://instruction-md/administering-an-org/SKILL.md |
Which skills to load first
session_bootstrap names the skills to load first in its skills field, by the kind of caller:
| Caller | Skills it names |
|---|---|
| Every caller | instruction-md-basics |
| An agent or a service whose credential has no write, publish or admin scope (and isn't a CI service) | following-instructions |
| A person, an agent or service with a write, publish or admin scope, or a CI service | writing-instructions, improving-an-instruction, releasing-and-rolling-back |
| A CI service (its client ID starts with ci- or names github) | release-gates-in-ci |
The lists add up: every caller gets instruction-md-basics, and a CI service gets the three for writers as well as release-gates-in-ci. Load the others when the task calls for them. capabilities_search finds skills and prompts too, by what you want to do in words.
What a skill can't do
A skill is guidance for the model, not a permission. A tool it names still checks the caller's scopes and role, and a tool that asks to confirm still asks. A skill never tells a model to do more than its person asked.
Generated from the code
The prompt and skill tables are built from the tool registry (packages/registry/registry.json) when the docs are built, and the "For" column from each skill's front matter. A prompt or skill added to the server appears here at the next build.