agentleFS
briandconnellybriandconnelly/amicus/.agents/skills/agent-friendly-mcp/SKILL.md

agent-friendly-mcp

Skill2 starsChanged 50 days agoMITView on GitHub

Use when designing, building, auditing, or reviewing an MCP server that AI agents will invoke directly. Symptoms include agents picking the wrong tool from many candidates, burning tokens loading hundreds of tool definitions upfront, repeated invalid tool calls due to ambiguous schemas, tools that mirror an underlying API endpoint-by-endpoint instead of completing tasks, missing or unclear resource browsing, prompts that duplicate tool contracts, token-heavy responses that should be paginated or filtered, brittle integrations that break across server versions, long-running operations with no progress, cancellation, or recoverable task status. Also use when defining or hardening tool, resource, or prompt schemas.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. briandconnelly/skills★ 1100% same

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 10 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to make MCP servers easy for agents to discover, invoke correctly, recover from, and use at low token cost without …

    line 12
  2. Very specific:

    Every result carries a required resultType, and server/discover, list, and read results carry the native cache hints ttlMs and cacheScope …

    line 20
  3. Distinctive:

    Read the cited ids — a row names the concern but does not define the rule, so a row is never a substitute for it.

    line 31
  4. Distinctive:

    Keep the conventions whose applicability rules hold — but never let them masquerade as protocol.

    line 49
  5. Very specific:

    Put convention metadata under a namespaced _meta key (e.g., com.example/chunks) — the spec-sanctioned extension point — so it cannot …

    line 60
  6. Distinctive:

    Do not use this skill for designing full user-experience flows.

    line 81
  7. Very specific:

    Read [1.spec-revision] and the native-vs-convention rule below whatever the surface.

    line 96
  8. Distinctive:

    Read the named sections in full — sections, not single bullets, so a rule is never read without its neighbours.

    line 97
  9. Very specific:

    Prefer a rule id over a section reference when you mean one specific rule.

    line 110
  10. Distinctive:

    Use contract-checklist.md as the detailed standard for both workflows.

    line 129
  11. Distinctive:

    Use mcp-vs-cli.md if deciding which surface to expose.

    line 130
  12. Very specific:

    When writing or auditing prose surfaces — server instructions, the capability summary, tool and resource descriptions — apply the …

    line 131
  13. Distinctive:

    Before declaring done, walk contract-checklist.md against your output.

    line 137
  14. Distinctive:

    Design tasks: every checklist section must have an answer in the schema set or be explicitly marked not-applicable with a one-line …

    line 139
  15. Very specific:

    Review tasks: every checklist section is either covered by a finding, marked OK with brief evidence, or noted not-checked with reason.

    line 140
  16. Distinctive:

    Use the severity scale and report format defined in review-workflow.md.

    line 141

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Agent-Friendly MCP

Use this skill to make MCP servers easy for agents to discover, invoke correctly, recover from, and use at low token cost without sacrificing correctness.

Spec Baseline

This skill is written against the MCP 2026-07-28 specification (final, released 2026-07-28); the field names, capability paths, method set, and task lifecycle it uses follow that revision, including the io.modelcontextprotocol/tasks extension (SEP-2663). Status caveat: the 2026-07-28 changelog calls tasks an official extension while the ext-tasks specification repository still labels itself experimental — treat the task contract as extension-versioned and re-verify it against the extension spec when it cuts a release. The protocol core is stateless: there is no initialize handshake or session id — every request carries io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in _meta (both required), and servers advertise their own capabilities via the mandatory server/discover method. Server-initiated requests are gone: elicitation, sampling, and roots requests ride Multi Round-Trip Requests (resultType: "input_required" with inputRequests, answered by retrying with inputResponses), and subscription notifications — list-changed, resource-updated, and task notifications — ride an opt-in subscriptions/listen stream, while request-scoped notifications (notifications/progress, notifications/message) stay on the originating request's response stream. Every result carries a required resultType, and server/discover, list, and read results carry the native cache hints ttlMs and cacheScope on their resultType: "complete" results — MRTR interim results are never cacheable. Roots, sampling, logging, the HTTP+SSE transport, and Dynamic Client Registration are deprecated on a twelve-month minimum window; design new servers without them. The extensions framework is formal but demanding: an extension needs a reverse-DNS identifier, its own maintained specification, and negotiation by both peers (declared in clientCapabilities.extensions and server/discover), so a namespaced _meta key remains a private convention until someone does that work. This section is the single home for revision-level facts: which revision is baseline, its release status, the tasks-extension caveat, and what is deprecated or removed. Checklist rules and native-wire-shapes.md necessarily restate the mechanics they govern, including a governed surface's deprecation status; for the revision-level frame they cite this section rather than restating it. For clients that still speak 2025-11-25, the binding rules here still govern what you build; the old revision's wire differences and version-bound failure modes are cataloged in the informative mcp-2025-11-25-compat.md, and decisions/001-mcp-2026-07-28-rebase.md records the rebase decision, verified fact sheet, and impact matrix.

