191f9f4f2a
Tighten root/core control flow, add dedicated post-mortem, web, and context-hygiene capabilities, and reduce instruction drift through clearer ownership, conflict-priority handling, and README/docs workflow alignment. This makes long-session AI behavior more deterministic while keeping the instruction system compact and maintainable.
91 lines
4.0 KiB
Markdown
91 lines
4.0 KiB
Markdown
---
|
|
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: workflow
|
|
impact: 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
|
|
```md
|
|
---
|
|
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
|
|
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. |