SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsupdate-docs

update-docs

Agents & models

View repository

Updated 10-15 21:40

About this skill

update-docs

Based on code changes, update CLAUDE.md and record it in_/.last-update-docs .

_/.last-update-docs File format

commit_hash=<hash>
commit_subject=<1行目>
commit_date=<ISO 8601>

This file is .gitignore is excluded by this and is local-only.

flow

Step 1: Check the previous update commit

_/.last-update-docs Load commit_hash and obtain . If the file does not exist, treat it as the first run and use the most recent commit as the baseline.

Step 2: Check the changes

git log <commit_hash>..HEAD --oneline
git diff <commit_hash>..HEAD --stat

Understand the changed files and their contents.

Step 3: Update CLAUDE.md

Updating Current Skills

List the skills divided into two groups, and update theCLAUDE.md の ## Current Skills section and the "Repository Management Skills" section respectively.

Group A: Full enumeration of distributable skills (subject to counting)

For upstream repositories (those withskills/ ), enumerate skills/ . For consumer repositories that do not haveskills/ , enumerate .agents/skills/ (including cases where the relevant directory does not exist, treat it as the empty set and do not stop the procedure on a non-zero exit).

# -L で symlink を追従する（skills/<name> や .agents/skills/<name> がディレクトリへの
# symlink の場合でも SKILL.md を取りこぼさないため。classify_b の候補集合も -L 付きで
# 全列挙しており、-L 無しだと系統 A と B1 の計上件数が食い違う）。
if [ -d skills ]; then
  find -L skills -mindepth 2 -maxdepth 2 -name SKILL.md | sed -E 's#^skills/##; s#/SKILL.md$##' | sort
elif [ -d .agents/skills ]; then
  find -L .agents/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sed -E 's#^\.agents/skills/##; s#/SKILL.md$##' | sort
fi
# いずれのディレクトリも無ければ何も出力しない（空集合。エラー終了しない）
  • Update the skill count: ## Current Skills (N)(N is Group A only)
  • Update the comma-separated list of skill names
  • CLAUDE.md に ## Current Skills Create the section anew if it does not exist

Group B: Full enumeration of skills under .claude/skills/ / .agents/skills/ (enumeration target. Whether it is counted depends on the breakdown)

The -L -with find below is a command for enumerating "all skills visible from.claude/skills/ と .agents/skills/ " without omission, and is a different thing from the -L without find .claude/skills ... -type d(extraction of only real directories. Different purpose) mentioned in "Notes" below. For the difference in purpose, refer to the "Notes" section.

# -L で symlink を追従し、.claude/skills/（symlink）と .agents/skills/（実体）の
# 両レイアウトを網羅する。SKILL.md を持つディレクトリのみを抽出し重複排除する。
# （npx skills add は .agents/skills/ に実体を置き .claude/skills/ から symlink する）
find -L .claude/skills .agents/skills -mindepth 1 -maxdepth 1 -type d \
  -exec test -f '{}/SKILL.md' ';' -print 2>/dev/null \
  | sed -E 's#.*/##' | sort -u

find -L Since symlinks are followed with , even if the contents under.claude/skills/ are symlinks, or even if the skill entities are on the .agents/skills/ side, they are not missed (with-type d alone, symlink entries are excluded, so -L is required).-exec test -f '{}/SKILL.md' ';' is not subject to shell re-expansion, so it is safe even if directory names contain spaces, etc.

Each entry of Group B is further classified into 3 categories bythe location of the entity, and whether to include it in the N of## Current Skills (N) is determined by this breakdown (the Group B category itself does not determine countability).

