Skip to content

fix(skills): force MCP tool usage in all 15 skills#227

Merged
HumanBean17 merged 2 commits into
masterfrom
fix/skills-force-mcp-usage
May 24, 2026
Merged

fix(skills): force MCP tool usage in all 15 skills#227
HumanBean17 merged 2 commits into
masterfrom
fix/skills-force-mcp-usage

Conversation

@HumanBean17
Copy link
Copy Markdown
Owner

Summary

  • All 15 skills described MCP tool calls in prose/example format but lacked enforcement directives — agents could bypass MCP entirely and answer from training data or file browsing
  • Added "MCP required" section to every skill with explicit YOU MUST call these MCP tools directive
  • Added reasoning preamble requirement (Q-class / Pick / Why) before each MCP call (matching AGENT-GUIDE.md convention)
  • Added reference to docs/AGENT-GUIDE.md for the full operating manual
  • Added "Do not" guardrails: no answering from training data, no file browsing when MCP can answer, no fabricating ids
  • Rewrote Steps sections with imperative language ("Call resolve..." instead of "resolve(...)")
  • Updated skills/README.md with skill structure documentation

Root cause

Skills were written as documentation (worked examples, argument contracts) without any enforcement language. An agent reading a skill understood what to do conceptually but wasn't forced to actually make MCP tool calls. The fix adds three enforcement layers:

  1. MCP required section — explicit dependency declaration + "YOU MUST" directive
  2. Reasoning preamble — forces the agent to think about which tool and why before each call
  3. Do not guardrails — explicitly prohibits the fallback behaviors (training data, file browsing, guessing)

Test plan

  • All 15 skills contain "MCP required", "Do not", "reasoning preamble", and AGENT-GUIDE reference (verified via grep)
  • ruff check . passes (docs-only change)
  • Manual: invoke each skill and verify agent makes MCP tool calls

🤖 Generated with Claude Code

HumanBean17 and others added 2 commits May 24, 2026 22:27
Skills described MCP calls in prose/example format but lacked
enforcement directives — agents could bypass MCP entirely and
answer from training data or file browsing. Added to every skill:

- "MCP required" section with YOU MUST directive
- Reasoning preamble (Q-class / Pick / Why) before each call
- Reference to docs/AGENT-GUIDE.md for full operating manual
- "Do not" guardrails against skipping MCP or fabricating ids
- Imperative language in Steps ("Call resolve..." not "resolve(...)")
- Skill structure section in README.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Explicitly delineate .agents/skills/ (developers working on this repo)
from skills/ (consumers using the MCP on their own codebase) to prevent
confusion between the two audiences.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@HumanBean17 HumanBean17 merged commit b01419d into master May 24, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant