codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-build-cc-settings/reference/cbp-conventions.md

@@ -0,0 +1,104 @@
+---
+scope: org-shared
+---
+
+# Settings Authoring Conventions
+
+Read this before creating or updating `.claude/settings.json` or `.claude/settings.local.json`. This file adds CBP-specific constraints on top of the official Claude Code settings spec.
+
+## Two-File Model (CBP Convention)
+
+| File                          | Synced                | Committed       | Contains                                                                                    |
+| ----------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------------------------- |
+| `.claude/settings.json`       | No (git-tracked only) | Yes             | Global + repo-merged: hooks, statusLine, `permissions.deny`, `permissions.ask`, attribution |
+| `.claude/settings.local.json` | No                    | No (gitignored) | Local-only: `permissions.allow` (personal), MCP config, `autoMemoryDirectory`               |
+
+**Runtime precedence:** Claude Code merges both; `settings.local.json` takes precedence for scalars, and arrays concatenate across scopes.
+
+## What Goes Where
+
+| Setting                                 | File                                               | Why                                                     |
+| --------------------------------------- | -------------------------------------------------- | ------------------------------------------------------- |
+| `hooks`                                 | `settings.json`                                    | Team-shared lifecycle scripts                           |
+| `permissions.deny`                      | `settings.json`                                    | Team security baseline — block secrets, destructive ops |
+| `permissions.ask`                       | `settings.json`                                    | Team-shared confirmation gates                          |
+| `permissions.allow`                     | `settings.local.json`                              | Personal — pre-approved commands for your workflow      |
+| `statusLine`                            | `settings.json`                                    | Team-shared status bar                                  |
+| `attribution.commit` / `attribution.pr` | `settings.json`                                    | Policy (CBP = empty strings, no co-author)              |
+| `env` (non-secret)                      | `settings.json`                                    | Team telemetry, feature flags                           |
+| `env` (secrets)                         | Neither — use `.env.local`                         | Never commit secrets                                    |
+| `mcpServers`                            | `settings.local.json`                              | Personal MCP endpoints                                  |
+| `autoMemoryDirectory`                   | `settings.local.json` or `~/.claude/settings.json` | Runtime **rejects** this key from project settings      |
+| `enabledPlugins`                        | `settings.local.json`                              | Personal plugin choice                                  |
+
+## CBP Policy Defaults
+
+These values are part of the CBP baseline and should not be weakened:
+
+```json
+{
+  "attribution": { "commit": "", "pr": "" },
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "deny": ["Bash(rm -rf /:*)", "Bash(rm -rf ~:*)", "Bash(rm -rf /*:*)"],
+    "ask": [
+      "Bash(git reset:*)",
+      "Bash(git clean:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git checkout -- :*)",
+      "Bash(git add .:*)",
+      "Bash(git add -A:*)",
+      "Bash(rm -rf:*)",
+      "Bash(pnpm add:*)",
+      "Bash(pnpm install:*)",
+      "Bash(npm install:*)",
+      "Bash(npm i:*)",
+      "Bash(npx add:*)"
+    ]
+  }
+}
+```
+
+| Rule                                                        | Reason                                             |
+| ----------------------------------------------------------- | -------------------------------------------------- |
+| `attribution.commit` = `""`                                 | No Claude / AI mention in commits (CBP git policy) |
+| `permissions.deny` covers `rm -rf` of root paths            | Catastrophic blast radius                          |
+| `permissions.ask` covers destructive git + package installs | Requires explicit user approval                    |
+
+## File Authority
+
+`settings.json` is git-tracked and local to the repo. Direct edits are the authoritative change — commit changes you want to keep.
+
+`settings.local.json` is never committed. It's yours.
+
+## Required `$schema` Line
+
+Always include:
+
+```json
+{ "$schema": "https://json.schemastore.org/claude-code-settings.json", ... }
+```
+
+Enables editor autocomplete + validation. The published schema lags the CLI, so a warning on a new field is not necessarily invalid.
+
+## When to Use Which Scope
+
+| Goal                                    | Scope                                          |
+| --------------------------------------- | ---------------------------------------------- |
+| Add a team-shared pre-commit hook       | `settings.json`                                |
+| Block a new dangerous Bash pattern      | `settings.json` (`permissions.deny`)           |
+| Pre-approve a command you run often     | `settings.local.json` (`permissions.allow`)    |
+| Point auto-memory at a custom directory | `settings.local.json` (project-scope rejected) |
+| Enable personal plugin                  | `settings.local.json`                          |
+| Add MCP server endpoint                 | `settings.local.json`                          |
+
+## Common Mistakes
+
+| Mistake                                                | Fix                                                |
+| ------------------------------------------------------ | -------------------------------------------------- |
+| Putting `autoMemoryDirectory` in `settings.json`       | Runtime rejects it — move to `settings.local.json` |
+| Personal `permissions.allow` in `settings.json`        | Team doesn't want your personal allowlist          |
+| Committing secrets in `env`                            | Use `.env.local` instead                           |
+| Weakening CBP defaults (removing deny rules)           | Don't — get team sign-off first                    |
+| Adding hooks without `scope:` header in the `.sh` file | Hook file needs `# @scope: org-shared` comment     |

