claude-init

When to use

Use this skill when the task involves creating, updating, or trimming repository-level CLAUDE.md .

It is especially suited to these scenarios:

The existing CLAUDE.md is too long, too broad, or already outdated
The repository only has Cursor, Copilot, Gemini, or AGENTS.md instructions and needs to be migrated to a Claude Code-specific version
Claude repeatedly makes the same kind of avoidable mistake in this repository
The repository workflow has changed and the Claude Code guidance needs to be cleaned up and converged accordingly

Instructions

Treat CLAUDE.md as a living checklist of collaboration constraints, not as codebase documentation.

Core rule: discoverability filter

Before writing each item, first ask:

Could Claude Code discover this information on its own just by reading the repository's README, code, configuration, scripts, and directory structure?

If it can be discovered, do not write it into CLAUDE.md
If it cannot be discovered, and it genuinely affects task success rate, cost, security, or the approval process, then it should be written in

Rewrite for Claude Code

The main output of this skill is CLAUDE.md, not .cursor/rules、.cursorrules、.github/copilot-instructions.md or GEMINI.md。

These files can only serve as migration input. Extract the real intent behind them, then rewrite it into rules suitable for Claude Code; do not copy them item by item according to the files.

Prioritize keeping content that directly changes Claude Code's behavior, such as:

Approval boundaries for high-risk operations
Non-obvious command restrictions or execution prerequisites
Routing rules between modules, directories, and subprojects
Areas that must not be touched casually, and hidden production dependencies
Constraints that apply only under specific tasks but are not made explicit in the code

If the repository already has AGENTS.md, treat it as an input source to absorb. Unless the repository explicitly requires maintaining both formats at the same time, overlapping information should be converged into CLAUDE.md。

If the repository is large, prefer recommending hierarchical CLAUDE.mdsplit by module, rather than cramming everything into a single root-level file.

What content is worth writing in

Only content that satisfies all of the following is worth keeping:

It cannot be discovered directly just from repository files
It genuinely affects execution results, command choices, cost, or security boundaries
It is specific enough for Claude Code to follow directly

Common examples:

Non-standard tool choices that cannot be seen from scripts
Commands that require special parameters, environment variables, or execution order
Approval rules for deletion, release, push, or modification of external systems
Directories or files that are deprecated but still referenced in the production chain
Local team conventions that materially change how Claude collaborates

What content not to write

The following usually should not be put into CLAUDE.md：

Tech stack introductions
Directory structure overviews
Architecture explanations that can be understood by looking directly at the code
Generic best practices
Rules already enforced by lint, typecheck, tests, CI, or other automation
Templated fluff that does not change actual behavior

Which files to check first

Before writing or cleaning up CLAUDE.md , prioritize checking these sources:

Existing CLAUDE.md
Existing AGENTS.md
README.md
PROJECT.md, if any
.claude/ existing project files under the directory, if any
Cursor rule files, such as .cursor/rules/ or .cursorrules
Copilot instruction files, such as .github/copilot-instructions.md
GEMINI.md
CI, workflow, package manager, and task runner configuration, especially when command behavior is inconsistent with intuition

If CLAUDE.md already exists, prioritize incremental improvements rather than rewriting the whole thing right away.

Maintenance mindset

CLAUDE.md is a temporary high-signal collaboration constraint, not a dumping ground for piling up information.

When the same type of problem occurs repeatedly:

First, find a way to fix the root cause in the code, scripts, tests, or automation
Until the root cause disappears, keep only the minimum necessary explanation
Actively delete outdated rules

Pre-finalization check

Before finalizing, go through each item one by one:

Is this information not directly discoverable
Is this information still accurate today
Can this information really reduce errors, waste, or back-and-forth communication

If any item does not hold, delete it.

Minimal `CLAUDE.md` skeleton

This is only a starting point; do not copy it mechanically, but converge according to the actual situation of the repository.

# Scope & routing

# Non-discoverable commands

# Approval boundaries

# Landmines

# Task-specific constraints