Post-processing enhancement layer for AI agent skills. Audits existing SKILL.md files against Anduril best practices and applies targeted optimizations: gotchas generation, description optimization, structure completion, and redundancy detection.
flowchart LR
I[Any SKILL.md] --> A[Audit<br/>9-dimension score]
A --> O[Optimize<br/>gotchas + description<br/>+ structure]
O --> V[Verify<br/>before/after score]
V --> R[Optimized Skill]
style I fill:#4a9eff,color:#fff
style R fill:#34d399,color:#fff
Works with any AI platform — the skill adapts to whatever tools are available:
| Action | Claude Code | OpenClaw | Gemini CLI |
|---|---|---|---|
| Read file | Read |
read_file |
read_file |
| Write file | Write |
write_file |
write_file |
| Search | Grep |
grep |
search_files |
| Shell | Bash |
run_command |
shell |
git clone https://github.com/yangsjt/skill-optimize.git ~/projects/skill-optimize
# Install slash command (enables /skill-optimize)
cp ~/projects/skill-optimize/commands/skill-optimize.md ~/.claude/commands/
# Install skill (provides methodology knowledge base)
cp -r ~/projects/skill-optimize/skill/ ~/.claude/skills/skill-optimize/Then in Claude Code:
/skill-optimize ~/.claude/skills/my-skill/
/skill-optimize --audit-only
git clone https://github.com/yangsjt/skill-optimize.git ~/projects/skill-optimize
# Symlink into OpenClaw skills directory
ln -sf ~/projects/skill-optimize/skill ~/.openclaw/skills/skill-optimizegit clone https://github.com/yangsjt/skill-optimize.git ~/projects/skill-optimize
# Register as Gemini CLI skill
gemini skills link ~/projects/skill-optimize/skillThen in Gemini CLI:
> optimize skill: review my SKILL.md quality
> audit skill at ./my-project/SKILL.md
Scores skills against the Anduril maturity model:
| Dimension | Weight | What's Checked |
|---|---|---|
| Structure | 15% | Frontmatter, sections, hierarchy |
| Description | 15% | Trigger precision, keywords |
| Gotchas | 20% | Failure modes, edge cases |
| references/ | 10% | Progressive disclosure |
| config.json | 5% | Metadata completeness |
| scripts/ | 5% | Reusable snippets |
| hooks/ | 5% | Tool-use integration |
| Redundancy | 15% | Content Claude already knows |
| Activation | 10% | When-to-use conditions |
P0 — Gotchas Generation (highest impact)
- Analyzes git history: revert commits, fix commits, high-churn files
- LLM inference: framework pitfalls, configuration traps, integration edge cases
- Output: structured gotchas with symptom / root cause / solution
P0 — Description Optimization
- Transforms generic descriptions into precise trigger conditions
- Adds action-oriented use cases and TRIGGER keywords
- Example:
"Coding patterns"→"React component architecture and state management. Use when creating components or debugging re-renders. TRIGGER: React, useState, useEffect."
P1 — Structure Completion
- Generates
references/directory for progressive disclosure - Creates
config.jsonwith metadata and trigger keywords - Scaffolds
hooks/templates
P2 — Redundancy Detection
- Flags content Claude would produce without the skill
- Suggests deletion or condensation
Before/after score comparison to confirm improvement.
skill-optimize/
├── commands/
│ └── skill-optimize.md # Claude Code slash command
├── skill/
│ ├── SKILL.md # Cross-platform skill (main)
│ └── references/
│ ├── anduril-checklist.md # Detailed scoring criteria
│ ├── gotchas-generation.md # Gotchas methodology
│ └── description-optimization.md # Description guide
└── README.md
Based on research comparing /skill-create (git-history extraction, ~60-100 lines output) and skill-seekers (external knowledge ingestion, 600-800+ lines). Neither tool reaches Anduril's maturity standard — both lack gotchas generation, description optimization, and structural completeness. /skill-optimize fills this gap as a post-processing layer that works with output from either tool.
Methodology derived from a comparative analysis of /skill-create, skill-seekers CLI, and Anduril's skill guide.
MIT