Question 1

How do you write a skill's description, and why does it matter so much?

Accepted Answer

Start from the mechanism: the agent does not see a skill's body — only its name and description. The description is the skill's only advertisement. My rule for writing it: 1. One sentence on what it does. 2. When to use it — in the words the user will actually use: "Compose review", "when adding a new Composable". 3. The key use case first, because the description gets truncated past a certain length in the listing. The typical mistake is writing it in your own technical language ("semantic analysis of Composables"). Users don't ask that way, so the skill never fires. Diagnosis: if a skill exists but is never auto-invoked, look at the description first, not the body.

Question 2

What is dynamic context injection (` !command `) good for? Give an Android example.

Accepted Answer

State the benefit in one sentence: when the agent opens the skill the needed information is already inside it — no extra step to go find it. Android examples: In a review skill, ` !git diff --name-only main -- '*.kt' — the changed Kotlin files are right there. In a version skill, !cat gradle/libs.versions.toml — the agent sees versions rather than guessing them. In a module skill, !./gradlew projects — the list of existing modules. State the limit too (this shows depth): the command runs every time and its output goes into context. So commands with large output (a full git diff`, say) are expensive this way — a list of file names is enough.

Question 3

A skill has grown to 800 lines. What do you do?

Accepted Answer

Explain why it is a problem, then fix it. Why it matters: once loaded, a skill's content stays in context for the rest of the session. 800 lines is a standing cost, plus the risk that a specific instruction gets lost. The fix — supporting files: `` compose-review/ ├── SKILL.md (navigation + core steps) ├── recomposition.md (deep reference) └── accessibility.md (deep reference) ` In SKILL.md, state what each file holds and when to open it. The agent reads only what it needs. A second question: is this really one skill, or three? 800 lines is often several distinct procedures piled together. Splitting them also sharpens each description`.

Frontmatter field	What it does
`description`	What the skill does and when to use it. The agent's decision rests on this — the most important field.
`when_to_use`	Additional trigger phrases and example requests.
`allowed-tools`	Tools usable without a prompt while the skill runs.
`disallowed-tools`	Tools removed from the pool while the skill is active.
`disable-model-invocation`	`true` — only you can invoke it with `/name`, the agent cannot.
`model` / `effort`	The model and effort level while the skill is active.
`context: fork`	Runs the skill in a separate subagent context.
`paths`	Globs — the skill auto-loads only when matching files are in play.

The anatomy of SKILL.md

📚 Sources and documentation