@fro.bot/systematic 1.22.8 → 1.23.1

package/{commands/ce/review.md → skills/ce-review/SKILL.md}

@@ -1,7 +1,7 @@
 ---
 name: ce:review
 description: Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees
-argument-hint: "[PR number, GitHub URL, branch name, or latest]"
+argument-hint: '[PR number, GitHub URL, branch name, or latest] [--serial]'
 ---
 
 # Review Command
@@ -51,9 +51,10 @@ Ensure that the code is ready for analysis (either in worktree or on current bra
 #### Protected Artifacts
 
 <protected_artifacts>
-The following paths are systematic pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
+The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
 
-- `docs/plans/*.md` — Plan files created by `/ce:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/ce:work`).
+- `docs/brainstorms/*-requirements.md` — Requirements documents created by `/systematic:ce-brainstorm`. These are the product-definition artifacts that planning depends on.
+- `docs/plans/*.md` — Plan files created by `/systematic:ce-plan`. These are living documents that track implementation progress (checkboxes are checked off by `/systematic:ce-work`).
 - `docs/solutions/*.md` — Solution documents created during the pipeline.
 
 If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
@@ -61,23 +62,56 @@ If a review agent flags any file in these directories for cleanup or removal, di
 
 #### Load Review Agents
 
-Read `systematic.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
+Read `compound-engineering.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
 
 If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
 
+#### Choose Execution Mode
+
+<execution_mode>
+
+Before launching review agents, check for context constraints:
+
+**If `--serial` flag is passed OR conversation is in a long session:**
+
+Run agents ONE AT A TIME in sequence. Wait for each agent to complete before starting the next. This uses less context but takes longer.
+
+**Default (parallel):**
+
+Run all agents simultaneously for speed. If you hit context limits, retry with `--serial` flag.
+
+**Auto-detect:** If more than 5 review agents are configured, automatically switch to serial mode and inform the user:
+"Running review agents in serial mode (6+ agents configured). Use --parallel to override."
+
+</execution_mode>
+
 #### Parallel Agents to review the PR:
 
 <parallel_tasks>
 
+**Parallel mode (default for ≤5 agents):**
+
 Run all configured review agents in parallel using task tool. For each agent in the `review_agents` list:
 
 ```
-task {agent-name}(PR content + review context from settings body)
+Task {agent-name}(PR content + review context from settings body)
+```
+
+**Serial mode (--serial flag, or auto for 6+ agents):**
+
+Run configured review agents ONE AT A TIME. For each agent in the `review_agents` list, wait for it to complete before starting the next:
+
+```
+For each agent in review_agents:
+  1. Task {agent-name}(PR content + review context)
+  2. Wait for completion
+  3. Collect findings
+  4. Proceed to next agent
 ```
 
-Additionally, always run these regardless of settings:
-- task agent-native-reviewer(PR content) - Verify new features are agent-accessible
-- task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
+Always run these last regardless of mode:
+- task systematic:review:agent-native-reviewer(PR content) - Verify new features are agent-accessible
+- task systematic:research:learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
 
 </parallel_tasks>
 
@@ -89,9 +123,9 @@ These agents are run ONLY when the PR matches specific criteria. Check the PR fi
 
 **MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
 
-- task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
-- task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
-- task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
+- task systematic:review:schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
+- task systematic:review:data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
+- task systematic:review:deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
 
 **When to run:**
 - PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
@@ -203,7 +237,7 @@ Complete system context map with component interactions
 
 ### 4. Simplification and Minimalism Review
 
-Run the task code-simplicity-reviewer() to see if we can simplify the code.
+Run the task systematic:review:code-simplicity-reviewer() to see if we can simplify the code.
 
 ### 5. Findings Synthesis and Todo Creation Using file-todos Skill
 
