Skills

tidy-repo

Installation
SKILL.md

技能 (Skill)：整仓整理

目的 (Purpose)

在单次运行中，扫描仓库（或指定范围）的目录结构，识别结构性问题——错放文件、命名不一致、空目录、过期制品、重复条目——并输出一份带优先级的整理报告，指导人工或自动清理。在 apply-safe 模式下，可直接执行安全、可逆的操作。

核心目标 (Core Objective)

治理目标：生成一份仓库整理报告，其中 (1) 以标准格式列出所有结构问题及建议操作，(2) 按影响和代价排序，给出具体的清理步骤，(3) 可选地在 apply-safe 模式下执行并记录操作日志。

成功标准（必须满足所有要求）：

  1. ✅ 范围已确定：明确扫描根路径和排除列表（.git、node_modules、.venv 等）
  2. ✅ 问题已枚举：所有发现以标准格式输出（位置、类别、严重性、标题、描述、建议）
  3. ✅ 优先级已排序：按影响（高|中|低）和操作代价（小|中|大）排序
  4. ✅ 清理计划可操作：每步包含具体路径、操作类型、完成条件
  5. ✅ 安全边界已遵守：report-only 模式不修改任何文件；apply-safe 仅执行可逆操作
  6. ✅ 报告已持久化：写入商定路径，包含合规前置事项

验收测试：团队是否可以仅凭此报告的前 5 项行动，让仓库结构显著改善？若否，减少歧义并强化优先级。

范围边界 (Scope Boundaries)

本技能负责：

  • 枚举并分析仓库文件和目录结构
  • 识别：错放文件、命名不一致、空目录、过期/废弃制品、重复条目
  • 按类别和严重性输出标准格式的发现列表
  • 生成优先级清理计划
  • （可选）在 apply-safe 模式下执行移动、删除空目录等可逆操作，并记录日志

本技能不负责：

  • 代码质量或架构问题 → review-codebase
  • 文档规范合规性 → assess-docs
  • 需求或计划文档的内容质量 → align-planning
  • 危险操作（批量删除有内容的目录、修改 git 历史等）→ 人工执行
  • 提交整理后的变更 → commit-work

转交点：报告交付后，可将提交操作交给 commit-work；若发现文档规范问题，交给 assess-docs；若发现架构问题，交给 review-codebase。

使用场景 (Use Cases)

  • 日常维护：仓库积累文件后的定期结构健康检查
  • 入职对齐：新成员加入时，快速了解并对齐目录约定
  • 重构后清理：代码重构或模块拆分后，清除残留的旧路径和废弃文件
  • CI/CD 门控：在流水线中作为结构合规检查步骤
  • 发布前整理：在版本发布前确保仓库整洁

行为 (Behavior)

第 0 阶段：Norms Resolution（v1.3 新增）

按 specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 的 §8.2 / §8.3 / §8.5 实现：读项目规范若声明了 repo-tidy artifact_type 的 path_pattern，则使用项目值；否则 fall through 到技能默认（docs/calibration/repo-tidy.md）。本技能为固定路径治理产出，只用 path_pattern 覆盖机制；整理操作本身会尊重项目声明的 artifact path_pattern（移动文件到项目规定的位置而非 AI Cortex 默认）。

交互策略

  • 前置条件：项目必须有文档规范（新增）
  • 默认模式：report-only，不修改任何文件
  • apply-safe 模式：执行前向用户确认操作列表；失败时回滚已执行步骤
  • 范围：默认扫描当前工作目录；排除 .git、node_modules、.venv、dist、build、__pycache__、.DS_Store 等

前置条件检查（新增）

目的：确保项目已建立文档规范，以便准确检测命名和路径问题

检查：

  1. 查找 docs/ARTIFACT_NORMS.md
  2. 若不存在，拒绝继续并输出： 
    ✗ 找不到文档规范

tidy-repo 需要项目先建立文档规范来准确检测文件位置和命名问题。

请先运行：
/discover-docs-norms

此命令将：
- 扫描现有 docs/ 结构
- 推导出项目的命名和路径约定
- 生成 docs/ARTIFACT_NORMS.md

然后重新运行 tidy-repo。

第 0 阶段：范围解析

  1. 解析仓库根路径（默认 CWD）和可选范围过滤
  2. 强制加载项目约定（前置条件已验证存在）：从 docs/ARTIFACT_NORMS.md 解析命名规则和目录结构期望
  3. 构建排除列表（二进制文件目录、依赖目录、构建产物目录）

第 1 阶段：结构扫描

  1. 递归枚举所有文件和目录（遵循排除列表）
  2. 构建目录树快照，记录：路径、类型（文件|目录）、大小、最后修改时间、扩展名

第 2 阶段：问题检测

对每个条目按以下类别检测：

