cyzus/suzent/suzent-skill-creator

Overview

This skill helps you author a new Suzent AgentSkill end to end: capture intent, scaffold the directory, write a focused SKILL.md, and reload it so it becomes available immediately.

A Suzent skill is a directory containing a SKILL.md (required) plus optional scripts/, references/, and assets/. User-authored skills live at ~/.suzent/skills/<name>/.

Frontmatter constraint (important). Suzent parses frontmatter with a

simple line-by-line key: value reader — it only understands flat

name: and description: fields and does not parse nested YAML

(no metadata: blocks, no lists). Keep frontmatter to exactly these two keys.

Workflow

1. Capture intent

Clarify only when these details are materially under-specified:

• What the skill does (the capability or SOP it encodes).
• When it should trigger — the concrete situations and phrasings. This drives

the description, which is what the agent matches against.

• What output is expected, and whether the skill needs bundled scripts/

(executable helpers) or references/ (docs the agent reads on demand).

When the request and repository conventions already answer these questions, proceed without asking the user to repeat them.

2. Scaffold the directory

Run the bundled helper to create the skeleton in the user skills directory:

python scripts/scaffold.py "<skill-name>" --description "<one-line trigger description>"

This creates ~/.suzent/skills/<skill-name>/ with a starter SKILL.md and empty scripts/, references/, assets/ directories. It refuses to overwrite an existing skill unless --force is passed.

In sandbox mode the ~/.suzent path may not be writable directly — write the skill via the filesystem skill / SUZENT_BASE_URL instead, mirroring the same layout.

3. Author SKILL.md

Edit the scaffolded SKILL.md. Guidelines that make skills work well:

• Keep the body focused — under ~500 lines. Link to references/ for depth.
• Write the description as trigger language: name the situations and verbs a

user would actually use. A vague description is the most common reason a skill never fires.

• Prefer explaining why an instruction matters over rigid "ALWAYS/NEVER" rules,

so the agent can generalize.

• If you add executable helpers, put them in scripts/ and document how to call

them from the body.

4. Reload and verify

Make the skill available without restarting:

suzent skill reload
suzent skill list          # confirm it appears under the 'user' source
suzent skill toggle <name> # enable it if it is off

Then test with 2–3 realistic prompts that should trigger it, and a couple that should not, to check the description isn't over- or under-matching. Refine the description and repeat.

Notes / scope

• This v1 covers scaffolding + authoring + reload. Eval harnesses and .skill

packaging are intentionally out of scope for now.

• To distribute a skill to others, share the directory; the recipient installs it

via the suzent-skill-installer skill.