folders-skill

项目文档与目录管理规范，做成一个 Agent 技能，附脚手架与只读体检脚本。目的：新项目开箱即用，不必每次重新交代文档怎么放、怎么命名、怎么整理。

适用于需要管理文档、版本成果和过程资料的项目，可独立使用。项目已有约定优先；按实际需要启用目录。命名示例与常见问题见 references/examples.md。

它规定什么

• docs/{ssot,draft,archive} 三桶：现行真相、临时流水、已退役；各自的命名与出口。
• draft → ssot → archive 的整理节奏（蒸馏而非改名；同轮分流；在用户授权范围内执行）。
• 当前进展与缺口的摘要写法；代码与测试结果变化时同步 ssot 的口径。
• 两种命名风格：分类风格表达全局身份（ssot/NN-主题、models/{ver}、datasets/{主题}-vN、场景名）；日期风格表达一次过程（draft/YYYY-MM-DD-、jobs/YYYYMMDDTHHMMSS-…-R<N>）。发布、冻结、证据、归档批次挂在分类目录下，叶子带日期。
• ssot 的常见主题方案（起步文档、主题菜单、四种脊）。
• 显式运行布局、项目时区与证据保护；可选的运行时适配见 运行工作区适配。

目录

folders-skill/
├── SKILL.md                  技能入口：速查与流程
├── references/
│   ├── standard.md           规范全文
│   ├── ssot-topics.md        SSOT 常见主题方案
│   ├── runtime-workspaces.md  显式运行布局与证据保护
│   └── examples.md           通用示例、选择依据与常见问题
├── templates/                脚手架与单篇模板
└── scripts/
    ├── scaffold.py           建骨架并可接入技能入口
    ├── check_docs.py         只读体检
    └── project_layout.py     标准库布局适配器

用法

# 新项目：先预览，再执行，最后记录基线
python3 scripts/scaffold.py <项目目录> --with jobs,models --dry-run
python3 scripts/scaffold.py <项目目录> --with jobs,models
python3 scripts/check_docs.py <项目目录>

# 既有项目：只读体检（输出 ERROR / WARN / INFO，不改任何文件）
python3 scripts/check_docs.py <项目目录>

• 脚手架保留已有正文，入口只补必要索引；AGENTS.md 已存在时只提示要并入的片段。
• 体检脚本只读；WARN 是建议整改，INFO 是旧形态或需人工判断的信号，不要据此自动改名或清理。
• 两个脚本只依赖 Python 3 标准库。
• 脚手架保留已有主题与编号，目录文档复用或选择历史未占用的下一编号；对已有非标准布局不自动建立第二套 SSOT。
• 如项目使用受支持的显式运行布局，脚本会识别其声明；机器 job 不强加 R<N>，运行证据不会按 work/ 清理。普通项目不需要安装运行时。

接入方式

将本仓库检出到任意目录，再接入所用 Agent 的技能目录。技能目录以该工具的配置为准，例如 ~/.agents/skills/、~/.claude/skills/ 或 ~/.codex/skills/。

git clone https://github.com/arcstep/folders-skill.git /path/to/folders-skill
# 以 ~/.agents/skills 为例；按所用工具修改技能目录
mkdir -p ~/.agents/skills
ln -s /path/to/folders-skill ~/.agents/skills/folders-skill

符号链接指向这份源码，更新时只维护一份。项目级接入可使用脚手架的可选 --wire；项目需要独立分发时，把完整技能作为可移植文件纳入版本管理。

与项目约定的关系

本技能提供通用默认，不依赖其他技能或私有规则。项目的 AGENTS.md、文档约定和冻结的运行合同决定具体布局、版本策略与保护范围。同步已有文档属于相关变更的一部分；迁移、归档和删除须在用户授权范围内，范围不明时先给出具体方案。

维护

• 改规范：同步 SKILL.md 速查与 templates/。
• 改脚本：用临时目录跑一遍"scaffold → check_docs"闭环，应零 WARN。
• 脚本回归：python3 -m unittest discover -s tests -v，覆盖既有正文与资产保留、历史编号、重复接入、预览不写入和机器布局的保护边界。
• 可选运行时互操作检查的环境设置见 运行工作区适配；常规回归无需外部源码或二进制。
• 示例使用虚构路径，不记录特定工作区的项目清单或扫描统计。