@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.2

package/skills/releasing/references/deprecations.md

@@ -0,0 +1,60 @@
+# Deprecation Process
+
+When removing a feature, changing a convention, or making a breaking change:
+
+1. Add entry to `deprecations.yml` in the Plastic source root
+2. Set severity: `info` (awareness), `warning` (action needed), `critical` (urgent)
+3. Provide clear migration steps
+4. Set `removal` version at least 2 minor versions ahead
+5. SessionStart hook displays active deprecations automatically
+6. Remove the feature AND the deprecation entry together
+
+## Pre-1.0 removal policy
+
+The numbered process above is the steady-state rule: a deprecation rides until its `removal`
+version, which step 4 sets at least two minors ahead. While Plastic is still pre-1.0 (any
+version below `1.0.0`), one exception applies:
+
+- **Pre-1.0 exception.** Before `1.0.0`, a *satisfied* deprecation (the migration it
+  announced is complete on installed machines) may be removed immediately, rather than waiting
+  for its declared `removal` major. Delete the entry from `deprecations.yml` (leaving
+  `deprecations: []` if it was the last one) the moment the migration is done.
+
+This exception only holds below `1.0.0`. From `1.0.0` onward, the steady-state grace rule
+(step 4, removal at least two minors ahead) governs again, unchanged. The exception narrows
+*when* a satisfied entry may be pulled early during the pre-release line; it does not loosen
+the grace window for the released-product contract.
+
+## Severity Levels
+
+| Severity | When to use | Dismissable? |
+|----------|-------------|--------------|
+| `info` | Upcoming change | Yes |
+| `warning` | Action needed | Yes (re-shown at removal) |
+| `critical` | Urgent/security | Never |
+
+## deprecations.yml Schema
+
+```yaml
+deprecations:
+  - id: unique-slug
+    severity: info | warning | critical
+    summary: "One-line description"
+    migration_steps:
+      - "Step 1"
+      - "Step 2"
+    introduced: "0.9.0"
+    removal: "1.0.0"
+    link: "optional URL"
+```
+
+## Dismissal
+
+Users dismiss by adding the id to `deprecations_dismissed` in `config.yml`:
+
+```yaml
+deprecations_dismissed:
+  - some-deprecated-feature
+```
+
+Critical deprecations and final-version warnings ignore dismissal.

package/skills/research/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:research
+name: plastic-research
 description: "Research a topic for the active intent. Agent decides shallow vs deep based on scope. Produces reports in the intent's resources/ directory."
 ---
 
@@ -14,7 +14,7 @@ Investigate a topic related to the active intent. Choose the right depth, produc
 Before proceeding, resolve the active intent:
 
 1. **Detect store:** Read `~/.plastic/projects.yml`, match CWD against registered project paths. If match → project store at `~/.plastic/projects/{slug}/store/`. If no match → global store at `~/.plastic/store/`.
-2. **Find active intent:** Read `INDEX.md` from the detected store. Look under `## Active`. If exactly one → use it. If multiple → ask which. If none → refuse: "No active intent. Create one first with /plastic:creating-intent"
+2. **Find active intent:** Read `INDEX.md` from the detected store. Look under `## Active`. If exactly one → use it. If multiple → ask which. If none → refuse: "No active intent. Create one first with /plastic-creating-intent"
 3. **Resolve intent directory:** `{store}/store/{id}--{slug}/`
 
 ## Depth Decision

package/skills/savepoint/SKILL.md

@@ -1,57 +1,66 @@
 ---
-name: plastic:savepoint
-description: Use when context is being compacted (PreCompact hook), user says "save" or "savepoint", or before ending a session. Saves the active intent's state so work can resume after /clear.
+name: plastic-savepoint
+description: Use when verifying or repairing an intent's savepoint ledger, when the user says "save" or "savepoint", or when a PreCompact hook fires. The ledger is written automatically by the gate hook at each lifecycle boundary; this skill only reads, verifies, and rebuilds it.
 ---
 
 # Savepoint
 
-## When to Use
-- PreCompact hook fires (automatic)
-- User says "save", "savepoint", or "save progress"
-- Before ending a long session
-- Before switching to a different intent
+`savepoint.md` is a deterministic, append-only ledger of an intent's cycle steps, one line
+per lifecycle milestone, newest at the bottom:
 
