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

- 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

```text
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

```markdown
---
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. Remove generic advice the base model already knows.
3. Keep brittle command syntax, auth caveats, safety rules, and validation.
4. Replace tables with bullets unless a table is clearly needed.
5. Relax prose; fragments ok.
6. Validate frontmatter and run any script tests touched.

## Validation

```bash
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.


#!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file of a skill folder

Usage:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

Example:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import sys
import zipfile
from pathlib import Path

from quick_validate import validate_skill


def _is_within(path: Path, root: Path) -> bool:
    try:
        path.relative_to(root)
        return True
    except ValueError:
        return False


def package_skill(skill_path, output_dir=None):
    """
    Package a skill folder into a .skill file.

    Args:
        skill_path: Path to the skill folder
        output_dir: Optional output directory for the .skill file (defaults to current directory)

    Returns:
        Path to the created .skill file, or None if error
    """
    skill_path = Path(skill_path).resolve()

    # Validate skill folder exists
    if not skill_path.exists():
        print(f"[ERROR] Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"[ERROR] Path is not a directory: {skill_path}")
        return None

    # Validate SKILL.md exists
    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"[ERROR] SKILL.md not found in {skill_path}")
        return None

    # Run validation before packaging
    print("Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"[ERROR] Validation failed: {message}")
        print("   Plea