Chunks

chunks

Overview

~/.claude/config/chunks.yaml is the user's opt-in switchboard for the guidance-chunk library shipped by config-chunks. Chunks are versioned guidance files; you opt in either by group (a named bundle of chunk slugs) or by an individual chunk slug. This skill toggles entries on that switchboard via the engine script — which is BSD-awk-safe, idempotent, and re-publishes + reconciles after every mutation so the change lands in ~/.claude/chunks/bundle.md immediately — no session restart needed.

targets: selects which host instruction files receive the assembled bundle:

• claude → a marker-wrapped @import line in ~/.claude/CLAUDE.md
• agents → the bundle body inlined into the AGENTS.md target

Omitting targets: auto-detects (CLAUDE.md / AGENTS.md if present).

Never hand-edit chunks.yaml from this skill. The reconciler's parser only accepts block-form YAML; inline form (groups: [recommended]) silently parses to empty and the user's bundle goes wrong without an error.

When to use

• "subscribe me to the recommended chunk group" → add-group recommended
• "unsubscribe from recommended" → remove-group recommended
• "toggle recommended" → toggle-group recommended
• "add the chunk directly" → add-chunk <slug>
• "remove the chunk" → remove-chunk <slug>
• "what chunks am I on" / "list my chunks" → list
• "write the bundle into AGENTS.md too" → add-target agents
• "only maintain CLAUDE.md" → set-targets claude
• "my chunks config feels off" / "diagnose" / "fix my chunks.yaml" → doctor

How to invoke

The engine is scripts/chunks-config.sh, but self-discover its location — do not assume an env var is set, and do not rely on a bare ../../ path (it only resolves when the shell's working directory is this skill directory; Claude Code sets that, but Cursor/Codex and other hosts run from the project root). You know the absolute path of this skill's own directory — it's where you're reading this SKILL.md from. Substitute it for <skill-dir> and run the probe; it binds ENGINE to the first candidate home that exists:

# Substitute <skill-dir> with the ABSOLUTE path of THIS skill directory,
# e.g. /Users/you/.cursor/skills/chunks  (or .../.claude/plugins/.../skills/chunks).
SKILL_DIR="<skill-dir>"

ENGINE=""
for cand in \
  "${CONFIG_CHUNKS_HOME:+$CONFIG_CHUNKS_HOME/scripts/chunks-config.sh}" \
  "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/scripts/chunks-config.sh}" \
  "$SKILL_DIR/../.engines/config-chunks/scripts/chunks-config.sh" \
  "$SKILL_DIR/../../scripts/chunks-config.sh"; do
  [ -n "$cand" ] && [ -f "$cand" ] && { ENGINE="$cand"; break; }
done

if [ -z "$ENGINE" ]; then
  echo "config-chunks engine not found near this skill." >&2
  echo "Fix: re-export with 'python3 scripts/export_skills.py --with-engine', or" >&2
  echo "     set CONFIG_CHUNKS_HOME to the engine home (the dir holding scripts/)." >&2
fi

bash "$ENGINE" <command> [args]

The candidates, in order: an explicit CONFIG_CHUNKS_HOME (set by install.sh / export_skills.py --with-engine), Claude Code's CLAUDE_PLUGIN_ROOT, the --with-engine exported layout (engine is a deterministic sibling at <skill-dir>/../.engines/config-chunks/), then the in-repo / Claude-plugin layout (<skill-dir>/../../). The exported-sibling probe is what lets this skill run on Cursor/Codex with zero env vars. Reuse $ENGINE for every command below.

Commands

All mutations automatically re-publish first-party chunks and run the reconciler so bundle.md and the host files stay up to date.

Step 1 — Resolve the user's intent

Pick the smallest matching command. If the user names something ambiguous ("subscribe me to recommended"), prefer add-group over add-chunk — groups are the canonical opt-in vehicle. Fall back to add-chunk only when the user explicitly references a slug.

For target changes: use add-target when the user wants to add a host file without disturbing the others; use set-targets when they want the target set to be exactly what they named ("only CLAUDE.md").

If the user asks for a status check ("what am I subscribed to", "is chunk X on for me"), use list. If they describe a problem ("my bundle didn't update", "the chunk isn't showing up"), run doctor first.

Step 2 — Run the command

Run the engine via Bash. Capture stdout and stderr.

Step 3 — Report back

Reflect the engine's result in one or two sentences. Quote the relevant line of output (e.g., added: groups += recommended or set-targets: targets = claude agents). If the engine reported already subscribed / not subscribed / already a target, say so plainly — don't pretend a mutation happened.

For doctor, surface every ✗ line verbatim with the recommended fix. For list, summarize: groups subscribed, standalone chunks, active targets, resolved slug count, and any foreign-plugin chunks visible (those are not togglable here).

If doctor reports an inline-form list, do not auto-rewrite the file — tell the user exactly what to change and where. The engine is conservative by design and refuses to mutate a key that is in non-empty inline form.

What this skill does not do

• It does not install or uninstall the plugin itself — that is a marketplace operation.
• It does not toggle foreign-plugin chunks. Those are gated by whether the contributing plugin is installed and publishing; toggling lives at the plugin layer, not here.
• It does not edit ~/.claude/CLAUDE.md or the AGENTS.md target directly — only the reconciler manages the marker-wrapped block / inlined body.