-## Workflow
+```
+2026-06-16T14:02Z  What  34--cycle-step-savepoints.md
+2026-06-16T14:20Z  Why   spec.md created
+2026-06-16T15:10Z  How   plan.md created
+2026-06-16T15:11Z  How   checklist.md created
+2026-06-16T16:40Z  Exec  outcome.md created
+```
 
-### 1. Find Active Intent(s)
-Read `~/.plastic/INDEX.md` (or the project INDEX.md) and extract all intents listed under `## Active`.
+It is **sugar on top of the conventions**, not a source of truth. The gate hook
+(`hook-gate-check`) writes each line automatically when a stage file is created, so there is
+nothing to save by hand. State is always derivable from files-on-disk; the ledger just lets
+a resuming agent read the cycle's succession from one glance (last line = where we are).
 
-### 2. For Each Active Intent
-Read the intent directory at `~/.plastic/store/ID--slug/`:
+## When to Use
+- A PreCompact hook fires, or the user says "save" / "savepoint": verify the ledger is current.
+- Resuming an intent: read the ledger to learn the cycle's succession quickly.
+- The ledger looks stale, empty, or missing: rebuild it from the filesystem.
 
-**a. Update checklist.md** (if exists):
-- Check off completed items
-- Add any new items discovered during the session
+## What this skill does NOT do
+- It does not write prose, "in progress", "next step", or "blockers". The old 50%-context
+  prose savepoint is retired. The semantic trace lives in `## Insights` (append-only,
+  newest at the bottom); the byte history lives in git.
 
-**b. Create/update savepoint.md:**
-```markdown
-# Savepoint
+## Workflow
 
-## Last Updated
-{{DATE}} — Session #{{N}}
+### 1. Find Active Intent(s)
+Read the active store's `INDEX.md` and extract intents under `## Active`.
 
-## In Progress
-- (what was being worked on when savepoint triggered)
-- Next: (immediate next step)
+### 2. For Each Active Intent — verify the ledger
+- Read `savepoint.md`. Confirm it exists and is non-empty.
+- Confirm the **last line's stage** matches the stage derived from files-on-disk
+  (`Bridge.derive_stage`). If they disagree, or the file is missing/empty, the ledger has
+  drifted.
 
-## Blockers
-(any blockers or open questions)
+### 3. Rebuild on drift
+Reconstruct from the filesystem rather than hand-editing:
 
-## Key Discoveries This Session
-- (important things learned)
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e \
+  'Bridge.rebuild_savepoint("<intent_dir>")'
 ```
 
-**c. Update `{ID}--{slug}.md`:**
-- Add observations to `## Insights` section
-
-### 3. Update INDEX.md
-Verify the `## Active` section is accurate.
+This rewrites `savepoint.md` from the milestone files present (timestamps from mtimes),
+in stage order. Safe to run anytime: the ledger is derived.
 
-### 4. Commit
+### 4. Commit (store only)
+If a rebuild changed the ledger, commit it in the store repo:
 ```bash
-git add .plastic/
-git commit -m "chore: savepoint — [active intent name]"
+cd <store-root> && git add . && git commit -m "chore: rebuild savepoint ledger — [intent]"
 ```
+Never push `~/.plastic/`.
+
+## References
 
-### 5. Notify User
-Tell the user: "Context is getting large. I've saved progress to intent [ID] — [name]. Please run `/clear` and say `continue` to resume."
+- Read `references/context-management.md` for the full save/continue protocol and how the
+  resume flow consumes the ledger.

package/skills/savepoint/references/context-management.md

@@ -0,0 +1,32 @@
+# Context Management (Start-Save-Continue)
+
+## Save Point
+Triggered by PreCompact hook or manually:
+1. Find active intent(s) from `~/.plastic/INDEX.md`
+2. Update active intent's `checklist.md` (check off completed items)
+3. Update active intent's `savepoint.md` (in-progress, next steps, blockers, discoveries)
+4. Add observations to `## Insights`
+5. Update INDEX.md
+6. Commit: `cd ~/.plastic && git add . && git commit -m "chore: savepoint — [intent name]"`
+7. Notify user to `/clear`
+
+## Continue
+Triggered by UserPromptSubmit hook when user says "continue". Priority order:
+
+**1. Active intents first (resume work):**
+1. Read INDEX.md → find active intent(s)
+2. Read active intent's `intent.md` → what and why
+3. Read active intent's `savepoint.md` → where we left off
+4. Read active intent's `checklist.md` → what's next
+5. Announce: intent name, current state, next step, blockers
+6. Resume
+
+**2. No active intents → offer future intents:**
+1. List all future intents from INDEX.md
+2. Present them as options
+3. When user picks one, move to Active in INDEX.md
+
+**3. Stale future intents (untouched 3+ days) → triage:**
+- **activate** — start working on it now
+- **abandon** — mark as abandoned
+- **defer to agent** — implement, research, or ideate

