Create Skill

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

• DEFAULTSKILLDIR: ~/.claude/skills/
• SHAREDAGENTSKILL_DIR: ~/.agents/skills/
• GITHUB_OWNER: the GitHub account every skill repo is published under. Defaults to the authenticated gh account (gh api user --jq .login; currently OctavianTocan).
• REPOVISIBILITY: public — matches the existing skill repos under GITHUBOWNER.

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 | 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 | Validate an existing skill's structure | | /create-skill edit | 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](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 .md per operation
• Does the skill run shell operations? → Create a scripts/ directory with executable helpers (see cookbook/create.md for 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.md with 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/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](cookbook/create.md) | User wants to create a new skill from scratch | | validate | [cookbook/validate.md](cookbook/validate.md) | User wants to check if a skill is well-formed | | edit | [cookbook/edit.md](cookbook/edit.md) | User wants to modify an existing skill | | publish-repo | [cookbook/publish-repo.md](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

1. SKILL.md should be lean ( --list`.
2. 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 of create — not opt-in. See [cookbook/publish-repo.md](cookbook/publish-repo.md).
3. 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](cookbook/publish-repo.md) is required.

Related Skills

Works with: /grill-me, /validate, /library

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: OctavianTocan
• Source: OctavianTocan/create-skill
• License: MIT

Install and usage instructions live in the source repository linked above.