Classification is not determined by the symlink's.claude/skills/<name> itself is a symlink" or "whether.agents/skills/<name> itself is the symlink target".position, such as "whether.claude/skills In a layout (parent symlink type) where the .agents/skills directory itself is a symlink pointing to , the contents under .claude/skills/<name> appears to be a real directory rather than a symlink (a real entity visible through the parent), so a determination that checks for the presence of a symlink does not hold in this layout. Therefore, the criterion is set as ".claude/skills/<name> from cd -P && pwd -P resolves physically to the same location as the physical resolution target ofskills/<name> or .agents/skills/<name> . This method can be determined by the same logic for any of the parent symlink type, child symlink type (.claude/skills/<name> itself is a symlink), or real directory type.

The enumeration source of Family A switches depending on the presence or absence of skills/ (see Step 3, Family A), so the determinations for B1/B3 also branch based on the presence or absence of the skills/ directory itself.Upstream layout（skills/ present. The enumeration source of Family A is skills/）とConsumer-side layout（skills/ absent. The enumeration source of Family A is .agents/skills/) There are two patterns, and which one the match against.agents/skills/<name> is classified into changes.

Category Location of entity Include in N Placement
B1 skills/<name>/（.claude/skills/<name> It has been verified that the physical resolution target of skills/<name> matches the physical resolution target ofIn the consumer-side layout, additionally .agents/skills/<name>/（.claude/skills/<name> It has been verified that the physical resolution target of .agents/skills/<name> matches the physical resolution target of .agents/skills/ is also included in B1 (because the enumeration source of Family A is Include (already counted in the enumeration of Family A. Do not increase or decrease N on the grounds of B1) ## Current Skills (N)
B2 .claude/skills/<name>/ が SKILL.md an entity withskills/<name>/ also in .agents/skills/<name>/ does not also fall underskills-lock.json and is not listed in Do not include "Repository-managed skill (placed in .claude/skills/)"
B3 Upstream layout only: .agents/skills/<name>/ が SKILL.md an entity with.claude/skills/<name> It has been verified that the physical resolution target of .agents/skills/<name> matches the physical resolution target of.claude/skills/<name> either the child symlink type where.claude/skills itself is a symlink, or the parent symlink type whereskills/<name> itself is a symlink).skills/ is positioned as a reference skill that is a separate entity from Do not include "Reference skill (placed in .claude/skills/)"
B4 Misplacement / indeterminable (skills-lock.json real directory listed in , mismatch or unreachability of physical resolution target, symlink to another target,jq not present so tie-break not performed, etc.) Do not include Not described in CLAUDE.md (warning only to stderr. Treated as a configuration problem requiring manual action)

Extraction commands for B1, B2, and B3 (defined as shell functions. Also in the "Verification" section,the same functionTo call, the command body is written here only once). The core of the classification is consolidated into a single classifier classify_b(which outputs exactly one exclusive class per name), andextract_b1・extract_b2・extract_b3 is defined as a thin wrapper that filters that output by category (the Step 3 and Verification sections call these 3 functions). All of them are self-contained scripts with the "Notes" tie-break built into classify_b itself, so that the classification logic and the description of the notes do not contradict each other.Cases that cannot be determined or do not satisfy the conditions are excluded from B1/B2/B3 and warned to stderr (fail-closed). Excluded items are treated as B4 and reconciled using the count consistency equation below:

# 物理パス正規化ヘルパー。symlink（子 symlink 型・親 symlink 型）・実ディレクトリの
# いずれの経路で見えるエントリも `cd -P` で辿った物理パスへ正規化することで、
# symlink の位置に依存しない解決先ベースの判定を可能にする。
# 到達不能（エントリ不在・broken symlink）の場合は空文字列を返す。
resolve() { cd -P -- "$1" 2>/dev/null && pwd -P; }