package/skills/uninstall/SKILL.md

@@ -1,48 +1,59 @@
 ---
-name: plastic:uninstall
-description: Use when the user wants to remove Plastic. Deregisters the plugin from the current agent (Claude Code, Cursor, etc.) and optionally deletes all data.
+name: plastic-uninstall
+description: Use when the user wants to remove Plastic from an agent. Runs the manifest-driven uninstaller (removes skills, hooks, statusline, and any legacy plugin layout), reports exactly what was removed and what was left behind, then gives verification steps. Optionally deletes the intent store.
 ---
 
 # Uninstall Plastic
 
-## Procedure
+The installer tracks every file it writes in a manifest, so uninstall is exact and
+leaves no orphans. Prefer running it through the CLI; this skill wraps the same
+underlying uninstaller and adds reporting + verification.
 
-### Step 1: Detect the current agent
+## Procedure
 
-Check environment variables to determine which agent is running:
-- `$CLAUDE_PLUGIN_ROOT` → Claude Code
-- `$CURSOR_PLUGIN_ROOT` → Cursor
-- Otherwise → unknown agent
+### Step 1: Run the uninstaller
 
-### Step 2: Deregister from the agent
+```bash
+npx @zalom/plastic@latest uninstall --claude
+```
 
-**Claude Code:**
-- Remove `"plastic"` from `extraKnownMarketplaces` in `~/.claude/settings.json`
-- Remove `"plastic@plastic"` from `enabledPlugins` in `~/.claude/settings.json`
-- Announce: "Plastic deregistered from Claude Code."
+(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx` works too.)
 
-**Other agents:** Provide manual instructions for their deregistration process.
+This removes, for the targeted agent:
+- all `~/.claude/skills/plastic-*/` skills
+- all `~/.claude/hooks/plastic-*` hooks (and restores any saved original statusline)
+- the `~/.claude/plastic/` state dir + manifest
+- any **legacy** plugin layout: `plugins/marketplaces/plastic`, `plugins/cache/plastic`,
+  the old nested `skills/plastic/`, and the `plastic@plastic` /
+  `extraKnownMarketplaces.plastic` / `known_marketplaces.json` registrations
 
-### Step 3: Offer the data decision
+### Step 2: Report removed vs left
 
-Present clearly:
+Relay the uninstaller's output to the user — what was **removed** and what was
+**left in place**:
+- **Left:** `~/.plastic/` (intent store, history, projects) and any non-Plastic
+  settings.json entries.
 
-```
-Plastic is deregistered from [agent name].
+### Step 3: Verify removal
 
-Your intent store at ~/.plastic/ is untouched.
+Tell the user to confirm:
 
-Would you like to delete your Plastic data now?
+```bash
+ls ~/.claude/skills | grep '^plastic-'    # → no output
+ls ~/.claude/hooks  | grep '^plastic-'    # → no output
+grep -n plastic ~/.claude/settings.json   # → no plastic hook/plugin refs
+```
 
-⚠️  WARNING: This permanently removes ALL intents, history,
-and any projects in ~/.plastic/projects/.
-This is irreversible.
+### Step 4: Offer the data decision
 
-a) Keep everything (recommended) — you can re-install Plastic later
-b) Delete everything now — removes ~/.plastic/ entirely
 ```
+Plastic is uninstalled from [agent].
+Your intent store at ~/.plastic/ is untouched.
 
-### Step 4: Execute user's choice
+Delete it too?
+  a) Keep everything (recommended) — re-install anytime with npx
+  b) Delete everything now — removes ~/.plastic/ entirely (irreversible)
+```
 
-- **Keep:** Done. Tell the user: "Your data is at ~/.plastic/. Re-install anytime with `/plastic:install`."
-- **Delete:** Run `rm -rf ~/.plastic/` and confirm: "Plastic data deleted."
+- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with `npx @zalom/plastic@latest install --claude`."
+- **Delete:** run `rm -rf ~/.plastic/` and confirm.

