writing-skills

Documentation writing skill

Notes

• Content should be universally applicable and should not depend on specific business unless explicitly stated
• Documentation should be understandable independently of specific project context
• Examples should be concise and impactful, without wordy filler

Directory structure

skills/
  <skill-name>/
    SKILL.md       ← 必须，skill 入口文件

Naming conventions

• Folder name: lowercase letters + hyphens, for example code-review、task-breakdown
• name Fields: must match the folder name
• Style: use nouns or verb phrases, concise and clear

SKILL.md format

---
name: <skill-name>
description: <一句话说明用途和触发时机>
---

# <标题>

## 依赖规范
#[[file:../rules/<规则文件>.md]]
#[[file:../<其他skill>/SKILL.md]]

## 目的
<一句话说明目标>

## 输入
- <输入项>

## 步骤

> 每个步骤先输出标题，再输出结果

- <步骤 1>
- <步骤 2>

## 输出
- <输出项>

## Review 检查清单
- <检查项>

Writing rules

• description: clearly state "when to use it"; Kiro relies on this to decide whether to activate the skill
• Dependency specification: list all referenced rules and other skills to ensure the complete context can be loaded when used independently
• Steps: add "for each step, output the title first, then output the result" to prevent the AI from skipping steps
• Reference consistency: for specification names mentioned in the text, there must be a corresponding #[[file:]]
• Writing documentation: if the steps involve writing documentation, add "paths must follow project-structure documentation storage specification"
• Stage end: if it is a process-stage skill, add "next stage" and a stage-gate reference at the end

Rule files

General rules are placed in skills/rules/ directory, not as standalone skills, and are referenced by other skills via #[[file:]] references:

skills/rules/
  <rule-name>.md

Rule files also need frontmatter (name + description), but do not need steps and output.