a4967df815
Conventions, community best practices research (Sept 2025 - March 2026), and prioritized improvement backlog for Claude Code workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2.9 KiB
Skills & Progressive Disclosure
Why This Matters
Progressive disclosure is the single most powerful technique for managing context. Instead of putting everything in CLAUDE.md (which competes with Claude's ~50 built-in system instructions for attention), skills load domain knowledge on demand — only when relevant.
Token savings: ~15,000 tokens per session recovered vs. loading everything upfront (82% improvement in one benchmark).
Current State
- One custom skill:
reflect - Skills symlinked from
~/dev/claude/custom-claude-skills/skills/into~/.claude/skills/
Architecture
CLAUDE.md # <200 lines, universal rules only
.claude/skills/ # Domain knowledge loaded on demand
.claude/rules/ # Path-scoped rules (YAML frontmatter for file pattern matching)
Skills use a three-stage loading: metadata (~100 tokens) -> full instructions (<5k tokens) -> bundled resources only as needed.
Suggested Skills to Build
/catchup
Reads all changed files in your git branch when resuming work. Shows what changed since last session, reads relevant memory files, and summarises the current state.
/validate
Codifies the "validate before deploying" principle. Runs helm template, kustomize build, linting, and type-checking as appropriate for the current project. Catches errors before they hit the cluster.
/deploy
Standardised deploy workflow for cluster-bootstrap. Validates first, applies, then runs the appropriate verify script.
/security-audit
Checks for secrets in code, insecure configurations, default credentials. Trail of Bits has 12+ open-source security skills that could be adapted.
/tdd
Test-driven development workflow. Write tests first, then implement until tests pass. From obra/superpowers — 20+ production-proven skills.
/handoff
Creates a structured handoff document (goals, progress, blockers, next steps) for session transitions. Useful before /clear or when hitting context limits.
Community Skills Worth Evaluating
| Skill/Resource | Description |
|---|---|
| obra/superpowers | 20+ skills: TDD, systematic debugging, root cause tracing, brainstorming |
| Trail of Bits security skills | 12+ security-focused skills for code auditing and vulnerability detection |
| cc-devops-skills | IaC validation, shell script generation, DevOps workflows |
| Context Engineering Kit | Advanced context engineering techniques with minimal token footprint |
| reddit-fetch | Workaround for Claude's inability to fetch Reddit — uses Gemini CLI as fallback |
Best Practices
- Limit to 20-30 high-quality skills. More than that degrades performance (Claude wastes tokens parsing descriptions).
- Each skill should have one clear purpose and be self-contained.
- Skills should be <200 lines / <5k tokens for the full instruction set.
- Use YAML frontmatter in
.claude/rules/for path-scoped conditional loading (e.g., rules that only apply to*.yamlfiles).