Skill Creator

Skill Creator

Scaffold new agent skills that pass ./scripts/skills-lint.sh on the first try. Walk the user through naming, trigger design, sub-file structure, and quality review.

What is a skill?

A skill is a directory under skills/<name>/ containing markdown files with YAML frontmatter. The entry point is always SKILL.md. Skills provide progressively disclosed guidance for compatible hosts such as Codex, Claude Code, and Raxol. Hosts use the description to decide when the skill applies and load the full instructions only when needed.

Skills are NOT agents, plugins, or code libraries. They are structured knowledge documents that shape an agent host's behavior for a specific domain.

Scaffolding workflow

Step 1: Choose a name

• Lowercase, hyphenated: my-skill-name
• Short but specific: prefer database-designer over db or database-schema-design-and-optimization-tool
• Check for overlap with existing skills before creating

Step 2: Write trigger clauses

The description field in SKILL.md frontmatter MUST include both:

• TRIGGER when: -- enumerate concrete conditions (imports, file types, user phrases)
• DO NOT TRIGGER when: -- exclude adjacent domains to prevent false activation

Good triggers are specific and observable:

TRIGGER when: user asks to design a REST API, define endpoint schemas,
or working with OpenAPI spec files (.yaml/.json with openapi: field).
DO NOT TRIGGER when: user is implementing API handlers (use the
language-specific skill), or configuring an API gateway.

Bad triggers are vague:

TRIGGER when: user is working with APIs.

Step 3: Write SKILL.md body

After the frontmatter, structure the body:

1. One-paragraph summary -- what the skill does, when to use it
2. Workflow or phases -- the step-by-step process the skill guides
3. Key rules or checklists -- what to always/never do
4. Common pitfalls -- table of mistake/fix pairs
5. Reading guide -- table linking to sub-files with backtick-wrapped paths

Step 4: Create sub-files

Each sub-file covers one focused topic. Every sub-file needs YAML frontmatter with three required fields:

• impact: one of CRITICAL, HIGH, MEDIUM, LOW
• impactDescription: one sentence explaining why this matters
• tags: comma-separated string (NOT a YAML array)

Sub-files should contain incorrect/correct example pairs showing what to do and what not to do, with brief explanations.

Step 5: Validate

./scripts/skills-lint.sh

The linter checks:

• SKILL.md exists with name:, description:, metadata: fields
• Description contains TRIGGER when: and DO NOT TRIGGER
• Sub-files have YAML frontmatter with impact and impactDescription
• Tags are comma-separated strings, not YAML arrays
• File references in reading guide tables point to real files
• Cross-skill references in "See also" point to real skill directories

What You Get

• A complete skills/<name>/ directory with a SKILL.md entry point containing valid frontmatter and trigger clauses
• Sub-files with correct YAML frontmatter (impact, impactDescription, tags) and incorrect/correct example pairs
• A skill that passes ./scripts/skills-lint.sh on the first run with no manual fixes needed

Reading guide

See also

• codebase-onboarding
• architect