package/skills/update/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: update
-description: Use when updating Plastic after a plugin update, or when the user says "update plastic". Runs the npx installer to sync core files and re-register agent adapters.
+name: plastic-update
+description: Use when updating Plastic. Runs the `update` verb, which reads the installed VERSION, derives its channel, queries npm dist-tags, and advances to the next version on that channel (or switches channel with a flag).
 ---
 
 # Update Plastic
@@ -8,70 +8,67 @@ description: Use when updating Plastic after a plugin update, or when the user s
 ## When to Use
 - User says "update plastic", "sync plastic", or "upgrade plastic"
 - Statusline shows "Plastic update available"
-- After a version bump notification
+- After a version-bump notification
 
-## Prerequisites
+## What it does
 
-Global install must exist (`~/.plastic/INDEX.md` present). If not, tell the
-user to run `npx @zalom/plastic@latest` first.
+`update` is a single deterministic command. It reads `~/.plastic/VERSION`, derives the
+channel from the version string (`-alpha`/`-beta`/none → stable), queries `npm` dist-tags,
+and advances to the **next version on the current channel**. "Already up to date" is a
+clean no-op. You do not compute the target yourself — the script does.
 
-## Procedure
+## Flags
 
-### Step 1: Verify global install exists
+| Flag | Behaviour |
+|------|-----------|
+| (none) | Advance to the next version on the **current** channel |
+| `--latest` | Switch to / advance the **stable** channel (toward stability — frictionless) |
+| `--beta` | Switch to / advance the **beta** channel |
+| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge — confirmed if moving down in stability) |
 
-```bash
-if [ ! -f ~/.plastic/INDEX.md ]; then
-  echo "No global install found. Run: npx @zalom/plastic@latest"
-  exit
-fi
-```
+Switching toward a more stable channel is frictionless; switching toward bleeding edge is
+confirmed. To roll **back** to a previously-installed version, use `plastic-versions`.
+
+## Prerequisites
+
+Plastic must be installed (`~/.plastic/VERSION` present). If not, run
+`npx @zalom/plastic install --claude` first.
+
+## Procedure
 
-### Step 2: Run the installer
+### Step 1: Run the update
 
 ```bash
-npx @zalom/plastic@latest --claude
+npx @zalom/plastic update            # next version on the current channel
+# or: npx @zalom/plastic update --beta   /   --latest   /   --alpha
 ```
 
-This re-runs the installer which:
-- Downloads the latest version from npm
-- Syncs core files (PLASTIC.md, scripts, hooks) to ~/.plastic/
-- Re-registers hooks and skills into Claude Code's ~/.claude/
-- Preserves all user data (INDEX.md, config.yml, projects.yml, store/)
+Append the agent flag(s) if not just Claude (`--codex`, `--hermes`, `--all`).
+The command prints the transition (`vX → vY`) or "already up to date", and records the
+move in the append-only `~/.plastic/versions.json` ledger.
 
-### Step 3: Announce key changes
+### Step 2: Announce key changes
 
-After the installer completes, read `~/.plastic/PLASTIC.md` and announce any
-convention changes that affect the current session. This corrects the agent's
-in-context understanding without needing /clear.
+After it completes, read `~/.plastic/PLASTIC.md` and announce convention changes that
+affect the current session:
 
-Format:
 ```
-Plastic updated to vX.Y.Z.
+Plastic updated to vX.Y.Z (channel).
 
-Key changes in this version:
-- [list notable convention changes if any]
+Key changes:
+- [notable convention changes, if any]
 
 Recommendation: run /clear for a clean session with all new conventions loaded.
 ```
 
-### Step 4: Run health check
-
-Invoke `plastic:doctor` to verify the installation is healthy after the update.
-
-If all checks pass, show: **"Health check: all clear."**
-
-If issues are found, show the full doctor report and offer to fix any fixable items.
+### Step 3: Health check
 
-### Step 5: Commit
+Invoke `plastic-doctor`. If all checks pass: **"Health check: all clear."** Otherwise show
+the report and offer to fix.
 
-```bash
-cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic core files" --allow-empty
-```
-
-### Step 6: Clear update cache
+### Step 4: Commit + clear update cache
 
 ```bash
+cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION versions.json 2>/dev/null && git commit -m "chore: update Plastic to $(cat ~/.plastic/VERSION)" --allow-empty
 rm -f ~/.plastic/.cache/update-check.json
 ```
