# Create Skill

> Guide for creating effective agent skills. Use when users want to create a new skill (or update an existing skill) that extends agent capabilities with specialized knowledge, workflows, or tool integrations.

- Skill: `alexandru/create-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alexandru/create-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexandru/create-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alexandru (https://skillmd.com/u/alexandru)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alexandru/create-skill

---


# Adding a Reusable Skill

Reference: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Agent Skills are modular capabilities that extend an AI agent's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that the agent uses automatically when relevant.

## Core principles (keep SKILL.md lean)
- Be concise: SKILL.md is loaded into context; every token competes with the user's request.
- Assume the agent is smart: only add context it wouldn't already know.
- Use progressive disclosure: keep detailed explanations and examples in `references/*.md`.

## Naming + metadata
- `name` must be lowercase, numbers, hyphens only; prefer a clear action or domain name.
- `description` must be third-person, specific, and include "when to use".

## Structure
- `skills/<skill-name>/SKILL.md` contains quick start, workflow, rules, and pointers to references.
- `skills/<skill-name>/references/*.md` holds extended explanations and examples.
- Keep references one level deep from SKILL.md (no nested references).
- Add a table of contents for reference files longer than ~100 lines.
- Cross-skill references are allowed, but must include install instructions (e.g., `npx skills add https://github.com/alexandru/skills --skill <skill-name>`).

## Guidance quality
- Prefer the smallest needed typeclass/constraint or API surface.
- Avoid time-sensitive guidance; move outdated info to an "old patterns" section if needed.
- Use consistent terminology across the skill.
- Provide concrete examples only when they materially improve correctness.
- Provide original sources (web links) in references; keep sources high-quality.

## Versioning (skills.json)
- Version uses semantic versioning (e.g., `1.0.0`).
- Increment patch for minor fixes (typos, code sample mistakes).
- Increment minor when adding a new skill.
- Increment major for more substantial skill changes.

## Workflow for adding a skill
1. Create `skills/<skill-name>/SKILL.md` with YAML frontmatter and concise instructions.
2. Add reference docs under `skills/<skill-name>/references/` as needed.
3. Register the skill in `skills.json` (name, path, description, tags).
4. Update `README.md` so the skill list and structure stay current.
5. Test with representative prompts and refine.

## Checklist
- [ ] Name/description meet format rules and are specific.
- [ ] SKILL.md is concise and directs to references.
- [ ] Examples are in references, not SKILL.md.
- [ ] No nested references; one level deep from SKILL.md.
- [ ] `skills.json` version updated per semantic versioning rules.
- [ ] `skills.json` updated with tags.
- [ ] `README.md` updated.
- [ ] Tested with at least a few real requests.