| name | Codex-skill-builder |
| description | Interactive skill creator for Codex and Agent Skills ecosystem. Build SKILL.md files with proper frontmatter, triggers, and structure. Triggers on creating skills, building skills, skill templates, skill frontmatter, allowed-tools, npx add-skill, agent skills. |
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash |
| model | sonnet |
| license | MIT |
| metadata | {"author":"raintree","version":"1.0"} |
Codex Skill Builder
Create well-structured skills compatible with Codex and the Agent Skills specification (used by npx add-skill).
When to Use
- User wants to create a new skill
- User needs help with skill structure or frontmatter
- User asks about trigger keywords or descriptions
- User wants to publish skills for
npx add-skill
Skill Structure
Minimal Skill (Single File)
skill-name/
└── SKILL.md
Full Skill (With References)
skill-name/
├── SKILL.md # Main skill file (required)
├── references/ # Additional documentation
│ └── api-guide.md
├── scripts/ # Helper scripts
│ └── helper.py
└── assets/ # Templates, examples
└── template.txt
SKILL.md Template
---
name: my-skill-name
description: Clear description of what this skill does. Include trigger keywords like keyword1, keyword2, keyword3 so the agent knows when to activate this skill.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
author: your-name
version: "1.0"
---
# Skill Title
## Purpose
Brief explanation of what this skill provides.
## When to Use
- Scenario 1 (include keywords)
- Scenario 2 (include keywords)
- Scenario 3 (include keywords)
## Process
### 1. Understand the Request
How to analyze what the user needs.
### 2. Gather Context
What information to collect.
### 3. Provide Solution
Step-by-step approach.
## Examples
### Example 1: Basic Usage
**Request:** "Help me with X"
**Response:** [How skill handles it]
## Best Practices
- Practice 1
- Practice 2
## Common Pitfalls
- Avoid X, do Y instead
Frontmatter Reference
Required Fields
| Field | Description | Example |
|---|
name | Lowercase with hyphens, max 64 chars | nextjs-expert |
description | What + When + Keywords, max 1024 chars | See below |
Optional Fields
| Field | Description | Values |
|---|
allowed-tools | Tools skill can use | Read, Write, Edit, Grep, Glob, Bash |
model | AI model preference | haiku, sonnet, opus |
license | License type | MIT, Apache-2.0 |
metadata.author | Skill author | Your name |
metadata.version | Semantic version | "1.0" |
Writing Effective Descriptions
Good description (includes what, when, keywords):
description: Expert in Next.js App Router, server components, and React Server Components. Use when user mentions Next.js, RSC, App Router, server actions, or React server-side patterns.
Bad description (too vague):
description: Helps with Next.js
Skill Types
1. Framework/API Expert
Purpose: Deep knowledge of specific technology
Triggers: Framework name, features, patterns
Tools: Read, Grep, Glob
name: fastapi-expert
description: FastAPI web framework expert covering routing, dependencies, Pydantic models, async endpoints, and OpenAPI generation. Triggers on FastAPI, Python API, Pydantic, async web.
2. Code Generator
Purpose: Create boilerplate or scaffolding
Triggers: "generate", "create", "scaffold"
Tools: Write, Read, Grep, Glob
name: component-generator
description: Generate React components with TypeScript, tests, and stories. Triggers on generate component, create component, scaffold component.
3. Code Analyzer
Purpose: Review and analyze code
Triggers: "review", "analyze", "audit"
Tools: Read, Grep, Glob
name: security-auditor
description: Security code review for common vulnerabilities including XSS, SQL injection, and OWASP Top 10. Triggers on security review, audit code, find vulnerabilities.
4. Workflow Automator
Purpose: Automate development tasks
Triggers: Task-specific keywords
Tools: Read, Write, Edit, Bash
name: release-helper
description: Automate release workflows including changelog generation, version bumping, and git tagging. Triggers on release, changelog, version bump, tag release.
5. Data Processor
Purpose: Transform or analyze data
Triggers: Format names, transformation keywords
Tools: Read, Write, Edit, Grep
name: csv-processor
description: Parse, transform, and analyze CSV files. Convert between CSV, JSON, and other formats. Triggers on CSV, parse CSV, convert CSV.
Publishing for npx add-skill
Skills following this format work with npx add-skill from any Git repository.
Repository Structure
your-repo/
├── skills/
│ ├── skill-one/
│ │ └── SKILL.md
│ └── skill-two/
│ └── SKILL.md
└── README.md
Installation Commands
npx add-skill your-username/your-repo
npx add-skill your-username/your-repo --list
npx add-skill your-username/your-repo --skill my-skill
npx add-skill https://github.com/user/repo/tree/main/skills/my-skill
Installation Locations
| Scope | Path | Use Case |
|---|
| Personal | ~/.Codex/skills/ | Your own tools |
| Project | .Codex/skills/ | Team-shared skills |
Interactive Skill Creation
When helping users create skills, gather:
- Skill name - lowercase-with-hyphens
- What it does - 1-2 sentence description
- When to activate - trigger keywords
- Tools needed - Read, Write, Edit, Grep, Glob, Bash
- Scope - personal or project
Then generate the SKILL.md with proper structure.
Validation Checklist
Before publishing:
Troubleshooting
Skill Not Activating
- Check description has specific keywords
- Verify file is named
SKILL.md (uppercase)
- Confirm path:
~/.Codex/skills/name/SKILL.md or .Codex/skills/name/SKILL.md
- Validate YAML syntax (no tabs, proper indentation)
- Restart Codex
Skill Conflicts
Multiple skills with similar triggers:
- Make descriptions more specific
- Use distinct keywords
- Consider combining into one skill
Resources
