SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsproject-init

project-init

Agents & models

View repository

Updated 10-15 20:10

About this skill

Project Init

Read the global protocol, analyze the project, and generate context.

Workflow

Step 1: Read the global protocol

Read ~/.claude/CLAUDE.md(and the files it @include references), and understand the global collaboration protocol. This is the baseline for generating project context—the format and structure of project documentation should align with the definitions in the global protocol (such as the documentation system, SOP, DECISIONS format, etc.).

Step 2: Read configuration

Read the config/profiles.yamlin this skill's directory to obtain:

  • skill_sources: Skill source repository path
  • profiles: Detection rules and Skill lists for each project type

Step 3: Detect project type

  1. Call scripts/init.sh detect <project_dir> to obtain the list of indicator files.
  2. Evaluate the detect rules in the order defined by profiles in the configuration:
    • any_of: Matches if any file exists
    • has_skill_md: SKILL.md exists in the root directory or the skills/ subdirectory
    • extensions: Number of files with the specified extension >= min_count
    • dir_patterns: Matches if any directory name exists
  3. The first matching profile is the detection result. If none match, use default_profile。

Step 4: Analyze the project

Before generating any files, first analyze the actual project situation:

  • Read package.json / pyproject.toml / Cargo.toml etc. to obtain the tech stack
  • Scan the directory structure to understand the project architecture (src/、app/、lib/ etc.)
  • Read the existing README.md or code to understand the project's purpose
  • Check whether .claude/、CLAUDE.md、docs/ etc. already exist

Summarize this information as the material for subsequently generating context.

Step 5: Present the plan and confirm

Present the detection result and generation plan to the user,must wait for confirmation. If the plan uses a file-based task source, also explain:

  • The name and location of the task file;
  • The Lite、Standard or Strict configuration selected based on risk and complexity, and the rationale;
  • The first batch of real tasks to be written, as well as the merge or skip strategy for existing task files.

Step 6: Create .claude/ and install Skills

mkdir -p .claude/skills/

For each Skill listed in the skills field of the profile, install it via symlink into the project's .claude/skills/ directory by calling the skill-manager Skill. skill-manager will automatically handle path resolution, deduplication, and version tracking.

Step 7: Generate AGENTS.md and CLAUDE.md

Do not copy a template; instead, generate a project-specific AGENTS.md based on the global protocol + project analysis results.

Refer to the structure templates and generation guides for each project type in templates/agents-template.md , combine them with the analysis results from Step 4, generate content containing real project information, and write it to AGENTS.md。

templates/agents-template.md Contains section definitions, structure templates, and desensitized examples for all project types, with no need to refer to other external files.

CLAUDE.md Do not repeat content; only write:

@include ./AGENTS.md

In this way, Claude Code and Codex share the same project protocol, maintaining only one source file.

Already has AGENTS.md show a diff when overwriting, letting the user decide whether to overwrite/merge/skip. If there is already CLAUDE.md but the content is not pure @include , also show a diff.

Step 8: Generate settings.json

Copy assets/claude-settings-template.json verbatim as the project's .claude/settings.json. Skip if it already exists.

Step 9: Create the .codex/ and .agents/ directories

bash scripts/init.sh codex "<project_dir>"
bash scripts/init.sh agents "<project_dir>"

Create the .codex/ directory structure:

  • config.toml: copy from assets/codex-config.toml copy
  • rules/default.rules: copy from assets/codex-default.rules copy
  • skills: symbolic link → ../.claude/skills(shared with .claude/skills/ , not installed separately)

Create the .agents/ directory structure:

  • skills: symbolic link → ../.claude/skills, so that agents following the .agents directory convention discover the same batch of Skills

Skip if either already exists. The directory-level symlink ensures each agent directory shares the same Skill source with .claude/skills/ : when installing or removing a Skill in .claude/skills/ , it syncs automatically, without copying per skill or double-writing links..codex/skills The symlink ensures Codex can directly access the Skills installed in .claude/skills/ .

Step 10: Generate docs/ documentation

Do not copy empty templates; instead generate documents with actual content based on the documentation system definition in the global protocol + the project analysis results.

Read the corresponding document templates as needed, and generate real initial content in combination with the collaborative documentation system chosen by the project; do not copy empty shells or leave placeholders:

  • docs/ROADMAP.md: read templates/roadmap-template.md, extract the vision, status, and phase plan from the README, version, and current implementation
  • docs/DECISIONS.md: read templates/decision-log-template.md, record the initialization decisions and work logs that actually exist, do not fabricate alternatives
  • task list file: create only when the project chooses a file-based task source; read templates/task-template.md, choose a task configuration based on project risk, and generate a real queue and task cards. Do not copy the generation guide verbatim, and do not generate empty sections unrelated to the chosen configuration. The file name and location are determined by the project context
  • docs/ARCHITECTURE.md: read templates/architecture-template.md, generate the initial architecture description from the directory structure, entry points, and tech stack
  • DESIGN.md: for projects containing only the frontend, read templates/design-template.md, and generate in combination with the actual design system and tech stack
  • CHANGELOG.md: when the project needs a changelog and the file does not exist, read templates/changelog-template.md, and generate an initialization record using an explicit version number and date

Task files serve only as the entry point for the current task: long-term direction stays in ROADMAP, important trade-offs stay in DECISIONS, and user-visible history stays in CHANGELOG. After the task is completed and the corresponding documents are synced, remove it from the active area; do not create snapshots,before copies, or dedicated history archives for task files. Create only files that do not exist; when a task file already exists, show a diff and let the user decide whether to merge or skip, do not overwrite directly.

Step 11: Create .gitignore

Copy assets/gitignore-template verbatim as the project's .gitignore. Skip if it already exists.

Step 12: Skill scaffolding (skill-project type only)

bash scripts/init.sh scaffold "<project_dir>" "<skill_name>"

Create references/、scripts/、assets/、SKILL.md、LICENSE.txt。

configuration description

Edit config/profiles.yaml to customize.

resource directory

  • templates/: after reading, select, trim, and fill in combination with project facts; do not copy verbatim, and do not leave placeholders. Files uniformly use *-template.md, to avoid having the same name as the generation target or hitting common Git ignore rules.
  • assets/: No need to load context; copy step by step or script verbatim to the target location; when the target file already exists, follow the idempotency rules.
  • When adding new resources, classify by consumption method, not by file extension. For files that are both text files, those that need to be understood and then generated go into templates/, and fixed content goes into assets/。

Idempotency

Symbolic link with the same target → skip; file already exists → do not overwrite.