personize-skill-builder
Personize Skill Builder
Skill Name: Skill-Builder
Description: Guide for creating new skills to extend agent capabilities, following the OpenAI Codex CLI skills standard.
Overview
Skills are modular, reusable packages of instructions that help AI agents perform specific tasks reliably. This skill documents how to create, structure, and add new skills to the Skills/ folder.
Skill Folder Structure
Based on OpenAI's Codex CLI skills framework:
Skills/
├── README.md # Skill catalog + routing guide
├── my-skill/ # Skill folder (use kebab-case)
│ ├── SKILL.md # Required: Main instructions + metadata
│ ├── scripts/ # Optional: Executable code/automation
│ ├── reference/ # Optional: Additional documentation
│ └── assets/ # Optional: Templates, images, resources
│
├── skill-builder/SKILL.md # This skill — how to create new skills
└── _internal/ # Platform dev docs (not discoverable skills)
Creating a New Skill
Option 1: Single-File Skill (Simple)
For straightforward skills, create a single .md file:
---
name: My Skill Name
description: Brief description of what this skill does
metadata:
short-description: One-line summary
---
# My Skill Name
> **Skill Name**: My-Skill-Name
> **Description**: Detailed description of the skill's purpose.
---
## Overview
[What this skill does and when to use it]
## Instructions
[Step-by-step guide]
## Examples
[Code samples or usage examples]
## References
[Links to relevant documentation]
Option 2: Folder-Based Skill (Complex)
For skills with scripts, assets, or extensive documentation:
Skills/
└── My-Complex-Skill/
├── SKILL.md # Main skill file (required)
├── scripts/
│ └── setup.sh # Automation scripts
├── references/
│ └── api-docs.md # Supporting documentation
└── assets/
└── template.json # Templates or resources
SKILL.md Template
---
name: [Skill Name]
description: [What this skill helps accomplish - used for skill selection]
metadata:
short-description: [One-line summary for UI display]
version: 1.0.0
author: [Your name or team]
tags: [api, database, frontend, etc.]
---
# [Skill Name]
## Overview
[Comprehensive description of the skill's purpose and use cases]
## Prerequisites
- [Required knowledge or setup]
- [Dependencies]
## Instructions
### Step 1: [First Action]
[Detailed instructions]
### Step 2: [Second Action]
[Detailed instructions]
## Verification
- [ ] [How to verify the skill worked correctly]
## Troubleshooting
| Issue | Solution |
|-------|----------|
| [Common problem] | [How to fix it] |
## References
- [Link to relevant documentation]
- [Related skills or resources]
Skill Naming Conventions
| Convention | Example | Usage |
|---|---|---|
| Kebab-case | Add-Data-Type-CRUD.md |
File names |
| Title Case | Add Data Type CRUD |
Skill display name |
| Descriptive | How to add new data type... |
Description field |
Best Practices
- RFC 2119 Constraints: Use MUST/SHOULD/MAY with rationale clauses in all enforcement sections (see Writing Standard below)
- Progressive Disclosure: Put the most important info first; details later
- Actionable Steps: Use numbered lists for procedures
- Code Examples: Include working code snippets
- Verification: Always include a way to verify success
- Links: Reference source files with relative paths
Writing Standard: RFC 2119 Constraints
All skills use RFC 2119 keywords to express enforcement levels. This replaces informal patterns like "always", "never", "important", and "prefer" in rule sections.
Inspired by Amazon's Agent SOPs from the Strands SDK — natural language markdown with formal requirement keywords creates a middle ground between rigid code and freeform prompting.
Keywords
| Keyword | Meaning | Agent Behavior | When to Use |
|---|---|---|---|
| MUST / MUST NOT | Absolute requirement | Agent fails the task if violated | Data integrity, security, user trust, API correctness |
| SHOULD / SHOULD NOT | Strong default | Follow unless you state explicit reasoning to deviate | Best practices, performance, quality patterns |
| MAY | Agent discretion | Choose either way without justification | Optimization hints, convenience, stylistic choices |
Rationale Clauses
Every constraint gets a "because" rationale after an em dash. This gives the agent context to make good decisions in edge cases rather than blindly following rules.
Format:
- **MUST** [do X] -- because [consequence of not doing it].
- **SHOULD** [do Y] -- because [benefit, with acceptable override conditions].
- **MAY** [do Z] -- because [benefit when applicable].
Before/After examples:
Before: "ALWAYS show the admin what you're about to change before calling the API."
After: "MUST show the admin the proposed change before calling any mutating API
-- because silent modifications erode trust and prevent catching errors
before they reach production."
Before: "Prefer section-level updates over full replace."
After: "SHOULD use section-level updates over full replace -- because scoped edits
reduce blast radius and allow concurrent editing; override only when
structural reorganization requires full rewrite."
Before: "Optionally add an IF node to check success."
After: "MAY add an IF node after the API call to check success -- because explicit
success checks simplify debugging in complex workflows."
Section Naming
Use ## Constraints (H2) for top-level enforcement sections. Use ### Constraints (H3) for per-action constraints within a dispatch skill.
Do NOT use: "Critical Rules", "Key Rules", "Important Rules", "Guardrails". The three-tier MUST/SHOULD/MAY gradient replaces severity signaling.
Balance Check
Not everything should be MUST. A skill with zero SHOULD or MAY rules is probably over-constraining. The gradient exists so agents can exercise judgment on best practices while never violating safety-critical requirements.
SOP Files (.sop.md)
For procedural workflows (multi-step processes with sequenced actions, branching, and explicit success criteria), create a .sop.md file alongside or instead of a SKILL.md.
When to Use .sop.md vs SKILL.md
| Signal | Use SKILL.md |
Use .sop.md |
|---|---|---|
| Multiple independent actions | Yes | No |
| Dispatch table ("jump to action") | Yes | No |
| Linear procedure with ordered steps | No | Yes |
| Steps have pre/post-conditions | No | Yes |
| Branching decision points | Either | Yes (preferred) |
| Measurable success criteria | Either | Yes (preferred) |
Both formats use the same RFC 2119 keywords and rationale clauses.
SOP Template
---
name: [procedure-name]
description: [what this SOP accomplishes]
type: sop
metadata:
version: 1.0.0
author: [your name or team]
---
# SOP: [Procedure Name]
## Overview
[What this procedure does, when to use it, expected duration]
## Parameters
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| [param] | yes/no | [value] | [what it controls] |
## Pre-conditions
- [What MUST be true before starting]
## Steps
### Step 1: [Action Name]
[Instructions]
**Constraints:**
- **MUST** [requirement] -- because [rationale].
- **SHOULD** [recommendation] -- because [rationale].
### Step 2: [Action Name]
[Instructions]
**Constraints:**
- **MUST** [requirement] -- because [rationale].
- **MAY** [option] -- because [rationale].
## Success Criteria
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
## Artifacts
| Artifact | Location | Description |
|----------|----------|-------------|
| [output] | [path] | [what it is] |
Skills Catalog & Routing
For the full skill catalog and routing guide, see the Skills README.