creators-industries/skill

Hard Skills

Parser, compiler and resolver for hard skills: markdown skills with embedded executable ```tool fences. One file declares what the model reads, what it may call, and what runs when it calls. The declared tools are the contract.

This package is the general purpose skill layer, engine-neutral by design: no model calls, no SDK bindings, zero runtime dependencies.

Built at CREATORS

Install

npm install @crtrs/skill

Skill file

---
skill: waitlist
description: Accept, reject and inspect waitlist signups.
---

Manage the product waitlist.

```tool
id: access
description: accept or reject a pending waitlist user
params:
  operation:
    type: string
    enum: accept, reject
    description: action to perform
    default: accept
  user:
    type: string
    format: email
    description: email of the user
run: uv run waitlist/handle.py --$operation $user
```

Prefer accepting users unless told otherwise.

A tool fence has four keys: id, description, params, run.

• Params are flat JSON Schema: type, format, enum, description, default.
• No default means required.
• Anything outside the shape is a SkillError at parse time.
• Every param appears in run, and every $name in run is a declared param. Both directions are checked at parse time.
• run becomes an argv, $param substitutes per word. No shell, ever:

'uv run waitlist/handle.py --$operation $user'
// { operation: 'accept', user: '[email protected]' }
['uv', 'run', 'waitlist/handle.py', '--accept', '[email protected]']

The run line is the whole call

A param that never appears in the template is a SkillError, the same as a $name no param declares. The rule runs both ways on purpose: a param the template does not mention would still reach the tool — through an environment variable, on stdin, through whatever side channel a host offers — and then the command someone read before approving the skill is not the command that runs.

params:
  path:
    type: string
  content:
    type: string
run: tee $path        # SkillError: 'content' is declared but never used in run

A whole file, a blob of JSON, a secret: if a tool receives it, it is an argv word, and the run line says so. Values substitute inside their word and never split it, so size and spaces are not a reason to reach for another channel.

What a skill carries

A tool that runs uv run handle.py needs handle.py. includes: in the frontmatter is where a skill says so — comma separated, each entry a path relative to the skill’s directory:

---
skill: waitlist
description: Accept, reject and inspect waitlist signups.
includes: handle.py, queries, Makefile
---

An entry is whatever is at that path. Nothing is read into its name — an extension is not what makes something a file — so the filesystem answers: a file is that file, a directory is everything under it, however deep. A path