Skill Creator

A meta-skill for creating, improving, and validating skills in the FlagOS skills repository.

Overview

This skill guides you through the full lifecycle of skill development:

1. 1. Create — scaffold a new skill from template, interview the user, write SKILL.md
2. Improve — analyze an existing skill, identify weaknesses, iterate with test cases
3. Validate — check structure, frontmatter, references, and conventions compliance

Usage

CODEBLOCK0

Execution

Step 0: Parse arguments and determine mode

Extract from user input:

• - {{skill_name}} — optional skill name (hyphen-case)
• INLINECODE1 — one of: create, improve, validate, eval, or interactive (default)

If no mode is specified, ask the user:

What would you like to do?

1. 1. Create a new skill from scratch
2. Improve an existing skill
3. Validate a skill's structure and conventions
4. Run test cases against a skill

-> Tell user: Confirm the mode and skill name.

---

Mode 1: Create a New Skill

Step 1: Capture intent

Start by understanding what the user wants to build. If the current conversation already contains a workflow the user wants to capture (e.g., "turn this into a skill"), extract answers from the conversation history first.

Key questions to clarify:

1. 1. What should this skill enable the agent to do?
2. When should this skill trigger? (user phrases, contexts, file types)
3. What's the expected output or end state?
4. Does the skill need scripts, reference docs, or asset files?
5. What tools does the skill need access to?

Adapt your communication style to the user — don't assume coding jargon familiarity. Pay attention to context cues.

-> Tell user: Summarize the captured intent and confirm before proceeding.

Step 2: Initialize the skill directory

Run the init script to scaffold the skill:

CODEBLOCK1

Where:

• - {{skill_root}} = absolute path to this skill-creator-flagos's directory
• INLINECODE8 = path to the skills/ directory (usually the parent of {{skill_root}})

The script creates the directory with SKILL.md template, LICENSE.txt, and optional subdirectories.

-> Tell user: Show the created directory structure.

Step 3: Write the SKILL.md

Based on the user interview, fill in these components:

Frontmatter (YAML)

Field	Required	Guidelines
INLINECODE11	Yes	Lowercase + hyphens, must match directory name, max 64 chars
INLINECODE12

Yes | 1-2 sentences: what it does AND when to trigger. Be specific and slightly "pushy" — err on the side of triggering too often rather than too rarely | | argument-hint | Recommended | Show expected arguments | | user-invokable | Recommended | true if invokable via /skill-name | | compatibility | Optional | Environment requirements | | metadata | Recommended | version, author, category, tags | | allowed-tools | Recommended | Space-separated tool list with patterns |

Body (Markdown)

Follow the structure documented in references/writing-guide.md. At minimum include:

• - Overview — what problem this solves, when to activate
• Prerequisites — environment requirements
• Execution steps — numbered steps with **-> Tell user** progress markers
• Examples — at least 2-3 realistic usage examples
• Troubleshooting — common problems and fixes

Read references/writing-guide.md for detailed patterns on progressive disclosure, output formats, domain organization, and writing style.

Step 4: Add supporting resources

Based on the skill's needs, create:

• - scripts/ — executable code for deterministic/repetitive tasks
• references/ — detailed docs loaded into context as needed
• assets/ — files used in output (templates, icons, etc.)

Rules:

• - Every script/reference must be documented in SKILL.md with usage instructions
• Scripts should have execute permissions (chmod +x)
• Keep SKILL.md under 500 lines; move detailed content to INLINECODE27
• For reference files >300 lines, include a table of contents

Step 5: Validate

Run validation to check conventions compliance:

CODEBLOCK2

Fix any reported issues. See Troubleshooting section below.

-> Tell user: Report validation results. On failure, diagnose and fix.

Step 6: Write README files

Create README.md (English) and optionally README_zh.md (Chinese) following the pattern in existing skills. The README should cover:

• - Overview / problem statement
• Usage instructions
• Directory structure
• File descriptions
• Examples
• Installation instructions

-> Tell user: Skill creation complete. Present the final directory tree and summary.

---

Mode 2: Improve an Existing Skill

Step 1: Analyze the current skill

Read the existing SKILL.md and all supporting files. Identify:

• - Unclear or missing trigger conditions in the description
• Missing examples or edge cases
• Steps that lack progress reporting (**-> Tell user**)
• Overly long SKILL.md that should be split into references
• Missing troubleshooting entries
• Scripts without documentation

-> Tell user: Present findings and proposed improvements.

Step 2: Draft test prompts

Create 2-3 realistic test prompts — things a real user would say. Share them with the user for confirmation.

Save to evals/evals.json:

CODEBLOCK3

See references/schemas.md for the full schema.

Step 3: Iterate

For each round:

1. 1. Apply improvements to SKILL.md and supporting files
2. Re-run validation
3. Review against test prompts (mentally or by spawning test runs)
4. Collect user feedback
5. Repeat until satisfied

-> Tell user: Report changes made in each iteration.

---

Mode 3: Validate

Run the validation script:

CODEBLOCK4

The script checks:

• - SKILL.md exists and has valid YAML frontmatter
• Required fields (name, description) are present
• INLINECODE35 matches directory name, follows naming conventions
• INLINECODE36 length within limits
• Body has sufficient content (>100 chars)
• Referenced files in scripts/ and references/ actually exist
• Scripts have execute permissions
• No hardcoded paths or credentials

-> Tell user: Report all findings with severity (error/warning).

---

Mode 4: Run Evals

If evals/evals.json exists, run the test prompts against the skill:

CODEBLOCK5

This generates a report showing which assertions passed/failed for each test case.

-> Tell user: Present results and suggest improvements.

---

Placeholders

Placeholder	How to derive
INLINECODE40	From user input, normalized to hyphen-case
INLINECODE41

Absolute path to this skill-creator-flagos's directory |
| {{repo_root}} | Absolute path to the repository root (parent of skills/) |
| {{skills_dir}} | Path to the skills/ directory containing all skills |

Examples

Example 1: Create a new skill from scratch
CODEBLOCK6

Example 2: Improve an existing skill
CODEBLOCK7

Example 3: Validate all skills
CODEBLOCK8

Example 4: Turn a conversation workflow into a skill
CODEBLOCK9

Troubleshooting

Problem	Cause	Fix
INLINECODE46	Frontmatter name differs from folder name	Ensure they are identical
INLINECODE48

Description too long | Move details to the body; keep description to 1-2 sentences | | SKILL.md body is too short | Insufficient instructions | Add overview, steps, examples, troubleshooting | | Missing required field | name or description absent in frontmatter | Add the missing field | | name must be lowercase+hyphens | Invalid characters in name | Use only a-z, 0-9, - | | Skill doesn't trigger | Description too narrow or vague | Make description more specific and slightly aggressive about triggering | | Referenced file not found | Script or reference listed in SKILL.md but not on disk | Create the file or remove the reference |