init-claude

init-claude

Perform the initial setup of Claude Code's .claude/ system in any repository. Configure everything at once: Japanese-language operation, purpose-specific Agents (category splitting), Rules setup, skill introduction, suppression of main consumption through delegation, model allocation, SessionStart hooks, and the operational prerequisites for implement-issue-tree.

For repositories where an existing .claude/ already exists, use update-claude .

Usage

init-claude [対象リポジトリのパス]

If the path is omitted, the current directory is targeted.

Prerequisites

• gh The CLI must be installed and authenticated (confirm withgh auth status )
• In the target repository, git must be initialized
• npx must be available (used for skill introduction vianpx skills add ).skills The CLI is executed with a pinned version (SKILLS_CLI_VERSION). For the value and update procedure, refer to the section "Pinning and Updating the skills CLI Version"
• readlink The command must be available (used to determine whether the workflow js symlink is stale/dangling. Check in advance withcommand -v readlink , and if it is unavailable in the environment, abort the relevant processing)

Flow

Step 1: Investigate the target repository

Identify the root of the target directory and determine the following.

# 言語・フレームワーク検出
ls <target-repo>/
cat <target-repo>/package.json 2>/dev/null || true
cat <target-repo>/Cargo.toml 2>/dev/null || true
cat <target-repo>/pyproject.toml 2>/dev/null || true

# ディレクトリ構成（最大深度 3）
find <target-repo> -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' | head -80