@@ -220,7 +254,7 @@ Remove duplicates, prioritize by severity and impact.
 
 - [ ] Collect findings from all parallel agents
 - [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
-- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
+- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/` (see Protected Artifacts above)
 - [ ] Categorize by type: security, performance, architecture, quality, etc.
 - [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
 - [ ] Remove duplicate or overlapping findings
@@ -245,9 +279,9 @@ Remove duplicates, prioritize by severity and impact.
 
 ```bash
 # Launch multiple finding-creator agents in parallel
-task() - Create todos for first finding
-task() - Create todos for second finding
-task() - Create todos for third finding
+Task() - Create todos for first finding
+Task() - Create todos for second finding
+Task() - Create todos for third finding
 etc. for each finding.
 ```
 
@@ -485,7 +519,7 @@ After presenting the Summary Report, offer appropriate testing based on project
 Spawn a subagent to run browser tests (preserves main context):
 
 ```
-task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
+Task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
 ```
 
 The subagent will:
@@ -504,7 +538,7 @@ The subagent will:
 Spawn a subagent to run Xcode tests (preserves main context):
 
 ```
-task general-purpose("Run /xcode-test for scheme [name]. Build for simulator, install, launch, take screenshots, check for crashes.")
+Task general-purpose("Run /xcode-test for scheme [name]. Build for simulator, install, launch, take screenshots, check for crashes.")
 ```
 
 The subagent will:
@@ -523,3 +557,4 @@ The subagent will:
 ### Important: P1 Findings Block Merge
 
 Any **🔴 P1 (CRITICAL)** findings must be addressed before merging the PR. Present these prominently and ensure they're resolved before accepting the PR.
+

package/{commands/ce/work.md → skills/ce-work/SKILL.md}

@@ -1,7 +1,7 @@
 ---
 name: ce:work
 description: Execute work plans efficiently while maintaining quality and finishing features
-argument-hint: "[plan file, specification, or todo file path]"
+argument-hint: '[plan file, specification, or todo file path]'
 ---
 
 # Work Plan Execution Command
@@ -23,6 +23,10 @@ This command takes a work document (plan, specification, or todo file) and execu
 1. **Read Plan and Clarify**
 
    - Read the work document completely
+   - Treat the plan as a decision artifact, not an execution script
+   - If the plan includes sections such as `Implementation Units`, `Work Breakdown`, `Requirements Trace`, `Files`, `Test Scenarios`, or `Verification`, use those as the primary source material for execution
+   - Check for a `Deferred to Implementation` or `Implementation-Time Unknowns` section — these are questions the planner intentionally left for you to resolve during execution. Note them before starting so they inform your approach rather than surprising you mid-task
+   - Check for a `Scope Boundaries` section — these are explicit non-goals. Refer back to them if implementation starts pulling you toward adjacent work
    - Review any references or links provided in the plan
    - If anything is unclear or ambiguous, ask clarifying questions now
    - Get user approval to proceed
@@ -73,12 +77,35 @@ This command takes a work document (plan, specification, or todo file) and execu
    - You plan to switch between branches frequently
 
 3. **Create Todo List**
-   - Use todowrite to break plan into actionable tasks
+   - Use your available task tracking tool (e.g., todowrite, task lists) to break the plan into actionable tasks
+   - Derive tasks from the plan's implementation units, dependencies, files, test targets, and verification criteria
+   - For each unit, read the `Patterns to follow` field before implementing — these point to specific files or conventions to mirror
+   - Use each unit's `Verification` field as the primary "done" signal for that task
+   - Do not expect the plan to contain implementation code, micro-step TDD instructions, or exact shell commands
    - Include dependencies between tasks
    - Prioritize based on what needs to be done first
    - Include testing and quality check tasks
    - Keep tasks specific and completable
 
+4. **Choose Execution Strategy**
+
+   After creating the task list, decide how to execute based on the plan's size and dependency structure:
+
+   | Strategy | When to use |
+   |----------|-------------|
+   | **Inline** | 1-2 small tasks, or tasks needing user interaction mid-flight |
+   | **Serial subagents** | 3+ tasks with dependencies between them. Each subagent gets a fresh context window focused on one unit — prevents context degradation across many tasks |
+   | **Parallel subagents** | 3+ tasks where some units have no shared dependencies and touch non-overlapping files. Dispatch independent units simultaneously, run dependent units after their prerequisites complete |
+
+   **Subagent dispatch** uses your available subagent or task spawning mechanism. For each unit, give the subagent:
+   - The full plan file path (for overall context)
+   - The specific unit's Goal, Files, Approach, Patterns, Test scenarios, and Verification
+   - Any resolved deferred questions relevant to that unit
+
+   After each subagent completes, update the plan checkboxes and task list before dispatching the next dependent unit.
+
+   For genuinely large plans needing persistent inter-agent communication (agents challenging each other's approaches, shared coordination across 10+ tasks), see Swarm Mode below which uses Agent Teams.
+
 ### Phase 2: Execute
 
 1. **Task Execution Loop**
@@ -87,15 +114,14 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    ```
    while (tasks remain):
-     - Mark task as in_progress in todowrite
+     - Mark task as in-progress
      - Read any referenced files from the plan
      - Look for similar patterns in codebase
      - Implement following existing conventions
      - Write tests for new functionality
      - Run System-Wide Test Check (see below)
      - Run tests after changes
-     - Mark task as completed in todowrite
-     - Mark off the corresponding checkbox in the plan file ([ ] → [x])
+     - Mark task as completed
      - Evaluate for incremental commit (see below)
    ```
 
@@ -113,7 +139,6 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    **When this matters most:** Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.
 
-   **IMPORTANT**: Always update the original plan document by checking off completed items. Use the Edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked.
 
 2. **Incremental Commits**
 
@@ -128,6 +153,8 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    **Heuristic:** "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."
 
+   If the plan has Implementation Units, use them as a starting guide for commit boundaries — but adapt based on what you find during implementation. A unit might need multiple commits if it's larger than expected, or small related units might land together. Use each unit's Goal to inform the commit message.
+
    **Commit workflow:**
    ```bash
    # 1. Verify tests pass (use project's test command)
@@ -160,7 +187,15 @@ This command takes a work document (plan, specification, or todo file) and execu
    - Add new tests for new functionality
    - **Unit tests with mocks prove logic in isolation. Integration tests with real objects prove the layers work together.** If your change touches callbacks, middleware, or error handling — you need both.
 
-5. **Figma Design Sync** (if applicable)
+5. **Simplify as You Go**
+
+   After completing a cluster of related implementation units (or every 2-3 units), review recently changed files for simplification opportunities — consolidate duplicated patterns, extract shared helpers, and improve code reuse and efficiency. This is especially valuable when using subagents, since each agent works with isolated context and can't see patterns emerging across units.
+
+   Don't simplify after every single unit — early patterns may look duplicated but diverge intentionally in later units. Wait for a natural phase boundary or when you notice accumulated complexity.
+
+   If a `/simplify` skill or equivalent is available, use it. Otherwise, review the changed files yourself for reuse and consolidation opportunities.
+
+6. **Figma Design Sync** (if applicable)
 
    For UI work with Figma designs:
 
@@ -170,7 +205,7 @@ This command takes a work document (plan, specification, or todo file) and execu
    - Repeat until implementation matches design
 
 6. **Track Progress**
-   - Keep todowrite updated as you complete tasks
+   - Keep the task list updated as you complete tasks
    - Note any blockers or unexpected discoveries
    - Create new tasks if scope expands
    - Keep user informed of major milestones
@@ -185,23 +220,25 @@ This command takes a work document (plan, specification, or todo file) and execu
    # Run full test suite (use project's test command)
    # Examples: bin/rails test, npm test, pytest, go test, etc.
 
-   # Run linting (per project conventions)
+   # Run linting (per CLAUDE.md)
    # Use linting-agent before pushing to origin
    ```
 
 2. **Consider Reviewer Agents** (Optional)
 
-   Use for complex, risky, or large changes. Read agents from `systematic.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
+   Use for complex, risky, or large changes. Read agents from `compound-engineering.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
 
    Run configured agents in parallel with task tool. Present findings and address critical issues.
 
 3. **Final Validation**
-   - All todowrite tasks marked completed
+   - All tasks marked completed
    - All tests pass
    - Linting passes
    - Code follows existing patterns
    - Figma designs match (if applicable)
    - No console errors or warnings
+   - If the plan has a `Requirements Trace`, verify each requirement is satisfied by the completed work
+   - If any `Deferred to Implementation` questions were noted, confirm they were resolved during execution
 
 4. **Prepare Operational Validation Plan** (REQUIRED)
    - Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
@@ -228,13 +265,28 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    Brief explanation if needed.
 
-   🤖 Generated with [OpenCode](https://opencode.ai)
+   🤖 Generated with [MODEL] via [HARNESS](HARNESS_URL) + Compound Engineering v[VERSION]
 
-   Co-Authored-By: Claude <noreply@anthropic.com>
+   Co-Authored-By: [MODEL] ([CONTEXT] context, [THINKING]) <noreply@anthropic.com>
    EOF
    )"
    ```
 
+   **Fill in at commit/PR time:**
+
+   | Placeholder | Value | Example |
+   |-------------|-------|---------|
+   | Placeholder | Value | Example |
+   |-------------|-------|---------|
+   | `[MODEL]` | Model name | Claude Opus 4.6, GPT-5.4 |
+   | `[CONTEXT]` | Context window (if known) | 200K, 1M |
+   | `[THINKING]` | Thinking level (if known) | extended thinking |
+   | `[HARNESS]` | Tool running you | OpenCode, Codex, Gemini CLI |
+   | `[HARNESS_URL]` | Link to that tool | `https://claude.com/claude-code` |
+   | `[VERSION]` | `plugin.json` → `version` | 2.40.0 |
+
+   Subagents creating commits/PRs are equally responsible for accurate attribution.
+
 2. **Capture and Upload Screenshots for UI Changes** (REQUIRED for any UI work)
 
    For **any** design changes, new views, or UI modifications, you MUST capture and upload screenshots:
@@ -308,7 +360,8 @@ This command takes a work document (plan, specification, or todo file) and execu
 
    ---
 
-   [![Systematic](https://img.shields.io/badge/Systematic-6366f1)](https://github.com/marcusrbrown/systematic) 🤖 Generated with [OpenCode](https://opencode.ai)
+   [![Compound Engineering v[VERSION]](https://img.shields.io/badge/Compound_Engineering-v[VERSION]-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
+   🤖 Generated with [MODEL] ([CONTEXT] context, [THINKING]) via [HARNESS](HARNESS_URL)
    EOF
    )"
    ```
@@ -328,59 +381,30 @@ This command takes a work document (plan, specification, or todo file) and execu
 
 ---
 
-## Swarm Mode (Optional)
-
-For complex plans with multiple independent workstreams, enable swarm mode for parallel execution with coordinated agents.
-
-### When to Use Swarm Mode
-
-| Use Swarm Mode when... | Use Standard Mode when... |
-|------------------------|---------------------------|
-| Plan has 5+ independent tasks | Plan is linear/sequential |
-| Multiple specialists needed (review + test + implement) | Single-focus work |
-| Want maximum parallelism | Simpler mental model preferred |
-| Large feature with clear phases | Small feature or bug fix |
-
-### Enabling Swarm Mode
+## Swarm Mode with Agent Teams (Optional)
 
-To trigger swarm execution, say:
+For genuinely large plans where agents need to communicate with each other, challenge approaches, or coordinate across 10+ tasks with persistent specialized roles, use agent team capabilities if available (e.g., Agent Teams in OpenCode, multi-agent workflows in Codex).
 
-> "Make a task list and launch an army of agent swarm subagents to build the plan"
+**Agent teams are typically experimental and require opt-in.** Do not attempt to use agent teams unless the user explicitly requests swarm mode or agent teams, and the platform supports it.
 
-Or explicitly request: "Use swarm mode for this work"
+### When to Use Agent Teams vs Subagents
 
-### Swarm Workflow
+| Agent Teams | Subagents (standard mode) |
+|-------------|---------------------------|
+| Agents need to discuss and challenge each other's approaches | Each task is independent — only the result matters |
+| Persistent specialized roles (e.g., dedicated tester running continuously) | Workers report back and finish |
+| 10+ tasks with complex cross-cutting coordination | 3-8 tasks with clear dependency chains |
+| User explicitly requests "swarm mode" or "agent teams" | Default for most plans |
 
-When swarm mode is enabled, the workflow changes:
+Most plans should use subagent dispatch from standard mode. Agent teams add significant token cost and coordination overhead — use them when the inter-agent communication genuinely improves the outcome.
 
-**Note:** OpenCode does not yet have a native Teammate coordination API equivalent to Claude Code's Teammate API. The swarm pattern below uses task() calls for parallel execution without explicit team coordination. Use this approach for independent workstreams.
+### Agent Teams Workflow
 
-1. **Create Task List with Dependencies**
-   - Parse plan into task items
-   - Set up dependencies for sequential tasks
-   - Independent tasks have no blockers (can run in parallel)
-
-2. **Spawn Specialized Tasks in Parallel**
-   ```
-   task({
-     name: "implementer",
-     subagent_type: "general-purpose",
-     prompt: "Implement these tasks: [list]. Follow AGENTS.md patterns."
-   })
-
-   task({
-     name: "tester",
-     subagent_type: "general-purpose",
-     prompt: "Write and run tests for: [list]. Verify all pass."
-   })
-   ```
-
-3. **Coordinate and Monitor**
-   - Main agent monitors task completion
-   - Spawn additional workers as phases unblock
-   - Handle plan approval if required
-
-See the `orchestrating-swarms` skill for detailed swarm patterns and best practices.
+1. **Create team** — use your available team creation mechanism
+2. **Create task list** — parse Implementation Units into tasks with dependency relationships
+3. **Spawn teammates** — assign specialized roles (implementer, tester, reviewer) based on the plan's needs. Give each teammate the plan file path and their specific task assignments
+4. **Coordinate** — the lead monitors task completion, reassigns work if someone gets stuck, and spawns additional workers as phases unblock
+5. **Cleanup** — shut down all teammates, then clean up the team resources
 
 ---
 
@@ -422,7 +446,7 @@ See the `orchestrating-swarms` skill for detailed swarm patterns and best practi
 Before creating PR, verify:
 
 - [ ] All clarifying questions asked and answered
-- [ ] All todowrite tasks marked completed
+- [ ] All tasks marked completed
 - [ ] Tests pass (run project's test command)
 - [ ] Linting passes (use linting-agent)
 - [ ] Code follows existing patterns
@@ -431,7 +455,7 @@ Before creating PR, verify:
 - [ ] Commit messages follow conventional format
 - [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
 - [ ] PR description includes summary, testing notes, and screenshots
-- [ ] PR description includes Systematic badge
+- [ ] PR description includes Compound Engineered badge with accurate model, harness, and version
 
 ## When to Use Reviewer Agents
 
@@ -451,6 +475,7 @@ For most features: tests + linting + following patterns is sufficient.
 - **Skipping clarifying questions** - Ask now, not after building wrong thing
 - **Ignoring plan references** - The plan has links for a reason
 - **Testing at the end** - Test continuously or suffer later
-- **Forgetting todowrite** - Track progress or lose track of what's done
+- **Forgetting to track progress** - Update task status as you go or lose track of what's done
 - **80% done syndrome** - Finish the feature, don't move on early
 - **Over-reviewing simple changes** - Save reviewer agents for complex work
+

package/{commands/create-agent-skill.md → skills/create-agent-skill/SKILL.md}

@@ -7,3 +7,4 @@ disable-model-invocation: true
 ---
 
 Invoke the create-agent-skills skill for: $ARGUMENTS
+

package/skills/create-agent-skills/SKILL.md

@@ -22,7 +22,7 @@ Custom slash commands have been merged into skills. A file at `.opencode/command
 
 **Use a skill directory** (`skills/name/SKILL.md`) when:
 - Need supporting reference files, scripts, or templates
-- Background knowledge Claude should auto-load
+- Background knowledge OpenCode should auto-load
 - Complex enough to benefit from progressive disclosure
 
 Both use identical YAML frontmatter and markdown content format.
@@ -56,18 +56,18 @@ All fields are optional. Only `description` is recommended.
 | Field | Required | Description |
 |-------|----------|-------------|
 | `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
-| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
+| `description` | Recommended | What it does AND when to use it. OpenCode uses this for auto-discovery. Max 1024 chars. |
 | `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
-| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
+| `disable-model-invocation` | No | Set `true` to prevent OpenCode auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
 | `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true`. |
-| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
+| `allowed-tools` | No | Tools OpenCode can use without permission prompts. Example: `Read, Bash(git *)` |
 | `model` | No | Model to use. Options: `haiku`, `sonnet`, `opus`. |
 | `context` | No | Set `fork` to run in isolated subagent context. |
 | `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name. |
 
 ### Invocation Control
 
-| Frontmatter | User can invoke | Claude can invoke | When loaded |
+| Frontmatter | User can invoke | OpenCode can invoke | When loaded |
 |-------------|----------------|-------------------|-------------|
 | (default) | Yes | Yes | Description always in context, full content loads when invoked |
 | `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
@@ -97,22 +97,11 @@ Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.
 
 ### Dynamic Context Injection
 
-The `` !`command` `` syntax runs shell commands before content is sent to Claude:
+Skills support dynamic context injection: prefix a backtick-wrapped shell command with an exclamation mark, and the preprocessor executes it at load time, replacing the directive with stdout. Write an exclamation mark immediately before the opening backtick of the command you want executed (for example, to inject the current git branch, write the exclamation mark followed by `git branch --show-current` wrapped in backticks).
 
-```yaml
----
-name: pr-summary
-description: Summarize changes in a pull request
-context: fork
-agent: Explore
----
-
-## Context
-- PR diff: !`gh pr diff`
-- Changed files: !`gh pr diff --name-only`
+**Important:** The preprocessor scans the entire SKILL.md as plain text — it does not parse markdown. Directives inside fenced code blocks or inline code spans are still executed. If a skill documents this syntax with literal examples, the preprocessor will attempt to run them, causing load failures. To safely document this feature, describe it in prose (as done here) or place examples in a reference file, which is loaded on-demand by Claude and not preprocessed.
 
-Summarize this pull request...
-```
+For a concrete example of dynamic context injection in a skill, see [official-spec.md](references/official-spec.md) § "Dynamic Context Injection".
 
 ### Running in a Subagent
 
@@ -273,3 +262,4 @@ For detailed guidance, see:
 
 - [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
 - [GitHub - anthropics/skills](https://github.com/anthropics/skills)
+