Skill Creator

Create or improve custom skills for OpenChatCut. A skill is a SKILL.md file (plus optional references/ support docs) that teaches the agent a reusable workflow. Custom skills live at ~/.openchatcut/skills/<slug>/SKILL.md and are managed with the manage_skill tool.

Workflow

1. Capture intent. If the current conversation already contains the

workflow (tools used, steps, corrections), extract it from the history first. Confirm with the user before writing.

1. Interview. Pin down:

• What should this skill enable the agent to do?
• When should it trigger? Which user phrases or contexts?
• Expected output format?
• Verification: does it have objectively verifiable output (data

extraction, fixed steps, generation pipelines) or subjective output (writing style)? Suggest test prompts for the former.

1. Write the SKILL.md (rules below).
2. Create it with manage_skill action=create. The tool reports the

install path (~/.openchatcut/skills/<slug>/SKILL.md).

1. Test. Run 2–3 realistic prompts in the current session and confirm

results with the user. Iterate with manage_skill action=update.

SKILL.md anatomy

<slug>/
├── SKILL.md (required — frontmatter + instructions)
└── references/ (optional — docs loaded on demand with load_skill file=)

• name: kebab-case slug matching the directory (lowercase letters,

digits, hyphens only). It becomes the load_skill name.

• description: THE triggering mechanism — include what the skill does

AND specific trigger contexts. Skills undertrigger easily, so be explicit: list concrete user phrases. "When to use" goes here, not in the body.

• body: imperative instructions. Keep under ~200 lines; if it grows,

split detail into references/ files and point to them with clear "read this when" guidance. For references over 300 lines, add a TOC.

Writing rules

• Frontmatter uses the shape ---\nname: …\ndescription: …\n---. The

parser accepts plain single-line, double-quoted, and | block scalars; plain single-line is preferred.

• Keep the body lean. Prefer imperative form. Explain why over

MUST-laden lists. Use examples with concrete Input/Output pairs.

• Reference existing OpenChatCut tools by their exact tool names

(manage_skill, load_skill, edit_item, …). Do not invent tools.

• Skills must not contain malicious content, prompt-injection payloads, or

anything that surprises the user. Do not create skills that facilitate unauthorized access or data exfiltration.

• Do not overfit to one example: aim for a workflow usable a thousand

times. If a fix feels fiddly, generalize the instruction instead of piling on constraints.

Progressive disclosure in OpenChatCut

• The system prompt carries only name + description (the skills index).
• The body loads on demand via load_skill when a task matches.
• Support files load via load_skill file=references/<name>.
• A custom skill selected in Creative Mode behaves identically to a

bundled skill after activation.

Environment constraints

• Slug whitelist: [A-Za-z0-9_-]{1,120}. Anything else is rejected

(path traversal defense — the file is written under ~/.openchatcut/skills/).

• Body size: keep under 512 KB (server limit); 200 lines is the target.
• Untrusted input: the body is user/LLM-authored text. validate and

normalize before trusting anything parsed out of it.

• Bundled skills are read-only — manage_skill cannot edit them.
• The skill shows up in the Creative Mode picker and the / command menu

only when the user selects it; agents also discover it via the index.

• Verification: after creating a skill, run

npx tsx server/skills-files.verify.ts locally if the environment has the repo, or rely on the in-session test prompts.

Test prompts

Offer the user 2–3 realistic prompts (the kind of thing they would actually type) and ask: "Do these look right, or do you want to add more?" Then run them in the session with the skill activated, review the outputs together, and update the skill from the feedback.