package/templates/skills/cbp-build-cc-settings/reference/permission-rules.md

@@ -0,0 +1,61 @@
+# Permission Rule Syntax
+
+Source: official Claude Code settings and permissions specs.
+
+## Form
+
+```
+Tool            # matches all uses of the tool
+Tool(specifier) # matches uses matching the specifier
+```
+
+Evaluated in order: **deny → ask → allow**. First matching rule wins.
+
+## Quick reference
+
+| Rule | Effect |
+|------|--------|
+| `Bash` | All Bash commands |
+| `Bash(npm run *)` | Commands starting with `npm run` |
+| `Bash(git push *)` | Commands starting with `git push` |
+| `Read` | All file reads |
+| `Read(./.env)` | Read of `.env` in project root |
+| `Read(./.env.*)` | Any `.env.*` file |
+| `Read(./secrets/**)` | Anything under `./secrets/` |
+| `Edit(./build/**)` | Writes under `./build/` |
+| `WebFetch` | All web fetches |
+| `WebFetch(domain:example.com)` | Fetches to example.com |
+| `Agent(Explore)` | Spawning the Explore subagent |
+| `Skill(commit)` | Invoking the commit skill (exact match) |
+| `Skill(review-pr *)` | Invoking review-pr with any args |
+
+## Path conventions
+
+For `Read(...)` and `Edit(...)` specifiers:
+
+| Prefix | Meaning |
+|--------|---------|
+| `./` or no prefix | Project-relative (relative to working dir) |
+| `//` | Absolute path |
+| `~/` | Home directory |
+| `**` | Recursive glob |
+| `*` | Single-segment wildcard |
+
+⚠️ Sandbox filesystem paths use *different* conventions — there, `/path` is absolute. See the sandbox section of the Claude Code settings spec.
+
+## Bash specificity
+
+`Bash(foo *)` matches commands starting with `foo `. It is **not** a full shell parser — it's prefix matching after expansion of `*`. So:
+
+- `Bash(git diff *)` matches `git diff HEAD` but not `git   diff HEAD` (double space)
+- Users can bypass loose patterns with command substitution. Don't rely on Bash patterns for security; use `deny` for hard blocks
+
+## Array merging
+
+`allow`, `ask`, `deny` **merge across scopes** (concatenate + dedupe). Managed + user + project + local all contribute. You cannot remove a higher-scope entry by leaving it off at a lower scope.
+
+## Deny wins
+
+- `deny` > `ask` > `allow`
+- Managed `deny` cannot be weakened by lower scopes
+- Use `deny` for secrets regardless of what any other scope says

package/templates/skills/cbp-build-cc-settings/reference/scope-precedence.md

