Proposal: Add Claude Code Skills for context window optimization

[drillan]

Problem

The current AGENTS.md file is quite large (~2,400 lines) and is always loaded into the context window. This consumes significant tokens and limits:

• Complex multi-step tasks
• Sub-agent parallel execution
• Long conversations

Proposed Solution

Introduce Claude Code Skills for progressive context loading:

• Core principles always loaded (~300 lines)
• Detailed guidance loaded on-demand via Skills
• Full documentation preserved for deep dives

Measured Results (from fork testing)

Metric	Before	After	Change
Memory files	34.6k tokens	13.6k tokens	-60.7%
Free space	75k tokens	108k tokens	+44%
Context usage	62%	46%	-16%

Proposed Skills Structure

.claude/skills/
├── README.md                    # Usage guide
├── design-philosophy/SKILL.md   # 5 pillars, decision framework
├── implementation-guide/SKILL.md # Core philosophy, technical guidelines
├── agent-usage/SKILL.md         # Sub-agent patterns, parallel execution
└── discoveries/SKILL.md         # Known issues and solutions

Benefits

1. Reduced context usage - Load only what's needed
2. Better performance - More room for complex tasks
3. Preserved documentation - Full docs remain available via references
4. No breaking changes - Existing workflows unaffected

Reference Implementation

Fork with working implementation: https://github.com/drillan/amplifier/tree/feat/claude-code-skills

Branch ready for PR: feat/claude-code-skills (892 lines added)

Next Steps

If there's interest, I can submit a PR adding the Skills infrastructure.

Would love to hear feedback on this approach!