# classify_b: 系統 B の各名前を B1/B2/B3 のいずれか 1 分類（該当しなければ B4 警告のみ）へ
# 排他的に振り分ける単一分類器。「名前ごとに 1 回だけ判定する」構造で排他性を保証する。
# 出力は "<区分>\t<名前>" 形式（B1/B2/B3 のみ。B4 は stdout に出さず stderr へ WARN する）。
#
# 候補集合: -L 付き全列挙（SKILL.md を持つディレクトリのみ）。「SKILL.md を持たない
# エントリは対象外（B4 にも計上しない）」の既存挙動は、この候補集合の構築自体で維持される。
#
# 判定順序（上から順・排他）:
#   1. .claude/skills/<n> の物理解決先が空（エントリ不在・broken symlink）→ B4 警告
#   2. skills/<n> の物理解決先が非空 かつ 一致 → B1
#   3. skills/<n> の物理解決先が非空 かつ 不一致 → B4 警告（配布実体と解決先不一致）
#   4. .agents/skills/<n> の物理解決先が非空 かつ 一致 →
#        - skills/ ディレクトリが存在する（上流・二重役割レイアウト）→ B3
#          （親 symlink 型・子 symlink 型の双方をこの 1 条件で吸収する。skills/<n> とは
#          別実体の参照スキルという位置づけのため上流レイアウトに限定する）
#        - skills/ ディレクトリが存在しない（消費側レイアウト。系統 A の列挙元は
#          .agents/skills/ そのもの）→ B1（系統 A で既に計上済みの実体へのリンクであり、
#          B3 に分類すると A のカウントと矛盾する）
#   5. .agents/skills/<n> の物理解決先が非空 かつ 不一致 → B4 警告（参照/配布実体と解決先不一致）
#   6. .claude/skills/<n> の物理解決先が .claude/skills 自体の物理解決先直下（.claude/skills/<n>
#      と等価）→ B2 候補 → skills-lock.json タイブレーク（jq 不在→B4／jq exit 0→掲載あり
#      誤配置として B4／exit 1→B2／それ以外→解析失敗として B4。既存の B2 タイブレークをそのまま踏襲）
#   7. 上記いずれにも該当しない（別ターゲットへの symlink 等）→ B4 警告
classify_b() {
  find -L .claude/skills .agents/skills -mindepth 1 -maxdepth 1 -type d \
    -exec test -f '{}/SKILL.md' ';' -print 2>/dev/null \
    | sed -E 's#.*/##' | sort -u |
    while read -r n; do
      p=$(resolve ".claude/skills/${n}")
      if [ -z "${p}" ]; then
        echo "WARN: .claude/skills/${n} から実体へ到達できない（未配置・broken symlink 等。B4 扱い）" >&2
        continue
      fi

      s=$(resolve "skills/${n}")
      if [ -n "${s}" ]; then
        if [ "${p}" = "${s}" ]; then
          printf 'B1\t%s\n' "${n}"
        else
          echo "WARN: .claude/skills/${n} の解決先が skills/${n} と一致しない（B4 扱い）" >&2
        fi
        continue
      fi

      a=$(resolve ".agents/skills/${n}")
      if [ -n "${a}" ]; then
        if [ "${p}" = "${a}" ]; then
          # skills/ が存在しない消費側レイアウトでは .agents/skills/ が系統 A の
          # 列挙元そのものであるため、この一致は B3（参照スキル）ではなく B1
          # （系統 A で計上済みの実体へのリンク）として扱う。B3 のまま倒すと
          # 「A に含める」と「B3 は N に含めない」が矛盾する。
          if [ -d skills ]; then
            printf 'B3\t%s\n' "${n}"
          else
            printf 'B1\t%s\n' "${n}"
          fi
        else
          echo "WARN: .claude/skills/${n} の解決先が .agents/skills/${n} と一致しない（B4 扱い）" >&2
        fi
        continue
      fi

      c=$(resolve ".claude/skills")
      if [ -n "${c}" ] && [ "${p}" = "${c}/${n}" ]; then
        if [ -f skills-lock.json ]; then
          if ! command -v jq >/dev/null 2>&1; then
            echo "WARN: jq が見つからないため ${n} の skills-lock.json タイブレークを判定できない（B4 扱い。jq を導入するか手動確認する）" >&2
            continue
          fi
          jq -e --arg n "${n}" '.skills[$n] != null' skills-lock.json >/dev/null 2>&1
          jq_status=$?
          # jq の終了ステータスは 0=真（掲載あり）/ 1=偽（掲載なし）/ それ以外=実行時
          # エラー（不正な JSON 等）の3値。0/1 以外を「掲載なし」と誤読すると
          # 壊れた skills-lock.json のときに誤配置スキルが素通りして B2 に混入する
          # ため、エラーは fail-closed で B4 に倒す（jq 不在時と同じ扱い）。
          if [ "${jq_status}" = "0" ]; then
            echo "WARN: ${n} は .claude/skills/ が実ディレクトリのまま skills-lock.json に掲載されている（symlink 化検討対象。B4 扱い）" >&2
            continue
          elif [ "${jq_status}" != "1" ]; then
            echo "WARN: skills-lock.json の解析に失敗した（jq exit=${jq_status}）ため ${n} のタイブレークを判定できない（B4 扱い）" >&2
            continue
          fi
        fi
        printf 'B2\t%s\n' "${n}"
        continue
      fi

      echo "WARN: ${n} は skills/ にも .agents/skills/ にも対応する実体がなく、.claude/skills 直下の実体でもない（別ターゲットへの symlink 等。B4 扱い）" >&2
    done
}

extract_b1() { classify_b | awk -F'\t' '$1 == "B1" { print $2 }'; }
extract_b2() { classify_b | awk -F'\t' '$1 == "B2" { print $2 }'; }
extract_b3() { classify_b | awk -F'\t' '$1 == "B3" { print $2 }'; }

This block is resolve・classify_b・extract_b1・extract_b2・extract_b3 の function definitions only, and does not include execution (the "Verification" section assumes this block is used as-is with source . If a function call were included here, listing side effects would run at the time of sourcing, and would be confused with the output during verification).extract_b1/extract_b2/extract_b3 executes classify_b (which internally scans the candidate set) independently on each call, so calling it multiple times outputs the stderr WARN: lines that many times as well (this is allowed as a human-readable explanation of the reason. Count calculation is done by the name-set difference in the "Verification" section, and does not depend on the number of stderr lines). For counting purposes in Step 3, source this block ina separate shellで extract_b2 と extract_b3 and call it (standard output becomes the listing for each section as-is):

extract_b2   # リポジトリ管理スキルの掲載一覧
extract_b3   # 参照スキルの掲載一覧

The classification principle isthe location of the entity as the primary criterionassume that.skills-lock.json の skills . The listing of the key refers only to referenced skills in the upstream repository and to all distributed skills in the consuming repository, and because the meaning is inverted depending on the role of the repository, it is used only for tie-breaking ambiguous cases that cannot be distinguished by the location of the entity alone (for details, see the real-directory-type repository section in "Notes". The B2 command above has this tie-break already implemented, and in environments withoutjq , the tie-break determination itself is not performed and the item is excluded and reported as B4. Fail-closed ensures that cases that cannot be determined are never mistakenly included in B2).

  • CLAUDE.md Update each section of "Repository-managed skills (placed in .claude/skills/)" and "Referenced skills (placed in .claude/skills/)" with B2 and B3
  • If the section does not exist, create it

Count consistency equation (placeholder. Measure each time in the target repository): The counts of lineages A, B1, B2, B3, and B4 change each time the configuration of the target repository changes, so theSKILL.md body has no fixed values. Run the extraction command for each lineage and confirm that the following two equations hold with the measured values.

B4 は stderr の WARN: Do not count the number of items, but obtain it by the difference of name sets （B4 = B − (B1 ∪ B2 ∪ B3), name-based comm calculated by). With a simple sum of counts, when the same name is WARNed in both the B2 and B3 loops for different reasons (e.g., skills-lock.json misplaced skill in a real-directory-type repository that is neither listed nor symlinked) it is double-counted, and conversely cases that "fall under neither B2 nor B3, and are not even scanned by either loop" (.claude/skills/<name> が skills/<name> but also .agents/skills/<name> nor symlinks to another target, etc.) produce no WARN at all and are missed. With a difference of name sets, these cases can also be mechanically recovered as B4, andWARN: is used only as a human-facing reason explanation in combination (see the execution procedure in the "Verification" section below).

Equation Meaning
B1 + B2 + B3 + B4 = B（-L 付き全列挙） The breakdown of Family B (B1/B2/B3/B4) matches the total enumerated count (calculated by the name-set difference ofB4 = B − (B1 ∪ B2 ∪ B3) . Also confirm that B1/B2/B3 are mutually exclusive)
A − B1 = B1 に現れない配布スキル数 Of Family A, .claude/skills/ the number of distributed skills not symlinked to

If the equation does not hold, there is an error in the extraction commands for B2/B3 (including tie-breaking) or in the counting method. If one or more B4 items appear, manually confirm the configuration according to the contents of the corresponding WARN: (symlink creation, re-running tie-breaking, etc.; update-docs itself does not change the configuration). For concrete numerical examples (actual measurement snapshots), refer to references/measurement-example.md (under the same directory as this SKILL.md. These are values specific to the upstream repository agent-cli-skills , and are not the expected values for other repositories).

Updating Repository Structure

Update the structure tree when the following changes occur:

  • .claude/agents/ agent definitions have been added/removed in
  • .claude/rules/ rules have been added/removed in
  • .claude/skills/ workflow skills have been added/removed in

Other Update Targets

  • Changes to the installation method
  • Addition of new conventions
  • Changes to the skill structure (Skill Anatomy)

Step 4: _/.last-update-docs update

git log -1 --format="%H"  # commit_hash
git log -1 --format="%s"  # commit_subject
git log -1 --format="%cI" # commit_date (ISO 8601)

With the acquired information, update _/.last-update-docs :

commit_hash=abc123def456
commit_subject=feat(playwright): Playwright リファレンススキルを追加
commit_date=2026-03-21T10:00:00+09:00

Step 5: Report the update details

Display the list of updated files and the details of the changes.

Verification

After updating, confirm completion with the following.

# CLAUDE.md のスキル数が実ディレクトリ数と一致しているか確認
grep "^## Current Skills" CLAUDE.md
if [ -d skills ]; then
  find -L skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l
elif [ -d .agents/skills ]; then
  find -L .agents/skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l
else
  echo 0
fi
  • ## Current Skills (N) that the N in matches the count
  • That the skills added/removed are reflected in the skill name list
  • _/.last-update-docs that has been updated with the latest commit hash

If Family B (B2/B3) has been updated, also perform the following as anew executionand confirm (reuse of existing logs or previous results is not allowed. If .claude/rules/verification.md exists in the target repository, follow its 5-stage gate).extract_b1・extract_b2・ extract_b3 is the same as the classify_b -based function defined in "Step 3" andidenticalcall (To avoid discrepancies caused by duplicating the command, the function body is not repeated here; source or copy the Step 3 bash block in advance, then execute the following). Exclusivity is classify_b guarantees this with a structure that "judges only once per name", butcomm -12 's exclusivity check is still executed as regression detection against implementation mistakes. While stderr (WARN: lines) is retained as a human-readable reason explanation, B4'scountis calculated by the difference of the following name sets (do not count the number of stderr lines. extract_b1/extract_b2/extract_b3 independently executes classify_b on each call, so the same WARN for the same name may be output redundantly across multiple calls, and the line count is not in itself a basis for the count). Each variable is sed '/^$/d' and must have blank lines removed before being retained (comm compares a variable containing an empty string as a "set containing 1 blank line", so if blank lines are left in and comm -12 is applied, in the case where both are empty sets the blank lines match each other and a false detection of "duplicate exists" occurs):

# B1・B2・B3・全列挙（B）を名前集合として求め、B4 = B − (B1 ∪ B2 ∪ B3) を算出する
# （extract_b1 / extract_b2 / extract_b3 は Step 3 で定義した関数）
# stderr（WARN:）はリダイレクトしない。ここで 2>/dev/null を付けると
# 「WARN は人間向けの理由説明として保持する」という方針に反して破棄されてしまう。
# $(...) はデフォルトで標準出力のみを捕捉するため、変数への代入はこのままで安全であり、
# WARN 行はコマンド実行時にそのまま端末（実際の stderr）へ表示される。
b1=$(extract_b1 | sort -u | sed '/^$/d')
b2=$(extract_b2 | sort -u | sed '/^$/d')
b3=$(extract_b3 | sort -u | sed '/^$/d')
full=$(find -L .claude/skills .agents/skills -mindepth 1 -maxdepth 1 -type d \
  -exec test -f '{}/SKILL.md' ';' -print 2>/dev/null | sed -E 's#.*/##' | sort -u | sed '/^$/d')

union=$(printf '%s\n%s\n%s\n' "${b1}" "${b2}" "${b3}" | sed '/^$/d' | sort -u)
b4=$(comm -23 <(printf '%s\n' "${full}" | sed '/^$/d') <(printf '%s\n' "${union}" | sed '/^$/d'))
printf '%s\n' "${b4}"   # B4 の名前一覧（空なら B4=0）

# B1/B2/B3 が互いに排他か（重複があれば以下のいずれかが空でない出力を返す）。
# `printf '%s\n' "${b1}"` は b1 が空文字列でも改行 1 行を出力してしまうため、
# process substitution 側でも毎回 `sed '/^$/d'` を通す（変数へ保持した時点で
# 空行を除いていても、展開のたびに空行が復活しうる。ここを省くと双方が
# 空集合のケースで空行同士が一致し「重複あり」の誤検出になる）
comm -12 <(printf '%s\n' "${b1}" | sed '/^$/d') <(printf '%s\n' "${b2}" | sed '/^$/d')
comm -12 <(printf '%s\n' "${b1}" | sed '/^$/d') <(printf '%s\n' "${b3}" | sed '/^$/d')
comm -12 <(printf '%s\n' "${b2}" | sed '/^$/d') <(printf '%s\n' "${b3}" | sed '/^$/d')
  • B2's output (stdout) matches CLAUDE.md 's "Repository-managed skills (placed in .claude/skills/)" section
  • B3's output (stdout) matches CLAUDE.md 's "Referenced skills (placed in .claude/skills/)" section
  • B1/B2/B3 exclusivity checks (comm -12 3) all produce empty output (if there are duplicates, there is an error in the tie-breaking of the B2/B3 extraction commands)
  • B1 (already counted in lineage A) + B2 + B3 + B4 (count calculated by name set difference) match-L 's count of all enumerations with
  • b4 is not empty, check the contents of the corresponding WARN: lines and do not include them in any section of CLAUDE.md (B4 is out of scope for documentation)