# ビルド・テストコマンドの確認
cat <target-repo>/Makefile 2>/dev/null | head -40 || true
cat <target-repo>/.github/workflows/*.yml 2>/dev/null | head -60 || true

Information to determine through investigation:

• Main languages and frameworks (Rust / TypeScript / Python, etc.)
• Directory structure (crates/ / src/ / packages/, etc.)
• Build command (e.g.,cargo build / npm run build / make )
• Test command (e.g.,cargo test / npm test / pytest )
• Whether an existing .claude/ directory exists

If an existing .claude/ exists, guide the user to the update-claude skill and abort processing.

Step 2: Design a configuration proposal and present it to the user for approval

Design the following configuration proposal based on the investigation results.

Agents design policy

Combine builder Agents for each technical layer with cross-cutting support Agents.

The model tier notation below is an abstract label for following model generation changes. In this Step, when presenting to the user and obtaining approval, finalize the specific model alias for each tier (e.g., top tier=opus or fable, standard tier=sonnet, lightweight tier=haiku; another alias may be used depending on the adopting organization's policy), and reflect the same mapping in the model allocation table of the target repo CLAUDE.md generated in Step 3-1/3-6, and in the model: of each Agent frontmatter generated in Step 3-2.

Category	Agent examples	model tier
research	explorer (cross-codebase investigation), reference-researcher (external specification research)	standard tier
implement	builder per technical layer (e.g., api-builder, web-builder, core-builder)	standard tier
testing	test-runner, e2e-runner	standard tier
quality	reviewer, security-auditor, linter	lightweight tier / standard tier
docs	docs-writer	lightweight tier

• Customize implementation-layer Agents according to the repository's technical layers (e.g., Rust workspace → per-crate builder / TypeScript monorepo → per-package builder)
• Complex cross-cutting decisions and architecture design use the top tier (limited especially to situations requiring large-scale design or complex cross-cutting decisions)
• Investigation, generation, and review use the standard tier
• Mechanical aggregation, frontmatter lint, and documentation updates use the lightweight tier

Rules design policy

Generate the following as standard, and add more according to repository characteristics.

File	Content
delegation.md	Delegation principles and path-based switching for the investigation/design phase
delegation-impl.md	Delegation mapping for the creation/editing phase
coding-<lang>.md	Language-specific coding conventions (Rust / TypeScript / Python, etc.)
security.md	OWASP Top 10 and prevention of secret leakage
japanese-style.md	Japanese output style
conventional-commits.md	Conventional Commits detailed conventions
code-comment-style.md	Comment conventions (embedding role, responsibility, and call context). The conventions (rule) are generated by init-claude, and comments are added and reinforced according to the conventions comment-code(skill) is installed via npx skills add
out-of-scope-tracking.md	Tracking conventions for out-of-scope items (do not leave out-of-scope items unattended)

Skills design policy

npx skills add Fandhe-AI/agent-cli-skills Install the following with.

• create-commit — Conventional Commits commit creation
• create-pr — PR creation
• create-issue — Issue creation
• implement-issue — Single Issue implementation
• implement-issue-tree — Issue tree parallel implementation
• implement-review — Review response
• implement-review-pr — PR review response
• update-docs — CLAUDE.md update
• comment-code — code-comment-style.md Addition and reinforcement of comments and documentation comments according to conventions

hooks design policy

• SessionStart: Japanese, delegation, Conventional Commits,--no-verify prohibition reminders
• PostToolUse: Automatic formatting according to language (Rust: rustfmt / TypeScript: biome or prettier / Python: ruff , etc.)

model allocation table (described in CLAUDE.md)

Purpose	model tier
Complex cross-cutting decisions and architecture design	Top tier
Investigation, generation, implementation, and review	Standard tier
Mechanical aggregation, lint, and documentation updates	Lightweight tier

After presenting the above configuration proposal (Agent list, Rules list, model allocation, hooks, Skills) tothe user and obtaining approval,proceed to the next Step.

Step 3: Generate the full .claude/ set

After approval, generate in the following order. If the target repository does not have dotclaude-via-temp rules (_/dotclaude/ (via), you may write directly to the target repository's .claude/ .

The execution order of substeps is 3-1 (CLAUDE.md skeleton) → 3-2 (agents/) → 3-3 (rules/) → 3-4 (settings.json) → 3-5 (skill installation) → 3-6 (CLAUDE.md finalization) in this order. Since CLAUDE.md references the list of Agents, Rules, and Skills, in 3-1 write only the items already finalized (Overview / Repository Structure, etc.), andSub-agents / Rules / Current Skills each table will be finalized in 3-6 to match the actual entities after 3-2 through 3-5 are complete.

3-1. Generate the outline of CLAUDE.md

In the root of the target repository, CLAUDE.md create the outline. Include the following sections, butSub-agents / Rules / Current Skills shall remain headings only (placeholders) until the actual entities are generated in 3-2 through 3-5, and the content will be finalized in 3-6.

# CLAUDE.md

## Overview
リポジトリの概要（調査結果から生成）

## Repository Structure
ディレクトリ構成ツリー（3〜4階層）

## 委譲方針（必読）
main の役割・パスベース切り替え表・model 配分表

## Sub-agents
（3-1 では見出しのみ。カテゴリ別 Agent 一覧の表は 3-2 完了後に 3-6 で確定する）

## Rules
（3-1 では見出しのみ。ルールファイル一覧の表は 3-3 完了後に 3-6 で確定する）
（標準セット: delegation / delegation-impl / coding-<lang> / security / japanese-style /
  conventional-commits / code-comment-style / out-of-scope-tracking）

## Current Skills
（3-1 では見出しのみ。導入済みスキル一覧は 3-5 完了後に 3-6 で確定する）

## Conventions
Conventional Commits・セキュリティレビュー・日本語出力・ユーザー承認フローなど

## hooks（settings.json）
SessionStart / PostToolUse の説明

3-2. Generate agents/

Create the Agents designed in Step 2 in .claude/agents/<category>/<name>.md . Each Agent has the following frontmatter.

---
name: <name>
description: "<役割の説明>"
model: <Step 2 の model 配分表で確定した tier alias>
tools: [必要最小限のツール]
---

model: write a concrete model alias (e.g., haiku・sonnet・opus・fable), but the value is not a fixed enumeration; choose it from the tier mapping table finalized in Step 2 (top tier / standard tier / lightweight tier → alias). Do not write an alias in the frontmatter that differs from the mapping table (update-claude the 2-1 diagnosis checks consistency with the mapping table).

For the frontmatter keys, follow the Claude Code subagent definition specification and use name (subagent_type is the parameter name when calling the Agent tool, not a definition key).

3-3. Generate rules/

Create the rules designed in Step 2 in .claude/rules/ . delegation.md・delegation-impl.md should be customized to match the path structure of the target repository, referring to the actual example in this repository (Fandhe-AI/agent-cli-skills).

code-comment-style.md と out-of-scope-tracking.md should be generated based on the following template outline, adjusted to match the language and structure of the target repository.

Template outline for code-comment-style.md

# コメント規約

## 目的

後続の読み手（Claude を含む）は渡された情報からしか判断できない。
コメントはパッケージ・サービス・モジュール視点での役割と、他ファイル・他サービスとの
文脈を埋め込み、ファイル単体で文脈が伝わる状態にする。

## 何を書くか

- このファイル・モジュール・関数の役割と責務境界（1〜2行要約をドキュメンテーションコメントで）
- 呼び出し元・呼び出し先の文脈（「〜から呼ばれる」「〜を呼んで〜を返す」）
- 他ファイル・他サービスとの契約（インターフェース・プロトコル・前提条件）
- 非自明な前提・副作用・エラー処理の意図

## 何を書かないか

- コードを読めば分かる逐語説明（`i++  // i をインクリメント` 等）
- 陳腐化しやすい実装詳細の重複（コードと2重に管理しない）

## ドキュメンテーションコメントの形式

言語慣習に従う（Rust: `///`、TypeScript/JavaScript: `/** */`、Python: docstring 等）。
パッケージ・モジュール・公開 API の入口には必ず1〜2行の役割要約を付ける。

Template outline for out-of-scope-tracking.md

# 実装対象外の追跡規約

## 目的

実装・レビュー中にスコープ外と判断した事項を放置しない。
後で埋もれるのを防ぐため、発見したタイミングで Issue に記録して追跡可能にする。

## フロー

1. **検出**: 実装・レビュー中にスコープ外と判断した事項をメモする
2. **既存 Issue の確認**:
   ```bash
   gh issue list --search "${KEYWORD}" --state open

Pass the keyword quoted with "${KEYWORD}" . 3. Obtain approval from the user: Confirm with the user whether to append to an existing Issue or create a new one 4. Record:

• If an existing Issue exists:

gh issue comment "${ISSUE_NUMBER}" --body "$(cat <<'EOF'
（本文をここに記述）
EOF
)"

• If it does not exist: create-issue-tree or create-issue file it under the appropriate parent Issue

1. Record the extraction destination in the original PR/review: Write the Issue number of the extraction destination in a comment or the PR body

Note

• Do not file an Issue on your own without the user's approval
• Do not mix out-of-scope fixes into the current PR (handle them in a separate Issue/PR)

#### 3-4. settings.json を生成する

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '<リポ名>: 日本語でやりとり / 作業は subagent へ委譲し main 消費を抑える (delegation.md, delegation-impl.md) / Conventional Commits 厳守 (--no-verify 禁止) / implement-issue は計画承認後に実装'"
          }
        ]
      }
    ]
  }
}

Propose a PostToolUse auto-formatting hook according to the language, and add it if the user wishes.

Security notes:

• command Do not embed API keys, tokens, or passwords in the value of
• Do not pass user input as-is to command do not expand to

3-5. Introduce skills

cd <target-repo>
# skills CLI (vercel-labs/skills) は固定版でのみ実行する（未固定 npx はレジストリ
# 乗っ取り時の任意コード実行経路になる）。正の定義箇所・更新手順は下記
# 「skills CLI のバージョン固定と更新手順」節を参照。
SKILLS_CLI_VERSION="1.5.23"   # 正の定義箇所。更新手順は下記節を参照
npx --yes "skills@${SKILLS_CLI_VERSION}" add Fandhe-AI/agent-cli-skills || {
  echo "エラー: skills@${SKILLS_CLI_VERSION} の実行が失敗しました（該当版の不存在・レジストリ障害等、原因は問わない）。未固定 npx skills add へのフォールバックは行わない。原因を確認してから再実行する。" >&2
  exit 1
}

skills-lock.json is generated.

3-6. Finalize CLAUDE.md

Based on the actual entities of the Agents, Rules, and introduced skills generated in 3-2 through 3-5, fill in and finalize each table of Sub-agents / Rules / Current Skills that was left as headings only in 3-1 with the actual lists (subagent_type / model / file name / introduced skill name). Do not leave non-existent items listed.

Step 4: Confirm the operational prerequisites of implement-issue-tree

# gh auth と sub_issues API の確認
gh auth status
# sub_issues は issue 番号付き `issues/{n}/sub_issues` のみ有効（リポジトリ直下に
# sub_issues エンドポイントは存在しない）。既存 issue があれば番号を指定して疎通確認する
# （issue が未作成なら gh auth status のみで前提確認とする）
gh api "repos/<owner>/<repo>/issues/<既存issue番号>/sub_issues" 2>&1 | head -5

# workflow js の参照確認（-L で symlink か実体かを判定し、readlink でターゲットも
# EXPECTED_TARGET と比較して stale（向き先が期待と異なる）も検出する）
# readlink の存在を事前確認する。利用できない環境では空の CURRENT_TARGET により
# 正常な symlink を stale と誤判定しうるため、その場合は判定自体を中断する
if ! command -v readlink >/dev/null 2>&1; then
  echo "エラー: readlink コマンドが見つからない。workflow js の stale/dangling 判定を中断する。readlink を導入するか、手動で ls -la <target-repo>/.claude/workflows/implement-issue-tree.js を確認する"
else
  EXPECTED_TARGET="../skills/implement-issue-tree/scripts/implement-issue-tree.js"
  LINK="<target-repo>/.claude/workflows/implement-issue-tree.js"
  if [ -L "$LINK" ]; then
    CURRENT_TARGET="$(readlink "$LINK")"
    echo "symlink 現在のターゲット: $CURRENT_TARGET"
    if [ ! -e "$LINK" ]; then
      echo "警告: dangling symlink（参照先が存在しない）"
    elif [ "$CURRENT_TARGET" != "$EXPECTED_TARGET" ]; then
      echo "警告: stale symlink（期待ターゲット $EXPECTED_TARGET と不一致）"
    fi
  elif [ -e "$LINK" ]; then
    echo "実体ファイルとして存在する（symlink ではない）"
  else
    echo "workflow js が存在しない"
  fi
fi

If any of missing, stale, or dangling is present, guide the user through the following remedies.

How to place/replace workflow js:

named workflow（{name: "implement-issue-tree"}) when not calling as .claude/workflows/ , placing it into scriptPath に .claude/skills/implement-issue-tree/scripts/implement-issue-tree.js of the Workflow tool directly (in either launch method, pass args.skillDir[the absolute path of this skill directory. Example /abs/path/.claude/skills/implement-issue-tree], which indicates where the extracted script is placed. If unspecified in a run other than dryRun, a startup error occurs).

When placing as a named workflow, use cp rather thanrelative symlink .cp If placed with npx skills add will no longer reach the named workflow.

For symlink placement, verify the current target with readlink , and if it differs from the expected target (stale) or the reference destination is missing (dangling), replace it. Do not overwrite real files (non-symlinks).readlink In environments where CURRENT_TARGET is unavailable, stale determination cannot be performed correctly (an emptycommand -v readlink , and if unavailable, abort automatic replacement and guide the user to handle it manually.

if ! command -v readlink >/dev/null 2>&1; then
  echo "エラー: readlink コマンドが見つからない。stale/dangling を正しく判定できないため workflow js の自動張り替えを中断する。readlink を導入するか、手動で symlink の張り替えを行う: ls -la <target-repo>/.claude/workflows/implement-issue-tree.js"
else
  EXPECTED_TARGET="../skills/implement-issue-tree/scripts/implement-issue-tree.js"
  LINK="<target-repo>/.claude/workflows/implement-issue-tree.js"

  if [ -L "$LINK" ]; then
    # 既存 symlink: ターゲット不一致（stale）または参照先消失（dangling）なら張り替える
    if [ "$(readlink "$LINK")" != "$EXPECTED_TARGET" ] || [ ! -e "$LINK" ]; then
      if [ -d "$LINK" ]; then
        # $LINK がディレクトリを指す symlink の場合、mv "$TMP_LINK" "$LINK" は
        # リンク自体を置換せず参照先ディレクトリ内へ TMP_LINK を移動してしまい、
        # 同名ファイルがあればユーザー資産を上書きし得る。安全のため張り替えを拒否する
        echo "エラー: $LINK はディレクトリを指す symlink のため自動では張り替えない。内容を確認し、意図しない参照先であれば手動で削除してから再実行する: ls -la $LINK"
      else
        echo "張り替え前のターゲット: $(readlink "$LINK")"
        # 新リンクを競合しない一時パスへ先に作成し、成功を確認してから mv で
        # 既存リンクを置換する（先に rm すると mkdir/ln 失敗時に旧リンクが失われるため）。
        # create 分岐と同様、過去の失敗で TMP_LINK が残存している場合は上書きせず案内する
        TMP_LINK="<target-repo>/_/dotclaude/workflows/implement-issue-tree.js"
        if [ -e "$TMP_LINK" ] || [ -L "$TMP_LINK" ]; then
          echo "エラー: 過去の失敗などで一時リンク $TMP_LINK が残存している。内容を確認し、意図しない参照先でなければ削除してから再実行する: ls -la $TMP_LINK"
        elif mkdir -p "$(dirname "$TMP_LINK")" && ln -s "$EXPECTED_TARGET" "$TMP_LINK"; then
          if mv "$TMP_LINK" "$LINK"; then   # 既存 symlink はここで初めて置換される（旧リンクは直前まで生存）
            rmdir <target-repo>/_/dotclaude/workflows 2>/dev/null
            rmdir <target-repo>/_/dotclaude 2>/dev/null
          else
            echo "エラー: symlink の置換 (mv) に失敗。一時リンク $TMP_LINK が残存している可能性があるため、内容を確認し必要なら手動で削除してから再実行する: ls -la $TMP_LINK"
          fi
        else
          echo "エラー: 新しい symlink の作成に失敗。既存の symlink は保持される"
        fi
      fi
    fi
  elif [ -e "$LINK" ]; then
    # 実体ファイル: ユーザー資産の可能性があるため上書きせず警告のみ
    echo "実体ファイルが存在するため symlink 化しない。symlink 化するか確認: ls -la $LINK"
  else
    # 不在: 新規作成（張り替え分岐と同様に、一時パスへ先に作成し mkdir/ln の成功を
    # 確認してから mv する。過去の失敗で TMP_LINK が残存している場合は上書きせず案内する）
    TMP_LINK="<target-repo>/_/dotclaude/workflows/implement-issue-tree.js"
    if [ -e "$TMP_LINK" ] || [ -L "$TMP_LINK" ]; then
      echo "エラー: 過去の失敗などで一時リンク $TMP_LINK が残存している。内容を確認し、意図しない参照先でなければ削除してから再実行する: ls -la $TMP_LINK"
    elif mkdir -p "$(dirname "$TMP_LINK")" && ln -s "$EXPECTED_TARGET" "$TMP_LINK" && mkdir -p "$(dirname "$LINK")"; then
      mv "$TMP_LINK" "$LINK"
      rmdir <target-repo>/_/dotclaude/workflows 2>/dev/null
      rmdir <target-repo>/_/dotclaude 2>/dev/null
    else
      echo "エラー: 新しい symlink の作成、または配置先ディレクトリの作成に失敗。$LINK は未作成のまま"
    fi
  fi

  # 設置後チェック: symlink 不在（作成/置換失敗）と dangling（参照先未解決）を区別する
  if [ -L "$LINK" ]; then
    # symlink としては存在する場合のみ resolve 失敗（dangling）を判定する
    [ -e "$LINK" ] || echo "警告: 張り替え後もなお dangling（期待ターゲット自体が未 vendored の可能性）。npx skills add で再取得を案内"
  else
    # symlink 自体が存在しない場合は create/replace 失敗（TMP_LINK 残骸等）が原因のため、
    # npx skills add の再実行では復旧しない。上記のエラーログを確認して原因を解消してから
    # 手動で ln -s するか再実行するよう案内する
    echo "エラー: $LINK に symlink が作成されていない。上記エラーの原因（TMP_LINK 残存・mkdir/ln/mv 失敗等）を解消し、必要なら手動で ln -s $EXPECTED_TARGET $LINK を実行してから再確認する"
  fi
fi

Step 5: Report the generation results

Report items:

• List of generated files (CLAUDE.md, Agents, Rules, settings.json)
• List of introduced skills (npx skills add results)
• Fulfillment status of implement-issue-tree operational prerequisites
• Guidance for the user's next actions (adding PostToolUse hooks, customizing Agents, etc.)

skills CLI version pinning and update procedure

Why: npx skills add Ifskills(vercel-labs/skills) package is taken over, this becomes a path for arbitrary code execution. Pinning to an exact version (X.Y.Z。dist-tag・^/~ ranges are prohibited) becomes the trust anchor.

How to decide the pinned version:

1. npm view skills version Check the current latest with
2. npm view skills repository.url が vercel-labs/skills Confirm that it is
3. npm view skills time --json Confirm that the publication date is not unnatural with

Update procedure:

1. Step 3-5 Within the fence SKILLS_CLI_VERSION update (the only place in this skill where a positive definition is given)
2. node --test skills/init-claude/tests/*.mjs verify exact semver and the pinned execution line
3. Actually run it in one repository and confirm that the diff is normal
4. chore(init-claude): skills CLI を X.Y.Z へ更新 commit with
5. the same skills pin the CLI update-claude / sync-skills-lock It is recommended to also update the section of the same name at the same time (value synchronization is not mandatory, but if they diverge, record that fact in one of the sections)

Known divergence (record): The value of SKILLS_CLI_VERSION in this section (1.5.23）は、sync-skills-lock/SKILL.md・sync-skills-lock/scripts/skills-lock-update.sh the value of SKILLS_CLI_VERSION pinned by (1.5.22) differs from (update-claude is synchronized with the same value as this section). Each skill is operated as an independent pinned version, and synchronization is not mandatory, so this is recorded as an intentional divergence. The next time either is updated, update this line to indicate whether the divergence has been resolved or maintained.

fail-closed: If the pinned version cannot be resolved (for any reason, such as the version not existing or a registry failure), npx exits nonzero and stops. Unpinned npx skills add No fallback retry to is performed.

Verification

# 生成ファイルの一覧確認
find <target-repo>/.claude -type f | sort

# CLAUDE.md の存在確認
ls <target-repo>/CLAUDE.md

# skills-lock.json の存在確認
ls <target-repo>/skills-lock.json

# implement-issue-tree の前提確認
gh auth status

# workflow js の symlink 検証（存在確認だけでなく、ターゲット一致・参照先解決も確認する）
LINK="<target-repo>/.claude/workflows/implement-issue-tree.js"
EXPECTED_TARGET="../skills/implement-issue-tree/scripts/implement-issue-tree.js"
if ! command -v readlink >/dev/null 2>&1; then
  echo "エラー: readlink コマンドが見つからない。symlink ターゲット検証を中断する"
elif [ -L "$LINK" ]; then
  echo "symlink ターゲット: $(readlink "$LINK")（期待値: $EXPECTED_TARGET）"
  [ -e "$LINK" ] && echo "参照先: 解決OK" || echo "参照先: dangling（未解決）"
else
  echo "workflow js: 未配置または非 symlink"
fi

Notes

• If an existing .claude/ exists, abort the process and update-claude guide the user to
• Without the user's approval of the configuration proposal, .claude/ do not start generating
• settings.json の command Do not hardcode tokens or secrets in
• --no-verify Do not set up commands containing
• npx skills add in hooks
• skills Run the CLI with the pinned version. For how to determine the pinned version and the update procedure, see the "skills CLI version pinning and update procedure" section
• Language-specific PostToolUse formatting hooks (rustfmt / biome / prettier / ruff) are proposed after confirming the existence of the tools in the target repository
• Agent の tools List only what is necessary in accordance with the principle of least privilege