From 24647106a741a362a0c080a4b7b80fdff7a268d4 Mon Sep 17 00:00:00 2001 From: Kakeru Nakabach Date: Fri, 19 Jun 2026 19:06:55 +0900 Subject: [PATCH 1/2] feat: add live official-docs cross-check to settings-audit Add a Step 0 that WebFetches the current Claude Code settings/schema/permissions/hooks docs and reconciles them against the static baseline before auditing. Record the doc source per finding and mark doc-dependent findings as 'verification needed' when a fetch fails. Add WebFetch to allowed-tools. --- .../skills/settings-audit/SKILL.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/plugins/claude-code-best-practice/skills/settings-audit/SKILL.md b/plugins/claude-code-best-practice/skills/settings-audit/SKILL.md index c09a9cf..9ec1065 100644 --- a/plugins/claude-code-best-practice/skills/settings-audit/SKILL.md +++ b/plugins/claude-code-best-practice/skills/settings-audit/SKILL.md @@ -2,7 +2,7 @@ name: settings-audit description: "Audit and improve Claude Code settings files (.claude/settings.json, .claude/settings.local.json, ~/.claude/settings.json) against official best practices. Detects missing attribution configuration, bloated permission allowlists, insecure deny-rule gaps, deprecated keys, and ill-scoped hooks; then proposes or applies concrete edits." argument-hint: "[--dry-run] [--scope ] [--lang ]" -allowed-tools: "Read, Edit, Write, Glob, Grep, Bash(git *), Bash(jq *), Bash(cat *), Bash(test *)" +allowed-tools: "Read, Edit, Write, Glob, Grep, WebFetch, Bash(git *), Bash(jq *), Bash(cat *), Bash(test *)" --- # Claude Code Settings Auditor & Fixer @@ -22,6 +22,8 @@ Audit Claude Code settings files against official best practices and apply safe Derived from the upstream `claude-code-best-practice` reference (`best-practice/claude-settings.md`) and the official Claude Code settings docs. +**Always cross-check against the latest official docs at audit time.** The principles below are a static baseline that can drift as keys are deprecated or added. Before auditing, fetch the current docs (see step 0) and reconcile any conflict in favor of the live documentation. If a fetch fails, do not guess — mark the affected finding as "verification needed (docs unreachable)". + ### 1. Use settings.json, not CLAUDE.md, for harness-enforced behavior Settings is deterministic; CLAUDE.md is hint-level. Prefer `attribution.commit: ""` over "NEVER add Co-Authored-By" in CLAUDE.md. Flag CLAUDE.md lines that duplicate what a settings key already enforces. @@ -92,6 +94,19 @@ Implications: ## Steps +### 0. Fetch Latest Official Docs + +Before checking anything, WebFetch the current docs and reconcile them against the static principles above. Fetch at least the settings page; the others as needed: + +- `https://code.claude.com/docs/en/settings` — all available keys, types, scopes, precedence (required) +- `https://json.schemastore.org/claude-code-settings.json` — machine-checkable schema for invalid-key / type-violation detection +- `https://code.claude.com/docs/en/permissions` — permission pattern syntax (required when auditing `allow`/`deny`/`ask`) +- `https://code.claude.com/docs/en/hooks` — hook event/matcher names (required when `hooks` is present) +- `https://code.claude.com/docs/en/cli-reference` — current config CLI flags (only if referencing CLI behavior) +- `https://code.claude.com/docs/en/changelog` — recent deprecations / new keys (only when a key looks ambiguous) + +`docs.claude.com` 301-redirects to `code.claude.com`; follow the redirect and refetch the new URL. Record the page name + cited key for each finding so the report can quote its source. If a fetch fails, proceed with the static baseline but flag every doc-dependent finding as "verification needed (docs unreachable)" rather than asserting it. + ### 1. Discover Settings Files Resolve target paths based on `--scope`: @@ -121,6 +136,7 @@ Apply the anti-pattern table in order. For each violation, record: - current value - proposed value (or `null` for removal) - explanation (one line) +- doc source (page name + key) from step 0, or "verification needed" if unconfirmed Cross-file checks: - Diff `allow` arrays between user + project + local; report duplicates. From b4f731ba0abfd6bc9b2e5f26640e7cb1ef33f33a Mon Sep 17 00:00:00 2001 From: b4tchkn Date: Sat, 20 Jun 2026 19:43:26 +0900 Subject: [PATCH 2/2] fix: quote YAML special chars in SKILL.md frontmatter Multiple bracket groups in argument-hint caused YAML parse errors. Also quoted allowed-tools containing | in semantic-branch. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01SggtVS3REvTDFL9t5CHkgr --- plugins/ccusage-analyzer/skills/analyze-usage/SKILL.md | 2 +- plugins/git-toolbox/skills/pr-auto-update/SKILL.md | 2 +- plugins/git-toolbox/skills/semantic-branch/SKILL.md | 4 ++-- plugins/git-toolbox/skills/semantic-commit/SKILL.md | 2 +- plugins/qa-toolbox/skills/copy-simple-qa-cases/SKILL.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/ccusage-analyzer/skills/analyze-usage/SKILL.md b/plugins/ccusage-analyzer/skills/analyze-usage/SKILL.md index 9934d85..d40d0a7 100644 --- a/plugins/ccusage-analyzer/skills/analyze-usage/SKILL.md +++ b/plugins/ccusage-analyzer/skills/analyze-usage/SKILL.md @@ -1,7 +1,7 @@ --- name: analyze-usage description: Analyze Claude Code usage and costs using ccusage CLI. Provides daily/monthly reports with cost summaries, trend analysis, and optimization insights. -argument-hint: [--monthly] [--session] [--since YYYYMMDD] [--until YYYYMMDD] [--breakdown] +argument-hint: "[--monthly] [--session] [--since YYYYMMDD] [--until YYYYMMDD] [--breakdown]" allowed-tools: Bash(npx ccusage*) --- diff --git a/plugins/git-toolbox/skills/pr-auto-update/SKILL.md b/plugins/git-toolbox/skills/pr-auto-update/SKILL.md index 1edb25b..7e4445e 100644 --- a/plugins/git-toolbox/skills/pr-auto-update/SKILL.md +++ b/plugins/git-toolbox/skills/pr-auto-update/SKILL.md @@ -1,7 +1,7 @@ --- name: pr-auto-update description: Auto-update PR descriptions based on Git change analysis -argument-hint: [--pr ] [--dry-run] [--lang ] +argument-hint: "[--pr ] [--dry-run] [--lang ]" allowed-tools: Bash(git *), Bash(gh *), Read, Grep --- diff --git a/plugins/git-toolbox/skills/semantic-branch/SKILL.md b/plugins/git-toolbox/skills/semantic-branch/SKILL.md index a3eb5c4..3fa9dd3 100644 --- a/plugins/git-toolbox/skills/semantic-branch/SKILL.md +++ b/plugins/git-toolbox/skills/semantic-branch/SKILL.md @@ -1,8 +1,8 @@ --- name: semantic-branch description: Create a semantically named branch from current changes or a given description -argument-hint: [--dry-run] [--lang ] [description] -allowed-tools: Bash(git *), Bash(echo * | pbcopy) +argument-hint: "[--dry-run] [--lang ] [description]" +allowed-tools: "Bash(git *), Bash(echo * | pbcopy)" --- # Semantic Branch diff --git a/plugins/git-toolbox/skills/semantic-commit/SKILL.md b/plugins/git-toolbox/skills/semantic-commit/SKILL.md index a2e1536..4078311 100644 --- a/plugins/git-toolbox/skills/semantic-commit/SKILL.md +++ b/plugins/git-toolbox/skills/semantic-commit/SKILL.md @@ -1,7 +1,7 @@ --- name: semantic-commit description: Split large changes into meaningful minimal units and commit with semantic messages -argument-hint: [--dry-run] [--lang ] +argument-hint: "[--dry-run] [--lang ]" allowed-tools: Bash(git *) --- diff --git a/plugins/qa-toolbox/skills/copy-simple-qa-cases/SKILL.md b/plugins/qa-toolbox/skills/copy-simple-qa-cases/SKILL.md index 3c99705..5f1b9a4 100644 --- a/plugins/qa-toolbox/skills/copy-simple-qa-cases/SKILL.md +++ b/plugins/qa-toolbox/skills/copy-simple-qa-cases/SKILL.md @@ -1,7 +1,7 @@ --- name: copy-simple-qa-cases description: Generate QA test cases from branch diff and PR body for manual testing handoff. Use when the user wants to create test cases, QA checklist, or testing instructions for a pull request. -argument-hint: [--lang en|ja] [PR number] +argument-hint: "[--lang en|ja] [PR number]" disable-model-invocation: true allowed-tools: Bash(git:*), Bash(gh:*), Read, Grep, Glob ---