# 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 `*.yaml` files).