# Expected Directory Structure for a New Skill Module in reverse-skill

> Understand the expected directory structure for a new skill module in reverse-skill. Learn about the mandatory SKILL.md and optional scripts and references subdirectories.

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

---

**A new skill module must follow a strict folder layout under `skills/<new-skill-name>/` with a mandatory [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point and optional `scripts/` and `references/` subdirectories.**

The `zhaoxuya520/reverse-skill` repository enforces this structure for automatic discovery by the AI routing system, tool-index refresh scripts, and bootstrap manifest. Deviating from this layout breaks pipeline integration.

## Where Skills Live: The `skills/` Directory

Every skill module resides under the top-level `skills/` folder. This centralizes discovery for:

- **AI routing** – the routing matrix scans `skills/` to build navigation paths
- **Tool indexing** – `scripts/refresh-tool-index.ps1` crawls subdirectories for executable scripts
- **Bootstrap integration** – [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) references skill paths for auto-installation

The naming convention is strict: **lower-case English letters and hyphens only** (e.g., `firmware-reverse`, not `firmware_reverse` or `固件分析`). This guarantees deterministic path resolution across Windows, Linux, and CI pipelines as defined in [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) and [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md).

## Mandatory and Optional Subdirectories

Each skill directory contains three possible levels:

| Component | Required | Purpose |
|-----------|----------|---------|
| [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) | **Yes** | Manifest declaring name, description, workflow, and mandatory sections |
| `scripts/` | No | PowerShell, Bash, or other automation scripts |
| `references/` | No | Cheat-sheets, research notes, external links |

### Complete Directory Template

```text
skills/
└── <new-skill-name>/
    ├── SKILL.md              # 必须：skill 入口文档

    ├── scripts/              # 可选：自动化脚本

    │   └── <workflow>.ps1
    └── references/           # 可选：参考资料、速查表

        └── <topic>.md

```

*(Source: [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md), "2. 目录结构模板")*

## The [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) Manifest: Required Structure

[`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) is the non-negotiable entry point. It must contain:

1. **YAML front-matter** with `name:` and `description:` fields
2. **ACTION REQUIRED** section – immediate execution steps marked with `NOW`, `NEXT`, `ACT`
3. **工作流** – the step-by-step workflow
4. **任务完成自检** – self-check checklist
5. **路由上下文** – upstream/downstream routing relationships

### Example: [`skills/firmware-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/firmware-reverse/SKILL.md)

```markdown
---
name: firmware-reverse
description: Reverse‑engineer embedded firmware images without IDA.
---

# Firmware Reverse Engineering

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

1. `NOW`：读取 `../field-journal/precedent-reverse.md`，确认授权范围。  
2. `NOW`：检查 `../tool-index.md` 中的 `binwalk` 可用性。  
3. `NEXT`：若缺工具，调用 `bootstrap-reverse.ps1` 自动安装。  
4. `ACT`：执行 `scripts/extract.ps1` 开始提取。

## 工作流

1. 使用 `binwalk` 进行固件分段。  
2. 运行自定义脚本解析文件系统。  
3. 生成阶段性报告并写入 `work/<case>/evidence/`。

## 任务完成自检

- [ ] 是否完整执行了工作流每一步？  
- [ ] 是否产出可复现的证据文件？  
- [ ] 是否更新了路由矩阵？  

## 路由上下文

**上游**: MASTER → **下游**: docs‑generator，报告输出

```

## Populating `scripts/` and `references/`

### Adding Automation Scripts

Scripts in `scripts/` are referenced from [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) via relative paths:

```powershell

# skills/firmware-reverse/scripts/extract.ps1

param(
    [Parameter(Mandatory)][string]$ImagePath
)

$binwalk = Resolve-Path (Join-Path $PSScriptRoot '..' '..' '..' 'tools' 'binwalk.exe')
& $binwalk $ImagePath -e -C "$ImagePath.extracted"
Write-Host "Extraction complete. Results in $ImagePath.extracted"

```

Referenced in [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md):

```markdown

## 工作流

1. `ACT`: `scripts/extract.ps1 -ImagePath <firmware.bin>`

```

### Adding Reference Materials

The `references/` folder holds supporting documentation without polluting the skill root. Typical contents include format specifications, attack technique summaries, or external URLs.

## Files to Update After Creating the Directory

Creating the directory structure alone is insufficient. You must update these repository-level files:

| File | Required Change |
|------|---------------|
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Add routing matrix entry mapping upstream/downstream relationships |
| `skills/scripts/refresh-tool-index.ps1` | Add `$scriptRefs` entry for any new scripts |
| [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) | Declare new external tools for auto-installation |
| [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) (root) | Add aggregate entry for AI's top-level menu |

## Summary

- **All skills live under `skills/<name>/`** with lower-case, hyphen-separated names
- **[`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) is mandatory** and must include YAML front-matter plus four required sections
- **`scripts/` and `references/` are optional** but recommended for automation and documentation
- **Four repository files need manual updates** after creating the directory: [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md), `refresh-tool-index.ps1`, [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json), and root [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)
- The structure is enforced by discovery pipelines; deviations break routing and bootstrapping

## Frequently Asked Questions

### What characters are allowed in the skill directory name?

Only lower-case English letters (`a-z`) and hyphens (`-`). Underscores, Chinese characters, numbers, and spaces are prohibited. This ensures cross-platform path resolution in Windows, Linux, and CI environments as specified in [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) and [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md).

### What happens if I omit [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)?

The skill becomes invisible to the AI routing system. The routing matrix, bootstrap manifest, and documentation pipelines all depend on parsing [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) for metadata. Without it, the directory is treated as orphaned data.

### Can I use Python scripts instead of PowerShell in `scripts/`?

Yes. The directory structure accepts any executable file type. However, `refresh-tool-index.ps1` specifically catalogs script references, so cross-platform skills should provide both PowerShell and Bash variants when targeting mixed Windows/Kali deployments.

### How does the `references/` folder differ from external links in [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)?

The `references/` folder stores **local, version-controlled content** (cheat-sheets, research notes) referenced via relative paths. External links in [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) point to **external URLs**. Local references ensure offline availability and audit trails critical to security workflows.