This document defines what a "production-grade Skill" means in this repository. Use it as the source of truth when creating or refactoring anything under `skills/`.
Keywords: MUST / SHOULD / MAY / MUST NOT / SHOULD NOT are normative.
## 1. Directory & Naming
- A Skill MUST be a directory under `skills/` named after its `name` field.
- The directory name MUST match `^[a-z][a-z0-9-]*$`.
- The Skill entrypoint MUST be `SKILL.md` at the root of the skill directory.
## 2. Frontmatter (Required)
`SKILL.md` MUST start with YAML frontmatter:
```yaml
---
name:skill-name
description:"What it does + when to use (activation triggers)."
---
```
Rules:
-`name` MUST match `^[a-z][a-z0-9-]*$`.
-`name` SHOULD equal the directory name.
-`description` MUST be decidable and operational:
- Good: "X development and debugging. Use when doing A/B/C."
- Bad: "Helps with X."
## 3. SKILL.md Structure
### 3.1 Required Sections
`SKILL.md` SHOULD follow this section order, and in strict mode it MUST:
1.`## When to Use This Skill`
2.`## Not For / Boundaries`
3.`## Quick Reference`
4.`## Examples`
5.`## References`
6.`## Maintenance`
Rationale:
- Activation reliability depends on explicit triggers and boundaries.
- Usability depends on short patterns and reproducible examples.
- Maintainability depends on sources and navigable references.
### 3.2 Quick Reference Rules
- Quick Reference MUST contain short, directly usable patterns.
- Quick Reference MUST NOT become a documentation dump.
- Long explanations SHOULD go to `references/`.
- A good target is <= 20 patterns, but large domains may justify more.
### 3.3 Example Rules
- The Examples section MUST contain reproducible examples.
- Each example SHOULD specify:
- input(s)
- steps
- expected output / acceptance criteria
- Pseudo-code MAY be used only if the platform is unavailable, and MUST be clearly labeled.
