# New Skill > Write a new SKILL.md to teach yourself a procedure for a recurring task. Use when asked to "write a skill", "create a skill", "add a skill", "remember how to X", "make a procedure for X", or when you notice a task pattern worth recalling in future sessions. - Skill: `av/new-skill` (Agent Skill) - Install (CLI): `npx skillmds@latest add av/new-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/av/new-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: av (https://skillmd.com/u/av) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/av/new-skill --- A skill is a SKILL.md with YAML frontmatter (`name`, `description`) and a procedural body. Skills teach procedures. For new capabilities (code that does something), write a tool instead — load the `self` skill for tool authoring. Write a skill only when the task recurs, the procedure is non-obvious, and a description can match unseen phrasings. For one-off work, just do it. `skill()` first — never duplicate an existing skill. ## Where it goes Write to `~/.agents/skills//SKILL.md`. `` is kebab-case, ideally one short word, and unique against the existing list (`skill()`). ## Anatomy ``` --- name: description: --- ``` The **description** is the only thing visible during skill selection. Include the verbs and phrases a user is likely to say ("write X", "fix Y", "check Z"), not an abstract summary. If it doesn't match the user's words, the skill never loads. The **body** is a procedure, not an essay. Lead with `Use when…` / `Skip if…`, then the steps. Aim for under 50 lines. Concrete bash commands beat prose. No preamble, no recap. ## Procedure 1. `skill()` to list — confirm nothing covers the task; read the closest match's body to be sure. 2. Pick ``. 3. Write the file in one command: ``` mkdir -p ~/.agents/skills/ && cat > ~/.agents/skills//SKILL.md <<'EOF' --- name: description: --- EOF ``` 4. Verify: call `skill({name: ''})` and check the body comes back. The harness reads disk on every call, so the new skill is loadable immediately. Do not skip this step — a typo in frontmatter silently breaks discovery. 5. Auto-advertisement of the description in the system prompt only happens at `mi` startup — `/reset` keeps the existing system prompt. Restart `mi` to pick up new skills automatically; until then the model can still load it by explicit name.