# Default Skill Review Rules

For any frontmatter field not listed below, check the upstream spec before flagging - this checklist lags the specs.

## Frontmatter Checklist

### Standard - required

#### `name`
- 1-64 characters; lowercase letters, numbers, and hyphens only; no leading, trailing, or consecutive hyphens
- Must match the containing directory name

#### `description`
- Non-empty; max 1024 characters
- Describes both **what** the skill does and **when** to use it; include keywords so agents can match it against user intent

### Standard - optional

#### `license`
- License name, or a reference to a bundled license file

#### `compatibility`
- Max 500 characters; states environment requirements (intended product, system packages, network access)
- Most skills omit it; flag only when the skill clearly has requirements that go undocumented

#### `metadata`
- Map of string keys to string values for properties outside the spec
- Prefer reasonably unique key names to avoid collisions with other clients

#### `allowed-tools`
- List of pre-approved tools the skill may use; experimental, support varies by harness
- Only list tools the skill actually needs - flag powerful tools (Bash, Write, Edit) listed without clear need
- Prefer a comma-space delimiter (`Read, Grep, Glob`); both the standard and Claude Code accept it
- Guide skills (`user-invocable: false`) and skills using only MCP tools do not need this field

### Claude Code extensions (Claude Code skills only)

#### `disable-model-invocation`
- Should be `true` for side-effect workflows (deploy, commit, send, publish)
- If absent and the skill has side effects, flag it

#### `user-invocable`
- Should be `false` only for background-knowledge skills (guidelines, context)
- If absent, default is `true` - verify that makes sense

#### `context`
- `fork` only makes sense with explicit task instructions, not guideline-only content
- If set to `fork`, verify the skill gives actionable steps (not just reference material)

#### `argument-hint`
- If the skill accepts arguments, present with a bracket-notation hint (e.g. `[issue-number]`)
- The body must then use `$ARGUMENTS` or positional substitutions (`$0`, `$1`, ... - 0-based; `$ARGUMENTS[N]` and `$N` are equivalent)
- Define the behavior when no argument is provided

#### `model`
- Optional override for which model to use when the skill is active
- Should be a valid model ID for the harness

#### `agent`
- Only relevant when `context: fork` is set
- Valid values: `Explore`, `Plan`, `general-purpose`, or a custom subagent name; defaults to `general-purpose`

#### `hooks`
- Optional YAML object for hooks scoped to the skill's lifecycle
- Verify hook configuration follows the hooks specification format

#### Invocation model coherence
- The combination of `user-invocable`, `disable-model-invocation`, and `description` should make sense together
- A skill that is not user-invocable AND has model invocation disabled would never trigger - flag this

## Content Checklist

### Size and structure
- Under 500 lines total; if over, reference supporting files instead of inlining everything
- Progressive disclosure: metadata ~100 tokens, instructions <5000 tokens, detailed reference in separate files

### Instructions
- Step-by-step instructions present (not just a wall of text)
- Examples of inputs and expected outputs where applicable
- Edge cases addressed or acknowledged

### Supporting files
- Referenced from SKILL.md with relative paths
- Organized in subdirectories (`references/`, `scripts/`, `assets/`) if more than 2-3 files
- File references should be one level deep - avoid deeply nested reference chains

## Integrity Checklist (verify with Glob/Read)

### File references
- All file paths mentioned in SKILL.md (e.g., `[guide](references/guide.md)`, `Read references/foo.md`) resolve to actual files
- Use Glob to check existence of each referenced path relative to the SKILL.md directory

### Preprocessor commands
- `` !`command` `` directives reference commands that would be available in a typical environment
- Check that referenced scripts exist and paths are correct

### Script files
- Files in `scripts/` should be documented (what they do, any dependencies)

## Anti-patterns (flag if found)

| Anti-pattern | Why it's bad |
|---|---|
| Vague one-line description ("Helps with X") | Poor auto-invocation matching, unclear scope |
| Auto-invocation enabled on side-effect workflows | Risk of unintended destructive actions |
| Over 500 lines with no supporting files | Hard to maintain, slow to load |
| Over-permissive `allowed-tools` | Unnecessary security surface |
| `context: fork` with guideline-only content | Wastes a fork on passive reference material |
| Missing examples or success criteria | User can't verify correct behavior |
| Domain assumptions without explanation | Breaks portability across projects |
| Hardcoded absolute paths | Not portable |
| Unused frontmatter fields | Confusing, may indicate copy-paste from template |