Notes

  • CLAUDE.md only is the update target. Individual skills' SKILL.md や references/ is out of scope
  • Auto-generated files are out of scope for updates
  • _/.last-update-docs が .gitignore check whether it has been added to
  • .claude/skills/ 's real directory extraction (note that the purpose differs): find .claude/skills -maxdepth 1 -mindepth 1 -type d（-L without) is an extraction command aimed at "real directories that are not symlinks = management skills specific to that repository", but.claude/skills itself is .agents/skills in a layout where it is a symlink pointing to (parent symlink type), all entries under it appear as real directories rather than symlinks, so this command always returns empty and cannot be used for B2 determination. Lineage B classification is classify_b（resolve based on comparison of physical resolution destinations), and-L find without has no purpose. In situations requiring full enumeration, always -L version with (above classify_b candidate set construction command)
  • github-docs handling of etc.: .claude/skills/github-docs(if child symlink type then symlink, if parent symlink type then appears as a real directory) physical resolution target matches .agents/skills/github-docs 's physical resolution target, therefore,classify_b in this repository (skills/ exists in the upstream layout), github-docs・anthropic-claude-code etc. are classified as B3 (reference skills). This is an exclusion from B2 and not an exclusion from CLAUDE.md , and is described in the "Reference skills (placed under .claude/skills/)" section.skills/ on consumer-side layouts that do not have, the same match is treated as B1 (see the classification table above)
  • Behavior in real-directory-type repositories: .claude/skills/<name> are placed as real directories in the repository (.claude/skills are operated as real directories in consumer-side repositories, etc.), if the judgment is made only on whether the entity is directly under .claude/skills/<name> , even externally imported skills will be picked up, and the "repository-managed skills" section may become excessive.classify_b prioritizes matching of physical resolution targets, and regardless of whether it is a real directory or a symlink, breaks ties in the following order:
    1. Physical resolution target matches skills/<name>/ 's physical resolution target → distributed skill (lineage A/B1). Not a repository-managed skill
    2. Physical resolution target matches .agents/skills/<name>/ 's physical resolution target → skills/ only if the directory exists (upstream/dual-role layout), reference skill (B3). skills/ In consumer-side layouts where the directory does not exist, .agents/skills/ is itself the enumeration source for lineage A, so the same match is treated not as B3 but as a distributed skill (lineage A/B1)
    3. skills-lock.json exists but jq cannot be used → undeterminable.jq When absent, skipping the tie-break itself and erroneously including it in B2 violates the fail-closed principle, so it is excluded as B4 (undeterminable) and a warning is sent to stderr
    4. skills-lock.json の skills If the key has a name → misplacement where an externally imported skill has not been symlinked. This is not a repository-managed skill, and is reported as B4 as a configuration problem that should be considered for symlinking (update-docs itself does not change the configuration)
    5. Only entities that do not fall under any of the above are treated as repository-managed skills (B2)
  • B3 resolution-target verification: .agents/skills/<name> Merely having the entity in is not enough to classify as B3. .claude/skills/<name> 's physical resolution target (cd -P normalized absolute path) matches .agents/skills/<name> 's physical resolution target (for parent symlink type, .claude/skills/<name> itself is not a symlink, so "being a symlink" is not made a requirement). If the resolution target does not match/ .claude/skills/<name> If the entity cannot be reached from, it is "unlinked/misplaced as a reference skill" and is excluded as B4, with a warning to stderr (do not mistakenly include it in B3). This B3 determination itself is skills/ The point that it is limited to upstream layouts where the directory exists is described in the above classification table and tie-break list (in consumer-side layouts, the same resolution-target match is treated as B1)
  • Handling of empty output: 2>/dev/null is limited to the purpose of allowing directory absence (e.g., .agents/skills a repository without). Do not immediately judge empty output as "0 items"; first confirm the existence of the target directory itself

Perspective on in-code comments (optional)

Guidelines to apply when comment reinforcement is requested. Implement as work independent of CLAUDE.md synchronization.

Basic policy

Comments describe not "what it does" but "the role of the target in this package/service." Since subsequent readers (including Claude) can judge only from the information passed to them, make the following perspectives explicit.

  • Perspective from the caller — what this symbol provides to the caller
  • Perspective from the callee — the relationship with external services/modules that this symbol depends on
  • Context with other files and other services — its positioning in the same process or adjacent services

Points for description

  • Not implementation details (algorithm steps), butrole, responsibility, boundariesstate
  • Do not repeat information obvious from variable names/types. Supplement information that lets readers grasp the context without opening another file
  • Public APIs (exported functions, types, constants) must always have comments. Private symbols only when complex
  • In inter-service communication or event-driven locations, specify which events/endpoints are connected

Reference destination for detailed conventions

For details of comment style (format, language, length, prohibitions), follow the target repository's .claude/rules/code-comment-style.md . If that file does not exist, match the existing comment style of the target repository.