skill-creator

Files (11)

• SKILL.md
• openai.yaml · agents/
• license.txt
• openai_yaml.md · references/
• output-patterns.md · references/
• workflows.md · references/
• generate_openai_yaml.py · scripts/
• init_skill.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/
• test_package_skill.py · scripts/

SKILL.md (first lines)

# 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

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw