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

name	description	category	impact
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.	workflow	medium

🏷️ 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, categoy, impact 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.
• NEVER assume missing requirements.

Workflows (Skill Creation Process)

1. Requirements Interview:
   • Ask one question at a time until required inputs are explicit.
   • Minimum inputs: domain, hard prohibitions, trigger wording ("Use when..."), and ✅/❌ examples.
   • If any required input is missing, do not draft yet.
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.

Impact Selection Criteria:

• high: Foundational rules. Security, state machines (root-skill), core ethics, or infrastructure integrity (IaC). If this rule is broken, the project or AI logic fails.
• medium: Workflow & Quality. Coding standards, Git practices, architectural patterns. Important for long-term health, but doesn't crash the system immediately.
• low: Formatting & Tools. Mermaid syntax, README structures, or temporary file handling. Purely aesthetic or helper-level instructions.

✅ / ❌ Examples

The Mandatory SKILL.md Template

---
name: <skill-name>
description: <what it does> <clear-description-for-ai-to-understand-when-to-load>
category: <meta|workflow|code|infra>
impact: <high|medium|low>
---

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

• When any frontmatter field changes, or when a skill is added, renamed, or removed: regenerate .ai/skill-list.txt by running the provided authoring script and commit the updated manifest.

  Example (from repo root):

  bash .ai/list-skills.sh > .ai/skill-list.txt
  # NOTE: Committing must be performed by a human operator. The AI MUST NOT run git add/commit/push.
  
  

  Note: list-skills.sh is an authoring helper and is referenced only in this skill's documentation.