docs: spinner verbs + tips personalization — new example + guide section

- New section §3.3 Terminal Personalization Settings (ultimate-guide.md:4978) spinnerVerbs (mode replace/add) + spinnerTipsOverride (excludeDefault) - New examples/config/settings-personalization.json — 19 verbs, 113+ tips, 13 categories - reference.yaml: new spinner_personalization entry + line number fix - CHANGELOG updated Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-28 10:00:58 +01:00 · 2026-02-28 10:00:58 +01:00 · e62af76767
commit e62af76767
parent 88c32c76ac
4 changed files with 404 additions and 7 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -8,6 +8,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ### Added

+- **Terminal Personalization Settings** — documentation `spinnerVerbs` + `spinnerTipsOverride` dans `guide/ultimate-guide.md` §3.3 Settings & Permissions
+  - Nouvelle section "Terminal Personalization Settings" (ligne 4978) : exemples JSON pour `spinnerVerbs` (mode replace/add) et `spinnerTipsOverride` (avec `excludeDefault: true`)
+  - `settings.json` available keys enrichi : ajout `spinnerVerbs`, `spinnerTipsOverride`, `plansDirectory`, `enableAllProjectMcpServers`
+  - Lien vers exemple complet dans la section du guide
+  - Nouveau fichier `examples/config/settings-personalization.json` — 183 lignes, 19 verbes custom, 113+ tips en 13 catégories (Context, Shortcuts, Prompting, Models, Plan Mode, Memory, Golden Rules, MCP, Tasks, CI/CD, Cost, Debug, Remote, Worktrees, Security, Hooks, Agents, Resources)
+  - `machine-readable/reference.yaml` : nouvelle entrée `spinner_personalization` + correction numéro de ligne `permissions_deny_tool_qualified` (4978→5008)
+  - Source : post LinkedIn sur les spinner verbs (évaluation score 3/5, gap confirmé depuis eval #070)
+
+- **Tool-qualified deny format documentation** — nouvelle section dans §3.3 Settings & Permissions (`guide/ultimate-guide.md`)
+  - Table Permission Patterns enrichie : `Read(file_path:*.env*)`, `Edit(file_path:*.pem)`, `Write(file_path:*.key)`, `Bash(command:*rm -rf*)`
+  - Nouvelle section "Tool-qualified deny format" avec exemple complet inspiré de configs production réelles (strangebee, aristote) : syntaxe `Read(file_path:...)` vs format simple `".env"`, glob patterns, note sur la limitation connue `permissions.deny` (GitHub #4160)
+  - Section référence §10.3 Permission Patterns mise à jour avec les 3 nouvelles lignes
+  - Source : analyse comparative de 3 configs `.claude/` production (StrangeBee/TheHive, Méthode Aristote, ccboard)
+
+- **Évaluations de ressources** — 2 nouvelles évaluations dans `docs/resource-evaluations/`
+  - `069-claude-code-best-practice-repo-eval.md` — Évaluation repo `shanraisshan/claude-code-best-practice` (score 4/5) : bug corrigé ligne 5646 (champs officiels agents mal classifiés "community patterns"), patterns intéressants identifiés
+  - `070-claude-code-best-practice-dot-claude-eval.md` — Évaluation config `.claude/` du même repo (score 4/5) : self-evolving agent pattern, Command→Agent→Skills architecture, `allowed-tools` wildcard scoping
+
+### Fixed
+
+- **Bug ligne 5646 `guide/ultimate-guide.md`** — champs frontmatter agents `skills`, `background`, `isolation`, `memory` étaient incorrectement étiquetés "community patterns / not official spec". Remplacés par table officielle complète vérifiée contre `code.claude.com/docs/en/sub-agents`. Champs concernés : `model`, `tools`, `disallowedTools`, `permissionMode`, `maxTurns`, `skills`, `mcpServers`, `hooks`, `memory`, `background`, `isolation`, `color` — tous officiels.
+
+### Changed
+
+- **`ccboard/.claude/settings.json`** — ajout `permissions.deny` avec format tool-qualifié (14 règles) : protection fichiers sensibles (`.env*`, `.pem`, `.key`, `credentials`, `secrets`) et commandes destructives (`rm -rf`, force-push, reset --hard). Config passait de `budget` seul à config de sécurité complète.
+
 - **Boris Cherny / Lenny's Newsletter integration** — 3 insights from Head of Claude Code interview (Feb 19, 2026, Lenny's Newsletter)
  - `guide/ultimate-guide.md` l. 2350 — Ratio empirique "80% Plan Mode" : Boris Cherny démarre ~80% de ses tâches en Plan Mode, blockquote dans la table "When to Use Plan Mode"
  - `guide/ultimate-guide.md` l. 4285 — Nouvelle section "Build for the Model 6 Months Out" dans CLAUDE.md compounding memory : principe stratégique pour concevoir ses workflows en anticipant les modèles futurs
--- a/examples/config/settings-personalization.json
+++ b/examples/config/settings-personalization.json
@ -0,0 +1,183 @@
+{
+  "spinnerVerbs": {
+    "mode": "replace",
+    "verbs": [
+      "Analyzing…",
+      "Thinking…",
+      "Hacking…",
+      "Spellcasting…",
+      "Overthinking…",
+      "Caffeinating…",
+      "Rubber ducking…",
+      "Hallucinating responsibly…",
+      "Reading the docs…",
+      "Pretending to know…",
+      "Indexing…",
+      "Refactoring…",
+      "Debugging…",
+      "Git blaming…",
+      "Stack overflowing…",
+      "Consulting the oracle…",
+      "Writing tests nobody will read…",
+      "Ignoring the linter…",
+      "Compiling excuses…"
+    ]
+  },
+  "spinnerTipsOverride": {
+    "excludeDefault": true,
+    "tips": [
+      "── CONTEXT MANAGEMENT ──────────────────────────────",
+      "Context >70%? Run /compact now — don't wait for slowdowns",
+      "Context >90%? /clear for a fresh start — context is not precious",
+      "Watch Ctx(u): in statusline — it's your most important metric",
+      "/status shows context usage + session cost at any time",
+      "/compact summarizes the conversation and keeps key decisions",
+      "After /compact, re-state your current task so Claude stays aligned",
+      "Ctrl+L clears the screen but keeps the full context intact",
+
+      "── KEYBOARD SHORTCUTS ──────────────────────────────",
+      "Shift+Tab cycles permission modes: Default → AcceptEdits → Plan → back",
+      "Shift+Tab × 2 enters Plan Mode — no files touched until you approve",
+      "Esc × 2 rewinds the last action — your undo button",
+      "Alt+T toggles thinking on/off mid-session — disable for simple tasks",
+      "Ctrl+R searches your command history interactively",
+      "Shift+Enter adds a new line without submitting the prompt",
+      "Ctrl+B opens background tasks panel",
+      "Ctrl+C interrupts Claude mid-response — use before it writes the wrong file",
+
+      "── PROMPTING FORMULA ───────────────────────────────",
+      "Formula: WHAT (deliverable) / WHERE (file paths) / HOW (constraints) / VERIFY (success criteria)",
+      "Bad: 'fix the bug'. Good: 'Fix null check in src/auth.ts:142, HOW: add early return, VERIFY: test passes'",
+      "Use @file.ts to reference a specific file in your prompt",
+      "Use @agent-name to call a custom agent directly",
+      "Use !command to run a shell command inline and include its output",
+      "Negative constraints alone don't work — always give an alternative",
+      "Vague prompts = vague output. One concrete deliverable per prompt.",
+
+      "── MODEL SELECTION ─────────────────────────────────",
+      "Haiku: boilerplate, renames, simple fixes — fast & cheap",
+      "Sonnet: feature dev, debugging, refactoring — your daily driver",
+      "Opus: architecture decisions, security audits, complex reasoning",
+      "OpusPlan: /model opusplan — Opus plans, Sonnet executes (best cost/quality ratio)",
+      "Opus thinking is ON by default at max budget — 'think hard' is cosmetic",
+      "Alt+T disables thinking → faster responses on simple tasks, real savings",
+      "Swap models on task boundaries, not mid-implementation (context loss)",
+      "/model haiku for lint/typo tasks, Opus only when depth truly matters",
+
+      "── PLAN MODE & THINKING ────────────────────────────",
+      "Plan Mode = read-only exploration. Nothing written until you approve.",
+      "Use Plan Mode before any task touching >3 files or production systems",
+      "Shift+Tab × 2 → state the task → review plan → Shift+Tab to execute",
+      "/plan enters Plan Mode, /execute exits it",
+      "In Plan Mode, Claude can read, search, analyze — but not write or edit",
+      "OpusPlan workflow: plan with Opus (deep reasoning) → execute with Sonnet (speed)",
+
+      "── FILE REFERENCES & MEMORY ────────────────────────",
+      "CLAUDE.md at project root = team memory. Commit it. Keep it short.",
+      "~/.claude/CLAUDE.md = your personal global instructions across all projects",
+      "settings.json (committed) = team hooks. settings.local.json (gitignored) = your permissions.",
+      ".claude/agents/ — define reusable AI personas for specialized tasks",
+      ".claude/commands/ — build slash commands for repetitive workflows",
+      ".claude/skills/ — preloaded knowledge modules injected into agent context",
+      ".claude/hooks/ — shell scripts that run on tool events (PreToolUse, PostToolUse…)",
+
+      "── GOLDEN RULES ────────────────────────────────────",
+      "Golden Rule #1: Always read the diff before accepting any change",
+      "Golden Rule #2: /compact before context hits 70% — not after",
+      "Golden Rule #3: Be specific — WHAT, WHERE, HOW, VERIFY every time",
+      "Golden Rule #4: Plan Mode first for complex or risky tasks",
+      "Golden Rule #5: Create CLAUDE.md for every project you care about",
+      "Golden Rule #6: Commit frequently — after each completed task, not at end of day",
+      "Golden Rule #7: Know what's sent to Anthropic — prompts, files, MCP results",
+
+      "── MCP SERVERS ─────────────────────────────────────",
+      "Context7 MCP: official library docs on demand — no more hallucinated APIs",
+      "Sequential MCP: structured multi-step reasoning for complex debugging",
+      "Serena MCP: semantic code indexing + persistent memory across sessions",
+      "grepai MCP: semantic search by intent — 'payment flow' finds it without grep",
+      "Playwright MCP: browser automation built into Claude's tool chain",
+      "/mcp shows the status of all connected MCP servers",
+
+      "── TASK MANAGEMENT ─────────────────────────────────",
+      "Tasks API (v2.1.16+): persistent task lists with dependencies across sessions",
+      "export CLAUDE_CODE_TASK_LIST_ID=project-name → tasks survive /compact and /clear",
+      "TaskCreate → TaskUpdate(in_progress) → TaskUpdate(completed) — the lifecycle",
+      "TaskGet(id) for full description — TaskList shows summary only",
+      "Store key context in task subject — it's visible in TaskList without fetching",
+      "Agent Teams (v2.1.32+): spawn parallel sub-agents with TeamCreate/SendMessage",
+
+      "── CI/CD & AUTOMATION ──────────────────────────────",
+      "claude -p 'query' for non-interactive mode — perfect for CI pipelines",
+      "claude -p --output-format json for structured output in scripts",
+      "claude -p --model haiku --dangerously-skip-permissions for automated fixes",
+      "--max-budget-usd 5.00 caps spending in print mode — use in CI",
+      "Hooks run as shell scripts — exit 0 to continue, exit 2 to block the action",
+
+      "── COST OPTIMIZATION ───────────────────────────────",
+      "Most tasks: Sonnet. Architecture: Opus. Boilerplate: Haiku. Don't overpay.",
+      "OpusPlan pays Opus only for planning (~10-20% of tokens) — Sonnet does the rest",
+      "Thinking disabled = faster + cheaper. Enable only when depth matters.",
+      "/insights shows your usage analytics and cost breakdown by session",
+      "RTK (Rust Token Killer): 60-90% token reduction on CLI operations — brew install rtk-ai/tap/rtk",
+
+      "── DEBUGGING & HEALTH ──────────────────────────────",
+      "claude doctor — built-in diagnostic for common setup issues",
+      "claude --debug — verbose mode showing all tool calls and API requests",
+      "claude --mcp-debug — debug MCP server connections specifically",
+      "/debug inside Claude triggers a systematic troubleshooting checklist",
+      "Hook blocking? Check exit code: 0=continue, 2=block, anything else=continue",
+      "MCP not working? claude mcp list to verify server registration",
+
+      "── REMOTE & MOBILE ─────────────────────────────────",
+      "Remote Control (v2.1.51+, Pro/Max): /rc or claude remote-control → QR code",
+      "Press spacebar after /rc to show the QR code for phone scanning",
+      "/mobile shows App Store + Play Store links for the Claude mobile app",
+      "tmux + multiple panes = multiple independent Claude sessions in parallel",
+      "Remote Control limitation: slash commands (/compact) must run from local terminal",
+
+      "── GIT WORKTREES ───────────────────────────────────",
+      "git worktree add ../project-feat feat — isolated branch, no stashing needed",
+      "Multiple Claude instances on different worktrees = true parallel feature dev",
+      "Rule: one worktree per task — never mix features in the main workspace",
+      "Worktrees don't share stash or index — commit before switching back to main",
+      "Clean up after merge: git worktree remove ../project-feat (then git branch -d feat)",
+      "using-git-worktree skill automates setup + safety checks — /using-git-worktree",
+
+      "── SECURITY & PERMISSIONS ──────────────────────────",
+      "Default mode: every tool requires approval. AcceptEdits: file edits auto-approved.",
+      "--dangerously-skip-permissions skips ALL confirmations — CI/CD only, never interactive",
+      "settings.json (committed) = team-wide permissions. settings.local.json (gitignored) = yours.",
+      "Review .claude/ before trusting a project — hooks run as shell scripts on your machine",
+      "Claude can read your .env — check what's in context before sharing or logging sessions",
+      "Scope your CLAUDE.md with explicit constraints to limit what Claude does autonomously",
+
+      "── HOOKS (ADVANCED) ────────────────────────────────",
+      "PreToolUse: intercept before execution — block dangerous commands, validate inputs",
+      "PostToolUse: react after execution — auto-format, notify, log tool usage",
+      "exit 2 from a hook = blocked with message shown to Claude. exit 0 = continue.",
+      "Hook env vars: CLAUDE_TOOL_NAME and CLAUDE_TOOL_INPUT available in every hook script",
+      "Cost guard pattern: PreToolUse on Read checks file size, warns before loading large files",
+      "Chain hooks: block rm -rf on Bash (PreToolUse) + run linter on Write (PostToolUse)",
+
+      "── CUSTOM AGENTS ───────────────────────────────────",
+      ".claude/agents/agent-name.md — persona + tools injected when @agent-name is called",
+      "Agent frontmatter: name, description, tools (whitelist), system prompt — that's it",
+      "Specialized agents outperform generalist Claude on focused tasks (security, docs, tests)",
+      "Limit tools per agent: a doc-writer agent doesn't need Bash, a reviewer doesn't need Write",
+      "Security reviewer pattern: read-only tools (Read, Grep, Glob) + security-focused prompt",
+      "subagent_type in Agent tool call selects which agent handles a delegated subtask",
+
+      "── RESOURCES & TOOLS ───────────────────────────────",
+      "Full guide (20K lines): cc.bruniaux.com/guide — search before asking Claude",
+      "Whitepapers FR+EN (9 PDFs): florian.bruniaux.com/guides — focused deep dives",
+      "RTK — 60-90% token reduction on CLI ops: rtk-ai.app — brew install rtk-ai/tap/rtk",
+      "ccusage — daily cost tracking & reports: bunx ccusage daily",
+      "ccstatusline — enriched statusline with context%/cost: npx -y ccstatusline@latest",
+      "ccboard — TUI/Web dashboard for session economics: /ccboard skill inside Claude",
+      "claude-code-viewer — browse session history: npx @kimuson/claude-code-viewer",
+      "CHANGELOG.md on GitHub — read it weekly, every feature is documented there",
+      "claude doctor — run this first when something breaks, before debugging manually",
+      "DeepWiki — AI-indexed version of this guide: deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide"
+    ]
+  }
+}
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@ -4903,7 +4903,7 @@ tar -xzf claude-config-YYYY-MM-DD_HH-MM-SS.tar.gz -C ~/

 ### settings.json (Team Configuration)

-This file configures hooks, permissions, environment variables, and more. The project-level `.claude/settings.json` is committed to the repo (shared with team). Available keys include: `hooks`, `env`, `allowedTools`, `autoApproveTools`, `dangerouslyAllowedPatterns`, `teammates`, `teammateMode`, `apiKeyHelper`.
+This file configures hooks, permissions, environment variables, and more. The project-level `.claude/settings.json` is committed to the repo (shared with team). Available keys include: `hooks`, `env`, `allowedTools`, `autoApproveTools`, `dangerouslyAllowedPatterns`, `teammates`, `teammateMode`, `apiKeyHelper`, `spinnerVerbs`, `spinnerTipsOverride`, `plansDirectory`, `enableAllProjectMcpServers`.

 **Hooks example** (most common use in `.claude/settings.json`):

@ -4975,6 +4975,38 @@ Personal permission overrides (gitignored):
 }
 ```

+### Terminal Personalization Settings
+
+Two settings let you customize the text that rotates in the terminal while the agent is working ("Analyzing…", "Prestidigitating…", etc.).
+
+**`spinnerVerbs`** — replaces or extends the action words displayed in the spinner:
+
+```json
+{
+  "spinnerVerbs": {
+    "mode": "replace",
+    "verbs": ["Hacking…", "Spellcasting…", "Overthinking…", "Caffeinating…"]
+  }
+}
+```
+
+Use `"mode": "add"` to extend the default list instead of replacing it.
+
+**`spinnerTipsOverride`** — customizes the tips shown in the spinner. Use `excludeDefault: true` to remove all built-in tips:
+
+```json
+{
+  "spinnerTipsOverride": {
+    "tips": ["Try /compact when context is full", "Use --print for CI pipelines"],
+    "excludeDefault": true
+  }
+}
+```
+
+These go in `~/.claude/settings.json` (personal, not committed) or `.claude/settings.json` (shared with team). Zero functional value — pure UX personalization.
+
+Full example with 80+ guide-derived tips and custom verbs: [`examples/config/settings-personalization.json`](../examples/config/settings-personalization.json)
+
 ### Permission Patterns

 | Pattern | Matches |
@ -4986,6 +5018,33 @@ Personal permission overrides (gitignored):
 | `WebSearch` | Web search capability |
 | `mcp__serena__*` | All Serena MCP tools |
 | `mcp__github__create_issue` | Specific MCP tool (format: `mcp__<server>__<tool>`) |
+| `Read(file_path:*.env*)` | Read matching file paths (tool-qualified format) |
+| `Edit(file_path:*.pem)` | Edit matching file paths (tool-qualified format) |
+| `Write(file_path:*.key)` | Write matching file paths (tool-qualified format) |
+
+**Tool-qualified deny format** — lock down file access by path pattern, not just by tool name:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(command:*rm -rf*)",
+      "Bash(command:*terraform destroy*)",
+      "Read(file_path:*.env*)",
+      "Read(file_path:*.pem)",
+      "Read(file_path:*credentials*)",
+      "Edit(file_path:*.env*)",
+      "Edit(file_path:*.key)",
+      "Write(file_path:*.env*)",
+      "Write(file_path:*.key)"
+    ]
+  }
+}
+```
+
+The `file_path:` prefix matches against the full path argument passed to Read/Edit/Write. Use glob patterns (`*`, `**`). This is more granular than the simple string form (e.g. `".env"`) which only matches exact file names.
+
+> **Defense-in-depth**: `permissions.deny` has a known limitation — background indexing may expose file contents via system reminders before permission checks apply ([GitHub #4160](https://github.com/anthropics/claude-code/issues/4160)). Store secrets outside the project directory for guaranteed protection.

 ### Permission Behavior

@ -5636,14 +5695,32 @@ tools: Read, Write, Edit, Bash, Grep, Glob

 ### Frontmatter Fields

+All official fields supported by Claude Code ([source](https://code.claude.com/docs/en/sub-agents)):
+
 | Field | Required | Description |
 |-------|----------|-------------|
 | `name` | ✅ | Kebab-case identifier |
-| `description` | ✅ | When to activate this agent |
-| `model` | ❌ | `sonnet` (default), `opus`, or `haiku` |
-| `tools` | ❌ | Allowed tools (comma-separated) |
+| `description` | ✅ | When to activate this agent (use "PROACTIVELY" for auto-invocation) |
+| `model` | ❌ | `sonnet` (default), `opus`, `haiku`, or `inherit` |
+| `tools` | ❌ | Allowed tools (comma-separated). Supports `Task(agent_type)` syntax to restrict spawnable subagents |
+| `disallowedTools` | ❌ | Tools to deny, removed from inherited or specified list |
+| `permissionMode` | ❌ | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |
+| `maxTurns` | ❌ | Maximum agentic turns before the subagent stops |
+| `skills` | ❌ | Skills to preload into agent context at startup (full content injected, not just available) |
+| `mcpServers` | ❌ | MCP servers for this subagent — server name strings or inline configs |
+| `hooks` | ❌ | Lifecycle hooks scoped to this subagent (`PreToolUse`, `PostToolUse`, `Stop`) |
+| `memory` | ❌ | Persistent memory scope: `user`, `project`, or `local` |
+| `background` | ❌ | `true` to always run as a background task (default: `false`) |
+| `isolation` | ❌ | `worktree` to run in a temporary git worktree (auto-cleaned if no changes) |
+| `color` | ❌ | CLI output color for visual distinction (e.g., `green`, `magenta`) |

-> **Community patterns**: Some users add extra fields like `skills`, `background`, `isolation`, or `memory` in their agent definitions. These are not part of the official documented spec but may work as conventions passed through to the agent's system prompt. The officially documented fields are `name`, `description`, `tools`, and `model`.
+**Memory scopes** — choose based on how broadly the knowledge should apply:
+
+| Scope | Storage | Use when |
+|-------|---------|----------|
+| `user` | `~/.claude/agent-memory/<name>/` | Cross-project learning |
+| `project` | `.claude/agent-memory/<name>/` | Project-specific, shareable via git |
+| `local` | `.claude/agent-memory-local/<name>/` | Project-specific, not committed |

 ### Model Selection

@ -6210,6 +6287,61 @@ Estimated savings: significant (varies by project)

 ---

+### The Self-Evolving Agent Pattern
+
+An agent that updates its own skills after each execution. Instead of manually maintaining documentation, the agent reads the current state of its domain and rewrites the knowledge injected into itself.
+
+**When to use**: Long-lived agents whose domain evolves — presentation editors, API clients tracking schema changes, agents managing living documents.
+
+**Core mechanism** (in agent system prompt):
+
+```markdown
+### Step N: Self-Evolution (after every execution)
+
+After completing your main task, update your preloaded skills to stay in sync:
+
+1. Read the current state of [the domain you modified]
+2. Update `.claude/skills/<your-skill>/SKILL.md` to reflect reality
+3. Log what changed and why in a "## Learnings" section of this agent file
+
+This prevents knowledge drift between what you know and what is.
+```
+
+**Full example** — a presentation curator agent that keeps its own layout/weight knowledge fresh:
+
+```yaml
+---
+name: presentation-curator
+description: PROACTIVELY use when updating slides, structure, or weights
+tools: Read, Write, Edit, Grep, Glob
+model: sonnet
+color: magenta
+skills:
+  - presentation/slide-structure
+  - presentation/styling
+---
+
+## Step 5: Self-Evolution (after every execution)
+
+Read presentation/index.html and update your skills:
+- slide-structure skill: update section ranges, weight table, slide count
+- styling skill: update CSS patterns if new ones were introduced
+- Append new findings to the "## Learnings" section below
+
+## Learnings
+_Each run appends findings here. Future invocations start informed._
+- Slide badges are JS-injected — never hardcode them in HTML.
+```
+
+**Why it works**: The `skills:` frontmatter injects skill content at agent startup. By writing back to those files after each run, the agent's next invocation starts with current knowledge. No human maintenance required.
+
+**Key constraints**:
+- Scope updates narrowly — only update what actually changed
+- Keep a `## Learnings` log so the agent builds cumulative knowledge over sessions
+- Pair with `memory: project` for cross-session persistence of broader context
+
+---
+
 # 5. Skills

 _Quick jump:_ [Understanding Skills](#51-understanding-skills) · [Creating Skills](#52-creating-skills) · [Skill Template](#53-skill-template) · [Skill Examples](#54-skill-examples)
@ -6340,12 +6472,27 @@ allowed-tools: Read Grep Bash
 |-------|------|-------------|
 | `name` | [agentskills.io](https://agentskills.io) | Lowercase, 1-64 chars, hyphens only, no `--`, must match directory name |
 | `description` | [agentskills.io](https://agentskills.io) | What the skill does and when to use it (max 1024 chars) |
-| `allowed-tools` | [agentskills.io](https://agentskills.io) | Space-delimited list of pre-approved tools (experimental) |
+| `allowed-tools` | [agentskills.io](https://agentskills.io) | Space-delimited list of pre-approved tools. Supports wildcard scoping: `Bash(npm run *)`, `Bash(agent-browser:*)`, `Edit(/docs/**)` |
 | `license` | [agentskills.io](https://agentskills.io) | License name or reference to bundled file |
 | `compatibility` | [agentskills.io](https://agentskills.io) | Environment requirements (max 500 chars) |
 | `metadata` | [agentskills.io](https://agentskills.io) | Arbitrary key-value pairs (author, version, etc.) |
 | `disable-model-invocation` | **CC only** | `true` to make skill manual-only (workflow with side effects) |

+**`allowed-tools` wildcard scoping** — limit a skill to specific command namespaces rather than opening full Bash access:
+
+```yaml
+# Scope to a specific CLI tool only — no other Bash commands allowed
+allowed-tools: Bash(agent-browser:*)
+
+# Scope to npm scripts only
+allowed-tools: Bash(npm run *)
+
+# Read-only + scoped writes
+allowed-tools: Read Grep Glob Edit(/docs/**)
+```
+
+This is more secure than granting broad `Bash` access: the skill can only run commands matching the pattern. Ideal for skills wrapping a specific CLI tool.
+
 > **Open standard**: Agent Skills follow the [agentskills.io specification](https://agentskills.io), created by Anthropic and supported by 30+ platforms (Cursor, VS Code, GitHub, Codex, Gemini CLI, Goose, Roo Code, etc.). Skills you create for Claude Code are portable. The `disable-model-invocation` field is a Claude Code extension.

 ### Validating Skills
@ -19221,6 +19368,9 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102
 | `Write` | All file writes |
 | `WebSearch` | Web search |
 | `mcp__serena__*` | All Serena tools |
+| `Read(file_path:*.env*)` | Block reading any `.env*` file path |
+| `Edit(file_path:*.pem)` | Block editing `.pem` certificates |
+| `Bash(command:*rm -rf*)` | Block destructive bash commands |

 ### CLI Flags Reference

--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@ -4,7 +4,7 @@
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code

 version: "3.29.0"
-updated: "2026-02-23"
+updated: "2026-02-26"

 # ════════════════════════════════════════════════════════════════
 # DEEP DIVE - Line numbers in guide/ultimate-guide.md
@ -282,6 +282,14 @@ deep_dive:
  sync_claude_config_script: "examples/scripts/sync-claude-config.sh"  # Full automation script
  pre_commit_secrets_hook: "examples/hooks/bash/pre-commit-secrets.sh"  # Git hook for secret detection
  settings_local_example: "examples/config/settings.local.json.example"  # Machine-specific overrides template
+  # Tool-qualified deny format (Added 2026-02-26)
+  permissions_deny_tool_qualified: "guide/ultimate-guide.md:5008"  # Permission Patterns table + full example
+  # Terminal personalization (Added 2026-02-27)
+  spinner_personalization: "guide/ultimate-guide.md:4978"  # spinnerVerbs + spinnerTipsOverride settings
+  permissions_deny_tool_qualified_syntax: "Read(file_path:*.env*) | Edit(file_path:*.pem) | Write(file_path:*.key) | Bash(command:*rm -rf*)"
+  permissions_deny_tool_qualified_vs_simple: "file_path: glob matches full path arg; simple '*.env' matches filename only"
+  permissions_deny_known_limitation: "background indexing may expose via system reminders before checks — GitHub #4160"
+  permissions_deny_defense_in_depth: "store secrets outside project dir for guaranteed protection"
  # Visual Reference (ASCII diagrams)
  visual_reference: "guide/visual-reference.md"
  # Architecture internals (guide/architecture.md)
@ -477,6 +485,14 @@ deep_dive:
  agentskills_guide_section: "guide/ultimate-guide.md:6383"
  agentskills_evaluation: "docs/resource-evaluations/agentskills-io-specification.md"
  agentskills_score: "4/5"
+  # claude-code-best-practice repo evaluations (Added 2026-02-26)
+  ccbp_repo_evaluation: "docs/resource-evaluations/069-claude-code-best-practice-repo-eval.md"
+  ccbp_repo_score: "4/5"
+  ccbp_repo_source: "https://github.com/shanraisshan/claude-code-best-practice"
+  ccbp_repo_critical_finding: "bug at guide/ultimate-guide.md:5646 — official agent fields misclassified as community patterns (fixed)"
+  ccbp_dotclaude_evaluation: "docs/resource-evaluations/070-claude-code-best-practice-dot-claude-eval.md"
+  ccbp_dotclaude_score: "4/5"
+  ccbp_dotclaude_patterns: "self-evolving agent, Command→Agent→Skills architecture, allowed-tools wildcard scoping"
  # Skills Marketplace (added 2026-01-23)
  skills_marketplace: 7212
  skills_marketplace_url: "https://skills.sh/"
@ -1204,6 +1220,28 @@ agent_template: |
  ---
  # Instructions here

+# Agent frontmatter — all official fields (verified 2026-02-26 against code.claude.com/docs/en/sub-agents)
+agent_frontmatter_official_fields:
+  name: "display name + /slash-command trigger"
+  description: "trigger description (required for auto-discovery)"
+  model: "sonnet (default) | opus | haiku | inherit"
+  tools: "comma-separated list: Read, Write, Edit, Bash, Grep, Glob, Task(agent_type)..."
+  disallowedTools: "tools to block (array)"
+  permissionMode: "default | acceptEdits | dontAsk | bypassPermissions | plan"
+  maxTurns: "integer — limit agent turns"
+  skills: "skills to preload at startup (full content injected)"
+  mcpServers: "MCP server configs"
+  hooks: "lifecycle hooks (same format as settings.json hooks)"
+  memory: "user | project | local — persistent memory scope"
+  background: "true = always run as background task"
+  isolation: "worktree = temporary git worktree isolation"
+  color: "CLI output color"
+agent_frontmatter_memory_scopes:
+  user: "~/.claude/memory/<agent-name>.md — cross-project"
+  project: ".claude/memory/<agent-name>.md — shared with team"
+  local: ".claude/memory/<agent-name>.local.md — gitignored"
+agent_frontmatter_guide_line: 5639  # Official fields table in ultimate-guide.md
+
 # ════════════════════════════════════════════════════════════════
 # HOOK EVENTS - see deep_dive.hooks
 # ════════════════════════════════════════════════════════════════