docs: assert the prompts-vs-skills boundary and guard against procedural drift #241

New issue

Closed

opened 2026-07-17 19:25:56 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-17 19:25:56 +00:00

(Migrated from codeberg.org)

Skills are MODEL-invoked (the client's model auto-triggers them on description match) and exist only for plugin users - SKILL.md is a Claude Code plugin construct.
Prompts are USER-invoked slash commands over the MCP protocol itself, so they work in ANY MCP client with no plugin - for that audience they are the only workflow-guidance surface.

This is intended multi-surface coverage (same philosophy as the #172 consolidation: the plugin owns hooks; the binary/MCP surface owns the cross-client path), and both already delegate tool shapes to madt_help, so tool-level detail cannot drift. Not redundant in the harmful sense; do NOT collapse one into the other.

The gap: no written assertion of the prompts-vs-skills boundary exists, and nothing guards the PROCEDURAL framing from drifting between a prompt's expansion and a skill's lifecycle text (the same multi-channel drift #172 eliminated for hooks). The two skills mark their mutual boundary with "intentionally separate from ..." comments; the prompt/skill boundary has none.

Scope:

Add a short boundary note (architecture doc or comment block) stating: skills = model-invoked rich guidance for plugin users; prompts = user-invoked protocol-native slash commands for any MCP client; both thin over madt_help as the single source of truth; a workflow may appear on both surfaces deliberately.
Decide and record whether a prompt and its sibling skill must stay procedurally aligned, and if so the cheapest guard (e.g. both cite the same madt_help topic; a test mapping every prompt name to a documented workflow).
No behavior change; legibility + drift prevention only.

Grounding: prompts in internal/mcp/prompts.go (6, with the server-wide CompletionHandler); skills in skills/dev-workflow/SKILL.md + skills/forge-workflow/SKILL.md (both delegate to madt_help).

The MCP prompt catalog (start-feature, finish-branch, file-issue, triage, review, standup) and the two plugin skills (dev-workflow = change lifecycle, forge-workflow = forge operations) cover the same workflows by design, via different mechanisms: - Skills are MODEL-invoked (the client's model auto-triggers them on description match) and exist only for plugin users - SKILL.md is a Claude Code plugin construct. - Prompts are USER-invoked slash commands over the MCP protocol itself, so they work in ANY MCP client with no plugin - for that audience they are the only workflow-guidance surface. This is intended multi-surface coverage (same philosophy as the #172 consolidation: the plugin owns hooks; the binary/MCP surface owns the cross-client path), and both already delegate tool shapes to madt_help, so tool-level detail cannot drift. Not redundant in the harmful sense; do NOT collapse one into the other. The gap: no written assertion of the prompts-vs-skills boundary exists, and nothing guards the PROCEDURAL framing from drifting between a prompt's expansion and a skill's lifecycle text (the same multi-channel drift #172 eliminated for hooks). The two skills mark their mutual boundary with "intentionally separate from ..." comments; the prompt/skill boundary has none. Scope: - Add a short boundary note (architecture doc or comment block) stating: skills = model-invoked rich guidance for plugin users; prompts = user-invoked protocol-native slash commands for any MCP client; both thin over madt_help as the single source of truth; a workflow may appear on both surfaces deliberately. - Decide and record whether a prompt and its sibling skill must stay procedurally aligned, and if so the cheapest guard (e.g. both cite the same madt_help topic; a test mapping every prompt name to a documented workflow). - No behavior change; legibility + drift prevention only. Grounding: prompts in internal/mcp/prompts.go (6, with the server-wide CompletionHandler); skills in skills/dev-workflow/SKILL.md + skills/forge-workflow/SKILL.md (both delegate to madt_help).

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#241

No description provided.

Rows
Columns