agentleFS
selamy-labsselamy-labs/agent-skills/skills/authoring-skills-vs-mcp/SKILL.md

authoring-skills-vs-mcp

Skill0 starsChanged 7 days agoMITView on GitHub

Use when deciding whether a capability should be a SKILL or an MCP SERVER, and how to author either well. The axis is knowledge-vs-capability: would the agent READ this to know how, or CALL this to do it?

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read-to-know-how → skill. (e.g.

    line 15
  2. Distinctive:

    Call-to-do-it → MCP. (e.g.

    line 16
  3. Distinctive:

    Provenance / security audit: run the server through a static skill/tool audit (malicious-code + injection scan) before any agent adopts it.

    line 36
  4. Distinctive:

    Use: when classifying a capability/knowledge item, or deciding how to extend an agent.

    line 42

≈ “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

Authoring: Skills vs MCP Servers

Two different ways to extend an agent, for two different things. Picking the wrong one is the most common waste: knowledge bloated into a server, or a real capability trapped in prose the model can only read, never call. This skill is the decision axis plus how to author each artifact. It composes with skill-creator / writing-skills (authoring mechanics) and mcp-builder (server mechanics) — it covers the choice between them, which they don't.

1. The decision axis (apply this first)

  • SKILL = knowledge. Methodology, convention, domain knowledge the model reads into context and then acts on with the tools it already has. There is nothing to "call."
  • MCP SERVER = capability. An external system / API / DB / service that needs credentials and structured I/O — a callable tool the model invokes to do something and get a typed result back.

The test: "Would the agent READ this to know how, or CALL this to do it?"

  • Read-to-know-how → skill. (e.g. "how to model a REST resource", "how we review for regressions".)
  • Call-to-do-it → MCP. (e.g. "search this ticketing system", "write a DNS record", "query the metrics warehouse".)

Two failure modes to reject:

  • Don't MCP-ify knowledge. A methodology doesn't become a server because it's important. It has no creds, no structured call — it's a skill.
  • Don't trap a capability in prose. A skill that says "here's how to hit API X: curl this, parse that" is a capability wearing a skill costume. Extract it into an MCP tool; leave at most a thin methodology skill behind.

Hybrids are real: keep the methodology as a skill and the call as an MCP (e.g. a "research discipline" skill beside a "search the source" MCP). Split along the read/call line.

2. How to author a SKILL

  • Frontmatter: name (kebab-case purpose), a description that says when to use (and when not) so it's discoverable cold.
  • Progressive disclosure: lead with the decision/the rule; push detail and edge cases lower or into companion files.
  • When-to-use / when-not: state both. A skill that never says when not to fire mis-activates.
  • Examples + anti-patterns: show the right call and the common wrong ones.
  • Gold-bar, no slop: a skill earns its place by changing behavior. If it restates what a capable model already does, don't ship it.

3. How to author an MCP SERVER

  • Tools & resources: model each tool as one clear verb with a typed input/output schema. Prefer a few sharp tools over one overloaded one.
  • Structured I/O: return structured results, not prose blobs — the caller is a program path.
  • Credentials stay out of the server body: fetch them at call-time from a secrets broker / secret store; never bake keys into the server or its config. Keys live in the broker, not the workload.
  • Idempotency & errors: make writes safe to retry; return typed errors the agent can branch on.
  • Provenance / security audit: run the server through a static skill/tool audit (malicious-code + injection scan) before any agent adopts it.

4. Gates and where it ships

Both artifacts clear the same publishing bar — gold-only utility, privacy/secret scan, gated PR, public-first routing. That bar lives in skill-curation; apply it, don't restate it here.

When to use / not

  • Use when classifying a capability/knowledge item, or deciding how to extend an agent.
  • Not for the line-by-line mechanics of writing a skill (skill-creator / writing-skills) or wiring a server (mcp-builder) — this picks which one, then hands off.

Anti-patterns

  • Building an MCP server for a pure methodology (knowledge-as-a-server).
  • A skill that teaches the agent to hand-call an external API (capability-in-prose) instead of an MCP tool.
  • One mega-tool with an untyped grab-bag input.
  • Credentials embedded in the server instead of fetched from a broker at call-time.
  • Adopting a server with no provenance/security audit.
  • Publishing either artifact with org traces, or on elegance instead of proven value.

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.