# How to Create Custom SKILL.md Files for New Analysis Scenarios in reverse-skill

> Learn how to create custom SKILL.md files for new analysis scenarios in reverse-skill. Follow this guide to add YAML headers, action blocks, workflows, and routing contexts.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-05

---

**Create a new skill directory under `skills/`, add a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) with YAML header, action block, workflow, routing context, and checklist, then register the skill in `master-route.ps1` and refresh the tool index if needed.**

The `reverse-skill` repository treats every analysis scenario as a **skill**—a self-contained module that the master router can discover and execute. Each skill lives in its own directory and is defined by a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file that specifies scope, workflow, and required tools. This guide walks through the exact steps to create custom SKILL.md files for new analysis scenarios, based on the source implementation in `zhaoxuya520/reverse-skill`.

## Understanding the Skill Architecture

The `reverse-skill` routing system relies on two core principles: **skill directories** and the **master routing matrix**. Every skill is a folder under `skills/` containing a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file. The master router—implemented in `skills/scripts/master-route.ps1`—resolves skill identifiers to these files at runtime.

Key source files governing this architecture:

- `skills/scripts/master-route.ps1` — Master routing script that adds new skill IDs
- [`skills/field-journal/_template.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/_template.md) — Template for SKILL.md structure and journal entries
- [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) — Central skill list controlling the entry point
- `skills/scripts/refresh-tool-index.ps1` — Updates [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) with real tool paths
- [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) — Alternative three-axis routing matrix
- [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) — Repository-wide rules and self-check checklist

## Step 1: Create the Skill Directory

Create a new directory under `skills/` using a short, descriptive name:

```bash
mkdir skills/my-new-scenario

```

The directory name becomes part of the skill's identity but does not affect routing—registration in the master router handles that.

## Step 2: Write the SKILL.md File

Every [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) must follow the repository template defined in [`skills/field-journal/_template.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/_template.md). The file requires five mandatory sections.

### YAML Header

Start with frontmatter defining `name` and `description`:

```markdown
---
name: my-new-scenario
description: |
  Brief one-sentence description of the analysis scenario.
---

```

The `name` field must match the directory name for consistency.

### ACTION REQUIRED Block

This block lists immediate checks the AI must perform before proceeding. Use the `NOW` / `NEXT` / `ACT` pattern from the template:

```markdown

## ACTION REQUIRED（读完后立刻执行）

1. `NOW`: 读取 `../field-journal/precedent-reverse.md` – 确认本 skill 的操作已获授权  
2. `NOW`: 在 `work/<case>/scope.md` 中写明目标范围（BSSID、IP、文件等）  
3. `NEXT`: 读取 `tool-index.md`，确认所有自定义工具路径可用  
4. `ACT`: 执行工作流步骤（示例见下方）

```

Each item must be actionable and reference concrete files in the repository.

### WORKFLOW Section

Enumerate concrete steps as a checklist. The template uses checkbox syntax with `□` (unchecked box) as a visual cue:

```markdown

## 工作流

```text
□ 启动必要的 MCP/服务（scripts/start.ps1）  
□ 调用自定义脚本或 MCP 工具（e.g. mytool_xyz --option）  
□ 收集证据 → 写入 `Evidence` 表格  
□ 生成报告 → [`report.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/report.md)

```

```

### ROUTING CONTEXT Table

Document upstream dependencies and prohibited operations:

```markdown

## 路由上下文

| 上游 | MUST NOT |
|------|----------|
| **MASTER‑ROUTING** → `R99` | 未授权的外部网络扫描 |

```

The `MUST NOT` column is critical for safety—list operations that would violate the skill's authorization scope.

### CHECKLIST Section

Final verification items the AI must complete before claiming success:

```markdown

## 任务完成自检

- [ ] 已读取 precedents  
- [ ] 已确认 scope.md 中的授权信息  
- [ ] 已使用真实的 tool‑index 路径调用工具  
- [ ] 已写入 Evidence 与报告  

```

## Step 3: Register in the Master Router

Add your skill to `skills/scripts/master-route.ps1` using a unique identifier. The script maps IDs to [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) paths. Example entry pattern:

```powershell

# In skills/scripts/master-route.ps1

$Skills["R99"] = @{
    Name = "my-new-scenario"
    Path = "skills/my-new-scenario/SKILL.md"
    Description = "Brief description for routing display"
}

```

Alternatively, if using [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), add a row to the three-axis table with the same ID and path reference.

## Step 4: Refresh the Tool Index (Conditional)

If your skill introduces new external tools, run the index generator to update paths:

```bash

# Linux/macOS

./skills/scripts/refresh-tool-index.sh

# Windows PowerShell

./skills/scripts/refresh-tool-index.ps1

```

This updates [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) with real filesystem paths for binaries, ensuring [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) references resolve correctly.

## Step 5: Update the Field Journal Template (Optional)

To enable practitioners to record your new scenario, extend [`skills/field-journal/_template.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/_template.md). Add a section referencing your skill's routing ID and typical evidence format.

