Skills: surface-neutral SKILL.md body, with MCP and CLI instructions in references/ files

[mocha06]

Problem

A SKILL.md today mixes rules that are true on every surface with instructions for one surface:

• The "CLI equivalent" column in every tool table.
• The MCP two-step delete: the [^mcp-confirm] footnote, confirm=true, confirmation_token (for example skills/ai-agents/pipefy-ai-agents/SKILL.md:28,32,331, skills/automations/pipefy-automations/SKILL.md:26,47,50).
• "Local profile" and "hosted URL" notes (pipefy-ai-agents/SKILL.md:169,240).
• MCP-only parameters: debug=true and skip_elicitation (pipefy-pipes-and-cards/SKILL.md:20,101), and include_parsed (pipefy-introspection/SKILL.md:37-44).

An agent that uses the SDK, not the MCP server or the CLI, reads all of this as instructions for itself. It has no confirm-token round trip and no CLI.

Links between skills are relative paths such as ../../ai-agents/pipefy-ai-agents/SKILL.md. Many agent frameworks load skills one level deep, as <skill>/SKILL.md. A consumer that flattens the catalog to that layout cannot follow the links.

Proposal

• The SKILL.md body holds only surface-neutral content: domain rules, payload shapes, steps, failure modes. It names each operation by the tool name that all surfaces share.
• Surface-specific instructions move to sibling files: references/mcp.md (confirm tokens, elicitation, local and hosted profiles, MCP-only parameters) and references/cli.md (commands and flags). The body points to them in one line, for example "MCP clients: read references/mcp.md".
• Links between skills use the skill name ("see the pipefy-automations skill"), not a relative path.

Non-breaking

MCP and CLI users keep every line. It is one file read away, which is how progressive disclosure already works. skills.sh and the Cursor plugin copy the whole directory, so the reference files travel with the skill.