# skill-creator

> Create or update Codex skills (SKILL.md plus optional scripts/references/assets). Use when asked to design a new skill, update an existing skill, or validate/package skills.

- Author: therealityreport
- Repository: therealityreport/THB-BBL
- Version: 20260104125043
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/therealityreport/THB-BBL
- Web: https://mule.run/skillshub/@@therealityreport/THB-BBL~skill-creator:20260104125043

---

---
name: skill-creator
description: Create or update Codex skills (SKILL.md plus optional scripts/references/assets). Use when asked to design a new skill, update an existing skill, or validate/package skills.
---

# Skill Creator

Skills are modular packages that extend AI agent capabilities with specialized knowledge, workflows, and tools. They follow the open [Agent Skills specification](https://agentskills.io) and work across Codex and other compatible agents.

## Core Principles

### Concise is Key

The context window is shared. Only add information Codex does not already have. Prefer concise examples over verbose explanations.

### Degrees of Freedom

Match specificity to task fragility:

- **High freedom** (text instructions): Multiple approaches valid, context-dependent
- **Medium freedom** (pseudocode/parameterized scripts): Preferred pattern exists, some variation acceptable  
- **Low freedom** (specific scripts): Operations fragile, consistency critical

## Skill Anatomy

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code
    ├── references/   - Documentation loaded as needed
    └── assets/       - Files used in output (templates, images)
```

### SKILL.md Structure

**Frontmatter (YAML):**
- `name`: Skill identifier (kebab-case, max 64 chars, must match directory name)
- `description`: What it does AND when to trigger it (max 1024 chars). This is the primary trigger mechanism; include all "when to use" info here, not in the body.
- `metadata` (optional): Key-value pairs like `author`, `version`
- `compatibility` (optional): Environment requirements (max 500 chars)
- `license` (optional): License name or reference to LICENSE file

**Body (Markdown):** Instructions loaded after skill triggers. Keep under 500 lines.

### Bundled Resources

**scripts/**: Executable code for deterministic, repeatable tasks. Token-efficient; may execute without loading into context.

**references/**: Documentation Codex reads as needed. Keeps SKILL.md lean. For files >10k words, include grep patterns in SKILL.md.

**assets/**: Files used in output (templates, logos, fonts). Not loaded into context, copied or modified in final output.

### Do NOT Include

- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
- User-facing documentation
- Setup/testing procedures

## Progressive Disclosure

Three-level loading system:

1. **Metadata** (~100 words) - Always in context
2. **SKILL.md body** (<5k words) - When triggered
3. **Bundled resources** (unlimited) - As needed

When approaching 500 lines, split into reference files. Reference all split files from SKILL.md with clear guidance on when to read them.

**Pattern examples:**

```markdown
## Advanced features
- **Form filling**: See [FORMS.md](references/FORMS.md)
- **API reference**: See [REFERENCE.md](references/REFERENCE.md)
```

For multi-domain skills, organize by domain so Codex only loads relevant context.

## Creation Process

### Step 1: Understand with Examples

Gather concrete usage examples. Ask:
- What functionality should this skill support?
- What would a user say to trigger this skill?
- Can you give example requests?

### Step 2: Plan Reusable Contents

For each example, identify:
- What scripts would help (repeated code)?
- What references would help (schemas, docs)?
- What assets would help (templates, boilerplate)?

### Step 3: Initialize

Run the initialization script:

```bash
python3 skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
```

Creates skill directory with SKILL.md template and example resource directories.

### Step 4: Edit

**Frontmatter:**
- Write clear, comprehensive `description` with all trigger scenarios
- Example: "Comprehensive document creation and editing. Use when working with .docx files for: (1) Creating documents, (2) Editing content, (3) Tracked changes, (4) Adding comments"

**Body:**
- Write for another Codex instance to use
- Include non-obvious procedural knowledge
- Use imperative/infinitive form
- See `references/workflows.md` for workflow patterns
- See `references/output-patterns.md` for output templates

**Resources:**
- Implement scripts, references, assets identified in Step 2
- Test scripts by running them
- Delete unused example files

### Step 5: Package

```bash
python3 skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>
```

Validates and creates `.skill` file for distribution.

### Step 6: Iterate

Use the skill on real tasks, identify struggles, update accordingly.