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

Create a new skill directory under skills/, add a 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 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 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 — Template for SKILL.md structure and journal entries
• skills/SKILL.md — Central skill list controlling the entry point
• skills/scripts/refresh-tool-index.ps1 — Updates tool-index.md with real tool paths
• skills/routing.md — Alternative three-axis routing matrix
• 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:

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 must follow the repository template defined in skills/field-journal/_template.md. The file requires five mandatory sections.

YAML Header

Start with frontmatter defining name and description:

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

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

## 工作流

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

## 任务完成自检

- [ ] 已读取 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 paths. Example entry pattern:

# 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, 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:

# Linux/macOS

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

# Windows PowerShell

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

This updates tool-index.md with real filesystem paths for binaries, ensuring 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. Add a section referencing your skill's routing ID and typical evidence format.

Step 6: Validate and Commit

Before submission, verify against 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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}