init-agent-project

name	init-agent-project
description	Initialize or align repository-level AI collaboration scaffolding with AGENT.md, a delegating CLAUDE.md compatibility stub, and .agent/. Use when a user asks to bootstrap a new repository, onboard an existing repository, migrate Claude conventions, create project memory/workspace directories, or standardize where stable collaboration preferences versus changing progress and paths are recorded.

Initialize Agent Project

Create a small, repository-specific collaboration entry point without turning it into a duplicate README. Support empty repositories, active repositories, and explicit migrations from other agent conventions.

Workflow

1. Resolve and inspect the repository

1. Resolve the target root from the user-provided path. Otherwise use the Git root when present, then fall back to the current working directory.
2. Inspect before writing:
   • top-level tree and relevant source/document directories;
   • README*, package manifests, build files, and authoritative docs;
   • AGENT.md, AGENTS.md, CLAUDE.md, .agent/, .claude/, and equivalent guidance;
   • Git status when the directory is a repository.
3. Read existing guidance completely before editing it. Preserve unrelated user changes.
4. Infer the project goal and working conventions from real files. Ask a question only when the goal cannot be inferred and guessing would materially mislead future agents.

Treat the target as one of these cases:

• New or empty repository: derive a minimal goal from the user's description and initialize the collaboration files.
• Existing repository: summarize its actual structure and merge project-specific conventions without replacing useful rules.
• Convention migration: translate requested names and references, detect destination collisions, and preserve content that still applies.

2. Decide the file boundary

Keep each file focused:

AGENT.md: stable collaboration contract

Include only durable information:

• a one-paragraph project goal;
• communication and collaboration preferences;
• stable task, engineering, data, or safety principles;
• where progress, temporary artifacts, README material, and formal docs belong;
• the instruction to read .agent/memory/project_progress.md at the start of work.

Do not put volatile details in AGENT.md, including current metrics, dated status, long absolute-path inventories, output filenames, temporary blockers, or a detailed implementation roadmap. Keep it concise enough to reread every turn.

CLAUDE.md: compatibility entry point

Create a root CLAUDE.md containing only:

Read `AGENT.md`.

Keep AGENT.md as the single source of truth. Do not duplicate collaboration rules in CLAUDE.md.

.agent/memory/project_progress.md: onboarding and changing state

Use this file for:

• a top-level note explaining that it is both a progress log and path memo;
• frequently reused project, data, output, or external dependency paths;
• dated progress, decisions, verified conclusions, pitfalls, and current state;
• file maps that prevent repeated repository discovery.

Order dated entries newest first. Keep one section per day and do not rewrite older entries. Record genuine project state, not administrative narration such as “created AGENT.md” unless that change itself matters to the project. Do not invent completed work or future plans.

If the file already exists, preserve history and add or revise only what the user authorized. Follow its established style.

.agent/workspace/<MM.DD>/: temporary artifacts

Place one-off analyses, scratch scripts, generated HTML, raw discussion exports, and other non-product artifacts here. Create the current date directory when the initialization request includes a workspace or when a temporary artifact needs a destination.

README and docs

Do not create a README by default. Reserve README for changing project structure, setup, commands, data locations, and formal outputs when the user asks for it. Reserve docs/ for stable interfaces, schemas, and detailed design specifications.

3. Implement safely

Default structure:

<repo>/
├── CLAUDE.md
├── AGENT.md
└── .agent/
    ├── memory/
    │   └── project_progress.md
    └── workspace/
        └── <MM.DD>/

Follow these rules:

1. Use the exact filename and directory convention requested by the user. Default to AGENT.md and .agent/ for this skill.
2. Create the one-line CLAUDE.md compatibility entry when it is absent. If an existing CLAUDE.md contains substantive rules, preserve and reconcile those rules before replacing it with the delegating stub.
3. Do not create competing root instructions when AGENTS.md or another active guide already exists. Reconcile the convention with the user's request and preserve the authoritative content.
4. Do not delete or rename .claude/ merely because this skill triggered. Migrate it only when the user explicitly requests migration.
5. Before migration, check whether the destination exists. Merge safely instead of overwriting.
6. Update internal references after an authorized rename, including memory and workspace paths.
7. Move temporary artifacts only when their ownership and destination are clear. Confirm the source exists and the destination does not before moving.
8. Avoid copying large datasets, generated outputs, credentials, or user logs into the repository.
9. Preserve the existing language and tone unless the user requests a change. Default to Chinese when the user's request and repository context are Chinese.

Use repository-specific prose. Do not paste a generic template unchanged or copy details from the repository where this skill is stored.

4. Validate the result

Perform documentation-level validation:

1. Confirm the expected files and directories exist and are non-empty where applicable.
2. Confirm root CLAUDE.md delegates to AGENT.md and contains no duplicate policy text.
3. Search hidden files for stale names after an explicit directory migration, such as old .claude/ references.
4. Check that every path mentioned in the new files is intentional. Distinguish currently unavailable external paths from broken repository-relative links.
5. Confirm AGENT.md contains stable preferences rather than a progress dump.
6. Confirm project_progress.md contains no fabricated history and follows newest-first ordering.
7. Run git diff --check when inside Git. Do not run application tests for documentation-only initialization unless another change requires them.
8. Report created, updated, moved, and deliberately untouched files separately.

Minimal content outlines

Use these as outlines, not fixed text.

AGENT.md

# AGENT.md — <项目名> 协作指南

> 每次开工前先读本文件，再读 `.agent/memory/project_progress.md`。

## 1. 项目目标（一句话）
## 2. 协作风格
## 3. 稳定的任务或工程原则
## 4. 开发与数据约定
## 5. 文档与记忆约定

project_progress.md

# 项目进展 — <项目名>

> 最新在最上，旧条目不改写；本文件也保存常用路径，避免重复查找。

## 常用路径速查

## YYYY-MM-DD

### <本阶段主题>

**背景 / 口径 / 结果 / 决策 / 踩坑 / 关键文件地图**

Adapt sections to the repository. Omit empty or irrelevant headings.

Reference examples

Real files from a working repository, useful for judging structure, tone, and the file boundary — study them, do not copy their content:

• references/example-AGENT.md — a concise, stable collaboration contract (goal, collaboration style, task/engineering principles, doc & memory conventions) with no volatile status.
• references/example-project_progress.md — a newest-first progress log that also serves as a path memo (top "常用路径速查" block, then dated sections with background / findings / decisions / pitfalls / file maps).