## Step 6: Validate and Commit

Before submission, verify against [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md):

- SKILL.md uses valid YAML frontmatter
- All file references are relative and resolve
- Routing ID is unique and registered
- Tool-index paths are current (if applicable)

For public repositories, open a PR that passes the repository's self-check checklist.

## Minimal SKILL.md Skeleton

Copy-paste template for rapid skill creation:

```markdown
---
name: my-new-scenario
description: |
  Brief one-sentence description of the analysis scenario.
---

# My New Scenario

## ACTION REQUIRED（读完后立刻执行）

1. `NOW`: 读取 `../field-journal/precedent-reverse.md` – 确认本 skill 的操作已获授权  
2. `NOW`: 在 `work/<case>/scope.md` 中写明目标范围（BSSID、IP、文件等）  
3. `NEXT`: 读取 `tool-index.md`，确认所有自定义工具路径可用  
4. `ACT`: 执行工作流步骤（示例见下方）

## 工作流

```text
□ 启动必要的 MCP/服务（scripts/start.ps1）  
□ 调用自定义脚本或 MCP 工具（e.g. mytool_xyz --option）  
□ 收集证据 → 写入 `Evidence` 表格  
□ 生成报告 → [`report.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/report.md)

```

## 工具链

| 工具 | 用途 |
|------|------|
| `mytool_xyz` | 说明为什么需要此工具 |

## 路由上下文

| 上游 | MUST NOT |
|------|----------|
| **MASTER‑ROUTING** → `R99` | 未授权的外部网络扫描 |

## 任务完成自检

- [ ] 已读取 precedents  
- [ ] 已确认 scope.md 中的授权信息  
- [ ] 已使用真实的 tool‑index 路径调用工具  
- [ ] 已写入 Evidence 与报告  

```

Save as `skills/<your-skill>/SKILL.md`.

## Summary

- **Skill directory**: Create under `skills/` with matching `name` in YAML header
- **SKILL.md structure**: YAML header → ACTION REQUIRED → WORKFLOW → ROUTING CONTEXT → CHECKLIST
- **Registration required**: Add unique ID to `skills/scripts/master-route.ps1` or [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)
- **Tool dependencies**: Run `refresh-tool-index.ps1`/`sh` to update [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)
- **Validation**: Check against [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) before commit

## Frequently Asked Questions

### What happens if I forget to register my skill in master-route.ps1?

The master router will not discover your skill. Execution attempts targeting your skill ID will fail with a routing error. Registration in `skills/scripts/master-route.ps1` (or [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)) is mandatory for routability.

### Can I use any routing ID format, or are there constraints?

Use short, unique identifiers like `R99`, `N01`, or `A10`. The repository follows a pattern matching `[A-Z][0-9]{2}` for consistency. Check existing entries in `skills/scripts/master-route.ps1` to avoid collisions.

### How do I reference tools in SKILL.md without hardcoding paths?

Always reference tools through [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md). Run `skills/scripts/refresh-tool-index.ps1` to regenerate this file with real paths, then use those mapped names in your WORKFLOW section. This ensures portability across environments.

### Is the Chinese text in the template mandatory?

Yes—the `ACTION REQUIRED` section uses specific Chinese phrases like `读完后立刻执行` to trigger parser recognition in the routing system. Keep these markers intact; translate only the procedural content within each numbered item.