Where The Recurring Concerns Live

A routing table, not a summary. Each row names a concern this skill keeps returning to and the rules that govern it; the rules themselves are stated only in contract-checklist.md. Read the cited ids — a row names the concern but does not define the rule, so a row is never a substitute for it.

ConcernGoverning rules
What carries the contract, and what is only advisory[5.scaffolding-only], [5.ap-contract-container], [2.instructions-advisory], [2.instructions-prefix], [2.truncation-signal]
Capability negotiation before optional features[1.negotiated-caps]
Tool granularity: tasks vs endpoints[3.task-completing], [3.hide-steps], [3.ap-endpoint-wrapping]
Side effects, idempotency, and rate limits[3.declare-effects], [3.honest-annotations], [3.annotation-defaults]
Prerequisites and implicit state an agent can act on[1.implicit-state], [2.summary]
Structured vs rendered output[3.structured-default], [3.output-schema]
Designing for the least-capable realistic client[2.compact-baseline], [2.progressive-disclosure], [2.client-variance]
Failure paths as contract[3.failure-contract], [6.symbolic-codes], [6.repair-object]

Cold-start first-call and first-repair success are the outcome measures this skill is tuned against: design-workflow.md Step 8 builds the measurement and Step 9 owns the regression gate.

Native Fields vs Convention Extensions

This skill is deliberately opinionated: native MCP fields alone are often insufficient for agent-friendliness, so well-designed servers add convention extensions such as structured errors, repair hints, prompt prerequisites, detail toggles, and — where target clients cache or pin the surface ([9.fingerprint]) — a capability fingerprint. Keep the conventions whose applicability rules hold — but never let them masquerade as protocol. The native-vs-convention rule is homed in this section; contract-checklist.md, native-wire-shapes.md, and examples.md cite it here rather than restating it.

  • Preserve native MCP field names and casing exactly; prefer snake_case for house/domain fields. A field's provenance is determined by the MCP type that contains it, not by its casing — native _meta carries an underscore, name/code/repair are lowercase on both sides, and a convention object may hold a mimeType-style name. So casing is a preference for house fields, never a test for whether a field is protocol. Tool: name, title, description, icons, inputSchema, outputSchema, annotations, _meta. Resource: uri, name, title, description, mimeType, size, icons, annotations, _meta. Resource template: uriTemplate, name, title, description, mimeType, icons, annotations, _meta. Prompt: name, title, description, icons, arguments, _meta. Implementation: name, title, version, description, icons, websiteUrl.
  • Put convention metadata under a namespaced _meta key (e.g., com.example/chunks) — the spec-sanctioned extension point — so it cannot collide with future MCP fields.
  • Label every convention extension as such where it appears, so a reader can tell protocol from house style.
  • The primary example blocks in this skill are wire-valid: convention metadata rides under a namespaced _meta key, never as a top-level field on a native record. See examples.md ex§1/ex§4/ex§5 for the worked _meta pattern; the few deliberately abbreviated blocks (e.g. ex§10) carry an explicit non-wire label.
  • For the exact native request/response envelopes, field names, and casing of the methods most often confused with house conventions — per-request _meta, list pagination and cache hints, completion, the tools/call result, MRTR, subscriptions, HTTP routing headers, and the tasks-extension lifecycle — see native-wire-shapes.md.

When To Use

  • Designing a new MCP server that agents (Claude Code, Codex, custom agents) will invoke.
  • Defining or hardening tool, resource, or prompt schemas for an existing server.
  • Auditing an existing MCP server for agent-friendliness.
  • Diagnosing concrete agent failures: wrong-tool selection from many candidates, repeated invalid tool calls, token waste from upfront definition loading, endpoint-mirroring tools that force long chains, broken cross-server upgrades.
  • Designing long-running work: progress notifications, cancellation, tasks via the negotiated extension, and long-running operation patterns (see contract-checklist.md §7 and examples.md ex§11).

When Not To Use

  • General code review of MCP server internals that does not face agents — use your normal code-review workflow.
  • Library or SDK design that is not exposed via MCP — this skill is MCP-specific.
  • Trivial schema additions to an already agent-friendly server; just follow the existing contract.
  • Out of scope: sampling and logging (both deprecated in 2026-07-28), server-operator dashboards, packaging/deployment, and skills-over-MCP (now a named extension in the formal extensions framework — revisit if it enters this skill's scope). Elicitation is in scope only as an agent-facing contract boundary; the binding rules live in contract-checklist.md §1 (declare the dependency on the client's elicitation modes) and §6 (elicitation use and the non-elicitation fallback). Do not use this skill for designing full user-experience flows.

Vocabulary

Shared terms — discovery surface, repair signal, state handle, capability fingerprint, negotiated capability, task-returning tool, and the rest — are defined in vocabulary.md; consult it when a term in the checklist or workflows is unfamiliar.

Checklist Map