-
-This removes the statusline warning since the update is now applied.

package/skills/versions/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: plastic-versions
+description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
+---
+
+# Plastic Versions — local version time-machine
+
+## When to Use
+- "show plastic versions", "version history", "what versions have I run"
+- "roll back plastic", "downgrade", "go back to the version that worked", "revert plastic"
+- A new version broke something and the user wants their last known-good build
+
+For upgrading to a **new** release, use `plastic-update`. This skill only navigates
+versions you have **already installed** — the ones recorded in the ledger.
+
+## The ledger
+
+`~/.plastic/versions.json` is an **append-only JSONL** ledger — one line per version
+change, never modified or deleted:
+
+```json
+{"version":"1.0.0-alpha.17","action":"install","at":"..."}
+{"version":"1.0.0-alpha.18","action":"update","at":"..."}
+```
+
+`action` ∈ `install | reinstall | update | downgrade` (derived from version direction; the
+channel is derived from the version string, never stored). It is a troubleshooting record.
+
+## Procedure
+
+### Show history
+
+```bash
+npx @zalom/plastic versions
+```
+
+Prints the table with the currently-installed version marked. If the most recent action was
+a `downgrade`, it asks whether to keep rolling back.
+
+### Roll back
+
+```bash
+npx @zalom/plastic versions --downgrade                    # one step back
+npx @zalom/plastic versions --downgrade --version 1.0.0-alpha.15   # to a specific run
+```
+
+Rollback targets are restricted to versions in the ledger (only builds you have actually
+run, so you only ever return to something known-good for you). The chosen version is
+re-fetched from npm and re-synced; your intent store, config, and the ledger are untouched.
+
+### Step forward (after a rollback)
+
+```bash
+npx @zalom/plastic versions --upgrade                      # one step forward in your history
+```
+
+### After any change
+
+Run `plastic-doctor` to confirm health, and suggest `/clear` so the session picks up the
+swapped conventions.
+
+## Notes
+- The ledger is **never** edited or pruned — it is the audit trail.
+- Downgrades cannot un-migrate a store-format change; if a warning appears, surface it to
+  the user rather than forcing the rollback.