类别 检测逻辑
misplaced 文件所在目录与其类型/内容不符（如 .md 在 src/，.py 在 docs/）
naming 文件或目录名违反项目约定（大小写、分隔符、前缀/后缀不一致）
empty-dir 目录下无任何有效文件（仅含 .gitkeep 除外）
dead-artifact 明显废弃的文件（扩展名为 .bak、.tmp、.orig；名称含 DEPRECATED、OLD、UNUSED；超过 180 天未修改且无引用）
duplicate 文件名或路径高度相似，疑似重复（如 util.py 与 utils.py 在同目录）
structure 顶层出现非预期目录，或缺少约定的标准目录（如 docs/、src/）
root-categorization docs/ 根目录中的文件应该分类到子目录（不应有除索引、治理文件外的内容）
naming/timestamp-misuse 文件名中包含不必要或格式错误的时间戳（仅对不允许时间戳的类型）

Root-Categorization 检测细节：

  1. 从 docs/ARTIFACT_NORMS.md 读取允许的根目录文件列表（索引文件、治理文件）
  2. 扫描 docs/ 根目录的所有 .md 文件
  3. 对每个 .md 文件：
    • 如果与允许列表匹配（README.md、INDEX.md、ARTIFACT_NORMS.md 等）→ 跳过
    • 否则，推断其 artifact_type（从 front-matter、文件名、内容）
    • 查询 ARTIFACT_NORMS.md 中该类型的 path_pattern
    • 创建 finding：root-categorization，建议移至该目录，严重性：suggestion（信息级别）
  4. 示例：docs/goals.md → 推断类型为 goals → 查询规范 → 建议移至 docs/goals/goals.md

Timestamp-Misuse 检测细节（新增）：

  1. 从 docs/ARTIFACT_NORMS.md 读取时间戳政策
  2. 对每个 .md 文件：
    • 检查文件名是否有 YYYY-MM-DD 前缀
    • 推断其 artifact_type
    • 查询该类型是否允许时间戳
    • 如果文件有时间戳但类型不允许 → 创建 finding：naming/timestamp-misuse，建议移除前缀
    • 如果文件没有时间戳但类型需要（adr、design-decision）→ 创建 finding：naming/timestamp-missing（可选）
    • 如果有时间戳但格式错误（如 2026/03/15）→ 建议正确格式：YYYY-MM-DD
  3. 示例：docs/requirements-planning/2026-03-15-api-requirements.md → 推断类型为 requirements → 查询规范 → 建议重命名为 api-requirements.md

第 3 阶段：发现输出

每个发现必须遵循标准格式：

字段 内容
位置 path/to/file-or-dir
类别 misplaced | naming | empty-dir | dead-artifact | duplicate | structure | root-categorization | naming/timestamp-misuse
严重性 critical | major | minor | suggestion
标题 简短问题摘要
描述 具体说明哪里不对
建议 具体操作（如"移至 X"、"重命名为 Y"、"删除空目录"、"确认是否废弃后删除"）

汇总：扫描文件总数、目录总数、各类别发现数量、各严重性发现数量。

第 4 阶段：优先级排序

对每个发现评估：

  • 影响（高|中|低）：对可导航性、CI、新成员入职的阻碍程度
  • 操作代价（小|中|大）：执行建议操作的工作量

排序原则：优先处理高影响、低代价的问题（快速胜利）；其次为高影响、高代价（需规划）；最后为低影响问题（可选）。

第 5 阶段：清理计划

输出最小可操作步骤集：

每步包含：

  • 操作路径
  • 操作类型（move | rename | delete-empty-dir | archive | review-manually）
  • 原因（Why now）
  • 完成条件
  • 是否可在 apply-safe 模式自动执行

第 6 阶段（可选）：apply-safe 执行

仅在用户明确传入 apply-safe 模式时激活：

  1. 向用户展示将要执行的操作列表，等待确认
  2. 仅执行以下安全操作：
    • 移动/重命名文件（git mv 优先）
    • 删除空目录
  3. 跳过（并标记为"需人工处理"）：
    • 删除有内容的目录
    • 覆盖已有文件
    • 任何不可逆操作
  4. 记录操作日志，追加到报告末尾

第 7 阶段：持久化报告

写入路径（按项目规范或默认 docs/calibration/repo-tidy.md）。报告前置事项：

artifact_type: repo-tidy
created_by: tidy-repo
lifecycle: living
created_at: YYYY-MM-DD

输入与输出 (Inputs & Outputs)

输入

  • 仓库根路径（默认 CWD）
  • 可选范围过滤（子目录或 glob）
  • 可选模式：report-only（默认）| apply-safe

输出

---
artifact_type: repo-tidy
created_by: tidy-repo
lifecycle: living
created_at: YYYY-MM-DD
---

# Repository Tidy Report

**Date:** YYYY-MM-DD
**Scope:** /path/to/root (filtered: src/)
**Mode:** report-only | apply-safe
**Summary:** N files, M dirs scanned; K findings (critical: X, major: Y, minor: Z, suggestion: W)