@@ -0,0 +1,73 @@
+# Scope Precedence & Merging
+
+Source: official Claude Code settings spec — *Settings precedence*.
+
+## Priority order (highest first)
+
+1. **Managed** (server-managed > MDM/OS > file-based > HKCU)
+2. **Command-line flags** (`--permission-mode`, etc.)
+3. **Local project** — `.claude/settings.local.json`
+4. **Shared project** — `.claude/settings.json`
+5. **User** — `~/.claude/settings.json`
+
+## Scalars vs arrays
+
+### Scalars (higher scope WINS outright)
+
+| Example | Effect |
+|---------|--------|
+| `model` | Managed value replaces user value |
+| `defaultMode` | Highest scope wins, no merge |
+| `autoUpdatesChannel` | Highest scope wins |
+| `language` | Highest scope wins |
+
+### Arrays (MERGE: concatenate + dedupe)
+
+| Example | Effect |
+|---------|--------|
+| `permissions.allow` / `ask` / `deny` | All scopes contribute |
+| `sandbox.filesystem.allowWrite` / `denyWrite` / `denyRead` | All scopes merge |
+| `sandbox.network.allowedDomains` / `deniedDomains` | All scopes merge |
+| `allowedHttpHookUrls` | All scopes merge |
+| `httpHookAllowedEnvVars` | All scopes merge |
+| `claudeMdExcludes` | All scopes merge |
+| `companyAnnouncements` | All scopes merge |
+| `additionalDirectories` | All scopes merge |
+
+You cannot *remove* an array entry from a higher scope by omitting it lower.
+
+## Managed-only keys
+
+Some keys are read **only** from managed settings — set in any other scope, they're ignored:
+
+- `allowManagedHooksOnly`
+- `allowManagedMcpServersOnly`
+- `allowManagedPermissionRulesOnly`
+- `allowedChannelPlugins`
+- `channelsEnabled`
+- `blockedMarketplaces`, `strictKnownMarketplaces`
+- `forceRemoteSettingsRefresh`
+- `pluginTrustMessage`
+
+## Project-forbidden keys
+
+Some keys are ignored when placed in `.claude/settings.json` (team-shared) to prevent shared repos from doing hostile things:
+
+- `autoMemoryDirectory` — shared repo cannot redirect memory writes
+- `autoMode` — shared repo cannot reshape the auto-mode classifier
+- `useAutoModeDuringPlan` — not read from shared project settings
+- `skipDangerousModePermissionPrompt` — shared repo cannot auto-bypass
+
+These work from user, local, or managed scope only.
+
+## Verify active settings
+
+```
+/status    # inside a Claude Code session
+```
+
+Shows each active layer, its origin (file / plist / registry / remote), and flags file-parse errors.
+
+## Backups
+
+Claude Code auto-backs-up settings files on change, keeping the last 5 versions.

package/templates/skills/cbp-build-cc-settings/reference/settings-fields.md