The normative standard lives in contract-checklist.md, with two named exceptions homed in this file: the Spec Baseline facts and the native-vs-convention rule. There are two routes into the standard, and every design or review declares which one it took.

  • Full walk — read the checklist top to bottom. Required for a new server, a new primitive, a change to the auth model or the error taxonomy, a change of protocol-revision target, and any audit that reports coverage across §1–§9.
  • Focused route — for a change scoped to a known surface, such as one tool's input schema or one error payload.
    1. Name the surface and the sections it touches.
    2. Read [1.spec-revision] and the native-vs-convention rule below whatever the surface; they govern how every other rule is read.
    3. Read the named sections in full — sections, not single bullets, so a rule is never read without its neighbours.
    4. Close over citations: for every rule you read, read the rule ids it cites, and repeat until nothing new is pulled in. Those citations are the dependency edges, and following them is what stops a focused read from applying a rule without the rules it depends on.
    5. Report the sections you did not read as not-checked with the reason, per review-workflow.md — a focused route is never reported as full coverage. Escalate to the full walk when step 4 pulls in more than two sections beyond those you named, or when the change turns out to add a primitive.

The closure in step 4 converges rather than expanding to the whole standard: measured against the current checklist, a single-rule seed closes at 1–3 rules, and a whole-section seed at 19–27% of the 12,211 words of rule text. What is not measured is the focused route's effect on review quality — no scenario in tests/scenarios.md yet compares the two routes. Until one does, prefer the full walk wherever its cost is acceptable, and treat the focused route as a documented reduction whose risk is unquantified. This index orients and routes — its one-line summaries aid navigation and never define or override a rule. State-handle discipline and long-running-operation contracts are normative in §1/§8 and §7 respectively; consult them there rather than a second copy here. Notation: bare §N always means a contract-checklist section; ex§N means section N of examples.md. A single rule is cited by its stable id, `[section.slug]` — [3.naming], [6.repair-object] — which resolves to exactly one bullet in contract-checklist.md and survives rewording of that bullet. Prefer a rule id over a section reference when you mean one specific rule; tests/check_rule_ids.py fails the build if a cited id does not resolve.

§SectionSection gistWorked examples
§1Server-LevelIdentity, transport (including required HTTP routing headers), auth modes, agent-actionable prerequisites, per-request capability declaration, and workspace scope — learnable in one read. State handles are declared here: opaque IDs, lifetime, expiry, auth on every use.ex§7, ex§8a
§2DiscoveryA capability summary plus compact definitions as the universal baseline; progressive disclosure is a client-dependent optimization — pick a mechanism by cost axis (host-managed context, server-managed catalog, or client-independent surface reduction).ex§7, ex§8
§3ToolsTask-completing tools over endpoint mirrors; strict closed schemas; honest annotations; failure paths are contract, not prose.ex§1, ex§2, ex§2a, ex§10, ex§12, ex§13
§4ResourcesStable hierarchical URIs; index before body; stable chunk ids; templates + completion; subscriptions for mutable resources.ex§3, ex§4, ex§5a, ex§5b
§5PromptsAdvisory orchestration scaffolding only — reference tools by name, never redefine their contract.ex§5
§6Failure RecoveryStable symbolic codes, field-level feedback, explicit retryability, repair hints naming real callable surfaces.ex§6
§7Long-Running OperationsChoose blocking / progress / task-augmented deliberately; declare duration and timeout; recover via the native task lifecycle with a labeled fallback.ex§11
§8Token EfficiencyConcise default with a detail toggle; native list methods paginate with nextCursor (omission = done) and carry honest ttlMs/cacheScope, while a tool's own result payload may use a documented has_more convention; explicit truncation with a repair hint; identifiers chosen by role.ex§2
§9VersioningPublish a capability fingerprint where target clients cache or pin the surface; deterministic list ordering; native list-changed notifications; discoverable deprecation.ex§9, ex§9a

Workflow

  1. Classify the task: new MCP server or redesign vs review of an existing one.
  2. For new design or redesign, follow design-workflow.md.
  3. For an audit, follow review-workflow.md; severity scale and report format live there.
  4. Use contract-checklist.md as the detailed standard for both workflows.
  5. Use mcp-vs-cli.md if deciding which surface to expose; use examples.md for concrete schema, response, error, and discovery shapes.
  6. When writing or auditing prose surfaces — server instructions, the capability summary, tool and resource descriptions — apply the rules-then-context discipline in contract-checklist.md §2/§3/§4; if a separating-context-from-constraints skill is available in your environment, use it as the audit lens for those surfaces.
  7. Once the contract is designed, implement it with an MCP SDK — e.g. FastMCP for Python or the official TypeScript SDK. This skill defines the agent-facing wire contract, not the framework; if a FastMCP (or equivalent SDK) skill is available in your environment, use it for implementation specifics.

Done Criteria

Before declaring done, walk contract-checklist.md against your output.

  • Design tasks: every checklist section must have an answer in the schema set or be explicitly marked not-applicable with a one-line justification.
  • Review tasks: every checklist section is either covered by a finding, marked OK with brief evidence, or noted not-checked with reason. Use the severity scale and report format defined in review-workflow.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.