Agent Skills Spec Design Principles

Core Principle

Skills are portable procedural knowledge (“how to do something”), while MCP provides connectivity (“what tool to use”). Anthropic’s official framing: “MCP connects Claude to data; Skills teach Claude what to do with that data.” The Agent Skills spec is an open standard adopted by 30+ agent products (Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenAI Codex, and others).

Why This Matters

Properly separating methodology from implementation makes skills:

• Portable across agent products (same SKILL.md works in Claude Code, Gemini CLI, Cursor, etc.)
• Maintainable when the backend changes (swap Obsidian for Notion, only the reference files change)
• Efficient with context (methodology loads always, implementation loads on demand)

The spec’s progressive disclosure model manages context cost: metadata (~100 tokens) loads at startup, SKILL.md body (<5000 tokens) loads on activation, reference files load only when needed.

Evidence/Examples

• Knowledge-management skill restructure: split a 308-line Obsidian-coupled skill into a methodology-focused SKILL.md (~230 lines) with implementation details in references/. Ad-hoc requests now get methodology without tool-call noise.
• Anthropic’s Google Drive skill example: describes folder structure, naming conventions, search best practices, and workflow steps. No API call sequences in the body.
• Spec’s compatibility field: the designated place to declare environment requirements (e.g., "Requires mcp-obsidian MCP server"). Not widely used yet but spec-compliant.
• Best practices guide on templates: “agents pattern-match well against concrete structures.” Short templates inline in SKILL.md; longer ones in assets/. (agentskills.io/skill-creation/best-practices)

Implications

When building MCP-dependent skills:

1. SKILL.md body = methodology: what to do, in backend-agnostic language. Keep under 500 lines.
2. references/ = implementation: tool catalogs, parameter formats, complex procedures with specific tool calls. Small, focused files with conditional loading (“consult references/X.md when executing Y”).
3. assets/ = templates: output format templates the agent copies verbatim (e.g., Obsidian-specific rendering components).
4. compatibility field: declare MCP server dependencies in frontmatter, not in the skill body.
5. Description triggers: keep backend keywords (“Obsidian”, “vault”) in the description for discoverability, even if the skill name is methodology-oriented.

Related Ideas

• Guide to LLM abstractions
• Agent Skills Specification
• Skills explained (Anthropic blog)
• What are Skills? (Claude Help Center)
• Best practices for skill creators

Questions

• How should skills degrade gracefully when the MCP server isn’t connected? The spec doesn’t address this. Should skills declare fallback behavior, or just inform the user and exit?
• The allowed-tools field is experimental. Will it evolve into a formal dependency/permission system?
• As skills become cross-platform, will MCP tool names diverge across products? The current approach of listing tool names in references assumes a stable naming convention.