@cruxy/cli 0.2.0 → 0.4.0

package/skills/using-skills/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: using-skills
+description: How cruxy skills work and how to author a SKILL.md. Use when the user asks about skills or wants to create or edit one.
+---
+
+# Skills in cruxy
+
+A **skill** is a directory containing a `SKILL.md` — YAML frontmatter plus a
+markdown instructions body — that packages reusable, task-specific know-how for
+the agent. Discover skills with the `list_skills` tool and pull a skill's full
+instructions with `load_skill` when a task matches its description.
+
+## Progressive disclosure
+
+Only each skill's `name` and `description` are visible by default (a cheap
+catalog). The full body is loaded **on demand** via `load_skill`, so a large
+library of skills costs almost nothing until one is actually used. Write the
+`description` so the agent can tell, from one line, _when_ to reach for the
+skill.
+
+## Authoring a SKILL.md
+
+Create `skills/<name>/SKILL.md`:
+
+```
+---
+name: <name>
+description: <one line — what it does and when to use it>
+---
+
+# instructions
+…the body the agent reads after load_skill…
+```
+
+Rules (all enforced, fail-loud):
+
+- `name` is kebab-case (`^[a-z0-9][a-z0-9-]*$`) and **must equal the directory
+  name**.
+- `description` is required and non-empty.
+- Frontmatter is strict: unknown keys, missing fields, or malformed YAML are
+  reported in `cruxy skills --status` and the skill is excluded from the
+  catalog.
+
+## Sources and precedence
+
+Skills are discovered from three layers; on a name collision the higher layer
+wins:
+
+1. **project** — `<cwd>/.cruxy/skills/`
+2. **user** — `~/.cruxy/skills/`
+3. **builtin** — shipped with the CLI
+
+Run `cruxy skills` to see the resolved catalog, or `cruxy skills --status` to see
+the source directories and any validation errors.
+
+## Bundled assets
+
+A skill may include `scripts/` and `reference/` subdirectories. `load_skill`
+returns their paths, but **nothing is auto-executed** — the agent runs a script
+through `run_command` (which goes through the normal approval gate) and reads a
+reference through `read_file`. Skills are data, not a privileged execution path,
+and may only reference files inside their own directory.