agent-folder-init

Agent 文件夹初始化

授权范围

仅在用户请求和现有授权范围内操作；加载此技能不会授予任何新权限。仅报告的请求必须仅作报告，遵守调用方对目标、主机、提供方和成本的限制，扩展范围前先征求同意，并将这些限制告知委派对象。

约定

输入：

• 现有项目根目录
• 项目名称和主要技术栈
• 可选的平台入口界面：Claude Code、Codex 和/或 Cursor

输出：

• 默认生成试运行计划
• 仅在明确指定 --write 后生成 .agents/ 文档结构和根目录 AGENTS.md
• 仅在明确选择相应平台时生成可选的 CLAUDE.md 或 .cursor/rules/agent-context.mdc；Codex 使用 AGENTS.md
• 汇总计划生成、已写入、已跳过和未更改的文件

创建/修改：

• .agents/、根目录 AGENTS.md、可选的 CLAUDE.md、可选的 Cursor 项目规则，以及 .editorconfig
• 不创建应用程序源代码

外部副作用：

• 默认试运行不会产生任何副作用；--write 仅执行本地文件写入

需要确认：

• 任何写入前：检查试运行计划，并明确使用 --write 重新运行
• 覆盖现有入口文件前：添加 --force-entry-files；始终拒绝符号链接和非文件目标
• 写入当前工作区之外的位置前

委派给：

• 启动新产品仓库时，委派给 project-init-orchestrator
• 应搭建新的 Shipshit.dev 产品时，委派给 project-init-orchestrator（v0 路由）/ npx @shipshitdev/v0
• 生成后委派给 agent-config-audit，以检测配置偏差或过期配置

用途

此技能先制定计划，再搭建精简的 AI Agent 文档系统，包括：

• 会话跟踪（在 .agents/sessions/ 中创建每日文件）
• .agents/memory/ 中的持久项目上下文（每个文件一个主题）
• 支持的平台入口界面，不复制命令、规则、Agent、用户设置或其他项目的配置

适用场景

• 为现有项目添加 AI 编码助手上下文
• 设置 AI 优先的开发工作流
• 将现有项目迁移为使用结构化 AI 文档

对于新的 Shipshit.dev 产品仓库，优先使用 project-init-orchestrator；它会路由到 npx @shipshitdev/v0，并包含标准的 .agents、.claude 和 .codex 设置。

用法

运行脚手架脚本：

python3 scripts/scaffold.py --help

# Basic usage
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project"

# Review the plan, then write the shared files
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project" \
  --write \
  --allow-outside

# Add only the documented Claude and Cursor entry surfaces
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project" \
  --platform claude \
  --platform cursor \
  --write \
  --allow-outside

默认始终为试运行。--force-entry-files 是唯一允许覆盖 AGENTS.md、CLAUDE.md 或生成的 Cursor 入口规则的标志。其他现有文件会保留。

生成的结构

文档（.agents/）

.agents/
├── README.md                    # Navigation hub
├── memory/
│   └── README.md                # Source of truth for durable project facts
└── sessions/
    ├── README.md                # Session format guide
    └── TEMPLATE.md              # Session file template

共享规则和编码标准应放在适用的 AGENTS.md 中。仅在有意覆盖某个子树时使用 AGENTS.override.md，仅在添加 Claude 专属内容时使用 CLAUDE.md。持久的补充细节应放在 .agents/memory/ 中。

任务跟踪使用 GitHub Issues（gh issue list、gh issue create），而非本地任务文件。

平台入口界面

AGENTS.md                         # shared instructions; native Codex entry
CLAUDE.md                         # only with --platform claude
.cursor/rules/agent-context.mdc   # only with --platform cursor

脚手架不会生成 .codex/commands、复制用户设置或导入库的检出副本。它只会复制 4 个 .agents/ 模板、.editorconfig 以及明确选择的入口模板。若缺少规范资源，则会在任何写入操作前直接失败；不会使用内置或过期的备用内容。

根目录文件

• AGENTS.md - 共享项目说明和 .agents/ 导航
• CLAUDE.md - 可选的 Claude 专属补充内容，引用 AGENTS.md
• .editorconfig - 编辑器配置

关键模式

memory/ 文件

• 每个文件一个主题：memory/architecture.md、memory/deployment.md、memory/entities.md 等。
• 每个文件的 front matter 都包含 last_verified: YYYY-MM-DD 字段。
• 短暂或生命周期较短的事实应添加 status: temporary。

会话文件

• 每天一个文件：sessions/YYYY-MM-DD.md
• 同一天的多个会话在同一个文件中使用 Session 1、Session 2 等标记。

自定义

搭建完成后，进行以下自定义：

1. 根 Agent 入口文件 - 添加项目专属的编码规范和“绝不执行”规则
2. .agents/memory/architecture.md - 记录架构决策
3. .agents/memory/entities.md - 记录数据实体
4. .agents/memory/deployment.md - 记录部署步骤和注意事项
5. GitHub Issues - 为任务创建 Issue（gh issue create）
6. 平台入口文件 - 仅添加无法写入共享 AGENTS.md 的特定运行环境指南

与其他技能集成

此技能与以下技能集成：

技能	协作方式
project-init-orchestrator	将新的产品请求路由到 v0，再进行更低层级的设置
project-init-orchestrator	使用 v0 创建新的 Shipshit.dev 产品工作区
linter-formatter-init	在搭建的项目中设置质量工具
husky-test-coverage	在提交前钩子中强制执行测试覆盖率要求