| name | codex-skill-generator |
| description | Create or update Codex skills that follow the repository skill format, trigger cleanly, and stay concise. Use when adding a new skill, refining an existing SKILL.md, or converting domain guidance into an installable Codex skill package. |
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
---
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
---
name: auth
description: This skill covers authentication.
---
# Auth Skill
This skill covers authentication patterns and best practices.
GOOD
---
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
## When to Activate
- Coding
- APIs
GOOD
## 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
