create-skill

Files (32)

• .gitignore
• .npmrc
• .vally.yaml
• LICENSE
• README.md
• SKILL.md
• README.md · evals/
• eval.yaml · evals/create-skill/
• package-lock.json
• package.json
• art-and-provenance.md · references/
• fixture-mode.md · references/
• repository-discovery.md · references/
• art.mjs · scripts/
• create-skill.mjs · scripts/
• png.mjs · scripts/
• providers.mjs · scripts/
• registration.mjs · scripts/
• render.mjs · scripts/
• repository.mjs · scripts/
• versioning.mjs · scripts/
• versions.mjs · scripts/
• art.test.mjs · test/
• cli.test.mjs · test/
• helpers.mjs · test/
• png.test.mjs · test/
• providers.test.mjs · test/
• registration.test.mjs · test/
• render.test.mjs · test/
• repository.test.mjs · test/
• versions.test.mjs · test/
• thumbnail.png

SKILL.md (first lines)

> [!CAUTION]
> Read and follow the shared safety rules before any action. Preview local writes and obtain
> explicit approval. Git and GitHub writes require their own approval and are outside this skill.

# Create Skill

Create one complete skill and register every repository surface without guessing. The workflow
plans first, fails closed on ambiguous conventions, and applies one approved change set.

## Commands

| Command | Purpose |
| --- | --- |
| `create-skill <name>` | Create and register a new skill with deterministic placeholder art. |
| `create-skill art <name>` | Preview and create or ingest thumbnail art for an existing skill. |
| `create-skill register <name>` | Preview and register an existing complete skill without replacing its authored files. |
| `create-skill check <name>` | Validate the skill shape and thumbnail parity without writing. |
| `create-skill fixture --input <json> --repo-root <path>` | Deterministically create a validated fixture skill without interview prompts. |

Every mutating command starts with `--dry-run`. Apply the unchanged plan only after the user
approves its single-use hash.

## Workflow

### 1. Resolve the request

Collect only missing values:

1. Skill name in lowercase-dash form.
2. A one-sentence summary.
3. Specific `USE FOR` phrases that users will type.
4. Specific `DO NOT USE FOR` boundaries and the sibling workflow that should win.
5. Copyright holder, when repository conventions do not identify one.
6. Art choice: Azure OpenAI GPT Image 2, OpenAI Images, custom workflow, or placeholder.

Search installed and repository skills for overlapping triggers before creation. If another skill
already owns the same job, stop and propose extending it.

### 2. Discover the repository

Run from the target repository, not this installed skill directory.

1. Prefer the nearest `skills-repo.config.json`.
2. Validate managed identity and settings before deriving canonical repository paths.
3. Without managed config, discover the existing populated `skills/` directory and known
   registration surfaces.
4. Stop before any write when multiple skill roots or catalog surfaces are plausible.

See [repository discovery](references/repository-discovery.md) for the exact contract.

### 3. Preview creation

Invoke this script by absolute path while keeping the target repository as the working directory:

```text
node <skill-dir>/scripts/create-skill.mjs <name> \
  --summary "<summary>" \
  --use-for "<trigger phrases>" \
  --do-not-use-for "<boundaries>" \
  --author "<holder>" \
  --dry-run
```

Show the complete JSON preview and approval token. The preview includes every skill file and every
registration surface. Ask the user to approve that exact hash once.

### 4. Apply creation

Repeat the same command and replace `--dry-run` with `--approve <hash>`. Do not alter any input
between preview and apply. The tool rejects a stale hash, existing skill directory, symlinked
destination, missing locked Vally toolchain, ambiguous registration, or invalid PNG.

Creation includes:

- `SKILL.md` with `name`, `description`, and `metadata.version` frontmatter.
- `README.md`, `LICENSE`, `package.json`, and `package-lock.json`.
- `.vally.yaml`, deterministic tests, and `evals/<name>/eval.yaml`.
- `thumbnail.png` as the tracked source for catalog synchronization when a catalog is present.
- Marketplace, plugin, README, eval workflow, Dependabot, and catalog registration when present.
- Prompt and non-secret provenance in `docs/thumbnail-prompts.md` when present.

### 5. Choose art

The initial placeholder is deliberate and deterministic. Replace it only when requested.

#### Built-in providers

Preview the exact action:

```text
node <skill-dir>/scripts/create-skill.mjs art <name> \
  --provider azure-openai \
  --prompt "<exact prompt>" \
  --dry-run
```

Supported choices:

- `azure-openai`: Azure OpenAI GPT Image 2 at the exact configured
  `https://<resource>.openai.azure.com` origin.
- `openai`: OpenAI Images at the exact `https://api.openai.com` origin.
- `placeholder`: deterministic local PNG with no network or billed call.

The placeholder and check commands run on bare Node. Before a network provider, run
`npm ci --ignore-scripts` in the installed `create-skill` directory so its locked SDKs are
available.

Show provider, exact endpoint, model, prompt, targets, billing status, one attempt, and no fallback.
Ask for approval of the single-use action hash. Then repeat with `--approve <hash>`.

Built-in requests disable redirects and SDK retries. Never retry automatically. Never switch
providers after a timeout, redirect, rate limit, service error, invalid response, or rejected PNG.
Report the failure and ask the user what to do.

#### Custom provider or delivery workflow

Ask: "Describe any provider and delivery workflow you want me to use for the thumbnail."

The answer is open-ended. It may name an API, MCP tool, browser flow, local application, uploaded

From jongio/skills, MIT.

More from jongio/skills