ai-superpower/.ai/skills/write-skill/SKILL.md

name	description	category
write-skill	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.	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

---
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

  .ai/list-skills.sh > .ai/list-skills.sh