# Chunks

> Manage guidance chunks — toggle subscription to chunk groups and standalone chunks in `~/.claude/config/chunks.yaml`, set which host files receive the bundle, or run a doctor check on the config. Use when the user says "/chunks", "list my chunks", "what chunks am I on", "add a chunk group", "opt into a chunk", "subscribe me to <group/chunk>", "unsubscribe from <group/chunk>", "set chunk targets", "diagnose my chunks config", "fix my chunks.yaml", or otherwise wants to change which guidance chunks land in their CLAUDE.md / AGENTS.md bundle. The skill drives the engine script — it never hand-edits YAML.

- Skill: `mnox/chunks` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mnox/chunks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mnox/chunks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mnox (https://skillmd.com/u/mnox)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mnox/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 <slug> chunk directly"* → `add-chunk <slug>`
- *"remove the <slug> 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:

```bash
# 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

| Command | Effect |
|---|---|
| `list` | Show current group/chunk subscriptions, active targets, resolved slug set, and what's available. |
| `doctor` | Ensure the config exists, validate block-form, flag the inline-form footgun, validate targets, list unknown subscriptions, and flag unpublished slugs. |
| `add-group <name>` | Subscribe to a group. Idempotent. |
| `remove-group <name>` | Unsubscribe from a group. Idempotent. |
| `toggle-group <name>` | Flip subscription state for a group. |
| `add-chunk <slug>` | Opt into a standalone chunk (bypasses group membership). |
| `remove-chunk <slug>` | Drop a standalone chunk. |
| `toggle-chunk <slug>` | Flip subscription state for a standalone chunk. |
| `add-target <claude\|agents>` | Add a host target. Idempotent. Only `claude` or `agents` are valid. |
| `set-targets <claude\|agents>...` | Replace the entire target set with the listed values (dedup, order preserved). |

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.