codex-skill-generator

# Codex Skill Generator Create focused Codex skills that trigger reliably, stay small, and encode reusable judgment instead of generic prose. ## When to Activate - Create a new skill for this repo - Refactor a large guidance document into a skill - Tighten a weak `description` so the skill triggers correctly - Convert AGENTS-style guidance into `skills/<name>/SKILL.md` - Review an existing skill for format drift - Add examples, tables, or a checklist to a thin skill - Update the README inventory after adding a skill ## Build Order | Step | Do | | --- | --- | | 1 | Pick one narrow domain with clear activation triggers | | 2 | Write a dense `description` that says what the skill does, when to use it, AND when NOT to use it | | 3 | Add 6-8 verb-led items under `## When to Activate` | | 4 | Organize the body around decisions, examples, and checklists | | 5 | End with a shipping-oriented checklist | | 6 | Update the repo inventory and validation surface | ## Required Format ```markdown --- name: kebab-case-name description: Dense sentence that says what the skill does, when to use it, AND when NOT to use it (scope boundary). Codex uses this for implicit activation matching. --- # Title One-sentence summary. ## When to Activate - Verb-led trigger ## Content Sections ## Checklist - [ ] Shipping check ``` Rules: - Folder name must match `name`. - Frontmatter must contain only `name` and `description`. - Put activation hints AND scope boundaries in `description`; that is what Codex matches against for implicit invocation. - Include at least one decision or comparison table. - Include at least one `BAD` / `GOOD` pair. - Keep the body terse and directly operational. - Optionally add `agents/openai.yaml` to the skill folder to set `interface` metadata, `policy.allow_implicit_invocation`, and `dependencies.tools` (e.g. required MCP servers). ## What Good Skills Contain | Include | Why | | --- | --- | | Trigger language in `description` | Helps the skill load at the right time | | Decision tables | Compress tradeoffs without bloating prose | | Realistic code or command examples | Makes the guidance executable | | A checklist | Gives Codex a final pass before finishing | | Avoid | Why | | --- | --- | | Meta-commentary like "this skill covers..." | Wastes tokens and weakens the signal | | Broad multi-domain sprawl | Makes triggering and usage fuzzy | | Long essays | Consumes context without improving execution | | Placeholder examples with no domain meaning | Low signal; hard to apply | ## BAD / GOOD Examples BAD ```markdown --- name: auth description: This skill covers authentication. --- # Auth Skill This skill covers authentication patterns and best practices. ``` GOOD ```markdown --- name: jwt-auth description: JWT authentication patterns for token issuance, validation, refresh rotation, and authorization checks. Use when building or reviewing bearer-token auth flows in APIs or services. Do NOT use for session-cookie auth, OAuth provider integration, or mTLS. --- # JWT Auth Implement bearer-token auth flows with explicit validation and rotation rules. ``` BAD ```markdown ## When to Activate - Coding - APIs ``` GOOD ```markdown ## When to Activate - Build a JWT login or refresh flow - Review token validation or claim handling - Add authorization middleware to an API ``` ## Editing Workflow For This Repo | Task | Action | | --- | --- | | Add a skill | Create `skills/<name>/SKILL.md` | | Keep counts accurate | Update `README.md` | | Keep CI aligned | Ensure `scripts/validate_skills.py` still matches format expectations | | Match house style | Read `skills/api-design/SKILL.md` and `skills/coding-standards/SKILL.md` first | ## Checklist - [ ] Skill name is kebab-case and matches the folder - [ ] Description says what the skill does, when to use it, AND when NOT to use it - [ ] `## When to Activate` has concrete verb-led triggers - [ ] At least one decision or comparison table is present - [ ] At least one `BAD` / `GOOD` example pair is present - [ ] The body is concise and code-forward - [ ] The checklist is written from a "before you ship" perspective - [ ] README inventory is updated after adding the skill