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.

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_package_skill.py

Writing Style Guide

Use imperative voice and explicit constraints.

Good:

• "Run python3 scripts/quick_validate.py <skill-dir> before packaging."
• "Load references/aws.md only when the selected provider is AWS."

Weak:

• "You might want to validate things eventually."
• "Read all references first."

Prefer:

• specific commands
• bounded scope
• clear success conditions

Avoid:

• vague phrases without operational meaning
• duplicated instructions in multiple files
• large inline reference dumps in SKILL.md

Validation Checklist

Before calling a skill complete, verify:

1. Frontmatter description clearly states what it does and when to use it.
2. Skill name uses lowercase skill-id characters (a-z, 0-9, -, .) and is <= 64 characters.
3. SKILL.md contains concise workflow guidance and links to deep docs.
4. Scripts execute successfully on representative inputs.
5. quick_validate.py passes.
6. Packaging (if needed) rejects unsafe paths and symlinks.
7. agents/openai.yaml is present and aligned when UI metadata is required.

Common Mistakes

• Putting trigger conditions only in the body instead of frontmatter.
• Keeping large variant-specific details in SKILL.md instead of references/.
• Shipping untested scripts.
• Leaving template placeholders in production skills.
• Including docs that explain creation process instead of runtime execution.

Review Workflow

Run a second pass focused on execution quality:

1. Simulate real user prompts.
2. Check whether the skill triggers correctly.
3. Confirm instructions are sufficient without hidden assumptions.
4. Tighten wording where ambiguity causes drift.

Use references/workflows.md and references/output-patterns.md for reusable review patterns and output contracts.