## Findings

| Location | Category | Severity | Title | Description | Suggestion |
| :--- | :--- | :--- | :--- | :--- | :--- |
| src/utils.bak | dead-artifact | major | Backup file in source | .bak file committed to source tree | Remove or archive to .archive/ |

(If no findings: "No structural issues found.")

## Cleanup Plan

### Quick Wins (high impact, low effort)

1. **Path:** src/utils.bak
   **Action:** delete
   **Why now:** Dead artifact pollutes source tree
   **Done condition:** File removed; no references in codebase
   **Auto-apply:** yes

### Plan Next Sprint (high impact, high effort)

...

### Optional / Low Priority

...

## Apply Log (apply-safe mode only)

| Action | Path | Result |
| :--- | :--- | :--- |
| delete-empty-dir | tmp/ | success |
| move | docs/OLD-arch.md → .archive/OLD-arch.md | success |
| skipped (manual) | src/legacy/ | non-empty directory — review manually |

## Machine-Readable Summary

    scope: "."
    mode: "report-only"
    filesScanned: 142
    dirsScanned: 28
    findings:
      total: 7
      bySeverity: { critical: 0, major: 3, minor: 2, suggestion: 2 }
      byCategory: { misplaced: 1, naming: 2, empty-dir: 1, dead-artifact: 2, duplicate: 1 }
    topActions:
      - { path: "src/utils.bak", action: "delete", impact: "high", effort: "small" }

限制 (Constraints)

硬边界 (Hard Boundaries)

  • report-only 模式绝不修改任何文件或目录
  • apply-safe 模式绝不删除有内容的目录；所有危险操作标记为"需人工处理"
  • 不伪造或推测文件内容；仅基于路径、名称、修改时间、大小判断
  • 不修改 git 历史
  • 不执行任何网络操作

技能边界 (Skill Boundaries)

不要做（其他技能处理）：

  • 代码质量、架构、依赖审查 → review-codebase
  • 文档内容规范和准备情况 → assess-docs
  • 需求/规划文档对齐 → align-planning
  • 提交清理结果 → commit-work

何时停止并交接：

  • 若发现大量文档规范违规 → 交给 assess-docs
  • 若需要提交整理变更 → 交给 commit-work
  • 若发现架构层面问题 → 交给 review-codebase

自检 (Self-Check)

核心成功标准（必须满足所有标准）

  • 范围已明确；排除列表已应用
  • 所有发现以标准格式输出（位置、类别、严重性、标题、描述、建议）
  • 发现已按影响和代价排序
  • 清理计划包含具体路径和操作类型
  • apply-safe 模式仅执行可逆操作，并记录操作日志
  • 报告已写入商定路径，包含合规前置事项

流程质量检查

  • 没有误报高严重性的低影响问题
  • 建议操作具体且可直接执行
  • 交接技能名称有效且最新

验收测试

团队是否可以仅凭报告前 5 项行动，让仓库结构显著改善？

若否：减少歧义，强化优先级和具体性。若是：报告已完成。

示例 (Examples)

示例 1：发现废弃制品

  • 文件：src/auth.py.bak，7 个月未修改
  • 发现：位置 src/auth.py.bak，类别 dead-artifact，严重性 major，标题"源码目录中的备份文件"，描述".bak 文件被提交至源码树中"，建议"删除或移至 .archive/"
  • 清理计划：Quick Win；apply-safe 可自动执行

示例 2：空目录

  • 目录：tmp/cache/（无任何文件）
  • 发现：类别 empty-dir，严重性 minor，建议"删除空目录，或添加 .gitkeep 若有意保留"
  • apply-safe 模式：自动删除

示例 3：命名不一致

  • 发现：src/ 下同时存在 UserService.py（PascalCase）和 auth_service.py（snake_case）
  • 严重性：major，建议"统一命名约定；参考项目现有主导风格决定重命名方向"
  • 标记为"需人工处理"（重命名涉及导入引用更新）

示例 4：apply-safe 执行日志

已执行：delete-empty-dir tmp/cache/        ✓
已执行：move docs/OLD-arch.md → .archive/ ✓
已跳过：src/legacy/（非空目录，需人工处理）

附录：输出合约 (Appendix: Output Contract)

本技能产出 Tidy Report：

元素 格式 必填字段 路径模式
报告主体 Markdown front-matter；章节：摘要 / 错放文件 / 命名违规 / 空目录 / 过期/死文件 / 重复 / 优先清单 docs/calibration/repo-tidy.md
发现条目 列表项 category / path / evidence / severity / suggested_action（move/rename/delete/archive）/ effort_estimate 各分类章节
优先清单 表格 rank / action / target_path / risk_level / safe_to_auto_apply（bool） 「优先清单」节
Related skills

More from nesnilnehc/ai-cortex

Installs
28
Repository
nesnilnehc/ai-cortex
GitHub Stars
7
First Seen
Mar 23, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass