SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsupdate-claude

update-claude

Agents & models

View repository

Updated 10-15 21:40

About this skill

update-claude

Diagnose the existing .claude/ system, present the differences from the ideal form (Japanese-language operation, category-based Agents, Rules organization, delegation rules, model allocation, SessionStart hooks, implement-issue-tree prerequisites), and after user approval, supplement only the differences. For existing Agents, Rules, and CLAUDE.md,Confirm before overwriting.

.claude/ For repositories that do not have init-claude , use

Usage

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

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

Prerequisites

  • The target repository has a .claude/ directory
  • gh CLI is installed and authenticated (check withgh auth status )
  • npx is available (used for skill completion vianpx skills add ). Theskills CLI is executed with a fixed version (SKILLS_CLI_VERSION). For the value and update procedure, refer to the section "Version Pinning and Update Procedure for the skills CLI"
  • readlink command is available (used to determine whether the workflow js symlink is stale/dangling. Check in advance withcommand -v readlink , and abort the relevant processing in environments where it is unavailable)

Flow

Step 1: Investigate the target repository and the existing .claude/

# .claude/ の存在確認
ls <target-repo>/.claude/ 2>/dev/null || echo ".claude/ が存在しない"

# 既存 Agent の一覧
find <target-repo>/.claude/agents -name "*.md" 2>/dev/null | sort

# 既存 Rules の一覧
find <target-repo>/.claude/rules -name "*.md" 2>/dev/null | sort

# 既存 Skills の一覧
ls <target-repo>/.claude/skills/ 2>/dev/null | sort

# hooks 確認
cat <target-repo>/.claude/settings.json 2>/dev/null || echo "settings.json なし"

# CLAUDE.md の確認
cat <target-repo>/CLAUDE.md 2>/dev/null | head -80 || echo "CLAUDE.md なし"

# skills-lock の確認
cat <target-repo>/skills-lock.json 2>/dev/null | head -30 || echo "skills-lock.json なし"

# implement-issue-tree workflow の確認（-L で symlink 判定し、readlink でターゲットも確認する）
# readlink の存在を事前確認する。利用できない環境では判定を中断する
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 コマンドが見つからない。workflow js の stale/dangling 判定を中断する"
elif [ -L "$LINK" ]; then
  echo "symlink ターゲット: $(readlink "$LINK")（期待値: $EXPECTED_TARGET）"
  [ -e "$LINK" ] || echo "警告: dangling symlink（参照先が存在しない）"
elif [ -e "$LINK" ]; then
  echo "実体ファイルとして存在する（symlink ではない）"
else
  echo "workflow js なし"
fi

.claude/ does not exist, guide the user to init-claude and abort the process.

Step 2: Diagnose the differences from the ideal form

Diagnose the current state from the following perspectives and create a gap list.

2-1. Agent diagnosis

Diagnosis item What to check
Category division Whether there is a category division into research / implement / testing / quality / docs
Builder per technical layer Whether builder Agents corresponding to the repository's technical layers exist
model allocation Whether each Agent's model is consistent with the model allocation table in the target repository's CLAUDE.md (mapping of top tier / standard tier / lightweight tier → alias). If there is no mapping table, record it as a gap
Least privilege Agent の tools Whether the list is the minimum necessary
Delegation Agents Whether there are Agents equivalent to skill-author / agent-author / rules-author / docs-writer

2-2. Rules diagnosis

Diagnosis item What to check
delegation.md Whether there are delegation principles for investigation mode and a path-based switching table
delegation-impl.md Whether there is a delegation mapping for creation/editing mode
coding conventions Whether there are coding conventions corresponding to the repository's main languages
security.md Whether OWASP Top 10 and prevention of secret information leakage are described
japanese-style.md Whether the Japanese output style is described
conventional-commits.md Is there a detailed Conventional Commits specification
code-comment-style.md Is there a comment convention (policy for embedding roles, call context, and responsibility boundaries)
out-of-scope-tracking.md Is there a convention for tracking out-of-scope items (Issue check → user approval → filing flow)

2-3. Skills diagnosis

npx skills add Fandhe-AI/agent-cli-skills Among the skills that can be introduced with skills-lock.json , list those not included in

Required skills (to be supplemented if missing):

  • create-commit・create-pr・create-issue
  • implement-issue・implement-issue-tree
  • implement-review・implement-review-pr
  • update-docs
  • comment-code（code-comment-style.md skill for adding and reinforcing comments according to the convention)

2-4. hooks diagnosis

Diagnosis item Check content
SessionStart Is there a reminder for Japanese, delegation, Conventional Commits, and prohibition of --no-verify
PostToolUse Is there an auto-format hook according to the language

2-5. CLAUDE.md diagnosis

Diagnosis item Check content
Delegation policy Is there a path-based switching table and a model allocation table
Sub-agents list Is there a table of Agents by category
Rules list Is there a table of rule files
Current Skills Is there a list of introduced skills

2-6. implement-issue-tree prerequisite diagnosis

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 の 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 コマンドが見つからない。workflow js の symlink 検証を中断する"
elif [ -L "$LINK" ]; then
  echo "symlink ターゲット: $(readlink "$LINK")（期待値: $EXPECTED_TARGET）"
  [ -e "$LINK" ] || echo "警告: dangling symlink"
else
  echo "workflow js: 未配置または非 symlink"
fi
  • Authentication status of gh auth
  • Response of the sub_issues API (specify an existing issue number. 404 = GitHub Apps may not be enabled. Also, repos/{owner}/{repo}/sub_issues is not used because the endpoint directly under the repository does not exist)
  • Existence of workflow js, target match (whether it is not stale), and reference resolution (whether it is not dangling)

Step 3: Present the gap list to the user and obtain approval

Present the gap list in the following format.

## .claude/ 診断結果

### 不足・追補が必要な項目

#### Agents
- [ ] <カテゴリ>/<Agent名>.md: <不足理由>
- ...

#### Rules
- [ ] delegation.md: 存在しない
- [ ] coding-<lang>.md: 主要言語（<lang>）対応規約が存在しない
- ...

#### Skills（npx skills add で補完可能）
- [ ] <スキル名>: skills-lock.json に含まれていない
- ...

#### hooks
- [ ] SessionStart: settings.json に SessionStart hook がない
- [ ] PostToolUse: <lang> の自動整形フックがない
- ...

#### CLAUDE.md
- [ ] 委譲方針表: パスベース切り替え表がない
- ...

#### implement-issue-tree 前提
- [ ] workflow js: .claude/workflows/implement-issue-tree.js が存在しない
- [ ] workflow js: symlink のターゲットが期待値と異なる（stale。旧パスを指したまま）
- [ ] workflow js: symlink の参照先が消失している（dangling）
- ...

### 既存資産（上書き確認が必要な項目）

以下は既に存在します。変更する場合は個別に確認します。
- <ファイルパス>: <現在の状態の要約>

Do not start supplementation or changes without user approval.

Granularity of approval:

  • "Supplement everything" → proceed to Step 4
  • "Supplement by narrowing down items" → confirm the targets, then proceed to Step 4
  • "When overwriting existing files" → obtain individual confirmation before overwriting

Step 4: Supplement the differences

Supplement only the approved items. Existing files are changedonly for items for which overwrite confirmation was obtained.

4-1. Add missing Agents

.claude/agents/<category>/<name>.md . If the target repo has dotclaude-via-temp Rules (_/dotclaude/ via) exists, follow that rule. If it does not exist, .claude/ may be written to directly.

---
name: <name>
description: "<役割の説明（発火トリガー語を含める）>"
model: <対象リポの model 配分表で確定した tier alias>
tools: [必要最小限のツール]
---

model: write a concrete alias (haiku・sonnet・opus・fable etc., or the value if the destination adopts a different alias) according to the model allocation table in the target repo's CLAUDE.md (the correspondence of top tier / standard tier / lightweight tier → alias checked in the 2-1 diagnosis). If there is no correspondence table, first record it as a gap in Step 2, and add it after deciding the alias (do not write an alias not in the correspondence table directly into frontmatter).

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

4-2. Add missing Rules

.claude/rules/ Add to. delegation.md・delegation-impl.md Customize according to the path structure of the target repository, referring to the examples in Fandhe-AI/agent-cli-skills.

code-comment-style.md と out-of-scope-tracking.md If is missing, init-claude Refer to the template outline described in "3-3. Generate rules/" of the skill and generate it. When generating, adjust it to match the language and structure of the target repository (documentation comment format, directory structure, etc.).

4-3. Supplement missing 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 Confirm that is updated.

4-4. Add hooks

settings.json Add or update the SessionStart hook in.

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

Security notes:

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

Propose the PostToolUse auto-format hook after confirming that the language's tool exists, and add it only if the user wants it.

4-5. Update CLAUDE.md

Add the missing sections (delegation policy table, Sub-agents list, Rules list, model allocation table, Current Skills). When overwriting existing sections, change only approved items.

4-6. Prepare the prerequisites for implement-issue-tree

Guidance when workflow js does not exist:

named workflow（{name: "implement-issue-tree"}), placing it in .claude/workflows/ is itself unnecessary, and you can directly specify scriptPath に .claude/skills/implement-issue-tree/scripts/implement-issue-tree.js of the Workflow tool (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 runs other than dryRun, an error occurs at startup).

When placing it as a named workflow, use cp notrelative symlink .cp If placed with , the symlink is replaced by the actual file, andnpx skills add updates via no longer reach the named workflow.

symlink は readlink Verify the current target with , and if it differs from the expected target (stale) or the reference destination has disappeared (dangling), relink it. Do not overwrite actual files (non-symlinks). If the target repository has a dotclaude-via-temp rule, place it via _/dotclaude/ according to that rule (if not, creating it directly with ln -s is also acceptable).readlink In environments where is unavailable, stale determination cannot be performed correctly (an empty CURRENT_TARGET may cause a valid symlink to be misjudged as stale), and proceeding directly to the relinking process risks unintentionally rewriting an existing symlink, socommand -v readlink Check in advance with , and if it is unavailable, abort automatic relinking and guide the user to handle it manually.

# .claude/workflows/ への配置・張り替え（named workflow として使う場合のみ）
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

If the sub_issues API is unavailable, guide the user to enable GitHub Apps.

Step 5: Report the supplementation results

Report items:

  • List of supplemented files and changes
  • Skipped items and reasons
  • Status of fulfillment of implement-issue-tree's operating prerequisites
  • Guidance on next actions for the user (items requiring manual configuration, etc.)

skills CLI version pinning and update procedure

Why: npx skills add If you run without pinning the version, npx will, if it is not in the local cache, immediately fetch and execute the latest version from the registry at that time without confirmation.skillsIf the (vercel-labs/skills) package is taken over, this becomes a path to arbitrary code execution. Pinning to an exact version (X.Y.Z。dist-tag・^/~ ranges are prohibited) serves as the trust anchor.

How to determine 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/time is not unnatural using etc.

Update procedure:

  1. Step 4-3 Within the fence, SKILLS_CLI_VERSION (the only place in this skill where the positive definition is located is this one place)
  2. node --test skills/update-claude/tests/*.mjs Verify the exact semver and the pinning of the execution line with
  3. Actually run it in one repository and confirm that the diff is normal
  4. chore(update-claude): skills CLI を X.Y.Z へ更新 commit with
  5. It is recommended to also update the same-named section of skills that pins the same init-claude / sync-skills-lock CLI at the same time (synchronizing the values 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 differs from the value of SKILLS_CLI_VERSION pinned by1.5.22) (init-claude is already 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. When updating either one next time, update this line with whether this 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 with a non-zero status and stops. Do not retry by falling back to an unpinned npx skills add .

Verification

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

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

# skills-lock.json の更新確認
cat <target-repo>/skills-lock.json 2>/dev/null | head -20

# implement-issue-tree の前提確認（存在確認だけでなく、ターゲット一致・参照先解決も確認する）
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
gh auth status

Notes

  • .claude/ For repositories where init-claude does not exist, guide the user to
  • Overwriting existing files is performed only after individual approval from the user
  • Do not start changes without the user's approval of the diagnosis
  • settings.json の command do not hardcode tokens/secrets in
  • --no-verify Do not set up commands containing
  • npx skills add If
  • skills Run the
  • If the target repo has a dotclaude-via-temp rule, follow that rule (if not, direct writing is allowed)
  • Agent の tools Following the principle of least privilege, list only the necessary items in the
  • If a security issue (inclusion of confidential information or injection risk) is discovered, interrupt the supplement and warn the user.