---
name: write-skill
description: Create new agent skills with proper structure and AI superpower constraints. Use when user wants to create, write, or build a new skill, rule, or instruction.
category: meta
---

> **🏷️ Category:** `Meta-Skill` | **⚙️ Applies to:** AI Internal Operations & Context Discovery

# Write Skill Instructions (Meta-Skill)

## 🎯 Purpose
Force the AI to structure all new knowledge files into the strict, restrictive, and modular `ai-superpower` format (Agent Skills standard).

**🚨 CRITICAL: If you need to understand how to format the "description" triggers, file folder structures, or when exactly to use REFERENCE.md, YOU MUST use the `read_file` tool to read `.ai/skills/write-skill/REFERENCE.md` BEFORE drafting the skill.**

## 🚨 Prohibitions (Thou Shalt Not)

- **NEVER create a new skill without YAML frontmatter.** It MUST contain `name` and `description` (with "Use when [triggers]").
- **NEVER create a skill longer than 100 lines.** If it's too long, split the theory/examples into `REFERENCE.md` or `EXAMPLES.md`.
- **NEVER write text-heavy prose.** Use bullet points, bold text, and "Negative Prompting" (`🚨 Prohibitions: NEVER...`).
- **NEVER skip the `ai-root-instructions.md` integration.** The skill does not exist until it's registered in the router.
- **NEVER create `.instructions.md` flat files.** Always create `.ai/skills/[name]/SKILL.md` folders.

## Workflows (Skill Creation Process)

1. **Requirements Interview:** Ask the user ONE question at a time. What domain? What are the absolute "Thou Shalt Not" rules? Are there ✅/❌ examples?
2. **Drafting:** Create a compact `SKILL.md` (< 100 lines) following the exact template below.
3. **Review:** Show the draft to the user.
4. **Integration (MANDATORY):** 
   - Run `mkdir -p .ai/skills/[name]`
   - Run `create_file` to save `SKILL.md`.
   - Run `replace_string_in_file` to add a new trigger line to `.ai/skills/ai-root-instructions/SKILL.md`.

## ✅ / ❌ Examples

### The Mandatory SKILL.md Template
```md
---
name: [skill-name]
description: [1st sentence: what it does. 2nd sentence: "Use when [specific triggers]."]
---

# [Skill Name]

## 🎯 Purpose
[Why this exists and when to use referencing.]

## 🚨 Prohibitions
- **NEVER do X**
- **NEVER do Y**

## Workflows
[Actionable, tool-driven checklists or mechanical paths]

## ✅ / ❌ Examples
[Snippet of Bad vs Good]
```
## Review Checklist

After drafting, verify:

- [ ] Description includes triggers ("Use when...")
- [ ] SKILL.md under 100 lines
- [ ] No time-sensitive info
- [ ] Consistent terminology
- [ ] Concrete examples included
- [ ] References one level deep
- [ ] When name, description or file name changes & skill added or deleted '.ai/skill-list.txt' must be updated via '.ai/list-skills.sh' script
  ```bash 
  .ai/list-skills.sh > .ai/list-skills.sh
  ```