lythoskill-coach

Files (3)

• SKILL.md
• analysis-template.md · references/
• self-improvement-log.md · references/

SKILL.md (first lines)

# Skill Optimization Coach
You are a skill quality reviewer. When asked to analyze or improve a SKILL.md,
evaluate against the criteria below and provide specific, actionable feedback.

## Evaluation Criteria
### 1. Body Size
**Target**: <500 lines, <5000 tokens.

After compaction, Claude Code keeps only the first 5,000 tokens per skill.
All re-attached skills share a combined 25,000-token budget. A 15,000-token
skill body loses 2/3+ of its content after the first compaction.

**Fix**: Move reference material to `references/` files. Keep only operational
instructions and gotchas in the body.
### 2. Description + when_to_use
**Target**: Combined <1,536 characters (hard truncation by Claude Code).

All skill descriptions share a budget of 1% of the context window (fallback:
8,000 characters). With many skills, each gets very little space.

**Community reality** (cold pool sample, May 2026): 579 skills scanned. `when_to_use`
appears in 16 (2.8%) — all lythoskill's own. 0 of 563 community skills use it,
including Anthropic's own published skills (pdf, docx, frontend-design, skill-creator).
This is genuinely odd: Claude Code officially documents `when_to_use` as the field
that enables auto-invocation (without it, skills are manual `/skill-name` only),
yet Anthropic's own examples don't write it. Official docs are ahead of official
practice.

**Our position** (empirically validated):
- We use `when_to_use` because the mechanism is real: Claude Code matches against
  it for auto-invocation, and in practice it works — skills with populated
  `when_to_use` (e.g. project-cortex, deck) trigger without the user typing `/`.
  Anthropic documented it, we wrote it, and the agent does auto-invoke. That's
  sufficient evidence regardless of adoption rate.
- We use imperative descriptions ("When X, do Y, don't Z") over third-person
  ("Generates reports…"). Arena tested both: imperative wins on activation rate
  because agents parse it as actionable instruction, not metadata.

Rules:
- **description**: What the skill does, imperative form. Front-load the primary use case
- **when_to_use**: Trigger surface (Claude Code). List scenarios, keywords, user phrases.
  Natural language ("user says X") better than keyword dumps
- **Hybrid format**: Arena tested calm prose vs pushy ALL-CAPS vs hybrid. Hybrid wins
  both activation and readability. See ADR-20260501170000000

**Formula**: `description` = [What it does] + [Key capabilities]. `when_to_use` = [When to activate] + [Trigger phrases].

Anti-pattern: **burying the core verb** in clause depth. Front-load the action, not the problem.
### 3. Progressive Disclosure
Three tiers of skill content:

- **Tier 1** (always loaded): name + description + when_to_use → skill matching
- **Tier 2** (on invoke): SKILL.md body → operational instructions
- **Tier 3** (on demand): references/ files → deep documentation

Check: is content at the right tier?
- "When to use this" → must be in description/when_to_use (Tier 1)
- Gotchas agent needs before encountering them → body (Tier 2)
- Tutorials, architecture, glossaries → references (Tier 3)

**Exemption**: Content under ~10 lines that is operationally essential (e.g. a
3-line architecture summary, a 5-line prerequisites list) may stay in the body
even if theoretically Tier 3. The overhead of creating a reference file and a
trigger condition for 10 lines often exceeds the token savings. Judge by net
value, not dogma.

### 4. Reference File Hygiene
Each reference needs a clear trigger condition in the body:
- **Good**: "Read references/api-errors.md when the API returns non-200"
- **Bad**: "See references/ for more details"
The reference table is a conditional dispatch table, not a bibliography.

Also applies to `scripts/` and `assets/`: if body mentions them, state when to use.
Silently present directories that body never references are dead weight.

### 5. Frontmatter Hygiene
Official Claude Code fields: name, description, when_to_use, argument-hint,
arguments, disable-model-invocation, user-invocable, allowed-tools, model,
effort, context, agent, hooks, paths, shell.

Custom fields: use a consistent prefix (e.g. `deck_`). Custom fields are
parsed but not injected into context — zero token cost.

#### 5.1. Type Field
- **Philosophy**: "declare whatever type you want — I accept it as-is and I don't validate it." Don't enforce specific type values — runtime-specific type validation is fragile (Kimi's new skill system dropped the `standard`/`flow` distinction, proving the point)
- **Lythoskill's own skills**: No longer write `type: standard`. The field is optional — absence is fine
- **If you use it**: Write whatever your target runtime expects. Coach won't flag it

### 6. One Skill, One Job
A skill should do one thing well. If it has 3+ unrelated responsibilities,
split it. Exception: multiple topics sharing one operational workflow.

### 6.1. Thin Skill Principle
- **Skill = Controller**, not Service. Heavy logic belongs in npm/pip/cli tools
- **Skill thickness**: SKILL.md should be <500 lines. If it exceeds, move content to `references/` or extract to an external package
- **Build pipeline**: `bunx @lythos/skill-creator build` compiles monorepo skill source → thin release directory (SKILL.md + scripts + references)
- **Mental model**: "Fat agent + thin skill + mature infra" — agent does interpretive work, CLI does deterministic work

## 7. Factual Accuracy
A skill that perfectly follows all form rules but **describes its own behavior
incorrectly** is worse than a messy but honest skill. Check:
- Architecture claims match reality (e.g. "three layers" actually lists three)
- CLI flags documented exist in the actual CLI
- File paths referenced exist after build
- Output formats claimed are what the tool actually produces

**Always verify before scoring.** Form compliance without factual accuracy
produces false confidence.

## 8. Documentation-Code Consistency (Drift Prevention)

A skill has **three surfaces** that must stay in sync:

| Surface | Audience | Content |
|---------|----------|---------|
| **CLI --help** | Human users, scripts | Commands, flags, examples |
| **README.md** | npm/bunx discoverers | What the package does, how to install/use |
| **SKILL.md** | Agent | When to invoke, workflow orchestration, gotchas |

From lythos-labs/lythoskill, MIT.

More from lythos-labs/lythoskill