0008 — Skill tool-dependency declaration (requires_mcp) with loud activation failure¶
- Work-item id: abstractskill-0008
- Owner: skill
- Status: Completed
- Completed: 2026-07-21
- Created: 2026-07-19
- Thread: dm:meshvault--skill#2 (asks 1-3, answered seq 3)
Summary¶
Give SKILL.md authors a declared way to say "this skill requires MCP server X (or tool Y)" so activation can FAIL LOUDLY with an install hint instead of agents discovering mid-task that the taught tools are absent — the teach-what-is-wired principle applied to skills themselves.
Reason / origin¶
The meshvault seat's meshvault-live-editing skill (operator-directed
registration discussion, 2026-07-19) teaches recipes that all presuppose a
reachable meshvault-mcp server — a third-party MCP dependency. The
frontmatter contract today carries no dependency field; the failure mode is
an agent activating the skill, following a recipe, and hitting absent tools
mid-task. Two body-side conventions exist now (dependency named in the
activation description; metadata: {requires_mcp: [...]} as a free-form
convention hosts may check) — this item is the HOST-SIDE half.
Scope¶
- Adopt
metadata.requires_mcp: [server-names](and possiblymetadata.requires_tools: [tool-names]) as a DOCUMENTED convention — no parser/contract change needed (metadata is already a free mapping); document in the skills contract docs. select_skills_for_context(the 0087 trust gate) surfaces arequiresfield on resolved selections the way trust verdicts ride today, so hosts can check declared dependencies against their live tool/MCP inventory and refuse-with-reason ("skill X requires meshvault-mcp — not reachable; install hint: ...") instead of activating blind.- Render rule (consumers, feature-detected): a skill whose declared dependency is absent renders selectable-with-warning or blocked-with-reason per the host's policy — never silently activated, never silently hidden (the launch-skills render rules extended by one verdict class).
Non-goals¶
- No hard contract field in frontmatter v1 (metadata convention suffices; a first-class field is a later widening through the normal path).
- No auto-install of missing servers (the hint names, never executes).
Current code reality¶
SkillMetadata.metadatais a frozen free-form mapping (models.py:20) — the convention rides today with zero code change.select_skills_for_contextreturns verdicts (trust state, reasons); no dependency awareness.- First consumer waiting: meshvault-live-editing (registration pending their SHA + evidence receipt).
Validation expectations¶
- A skill declaring
requires_mcp: [x]resolves with the requires field surfaced; a host with x absent refuses with the reason verbatim; a host with x present activates normally. Pinned by tests on the selection surface; docs updated in the same change (coredoc discipline).
Completion report¶
- Date: 2026-07-21
- Summary:
SkillRequires+SkillSelection.requiresshipped — frontmattermetadata.requires_mcp/metadata.requires_toolssurface on the selection for every resolved name (active/held/blocked; no row when nothing declared). Host information for refuse-with-reason; never a gate in this library, never an auto-install (scope items 1-3 delivered: convention documented in docs/api.md Models + Selection; requires field on resolved selections; render rule stated as host policy, never library enforcement). - Files: src/abstractskill/selection.py (SkillRequires, _parse_requires, requires field + population), src/abstractskill/init.py (export), tests/test_selection.py (6 pins incl. both-channel warning), tests/test_shelf.py (live-shelf pin: meshvault keeps declaring), docs/api.md, llms-full.txt, CHANGELOG.md.
- Tests: 166 passed (5 synthetic + 1 live-shelf pin new).
- Adversary: fable5 pass — 0 P0, 1 P1 (live-shelf pin missing — folded), 6 P2s (5 folded: absent-vs-empty comment semantics, order-preserving dedup, both-channel warning pin, author-facing Models pointer, card hygiene; 1 routed: gateway consumer pointer).
- Follow-ups: (1) gateway seat pointed at the surface (their entity_skills resolve is the first host consumer — the refuse-with-reason check is theirs to wire); (2) first-class frontmatter field stays a later widening through the normal path (non-goal held).