octaviantocan Create Skill
Creates skills following the cookbook-based format: a lean SKILL.md as a routing document plus detailed cookbook/ files for each operation. Step 1 is always the Grill — a relentless one-question-at-a-time interview (like /grill-me) that walks the design tree until there's shared understanding. Each question includes a recommended answer the user can accept, modify, or reject.
Variables
- DEFAULT_SKILL_DIR:
~/.claude/skills/ - SHARED_AGENT_SKILL_DIR:
~/.agents/skills/ - GITHUB_OWNER: the GitHub account every skill repo is published under. Defaults to the authenticated
ghaccount (gh api user --jq .login; currentlyOctavianTocan). - REPO_VISIBILITY:
public— matches the existing skill repos under GITHUB_OWNER.
How It Works
Skills use progressive disclosure. Metadata (frontmatter) is always loaded by the agent. The SKILL.md body is read when a trigger matches. Cookbook files are read on demand when a specific command is invoked. This keeps context windows small while supporting complex multi-step workflows.
Commands
| Command | Purpose |
|---|---|
/create-skill <name> <desc> |
Create a new skill with the given name |
/create-skill --project |
Create a skill in .claude/skills/ (project scope) |
/create-skill --global |
Create a skill in ~/.agents/skills/ (all agents) |
/create-skill validate <name> |
Validate an existing skill's structure |
/create-skill edit <name> |
Edit or update an existing skill |
Every skill created with create-skill is published as its own standalone, npx skills-installable repo on GITHUB_OWNER's account — every time, as the final step of create. See cookbook/publish-repo.md.
Decision Tree
Before creating, determine what the skill needs:
- Should multiple AI agents have access to it? → Create it in
~/.agents/skills/ - Does the skill have multiple operations/commands? → Create a
cookbook/directory with one.mdper operation - Does the skill run shell operations? → Create a
scripts/directory with executable helpers (seecookbook/create.mdfor detailed guidance) - Does the skill need reference documentation? → Create a
references/directory - Does the skill need templates or assets? → Create an
assets/directory - Simple single-workflow skill? → Just
SKILL.mdwith inline instructions
Regardless of the layout above, every skill is published as its own standalone, npx skills-installable Git repo on GITHUB_OWNER's account — this is not optional and runs every time (see cookbook/publish-repo.md).
Cookbook
Each command has a detailed step-by-step guide. Read the relevant cookbook file before executing a command.
| Command | Cookbook | Use When |
|---|---|---|
| create | cookbook/create.md | User wants to create a new skill from scratch |
| validate | cookbook/validate.md | User wants to check if a skill is well-formed |
| edit | cookbook/edit.md | User wants to modify an existing skill |
| publish-repo | cookbook/publish-repo.md | Always — final step of create; publishes the skill as its own repo on GITHUB_OWNER's account and cleans it up there |
When a user invokes a /create-skill command, read the matching cookbook file first, then execute the steps.
Key Principles
- SKILL.md should be lean (<3k words) — it is a routing document, not a manual.
- Cookbook files contain the detailed step-by-step procedures.
- One cookbook file per operation or concern.
- Use imperative language in all instructions.
- Progressive disclosure: metadata → SKILL.md → cookbook → resources.
- The
descriptionfield MUST include trigger keywords so the agent discovers the skill. - Frontmatter must have
nameanddescriptionat minimum. - Include a
stagesfield in frontmatter to enable cross-skill discovery. - Keep every skill
npx skills-installable: a valid rootSKILL.md, relative links only, no symlinks or absolute paths leaking outside the skill dir. Verify withnpx skills add <skill_dir> --list. - Every skill gets its OWN repo on GITHUB_OWNER's account, every time, with the standard layout (
SKILL.md+README.md+LICENSE+CHANGELOG.md+.gitignore+cookbook/…), matching the other published skills. This is the mandatory final step ofcreate— not opt-in. See cookbook/publish-repo.md. - After pushing, leave the repo clean on GitHub: a clean working tree, a set repo description, only intended files tracked (no cruft, no leftover
TODO:markers), and a verified public install. The "clean it up on GitHub" step in cookbook/publish-repo.md is required.
Related Skills
Works with: /grill-me, /validate, /library