Restructure SKILL.md with progressive disclosure (390 → 154 lines)#13
Open
gdilla wants to merge 1 commit into
Open
Restructure SKILL.md with progressive disclosure (390 → 154 lines)#13gdilla wants to merge 1 commit into
gdilla wants to merge 1 commit into
Conversation
Move the tool routing matrix (~230 lines, 20+ tool profiles) from
SKILL.md into references/tool-profiles.md, loaded on demand after
the target tool is identified.
Motivation:
- SKILL.md was 390 lines. The Agent Skills spec recommends <500 lines
and <5000 tokens for the main SKILL.md (agentskills.io/specification).
While technically under the limit, ~60% of the content was tool-specific
routing profiles that are irrelevant for any given invocation — only 1
profile is needed per prompt, but all 20+ were loaded every time.
- Per Anthropic's best practices (agentskills.io/skill-creation/best-practices):
"Once a skill activates, its full SKILL.md body loads into the agent's
context window alongside conversation history. Every token in your skill
competes for the agent's attention."
What changed:
- SKILL.md: 390 → 154 lines (61% reduction in tokens loaded per invocation)
- Kept: identity, hard rules, output format, intent extraction,
diagnostic checklist, memory block, safe techniques, verification
- Added: Gotchas section (8 tool-specific pitfalls — highest-value
content per Anthropic's guidance)
- Added: conditional pointer to tool-profiles.md
- Moved: all 20+ tool profiles → references/tool-profiles.md
- references/tool-profiles.md: new file (157 lines)
- All tool profiles (Claude, GPT, Gemini, o1/o3, Qwen, Ollama, Llama,
DeepSeek, Claude Code, Antigravity, Cursor, Copilot, Bolt/v0/Lovable,
Devin, Perplexity, Image AI, Video AI, Voice AI, Workflow AI)
- Loaded only after the target tool is identified — not on every activation
The existing references/templates.md and references/patterns.md are unchanged.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
@nidhinjs Can the conflicts be resolved and this merged? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
references/tool-profiles.mdWhy
When prompt-master activates, the entire 390-line SKILL.md loads into the agent's context window. But ~60% of that content is tool-specific routing profiles (Claude, GPT, Gemini, o1, Cursor, Midjourney, etc.) — and only one profile is relevant for any given invocation. The other 19+ profiles compete for attention while adding zero value.
Per Anthropic's best practices:
The spec recommends keeping SKILL.md under 500 lines / ~5000 tokens, with detailed reference material in separate files loaded on demand via progressive disclosure.
What changed
SKILL.mdreferences/tool-profiles.mdreferences/templates.mdreferences/patterns.mdWhat stayed in SKILL.md (always loaded)
What moved to references/tool-profiles.md (loaded on demand)
The agent reads tool-profiles.md only after identifying the target tool — not on every activation.
How the flow works now
references/tool-profiles.md→ finds Claude Code section → applies those specific patternsPreviously step 2 and 3 were merged — all profiles loaded upfront whether needed or not.
Test plan
🤖 Generated with Claude Code