Creating Agent Skills

Create a basic skill:

Bash
mkdir my-skill && cd my-skill
cat > SKILL.md << 'EOF'
---
name: my-skill-name
description: Explains exactly when this skill should and should not trigger.
---

Immediate actionable example or steps.

1. Step one with specific inputs
2. Step two with expected outputs
3. Final step with deliverables

Example 1: Input: [specific scenario] Output: [concrete result]

1. Define Scope

   • Identify the single job this skill should handle
   • Write clear trigger conditions for implicit invocation
   • Determine if instruction-only or scripts needed

2. Create Structure

   my-skill/
   ├── SKILL.md           # Required: instructions + metadata
   ├── scripts/           # Optional: executable code
   ├── references/        # Optional: documentation
   ├── assets/           # Optional: templates, resources
   └── agents/openai.yaml # Optional: UI metadata, dependencies
   

3. Write SKILL.md

   • YAML frontmatter with name (kebab-case) and description
   • Progressive sections: Quick Start, Workflow, Examples, Best Practices
   • Focus on imperative steps with explicit inputs/outputs

4. Add Optional Metadata (agents/openai.yaml):

   YAML
   interface:
     display_name: "User-Facing Name"
     short_description: "Brief description for UI"
     icon_small: "./assets/icon.svg"
     brand_color: "#3B82F6"
   policy:
     allow_implicit_invocation: true
   dependencies:
     tools:
       - type: "mcp"
         value: "toolName"

5. Test and Deploy

   • Save to appropriate location (repo/.agents/skills or ~/.agents/skills)
   • Test trigger phrases match description
   • Verify Codex auto-detects (restart if needed)

Example 1: Repository Skill Location: $REPO_ROOT/.agents/skills/code-review/

Markdown
---
name: code-review-checklist
description: Performs systematic code reviews using team standards. Use when reviewing pull requests or code changes.
---

Review this PR: [paste URL or diff]

1. Security: Check for vulnerabilities, secrets, permissions
2. Logic: Verify correctness, edge cases, error handling
3. Style: Enforce coding standards, naming, comments
4. Performance: Identify bottlenecks, inefficient patterns

**Example 2: User Skill**
Location: `~/.agents/skills/meeting-notes/`
```markdown
---
name: meeting-notes-formatter
description: Converts raw meeting transcripts into structured notes with action items. Use when processing meeting recordings or notes.
---

Format these meeting notes: [paste transcript]

1. Extract key decisions and action items
2. Organize by topic with timestamps
3. Create follow-up task list with owners
4. Generate summary for stakeholders