@@ -0,0 +1,166 @@
+# settings.json Field Reference
+
+Source: official Claude Code settings spec. Grouped by category. All fields are optional.
+
+## Permissions & modes
+
+| Key | Purpose |
+|-----|---------|
+| `permissions.allow` | Pre-approve tool rules |
+| `permissions.ask` | Force confirmation for these rules |
+| `permissions.deny` | Block these rules outright |
+| `permissions.additionalDirectories` | Extra dirs Claude may touch (no config discovery) |
+| `permissions.defaultMode` | Default permission mode at session start |
+| `disableBypassPermissionsMode` | `"disable"` to prevent `--dangerously-skip-permissions` |
+| `skipDangerousModePermissionPrompt` | Skip the bypass confirmation |
+
+## Hooks
+
+| Key | Purpose |
+|-----|---------|
+| `hooks` | Event → matcher → command mappings |
+| `disableAllHooks` | Kill switch |
+| `allowedHttpHookUrls` | URL allowlist for HTTP hooks |
+| `httpHookAllowedEnvVars` | Env var allowlist HTTP hooks may interpolate |
+| `allowManagedHooksOnly` | Managed-only: only managed/SDK/managed-plugin hooks run |
+
+## Sandbox (mac/linux/WSL2)
+
+| Key | Purpose |
+|-----|---------|
+| `sandbox.enabled` | Turn on sandboxing |
+| `sandbox.failIfUnavailable` | Exit rather than degrade |
+| `sandbox.autoAllowBashIfSandboxed` | Auto-approve Bash when sandboxed |
+| `sandbox.excludedCommands` | Run these outside the sandbox |
+| `sandbox.allowUnsandboxedCommands` | Allow the `dangerouslyDisableSandbox` escape hatch |
+| `sandbox.filesystem.allowWrite` / `denyWrite` / `allowRead` / `denyRead` | Path controls |
+| `sandbox.network.allowedDomains` / `deniedDomains` | Domain allow/deny |
+| `sandbox.network.allowLocalBinding` | Listen on localhost |
+| `sandbox.network.allowUnixSockets` / `allowAllUnixSockets` | Socket policy |
+| `sandbox.network.httpProxyPort` / `socksProxyPort` | BYO proxy ports |
+
+## Attribution
+
+| Key | Purpose |
+|-----|---------|
+| `attribution.commit` | Commit trailer (empty string hides) |
+| `attribution.pr` | PR body attribution (empty string hides) |
+
+## Env & models
+
+| Key | Purpose |
+|-----|---------|
+| `env` | Per-session environment variables |
+| `model` | Override default model |
+| `modelOverrides` | Map model IDs (e.g. Bedrock profile ARNs) |
+| `availableModels` | Restrict which models `/model` exposes |
+| `effortLevel` | Persist effort across sessions |
+| `alwaysThinkingEnabled` | Extended thinking on by default |
+| `showThinkingSummaries` | Show thinking summaries |
+
+## Memory & rules
+
+| Key | Purpose |
+|-----|---------|
+| `autoMemoryEnabled` | Toggle auto memory |
+| `autoMemoryDirectory` | Custom auto-memory path (user/local/policy only) |
+| `claudeMdExcludes` | Glob excludes for CLAUDE.md files |
+
+## Plugins
+
+| Key | Purpose |
+|-----|---------|
+| `enabledPlugins` | `{"plugin@marketplace": true/false}` |
+| `extraKnownMarketplaces` | Extra marketplace sources |
+| `strictKnownMarketplaces` | Managed-only allowlist |
+| `blockedMarketplaces` | Managed-only blocklist |
+| `pluginTrustMessage` | Managed-only trust message |
+
+## MCP
+
+| Key | Purpose |
+|-----|---------|
+| `enableAllProjectMcpServers` | Auto-approve `.mcp.json` servers |
+| `enabledMcpjsonServers` / `disabledMcpjsonServers` | Explicit MCP control |
+| `allowedMcpServers` / `deniedMcpServers` / `allowManagedMcpServersOnly` | Managed-only MCP gating |
+
+## Channels (Team/Enterprise)
+
+| Key | Purpose |
+|-----|---------|
+| `channelsEnabled` | Managed-only switch |
+| `allowedChannelPlugins` | Managed-only allowlist |
+
+## UI / UX
+
+| Key | Purpose |
+|-----|---------|
+| `statusLine` | Custom status line command |
+| `tui` | `"fullscreen"` or `"default"` |
+| `viewMode` | Default transcript view |
+| `spinnerTipsEnabled` / `spinnerTipsOverride` / `spinnerVerbs` | Spinner look |
+| `language` | Preferred response language |
+| `prefersReducedMotion` | Reduce animations |
+| `companyAnnouncements` | Startup banner strings |
+
+## Updates & versions
+
+| Key | Purpose |
+|-----|---------|
+| `autoUpdatesChannel` | `"stable"` or `"latest"` |
+| `minimumVersion` | Floor for updates |
+
+## Fast mode / background tasks
+
+| Key | Purpose |
+|-----|---------|
+| `fastModePerSessionOptIn` | Require opt-in per session |
+| `useAutoModeDuringPlan` | Auto mode during plan mode |
+| `disableAutoMode` | Kill auto mode entirely |
+
+## Sessions & persistence
+
+| Key | Purpose |
+|-----|---------|
+| `cleanupPeriodDays` | Transcript TTL |
+| `feedbackSurveyRate` | Quality survey probability |
+| `awaySummaryEnabled` | Away-return session recap |
+
+## Worktrees (monorepo)
+
+| Key | Purpose |
+|-----|---------|
+| `worktree.symlinkDirectories` | Dirs to symlink (e.g. `node_modules`) |
+| `worktree.sparsePaths` | Sparse-checkout paths |
+
+## Auth & login
+
+| Key | Purpose |
+|-----|---------|
+| `apiKeyHelper` | Script generating API key |
+| `forceLoginMethod` | `"claudeai"` or `"console"` |
+| `forceLoginOrgUUID` | Organization lock |
+| `awsAuthRefresh` / `awsCredentialExport` | Bedrock helpers |
+
+## File suggestion
+
+| Key | Purpose |
+|-----|---------|
+| `fileSuggestion` | Custom `@` autocomplete command |
+| `respectGitignore` | `@` picker respects `.gitignore` |
+
+## Miscellaneous
+
+| Key | Purpose |
+|-----|---------|
+| `agent` | Run main thread as a named subagent |
+| `outputStyle` | Custom output style |
+| `plansDirectory` | Where plans live |
+| `defaultShell` | `"bash"` or `"powershell"` |
+| `disableSkillShellExecution` | Block `!`-command injection |
+| `skipWebFetchPreflight` | Skip WebFetch safety check |
+| `includeGitInstructions` | Include built-in git instructions |
+| `voiceEnabled` | Enable push-to-talk dictation |
+| `sshConfigs` | Desktop SSH connections |
+| `otelHeadersHelper` | Dynamic OTel headers |
+| `disableDeepLinkRegistration` | Block `claude-cli://` protocol handler |

package/templates/skills/cbp-build-cc-settings/templates/settings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(git status *)",
+      "Bash(git diff *)",
+      "Bash(git log *)"
+    ],
+    "deny": [
+      "WebFetch",
+      "Bash(curl *)",
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)"
+    ]
+  },
+  "env": {},
+  "hooks": {},
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  }
+}

package/templates/skills/cbp-build-cc-settings/templates/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(pnpm *)",
+      "Bash(jq *)",
+      "Read(~/.zshrc)"
+    ]
+  }
+}

package/templates/skills/cbp-build-cc-skill/SKILL.md

@@ -0,0 +1,154 @@
+---
+scope: org-shared
+name: cbp-build-cc-skill
+description: Build a Claude Code skill at .claude/skills/{name}/SKILL.md following the official skills spec — frontmatter, supporting files (templates, examples, reference, scripts), invocation control, argument substitution, dynamic context, fork-to-subagent, allowed-tools.
+argument-hint: "[skill-name] [--scope=project|user] [--fork] [--disable-model-invocation]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
+effort: xhigh
+---
+
+# Build Claude Code Skill
+
+Create a Claude Code skill following the official Claude Code skills spec. Uses every feature the runtime supports: frontmatter, supporting files, argument substitution, dynamic context injection, forked subagent execution, pre-approved tools.
+
+**CBP authoring quality** (one-responsibility discipline, pipeline clarity, approval gates, auto-trigger vs wait, command follow-up format; hook warns at 300 lines, blocks at 600): read [reference/cbp-quality.md](reference/cbp-quality.md) before writing.
+
+## Arguments
+
+`$ARGUMENTS` — skill name (kebab-case, required). Flags: `--scope=project|user` (default `project`), `--fork` (add `context: fork`), `--disable-model-invocation` (manual-only).
+
+## When to Use
+
+- You keep pasting the same playbook/checklist into chat
+- A section of CLAUDE.md has grown into a procedure rather than a fact
+- You want a reusable workflow accessible via `/skill-name`
+- You need a step-by-step task that can accept arguments
+
+**Skills vs subagents vs CLAUDE.md** (per official docs):
+
+| Mechanism | Runs in                  | Loads when                  | Use for                                  |
+| --------- | ------------------------ | --------------------------- | ---------------------------------------- |
+| CLAUDE.md | main context             | every session               | Facts Claude needs every conversation    |
+| Skill     | main context (or forked) | on invocation or auto-match | Reusable workflows and prompts           |
+| Subagent  | isolated context         | on delegation               | Self-contained tasks with verbose output |
+
+## Instructions
+
+### Step 1 — Validate inputs
+
+- Name is kebab-case, max 64 chars, lowercase + digits + hyphens only
+- Reject collisions with bundled skills (`/simplify`, `/batch`, `/debug`, `/loop`, `/claude-api`, `/init`, `/review`, `/security-review`)
+- Reject if the skill directory already exists unless the user asked to update
+
+### Step 2 — Pick scope
+
+| Scope   | Path                               | Available to      |
+| ------- | ---------------------------------- | ----------------- |
+| project | `.claude/skills/{name}/SKILL.md`   | This project only |
+| user    | `~/.claude/skills/{name}/SKILL.md` | All your projects |
+
+Default: `project`. Higher priorities (enterprise/personal/project/plugin) are documented for reference but this skill only writes project or user.
+
+### Step 3 — Create the directory structure
+
+```
+{scope-path}/{name}/
+├── SKILL.md            # Required. Main instructions
+├── templates/          # Optional. Copy-and-fill templates
+├── examples/           # Optional. Reference examples
+├── reference/          # Optional. Detailed docs — loaded only when linked
+└── scripts/            # Optional. Executable helpers
+```
+
+Only create subfolders you'll actually fill. Reference each supporting file from `SKILL.md` using relative paths so Claude knows when to load it.
+
+### Step 4 — Classify the skill
+
+Pick the pattern that fits. This drives frontmatter choices:
+
+| Pattern     | Description                                | Frontmatter                                                             |
+| ----------- | ------------------------------------------ | ----------------------------------------------------------------------- |
+| Reference   | Conventions/patterns Claude applies inline | plain `name` + `description`                                            |
+| Task        | Step-by-step action with side effects      | add `disable-model-invocation: true`                                    |
+| Knowledge   | Background context, not actionable         | add `user-invocable: false`                                             |
+| Forked      | Runs in a subagent for isolation           | add `context: fork` + `agent: Explore\|Plan\|general-purpose\|<custom>` |
+| Path-scoped | Only loads when matching files are in play | add `paths: ["glob/**"]`                                                |
+
+Concrete templates: [examples/task-skill.md](examples/task-skill.md), [examples/knowledge-skill.md](examples/knowledge-skill.md), [examples/fork-skill.md](examples/fork-skill.md), [examples/dynamic-context.md](examples/dynamic-context.md).
+
+### Step 5 — Fill the frontmatter
+
+Read `${CLAUDE_SKILL_DIR}/templates/skill.md` as the canonical frontmatter. Fill only the fields you need — every field except `description` is optional, and even `description` falls back to the first markdown paragraph.
+
+Full field table: [reference/frontmatter-fields.md](reference/frontmatter-fields.md).
+
+Key fields by use case:
+
+| Use case                                             | Fields                                                                                                                                                                                                                           |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Manual-only workflow                                 | `disable-model-invocation: true`                                                                                                                                                                                                 |
+| Hide from `/` menu                                   | `user-invocable: false`                                                                                                                                                                                                          |
+| Pre-approve tools                                    | `allowed-tools: Bash(git add *) Bash(git commit *)`                                                                                                                                                                              |
+| Accept arguments                                     | `argument-hint: [file] [mode]`, optionally `arguments: [file mode]` for named `$file`/`$mode`                                                                                                                                    |
+| Set model/effort (always required for plugin skills) | `model: sonnet`, `effort: xhigh` — defaults for plugin skills. Lower (`haiku`/`low` or Opus/`high`) only as a documented exception per [/cbp-build-cc-mode](../build-cc-mode/SKILL.md). `model: inherit` is NOT permitted |
+| Path-scoped auto-load                                | `paths: ["src/api/**/*.ts"]`                                                                                                                                                                                                     |
+| Fork to subagent                                     | `context: fork`, `agent: Explore`                                                                                                                                                                                                |
+
+### Step 6 — Write the body
+
+Structure the markdown body:
+
+1. **Title + one-line purpose**
+2. **Numbered instructions** — concrete, verifiable steps
+3. **Argument substitution** if the skill takes input (see [reference/string-substitutions.md](reference/string-substitutions.md))
+4. **Dynamic context blocks** — see [examples/dynamic-context.md](examples/dynamic-context.md) for both inline and fenced shell-substitution syntax. Disabled globally when settings.json sets `disableSkillShellExecution: true`.
+5. **Additional resources** section linking to supporting files
+
+Keep `SKILL.md` under 500 lines. Push detailed reference to `reference/*.md` and load on demand.
+
+> Note for skill authors: do NOT write the literal bang-backtick or triple-backtick-bang trigger sequences inside prose in your own SKILL.md body — the runtime parses them as shell substitutions during invocation. When documenting the feature, link to an example file (as this skill does) rather than spelling the trigger inline.
+
+### Step 7 — Add supporting files
+
+Reference every supporting file from `SKILL.md` so Claude knows when to read it:
+
+```markdown
+## Additional resources
+
+- Fill the template at [templates/skill.md](templates/skill.md)
+- See [examples/task-skill.md](examples/task-skill.md) for a side-effecting workflow
+- Frontmatter reference: [reference/frontmatter-fields.md](reference/frontmatter-fields.md)
+- Run `bash "${CLAUDE_SKILL_DIR}/scripts/do-work.sh"` for the bundled helper
+```
+
+Scripts are executed, not loaded into context — use them for heavy lifting.
+
+### Step 8 — Validate
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/validate-skill.sh" "{scope-path}/{name}/SKILL.md"
+```
+
+Checks: name matches directory, frontmatter parses, no invalid fields, arg-hint syntax.
+
+### Step 9 — Test
+
+- Live change detection picks up edits within the current session
+- Invoke directly: `/{name}` (if `user-invocable` is not `false`)
+- Ask Claude a question matching the `description` to test auto-invocation
+- Use `/doctor` or `/context` to confirm the skill is discovered
+
+## Integration
+
+- **Triggered by**: user invocation
+- **Reads**: `${CLAUDE_SKILL_DIR}/templates/*.md`, `${CLAUDE_SKILL_DIR}/reference/*.md`
+- **Writes**: `.claude/skills/{name}/**/*` or `~/.claude/skills/{name}/**/*`
+- **Related skills**: `/cbp-build-cc-agent` (forked execution target), `/cbp-build-cc-rule` (for always-loaded constraints), `/cbp-build-cc-settings` (for `disableSkillShellExecution` and permissions on `Skill(name)`), `/cbp-build-cc-mode` (canonical model/effort matrix — audit or apply)
+
+## Key Rules
+
+- Rendered `SKILL.md` content enters the conversation once when invoked and stays until compaction — write standing instructions, not one-time steps
+- Preloaded subagent skills cannot have `disable-model-invocation: true`
+- `context: fork` is only meaningful when the skill body contains an actionable task; otherwise the subagent receives guidelines with no prompt
+- Descriptions front-load key use case: `description` + `when_to_use` cap at 1,536 chars in the skill listing
+- `paths:` scoping applies when Claude reads files matching the globs, not on every tool use

package/templates/skills/cbp-build-cc-skill/examples/dynamic-context.md

@@ -0,0 +1,31 @@
+---
+name: pr-summary
+description: Summarize changes in the current pull request
+context: fork
+agent: Explore
+allowed-tools: Bash(gh *)
+---
+
+## Pull request context
+
+- PR metadata: !`gh pr view --json title,body,author,labels`
+- PR diff: !`gh pr diff`
+- Changed files: !`gh pr diff --name-only`
+- PR comments: !`gh pr view --comments`
+
+## Environment
+
+```!
+node --version
+pnpm --version
+git rev-parse --abbrev-ref HEAD
+```
+
+## Your task
+
+Using the context above, produce a one-page PR summary:
+
+1. **What changed** — 2-3 bullets
+2. **Why it changed** — inferred from PR body and commits
+3. **Risk areas** — files touched that affect shared infrastructure
+4. **Suggested reviewers** — based on CODEOWNERS and recent blame

package/templates/skills/cbp-build-cc-skill/examples/fork-skill.md

@@ -0,0 +1,22 @@
+---
+name: deep-research
+description: Research a topic thoroughly using the Explore agent, without polluting the main conversation with search results.
+context: fork
+agent: Explore
+argument-hint: [topic]
+---
+
+Research $ARGUMENTS thoroughly:
+
+1. Find relevant files using Glob and Grep
+2. Read and analyze the code
+3. Look for related tests, docs, and configuration
+4. Summarize findings with specific file:line references
+
+Return:
+
+- **Summary** — one paragraph
+- **Key files** — list of paths with purpose
+- **Entry points** — where the code is called from
+- **Related tests** — paths to existing coverage
+- **Open questions** — ambiguities worth raising with the user