Skills

⚡ 4 min read

A Skill is a repeatable workflow. It lives in a folder named after the Skill, with SKILL.md as the entry file. Split distinct workflows into more Skills instead of growing one file past a few thousand tokens.

Save the entry file as --kind skill --name <name>. Companion files use --file.

Shape

/transcodes asks for this shape. The CLI does not enforce it.


Size	500–2,000 tokens, under 500 lines
Frontmatter	Non-empty `name` (matches the folder) and a trigger-focused `description`
Sections	`# Prerequisites`, `# Steps`, `# Output`
Optional	`# Gotchas` only when there is an environment-specific fact the agent would get wrong

# Output must include bold Deliverable and Done when.


---
name: review
description: Review a pull request for security and missing tests
---
 
# Prerequisites
- The branch and the files that changed
 
# Steps
1. Inspect the diff and the surrounding tests
2. Check auth, tokens, and error paths
3. Report findings with file paths
 
# Output
**Deliverable** — a short review with severity and file paths
**Done when** — every finding has a path, or you state that none were found

Companions

Folder	What belongs there
`references/`	Long Markdown only. Write tables as GFM tables and diagrams as fenced `mermaid` blocks — do not screenshot them as PNG/PDF.
`scripts/`	Non-interactive helpers (flags only, never prompts). Print results to stdout, diagnostics to stderr. Exit non-zero on failure.
`assets/`	Original files the workflow must process (for example a PDF a script reads).

transcodes persona save --file writes # Available scripts / # References in SKILL.md with the real path. You may later refine the when-to-run / when-to-read text. Companions are unused unless SKILL.md names them.

SKILL.md must exist before you add a companion. Keep templates and short examples in SKILL.md; move long reference docs out.

Save


transcodes persona save --persona developer --kind skill --name review --content-file /tmp/SKILL.md
transcodes persona save --persona developer --kind skill --name review --file references/checklist.md --content-file /tmp/checklist.md

Next: Apply