Skill Creator

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

• For durable MarketingClaw skill creation or updates in an agent session, use skill_workshop to create or revise a pending proposal. Do not scaffold or apply live SKILL.md files with shell commands or helper scripts.
• Keep SKILL.md lean; Codex is already capable.
• Put only trigger-critical facts in frontmatter description.
• Quote frontmatter description.
• Frontmatter needs name + description; local MarketingClaw 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

1. Read existing skill and nearby resource names.
2. Draft the proposed SKILL.md content.
3. Create or revise the pending proposal through skill_workshop when the change should persist as an MarketingClaw skill.
4. Remove generic advice the base model already knows.
5. Keep brittle command syntax, auth caveats, safety rules, and validation.
6. Replace tables with bullets unless a table is clearly needed.
7. Relax prose; fragments ok.
8. 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.