v0.19.1 to v0.19.1

---

name: lythoskill-coach

version: 0.19.1

description: |

Analyzes SKILL.md files against Agent Skills best practices. Reviews

body size, description quality, progressive disclosure, frontmatter

usage, and context efficiency. Provides actionable optimization advice.

when_to_use: |

Creating a new skill, reviewing SKILL.md, optimizing skill quality,

reducing skill token usage, improving skill discovery, skill audit,

skill writing best practices.

---

# 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 |

### Common Drifts

**SKILL.md documents a command that doesn't exist in the CLI.**

- Example: SKILL.md says `generate` but CLI only has `template` and `prompt`

- Fix: Remove the fictional command from SKILL.md. Add it to CLI if it belongs there.

**SKILL.md implies output formats the tool doesn't produce.**

- Example: "Render to SVG or PNG" but `render` only outputs SVG, PNG needs a separate `convert`

- Fix: Be precise. "`render` produces SVG. Use `convert` for PNG/WebP/JPG/AVIF."

**README.md is missing or stale.**

- npm/bunx users see an empty README and can't figure out what the package does

- Fix: README must have: one-line description, install/run commands, at least one example

**SKILL.md does agent work that should be in the CLI, or vice versa.**

- Example: CLI has a `prompt` command that generates LLM prompt templates. Prompt engineering belongs in SKILL.md (agent layer), not in CLI (tool layer).

- Rule: CLI does **deterministic** work (templates, rendering, validation). Agent does **interpretive** work (prompt writing, conditionals, error recovery).

### Verification Method: Subagent Test

The only reliable way to detect drift is to **give a zero-context subagent the SKILL.md and a task**:

> "You have no prior knowledge of this project. Use the skills in the working set directory

> to [do X]. Read SKILL.md for instructions. Do not ask for help."

If the subagent fails because SKILL.md told it to use a non-existent command,

you have a drift. Fix it.

## 9. Naive Agent Test (Content Completeness)

A skill that passes all static checks may still fail in practice because it

assumes knowledge the agent doesn't have. Test by mental simulation (or actual

subagent dispatch):

> Give a naive agent only this SKILL.md + a typical user request. Can it

> complete the task without guessing?

Common completeness gaps:

- **No Quick Start / end-to-end example**: Agent knows commands exist but not

the expected sequence or output format.

- **No prerequisites**: Agent doesn't know it needs Bun, pnpm, or a specific

directory structure.

- **No boundary behavior**: "What if the target directory already exists?"

"What if SKILL.md lacks frontmatter?" Agent has to guess.

- **Output not described**: A scaffold tool must show the generated directory

tree. A review tool must show the output format. Without this, the agent

hallucinates.

**This is the most important dimension.** A 39-line skill with complete

instructions outperforms a 390-line skill full of gaps.

## Key Numbers (Quick Reference)

| Metric | Value | Source |

|--------|-------|--------|

| SKILL.md body max lines | 500 | Claude Code docs |

| Post-compaction budget per skill | 5,000 tokens | Auto-compaction |

| Total re-attached skills budget | 25,000 tokens | Auto-compaction |

| description + when_to_use cap | 1,536 characters | Skill listing |

| All descriptions budget | 1% of context window (fallback: 8,000 chars) | Skill listing |

| Budget override env var | `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Claude Code config |

| SKILL.md `type` | Optional; no enforced values | Runtime-specific, fragile to validate |

| Custom field prefix | `deck_` | lythoskill convention |

| Locator format | FQ: `host.tld/owner/repo/skill` | ADR-20260502012643244 |

## Gotchas

**"See references/ for more details" is a bibliography, not a dispatch table.**

Every reference entry needs a trigger condition: "Read X when Y happens."

"For teams that struggle with maintaining consistent deployment pipelines…"

→ "Automates multi-environment deployments with rollback support."

Front-load the solution, not the problem.

**Don't paste reference content into the body "just in case."**

If the agent can always reach the reference, body bloat buys nothing. The 5,000-token

compaction budget is real — a 15,000-token skill loses 2/3 of its content.

**Reference community practice when rules conflict with reality.**

High-star skills (gstack, anthropic-official) use narrative descriptions with

conditional clauses ("Use when user uploads…"). The formula is

[What it does] + [When to use it] + [Key capabilities], not "functional only."

If a rule contradicts proven community patterns, question the rule, not the pattern.

## Analysis Output

When reviewing a SKILL.md, produce a scoring table and then list the top 3

highest-impact improvements with before/after examples.

**Before each review**: read [references/self-improvement-log.md](./references/self-improvement-log.md)

for recent meta-lessons that may affect your scoring (e.g. updated rules,

community practice findings, common pitfalls from past reviews).

See [references/analysis-template.md](./references/analysis-template.md) for the

exact table format and prioritization rules.

## Supporting References

Read this **only when producing the analysis table**:

| When you need to… | Read |

|--------------------|------|

| See the full scoring table template and improvement format | [references/analysis-template.md](./references/analysis-template.md) |