Agent skill guide
Agent Skills vs MCP: Choose Instructions, Tool Access or Both
Understand the practical boundary between agent skills and MCP, with examples for Figma, Notion, CI diagnosis and local document tasks, plus a dependency worksheet.
An agent skill describes how to perform a task. MCP provides a protocol through which an application can expose capabilities and context to an agent. A workflow can need either layer or both. The useful decision is whether your bottleneck is missing procedure, missing access or an unverified result. This guide was reviewed on 20 October 2026 and uses source-based examples, not runtime compatibility claims.
What does each layer actually provide?
The Agent Skills format packages instructions and optional supporting files. A skill can tell an agent how to review a report, which checks to apply and where to save an artifact. If it includes scripts, those scripts still need an execution environment and the task’s permissions.
MCP’s official introduction describes connections between AI applications and external systems. A configured server can expose operations such as looking up an issue or reading design context. Whether any operation is available depends on the server, client, account and authorization configuration.
| Question | Agent skill | MCP integration |
|---|---|---|
| Primary job | Package a repeatable procedure | Expose capabilities and context through a protocol |
| Typical input | Task, instructions, templates and reference material | Tool arguments and authorized service context |
| Typical dependency | Host agent tools and any bundled helpers | Server, client support and service access |
| What it does not guarantee | Tools exist, task quality or safe execution | Correct workflow, appropriate writes or factual output |
| Review focus | Instructions, code, references and intended scope | Tool schema, permissions, destinations and returned data |
When is a skill enough for the task?
A local document task may need procedural guidance and existing filesystem tools without any MCP server. The PDF workflow emphasizes extracting content, creating a document and inspecting rendered pages. Its additional dependencies are local packages and rendering tools. Adding an unrelated connector would increase setup work without addressing that task’s main quality problem.
A CI diagnosis workflow in this collection uses GitHub CLI. Access to GitHub is necessary, but the reviewed implementation does not require that access to be supplied through MCP. Choose the supported access mechanism already appropriate to the project rather than adding a protocol layer by default.
When does a workflow need both?
The Figma MCP Skill supplies a sequence: obtain exact design context, obtain a visual reference, then translate the design into the project’s components. The Figma connection supplies the design-reading capability. Without the connection, the agent may know the sequence but lack the design data. Without a suitable procedure, the same design data can be used inconsistently.
The Notion research workflow similarly separates source gathering, synthesis and destination publishing. The integration can read or write pages; the skill gives the research structure. A good result also needs citation checks and a destination audience that is authorized to read the underlying material.
How do you diagnose which layer is missing?
- Can the agent access the required input? If not, inspect the service connection, account and scope before rewriting instructions.
- Can it explain a valid procedure? If access exists but steps are inconsistent, a narrow skill or better task instructions may help.
- Can it produce an artifact with that procedure? Check tool and runtime dependencies next.
- Can you verify the artifact? Add acceptance checks; another integration alone will not establish correctness.
For example, “Notion search returned no pages” can be a permissions or query problem. “The report omitted a contradictory proposal” can be a research-scope or synthesis problem. “The report was published to the wrong team” is a destination and authorization failure. Treating all three as a skill-discovery issue leads to the wrong fix.
Which permissions deserve separate review?
List reads, writes and external transfers as separate operations. A source-reading tool does not justify a page-creation tool. A skill that asks for a draft does not authorize an external post. Review tool results and retrieved pages as untrusted material, especially if they contain instructions to change scope or access secrets.
The MCP Builder profile is an authoring workflow for making servers, not a universal ready-to-use connector. A generated server needs its own input validation, authentication, error handling and operation-level tests. Begin with a read-only synthetic prototype if a custom integration is necessary.
What should a reproducible dependency record contain?
Record the skill repository and commit, the host and model, helper versions, MCP server identity, authorized service scope, input fixture and expected output. For remotely fetched rules, record their version too. Keep secret values out of this record; name the credential source or account role rather than storing the token.
Use the dependency and permission worksheet to decide which layer is needed. The evaluation guide then checks the combined workflow against an unchanged baseline.
Common architecture questions
Does installing a skill install its MCP server?
Do not assume so. Some distribution packages can bundle several components, but a folder of instructions and a configured service connection remain distinct things to inspect and authorize.
Should every internal process become a skill?
No. A short one-time request may be clearer as a prompt. A stable project convention may belong in the project’s rules. Reusable procedural instructions are most useful when the same multi-step task recurs with different inputs.
What changed: first edition adds a layer-by-layer diagnosis method and four task examples. No performance, security or cross-platform equivalence is inferred from protocol support.