# Create Skill > Bootstraps a new agent skill by generating SKILL.md, README.md, LICENSE, and optional reference files as a directory inside the pavelsimo/skills repo and registering it in the index README. Use when the user wants to create a new Claude Code skill from scratch. - Skill: `pavelsimo/create-skill` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add pavelsimo/create-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/pavelsimo/create-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: pavelsimo (https://skillmd.com/u/pavelsimo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pavelsimo/create-skill --- # create-skill skill A Claude Code skill that scaffolds a new agent skill from a plain-text description — generates SKILL.md, README.md, LICENSE, and optional `reference/*.md` files, writes them as a `skills//` directory inside the centralized `pavelsimo/skills` repo, and registers the skill in the index README. ## features - generates SKILL.md (`name` + `description` frontmatter, features, usage, workflow, best practices) from the user's description - produces a README.md matching the standard skill template (usage, installation via `npx skills@latest add pavelsimo/skills`, license) - writes an MIT LICENSE with the current year and "Pavel Simo" as the copyright holder - creates optional `reference/*.md` files for large tables, catalogs, examples, or templates - creates the skill as a `skills//` directory inside the `pavelsimo/skills` repo — no separate repo, no submodule - updates the index `README.md`: adds a table row and a detailed `### [name]` section linking to `skills/` - commits the new skill with a single `➕` commit and offers to push ## usage ``` /create-skill # prompt for name and description /create-skill # prompt for description only ``` ## what gets created ``` skills// ├── SKILL.md # full skill specification (generated from your description) ├── README.md # user-facing docs with usage + installation ├── LICENSE # MIT, current year, Pavel Simo └── reference/ # optional bulky catalogs, templates, or examples └── .md ``` plus a table row and a `### [](skills/)` detail section appended to the repo's `README.md`. ## workflow 1. parse args: - if `` is provided, use it; otherwise ask: `skill name (kebab-case):` - validate: all lowercase, only `[a-z0-9-]`, no spaces; reject anything else with a clear error 2. collect the skill description: - ask: "describe this skill — what it does, what triggers it, its key flags/modes, and the workflow steps it follows:" - wait for the user's response (a paragraph or several paragraphs is fine) 3. generate SKILL.md from the description: - frontmatter: `name`, `description` only - `## features` — 4–8 bullet points extracted from the description - `## usage` — command + flag examples in a fenced code block - `## workflow` — numbered steps in imperative mood; include exact bash commands where applicable; conditional branches use sub-bullets ("if X: …") - `## best practices` — 4–8 bullets - if the skill involves a large enumerated set of values, examples, or output templates, keep only a pointer in SKILL.md and generate `reference/.md` 4. generate README.md: - `# skill` title + one-sentence description - `## Usage` — copy the usage block from SKILL.md - one skill-specific section (e.g., output format, examples, what it produces) inferred from the description - `## Installation` — single bash code block: `npx skills@latest add pavelsimo/skills` - `## Contributing` — "open an issue or pull request. keep commits atomic." - `## License` — "MIT" 5. generate LICENSE: - MIT License text - year: run `date +%Y` to get the current year - copyright holder: Pavel Simo 6. show all generated files and ask: `create skills// with these files? yes / edit / cancel` - **edit**: ask which file to revise and what to change; regenerate and re-show; repeat - **cancel**: stop immediately, delete nothing (nothing was written yet) - **yes**: proceed 7. locate the skills repo root: - if the current directory is the `pavelsimo/skills` repo (contains a `skills/` directory plus the index `README.md` and `AGENTS.md`), use it - otherwise run `gh repo clone pavelsimo/skills` to a temp location and use that - abort if `skills//` already exists: "skill `` already exists — choose a different name" 8. write the directory and files: ```bash mkdir -p skills/ # write SKILL.md, README.md, LICENSE, and any reference/*.md files into skills// ``` 9. register in the index `README.md`: - add a row to the existing HTML skills table, **in alphabetical position** by skill name (the table is kept sorted): ``` ``` - insert a matching detailed section **in alphabetical position** among the existing `###` sections (the sections are kept sorted): ``` ### [](skills/) ``` / # example invocation ``` ``` 10. commit: ```bash git add skills/ README.md git commit -m "➕ add skill" ``` - then ask: `push to origin now? yes / skip`; on **yes** run `git push` 11. report results: - skill directory: `skills//` - install with: `npx skills@latest add pavelsimo/skills` - invoke with: `/` ## best practices - **validate the name first** — reject uppercase, spaces, or special characters before doing anything else - **show drafts before writing** — always show generated files and wait for confirmation; never write to disk without approval - **keep SKILL.md lean** — every skill has `SKILL.md`, `README.md`, and `LICENSE`; use `reference/*.md` for large tables, catalogs, examples, and templates - **one atomic commit** — a single `➕ add skill` commit covering the new directory and the README index update - **preserve README.md structure** — insert the table row and the detailed `###` section in **alphabetical position** (both lists are kept sorted by skill name); link to `skills/`, never an external repo - **derive the year dynamically** — run `date +%Y` rather than hardcoding the current year in the LICENSE