Add why-and-when doc: value proposition and decision guide (#62)

* Add why-and-when doc explaining value proposition and decision guide

Adds docs/why-and-when.md covering why skills over MCP matters (same
channel as tools, discovery, dynamic updates, control model, multi-server
composition, enterprise distribution) and when MCP distribution adds
value vs simpler alternatives. Linked from README and problem-statement.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add why-and-when summary to README before problem statement

Gives newcomers the value proposition immediately: skills are context,
MCP is a context protocol, and remote MCP servers can serve tools and
know-how together. Links to the full doc for depth.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add portable sub-agent point to why-and-when doc

Skills over MCP replaces the pattern of independently wrapping each
MCP server in a custom sub-agent with hand-written instructions —
the server author ships orchestration guidance once, everyone benefits.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Acknowledge enterprise trust trade-offs in both directions

Address PR feedback: git-based and MCP-based skill distribution each
raise different governance concerns. Link to open question on security
and trust boundaries.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ola Hungerford 2026-03-17 06:25:30 -07:00 • committed by GitHub
commit b2a2119984
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -22,6 +22,14 @@ This Interest Group explores how "[agent skills](https://agentskills.io/)" (rich
- **Client implementation mandates:** We can document patterns but not require specific client behavior
- **Plugin/bundle packaging:** Some use cases surface a broader need for installable bundles (skills + servers + subagents + configuration as a single artifact). How to solve for this is out of scope.
## Why Skills Over MCP?
MCP servers give agents tools, but tools alone are insufficient for complex workflows — tool descriptions tell an agent *what* a tool does, not *how to orchestrate* multiple tools to achieve a goal. Skills bridge this gap. They are structured "how-to" knowledge: multi-step workflows, conditional logic, and orchestration instructions that can run to hundreds of lines.
Skills are *context*, and MCP is a *context protocol*. Agents already connect to remote services over MCP to get tools — they can get the know-how to use those tools through the same channel. A remote MCP server can serve both its tools and the instructions for using them together, as a single atomic unit. This also enables automatic discovery (connect to a server, find its skills), dynamic updates (server-side changes flow without reinstall), multi-server composition (skills orchestrating tools across servers), and enterprise distribution (RBAC, multi-tenant, version-adaptive content) — all through infrastructure MCP servers already provide.
See [why-and-when.md](docs/why-and-when.md) for the full value proposition and a guide for when MCP distribution applies vs. simpler alternatives.
## Problem Statement
Native "skills" support in host applications demonstrates demand for rich workflow instructions, but there's no convention for exposing equivalent functionality through MCP primitives. Current limitations include:
@ -38,6 +46,7 @@ See [problem-statement.md](docs/problem-statement.md) for full details.
| Document | Description |
| :--- | :--- |
| [Problem Statement](docs/problem-statement.md) | Current limitations and gaps |
| [Why Skills Over MCP?](docs/why-and-when.md) | Value proposition and decision guide |
| [Use Cases](docs/use-cases.md) | Key use cases driving this work |
| [Approaches](docs/approaches.md) | Approaches being explored (not mutually exclusive) |
| [Open Questions](docs/open-questions.md) | Unresolved questions with community input |