Anthropic’s framing draws the line cleanly: “MCP connects Claude to data; Skills teach Claude what to do with that data.” Skills carry portable procedural knowledge (“how to do something”); MCP provides connectivity (“what tool to use”). The Agent Skills spec is an open standard adopted by 30+ agent products (Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenAI Codex), and the design payoff comes from keeping methodology and implementation cleanly separated rather than mashing them into one document.
The benefits compound. Portable: the same SKILL.md works across agent products. Maintainable: when the backend changes (swap Obsidian for Notion), only the implementation reference files change. Efficient with context: the spec’s progressive-disclosure model loads metadata (~100 tokens) at startup, the SKILL.md body (<5000 tokens) on activation, and reference files only when needed. A skill that mashes methodology and implementation pays the activation cost up-front and re-pays it every time the backend shifts.
The recipe that falls out: SKILL.md body = methodology (what to do, in backend-agnostic language; keep under ~500 lines); references/ = implementation (tool catalogs, parameter formats, complex procedures with specific tool calls; small focused files, conditionally loaded with phrases like “consult references/X.md when executing Y”); assets/ = templates (output format templates the agent copies verbatim, e.g. Obsidian rendering components). Declare MCP server dependencies via the spec’s compatibility frontmatter field, not in the skill body. Keep backend keywords (“Obsidian,” “vault”) in the description for discoverability even when the skill name is methodology-oriented.
The knowledge-management skill restructure is a worked example: a 308-line Obsidian-coupled skill split into a methodology-focused SKILL.md (~230 lines) with implementation in references/. Ad-hoc requests now get methodology without tool-call noise, and swapping in a non-Obsidian backend touches only references. See agentskills.io/skill-creation/best-practices for the broader pattern catalog.