/skill-creator

name: skill-creator
description: "Create and update SKILL.md-based skills with strong trigger metadata, lean docs, and reliable init, validate, package, and publish workflows."
user-invocable: true
disable-model-invocation: false
metadata:
  hybridclaw:
    category: development
    short_description: "Create and update skills."
    tags:
      - skills
      - authoring
      - development
      - packaging

Skill Creator

Build high-quality skills that are clear to trigger, cheap in context, and reliable in execution.

Core Principles

1) Concise is a hard requirement

Assume the model already knows general concepts. Include only information that improves outcomes for this specific skill.

• Prefer short imperative instructions over essays.
• Keep essential workflow in `SKILL.md`.
• Move deep detail into `references/`.

2) Set the right degrees of freedom

Pick guidance strictness by task fragility:

• High freedom: heuristics and decision rules.
• Medium freedom: parameterized scripts and pseudocode.
• Low freedom: exact commands and narrow steps.

Use low freedom when consistency and safety matter; allow higher freedom when multiple valid approaches exist.

3) Design for progressive disclosure

Skills should load in layers:

1. Frontmatter `name` + `description` (always loaded) 2. `SKILL.md` body (loaded on trigger) 3. `references/`, `scripts/`, `assets/` (loaded only when needed)

Target sizes:

• `SKILL.md` body: 1,500-2,000 words
• `references/*`: 2,000-5,000+ words when needed
• Keep `SKILL.md` under ~500 lines; split earlier if it grows fast

Anatomy of a Skill

Required:

• `SKILL.md`
• YAML frontmatter with `name`, `description`, and `metadata.hybridclaw.category`

Recommended:

• `agents/openai.yaml` for UI-facing metadata

Optional:

• `scripts/` for deterministic or repeated operations
• `references/` for deep guidance and domain details
• `assets/` for templates/images/files used in outputs
• `license.txt` when sharing externally

For API-backed skills, prefer deterministic `*.cjs` scripts that provide an easy CLI over the external API. The script should own endpoint selection, methods, payload shaping, URL encoding, write-tier classification, and secret reference construction, then emit gateway-ready JSON for the model to pass to tools such as `http_request`. The model should run the CLI and use its emitted request objects instead of handcrafting API calls from memory.

What Goes Where

Use this taxonomy to keep skills maintainable:

• `SKILL.md`: trigger semantics, decision flow, command contract, minimal examples
• `metadata.hybridclaw.category`: short bucket like `development`, `office`, `apple`, or `memory`
• `references/`: long docs, schemas, framework variants, advanced patterns
• `scripts/`: executable deterministic helpers, including `*.cjs` API wrapper

CLIs for skills that call external services

• `assets/`: output resources that should not be read into context by default

Keep references one level deep from `SKILL.md` links. Avoid deep reference chains.

What Not to Include

Do not add process clutter that does not improve runtime behavior, such as:

• `README.md`
• `CHANGELOG.md`
• installation how-to docs for humans only
• duplicate copies of instructions already in `SKILL.md`

Keep only files that help another agent execute the task.

Skill Discovery Notes

Many runtimes resolve skills from multiple roots. Document your effective precedence so users know where overrides win.

Common locations:

• `./skills/<skill>/SKILL.md` (workspace)
• `./.agents/skills/<skill>/SKILL.md` (project-local)
• `~/.agents/skills/<skill>/SKILL.md` (user-level)
• `~/.claude/skills/<skill>/SKILL.md` (user-level)
• `~/.codex/skills/<skill>/SKILL.md` (user-level)
• bundled/package-managed skill directories (environment-specific)

If precedence differs in your runtime, state the exact order in project docs and keep this skill focused on authoring quality.

To install a skill someone hands you (a folder or a `.zip`), run `hybridclaw skill import <path>`. It runs the security scanner before installing. Never unzip or copy it into a skills folder yourself.

Skill Creation Workflow

Follow this sequence unless there is a clear reason to skip a step.

Step 1: Gather concrete usage examples

Identify 3-6 realistic prompts that should trigger the skill.

Ask focused questions, for example:

• What user requests should activate this skill?
• What should this skill handle directly vs defer?
• Which file types, tools, or APIs are in scope?

Step 2: Plan reusable artifacts

For each example, identify repeatable parts and place them in the right resource type.

Examples:

• Repeated code logic -> `scripts/*.py`
• Domain rules/schemas -> `references/*.md`
• Starter templates -> `assets/`

Step 3: Initialize scaffold

Use the initializer for consistent structure:

python3 scripts/init_skill.py <skill-name> --path <skills-dir> --resources scripts,references,assets

For UI metadata, provide deterministic interface values:

python3 scripts/init_skill.py <skill-name> --path <skills-dir> \
  --interface display_name="..." \
  --interface short_description="..." \
  --interface default_prompt="Use $<skill-name> to ..."

Step 4: Implement and refine

1. Build scripts and references first. 2. Write `SKILL.md` as an execution guide, not an essay. 3. Link to references only where decisions require them. 4. Delete placeholder/example files that are not used.

Step 5: Validate

Run structural and metadata checks:

python3 scripts/quick_validate.py <path/to/skill>

If UI metadata is used, regenerate and compare:

python3 scripts/generate_openai_yaml.py <path/to/skill>

Step 6: Package and test (if distributing)

Create a `.skill` archive with path and symlink safety checks:

python3 scripts/package_skill.py <path/to/skill>

Run packaging regression tests:

python3 scripts/test_pack