skill-creator

steipete/clawdis

Create, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files.

What is skill-creator?

Skill Creator helps you build and maintain SKILL.md packages for AI agents. It enforces lean metadata, proper file structure, and YAML validation to keep skills compact and triggerable.

Validate YAML frontmatter and skill structure
Audit and tidy existing SKILL.md files
Enforce lean metadata and trigger-critical descriptions
Organize skill assets into scripts/, references/, and assets/ directories
Validate skill shape and file organization

How to install skill-creator

npx skills add https://github.com/steipete/clawdis --skill skill-creator

Prerequisites

Python (for validation scripts)
Basic understanding of YAML syntax
Familiarity with SKILL.md format and frontmatter requirements

Claude Code

Cursor

Windsurf

Cline

How to use skill-creator

1.Read the existing skill and nearby resource names
2.Remove generic advice already known by the base model
3.Keep brittle command syntax, auth caveats, safety rules, and validation steps
4.Replace tables with bullets unless a table is clearly needed
5.Relax prose; fragments are acceptable
6.Validate frontmatter using quick_validate.py or the inline Python validation script
7.Run any script tests that were touched during edits

Use cases

Good for

Creating a new AgentSkill from scratch with proper structure
Refactoring an existing skill to remove bloat and improve organization
Validating a skill bundle before publishing to a registry
Auditing multiple skills for consistency and compliance
Moving documentation and examples to appropriate reference files

Who it's for

Skill developers and maintainers
AI agent framework maintainers
Teams building reusable skill libraries
Anyone publishing AgentSkills to registries

skill-creator FAQ

What goes in the frontmatter description?

Only trigger-critical facts in a short noun-phrase format. Quote the description field. Include name and description; local OpenClaw skills may also use metadata, homepage, allowed-tools, user-invocable, and license.

Where should long examples and documentation go?

Move long examples and docs to references/; deterministic scripts to scripts/; templates and media to assets/. Do not include extra README/changelog/setup docs inside a skill unless they are actual task references.

How do I validate a skill?

Use python skills/skill-creator/scripts/quick_validate.py skills/<name> or run the inline Python validation that checks for frontmatter presence and valid YAML.

What is the recommended skill directory structure?

skill-name/ containing SKILL.md (required), scripts/ (optional), references/ (optional), assets/ (optional), and agents/ (optional for UI metadata).

Should I include generic advice in SKILL.md?

No. Keep SKILL.md lean and remove generic advice the base model already knows. Focus on trigger-critical facts, brittle command syntax, auth caveats, and safety rules.

Full instructions (SKILL.md)

Source of truth, from steipete/clawdis.

name: skill-creator description: "Create, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files."

Skill Creator

Skills are compact triggerable workflows. Metadata is always visible; body loads only after trigger; references/scripts/assets load only as needed.

Hard rules

Keep SKILL.md lean; Codex is already capable.
Put only trigger-critical facts in frontmatter description.
Quote frontmatter description.
Frontmatter needs name + description; local OpenClaw skills may also use metadata, homepage, allowed-tools, user-invocable, license.
Prefer noun-phrase descriptions; short generic trigger phrase, not full workflow.
Move long examples/docs to references/; scripts to scripts/; templates/media to assets/.
No extra README/changelog/setup docs inside a skill unless they are actual task references.
Validate YAML frontmatter after edits.

Shape

skill-name/
  SKILL.md
  scripts/      optional deterministic helpers
  references/   optional docs loaded only when needed
  assets/       optional output resources/templates
  agents/       optional UI metadata

Good SKILL.md

---
name: pdf-tools
description: "Inspect, split, merge, OCR, redact, or convert PDFs with local CLI tools."
---

# PDF tools

Use for PDF manipulation. Prefer deterministic scripts for page edits.

## Workflow

1. Inspect file/page count.
2. Choose exact operation.
3. Write output beside input unless user asked otherwise.
4. Render/verify changed pages.

Edit workflow

Read existing skill and nearby resource names.
Remove generic advice the base model already knows.
Keep brittle command syntax, auth caveats, safety rules, and validation.
Replace tables with bullets unless a table is clearly needed.
Relax prose; fragments ok.
Validate frontmatter and run any script tests touched.

Validation

python skills/skill-creator/scripts/quick_validate.py skills/<name>
python - <<'PY'
from pathlib import Path
import yaml
for p in Path("skills").glob("*/SKILL.md"):
    text=p.read_text()
    if not text.startswith("---\n"):
        raise SystemExit(f"missing frontmatter: {p}")
    fm=text.split("---",2)[1]
    yaml.safe_load(fm)
print("ok")
PY

quick_validate.py is conservative; repo-local frontmatter may allow keys beyond public skill bundles.