package/skills/writing-instructions/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: plastic-writing-instructions
+description: >
+  Write or restructure agent instructions, conventions files, and SKILL.md
+  content using progressive disclosure and the agentskills.io specification.
+  Use when creating PLASTIC.md, rewriting convention docs, authoring new
+  skills, restructuring large instruction files to fit context budgets,
+  or when instructions feel too long, too vague, or agents aren't following
+  them. Also use when the user says "progressive disclosure", "restructure
+  instructions", or "the instructions are too big".
+---
+
+# Writing Agent Instructions
+
+Based on the [agentskills.io specification](https://agentskills.io).
+
+## Progressive Disclosure Architecture
+
+All agent instructions follow three loading stages. Design for this — it's the
+architecture, not a nice-to-have.
+
+| Stage | What loads | Budget | Design for |
+|-------|-----------|--------|------------|
+| **Discovery** | name + description | ~100 tokens | Trigger accuracy |
+| **Activation** | Full instruction body | <5000 tokens / <500 lines | Core procedures |
+| **Execution** | references/, scripts/, assets/ | As needed | Deep detail |
+
+**The description carries the entire burden of triggering.** If agents aren't
+activating your skill, the description is the problem.
+
+## Procedure
+
+### Step 1: Audit the content
+
+Before writing or restructuring, classify every piece of content:
+
+| Classification | Where it goes | Example |
+|---------------|---------------|---------|
+| **Trigger context** | description field | "Use when...", keywords |
+| **Core procedure** | SKILL.md body | Step-by-step workflows |
+| **Gotchas** | SKILL.md body (early) | Facts that defy assumptions |
+| **Deep reference** | references/ | API details, full schemas |
+| **Templates** | assets/ or inline | Output format examples |
+| **Executable logic** | scripts/ | Validation, data processing |
+
+Ask for each piece: "Would the agent get this wrong without this?"
+If no — cut it. If unsure — test it.
+
+### Step 2: Write the description
+
+The description must convey WHEN to use, not just WHAT it does.
+
+**Rules:**
+- Imperative phrasing: "Use this skill when..." not "This skill does..."
+- Focus on user intent, not implementation
+- Err on the side of being pushy — list contexts explicitly
+- Include cases where user doesn't name the domain directly
+- Under 1024 characters (hard limit)
+- Include specific trigger keywords
+
+**Template:**
+```yaml
+description: >
+  [One sentence: what it does]. Use when [primary trigger context],
+  [secondary trigger], or when [indirect trigger where user doesn't
+  name the domain]. Also use when [edge case trigger].
+```
+
+### Step 3: Write the body
+
+**Principles (in priority order):**
+
+1. **Procedures over declarations** — Teach HOW to approach a class of problems,
+   not WHAT to produce for a specific instance
+2. **Defaults, not menus** — Pick one approach, mention alternatives briefly.
+   "Use X. For Y cases, use Z instead." Never present options as equals.
+3. **Calibrate control to fragility** — Prescriptive for fragile/sequential tasks,
+   flexible when multiple approaches are valid. Most skills have a mix.
+4. **Reasoning over rigid directives** — "Do X because Y tends to cause Z" beats
+   "ALWAYS do X, NEVER do Y"
+5. **Add what the agent lacks, omit what it knows** — No explaining HTTP, PDFs,
+   or what a migration is. Jump to what's non-obvious.
+
+**Structure:**
+```markdown
+# Title
+
+[1-2 sentence purpose statement]
+
+## Gotchas
+- [Highest-value content first — facts that defy assumptions]
+- [Each gotcha is a concrete correction, not general advice]
+
+## Procedure
+### Step 1: ...
+### Step 2: ...
+
+## Patterns
+[Only if the skill covers multiple approaches to similar problems]
+```
+
+### Step 4: Extract to references/
+
+Anything over 500 lines or 5000 tokens goes to `references/`. But tell the
+agent WHEN to load each file — conditional references, not a generic "see
+references/ for details."
+
+**Good:** "Read `references/api-errors.md` if the API returns a non-200 status"
+**Bad:** "See references/ for more information"
+
+### Step 5: Validate
+
+Run through this checklist:
+
+- [ ] Description under 1024 chars
+- [ ] Body under 500 lines / 5000 tokens
+- [ ] Every instruction passes "would the agent get this wrong without it?"
+- [ ] Gotchas are concrete corrections, not general advice
+- [ ] Defaults chosen, not menus presented
+- [ ] Control calibrated: prescriptive where fragile, flexible where tolerant
+- [ ] References have conditional load triggers
+- [ ] No explaining what the agent already knows
+
+For structured evaluation beyond this checklist (paired evals, pass rate
+tracking, regression testing), use `plastic-evaluating-skills`.
+
+## Gotchas
+
+- Hook `additionalContext` truncates at **10,000 characters**. If instructions
+  must load via hooks (not skills), they must fit this budget.
+- `~/.claude/rules/*.md` files load fully with no truncation — use for
+  always-loaded conventions that don't fit in a skill.
+- CLAUDE.md supports `@path/to/file` imports (max depth 4) — another way
+  to load large instruction sets without truncation.
+- Agents only consult skills for tasks beyond what they can handle alone.
+  Simple one-step requests may not trigger even with a perfect description.
+- Content from real domain expertise (runbooks, incident reports, code review)
+  dramatically outperforms LLM-generated instructions without project context.
+- The most common cause of agents not following instructions: the instruction
+  was too vague, didn't apply to the current task, or presented too many
+  options without a clear default. Read execution traces to diagnose.
+
+## For Convention Files (PLASTIC.md, CLAUDE.md)
+
+Convention files aren't skills — they load differently. Apply progressive
+disclosure by splitting:
+
+| Layer | Mechanism | Budget | Content |
+|-------|-----------|--------|---------|
+| **Always-on** | `~/.claude/rules/` or hook | <10K chars | Core identity, gotchas, critical procedures |
+| **On-demand** | Skills (SKILL.md) | <5K tokens each | Specific workflows activated by task |
+| **Deep reference** | `references/` in skills | Unlimited | Full specs, schemas, examples |
+
+**The always-on layer should answer: "What does this agent need to know about
+every single task?"** Everything else activates on demand.
+
+## References
+
+- Read `references/agentskills-spec.md` for the complete agentskills.io specification including frontmatter fields, description optimization methodology, evaluation framework, and script design requirements