> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills System

> Universal reusable workflows and best practices

export const ThemedImage = ({light, dark, alt = ""}) => {
  const [darkMode, setDarkMode] = useState(null);
  useEffect(() => {
    const root = document.documentElement;
    const syncTheme = () => setDarkMode(root.classList.contains("dark"));
    const observer = new MutationObserver(syncTheme);
    syncTheme();
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class"]
    });
    return () => observer.disconnect();
  }, []);
  if (darkMode === null) return null;
  return <img src={darkMode ? dark ?? light : light} alt={alt} loading="lazy" />;
};

# Skills System

Overdeck's skills system provides reusable workflows and best practices for AI agents.

The dashboard's **Skills** page lists every skill side by side per harness — here `Overdeck (108)` and `Claude (123)` — with each skill's on-disk path, internal `name`, and a sync indicator linking to its `SKILL.md`. It's the quickest way to confirm a skill landed where the agent (or the conversation you're driving) can invoke it.

<ThemedImage light="/images/dashboard/skills-light.png" dark="/images/dashboard/skills-dark.png" alt="Skills page: per-harness columns (Overdeck and Claude) listing each skill's path, name, and SKILL.md sync status, with an activity feed on the right" />

## What Are Skills

Skills are reusable, shareable workflows that encode best practices for common development tasks. They are:

* **Universal** - Work across all AI coding tools (Claude Code, Codex, Cursor, Gemini CLI, Google Antigravity)
* **Shareable** - Distribute via `pan sync` to sync to all connected AI tools
* **Contextual** - Invoked with `/skill-name` in AI tool prompts
* **Best-practice-driven** - Encode proven workflows and checklists

Skills eliminate the need to repeatedly explain how to do common tasks. Instead of telling an agent "please review this code for security issues", you invoke `/code-review-security` and the agent follows the established workflow.

## Built-In Skills

Overdeck ships with 70+ built-in skills organized by category:

### Development Workflows

| Skill | Description |
| - | - |
| `feature-work` | Standard feature implementation workflow |
| `bug-fix` | Systematic bug investigation and fixing |
| `refactor` | Safe refactoring with tests first |
| `code-review` | Comprehensive code review checklist |
| `code-review-security` | OWASP Top 10 security analysis |
| `code-review-performance` | Algorithm and resource optimization |
| `release` | Step-by-step release process |
| `dependency-update` | Safe dependency updates |
| `incident-response` | Production incident handling |
| `onboard-codebase` | Understanding new codebases |
| `work-complete` | Checklist for completing agent work |

### AI Self-Monitoring

| Skill | Description |
| - | - |
| `knowledge-capture` | Captures learnings when AI gets confused or corrected |
| `refactor-radar` | Detects systemic issues causing AI confusion |
| `session-health` | Detect and clean up stuck sessions |

### Overdeck Operations (pan-\*)

| Skill | Description |
| - | - |
| `pan-help` | Show all Overdeck commands |
| `pan-up` | Start dashboard and services |
| `pan-down` | Stop dashboard and services |
| `pan-status` | Show running agents |
| `pan-issue` | Spawn agent for an issue |
| `pan-plan` | Create execution plan for issue |
| `pan-tell` | Send message to running agent |
| `pan-kill` | Kill a running agent |
| `pan-approve` | Approve agent work and merge |
| `pan-health` | Check system health |
| `pan-sync` | Sync skills to AI tools |
| `pan-install` | Install prerequisites |
| `pan-setup` | Initial setup wizard |
| `pan-quickstart` | Quick start guide |
| `pan-projects` | Manage registered projects |
| `pan-tracker` | Issue tracker operations |
| `pan-logs` | View agent logs |
| `pan-rescue` | Recover crashed agents |
| `pan-diagnose` | Diagnose agent issues |
| `pan-docker` | Docker operations |
| `pan-network` | Network diagnostics |
| `pan-config` | Configuration management |
| `pan-restart` | Safely restart Overdeck dashboard and services |
| `pan-code-review` | Orchestrate parallel code review (3 reviewers + synthesis) |
| `pan-subagent-creator` | Create specialized subagents |
| `pan-skill-creator` | Create new skills (guided) |
| `pan-reopen` | Reopen completed issue for re-work |
| `pan-oversee` | Supervise agent through full work lifecycle |
| `pan-sync-main` | Sync latest main into workspace feature branch |
| `pan-docs` | Search Overdeck documentation |

### Utilities

| Skill | Description |
| - | - |
| `beads` | Git-backed issue tracking with dependencies |
| `claude-skill-creator` | Guide for creating Claude Code skills |
| `web-design-guidelines` | UI/UX review checklist |
| `clear-writing` | Proven rules for clearer prose in docs, commits, and UI text |
| `crash-investigation` | Investigate system crashes, OOM kills, and freezes |
| `opus-plan` | Opus-driven planning with PRD, STATE.md, and beads |
| `spec-readiness` | Evaluate issue requirements readiness (scored 0-100) |
| `check-merged` | Verify if a feature branch has been merged into main |
| `react-best-practices` | React/Next.js performance optimization from Vercel |
| `stitch-design-md` | Synthesize Stitch designs into DESIGN.md files |

## Using Skills

Skills are invoked via slash commands in any AI coding tool:

```
# In Claude Code, Cursor, Windsurf, etc:
/feature-work
/code-review-security
/bug-fix
/pan-help
```

When you invoke a skill, the AI tool injects the skill's prompt into the conversation, giving the agent detailed instructions on how to proceed.

## Creating Custom Skills

Skills are markdown files stored in `~/.overdeck/skills/`. Create your own with:

```bash theme={null}
# Use the guided skill creator
/pan-skill-creator

# Or manually create a skill
mkdir -p ~/.overdeck/skills/my-custom-skill
cat > ~/.overdeck/skills/my-custom-skill/skill.md <<'EOF'
# My Custom Skill

Brief description of what this skill does.

## When to Use

Describe when this skill should be invoked.

## Steps

1. Step 1 description
2. Step 2 description
3. Step 3 description

## Best Practices

- Tip 1
- Tip 2
EOF

# Sync to all AI tools
pan sync
```

**Skill anatomy:**

```markdown theme={null}
# Skill Title

One-line description.

## When to Use

When to invoke this skill (triggers).

## Steps

1. Detailed step-by-step instructions
2. With specific commands or patterns
3. And expected outcomes

## Checklist

- [ ] Item 1
- [ ] Item 2
- [ ] Item 3

## Examples

\`\`\`bash
# Example command
\`\`\`

## Related Skills

- /other-skill - When to use instead
- /complementary-skill - Use together with this
```

See the [Claude skill creator](/cli/core-commands) or use `/pan-skill-creator` for guided creation.

## Skill Distribution

Skills can be distributed via:

1. **Project-specific** - Store in `.overdeck/skills/` in your repo
2. **User-specific** - Store in `~/.overdeck/skills/` (synced to AI tools)
3. **Team-shared** - Commit to version control and share via git
4. **Public packages** - Distribute via npm or GitHub

### Syncing Skills

```bash theme={null}
# Sync all skills to Claude Code (~/.claude/skills) and Codex/Pi (~/.agents/skills)
pan sync

# Only sync skills (skip agents, hooks)
pan sync --skills-only

# Verify sync status
pan sync --dry-run
```

The `pan sync` command:

* Copies skills from `~/.overdeck/skills/` to each AI tool's config directory
* Updates existing skills if versions differ
* Removes manifest-managed skills from harness directories after their bundled source is removed
* Preserves user-owned and user-modified files, reporting modified stale files instead of deleting them
* Ignores empty bundled skill directories so they do not reappear in caches or harness targets

## Turning skills on and off

Every skill has an on/off state that you can set at three levels: a **global default**, a **project override**, and an **issue override**. A conversation can also carry its own values, the narrowest level of all. The narrowest level that has a value wins:

**conversation > issue > project > global > default (on)**

A skill with no value at any level is on. The global level is two-state: a skill is either on (no stored value) or off. Project and issue levels are three-state: **Inherit**, **On**, or **Off**, so a project can turn on a skill that is off globally, and an issue can turn off a skill its project turned on.

Conversation values are set only when the conversation is created, in the **New conversation with options…** dialog (see [Conversations](/features/conversations)). They are stored on the conversation row and applied at every launch, resume, restart and fork of that conversation. A conversation value for a pack skill (`pack/skill`) beats every level and every pack toggle, so a conversation can turn on one opt-in pack skill for itself. Core skills ignore conversation values too.

### Core skills are always on

The pipeline depends on these 11 skills, so they are always on and cannot be overridden at any level:

`pan`, `pan-done`, `pan-flywheel`, `pan-foreman`, `pan-plan`, `pan-start`, `pan-task`, `pan-tell`, `pan-worker`, `work-complete`, `write-xbrief`

### Where each level is stored

| Level | Stored in |
| - | - |
| Global | `~/.overdeck/config.yaml`, under `skills.overrides` (`<skill>: false`) |
| Project | `~/.overdeck/projects.yaml`, under `projects.<key>.skill_overrides` |
| Issue | `<planHome>/.pan/skill-overrides/<ISSUE>.yaml` in the project's plan home, committed and pushed on `main` as `chore(workspace): skill overrides for <ISSUE>` |
| Conversation | `conversations.skill_overrides` (JSON) in `~/.overdeck/overdeck.db`; the conversation's launcher rereads it at every launch |

Clearing the last override for an issue deletes its file and commits the deletion. Skills that exist only in a project's `.pan/skills/` directory are **project skills**: they appear in that project's settings and its issues, never on the global Skills page.

### From the CLI

```bash theme={null}
# Every skill with its effective state and where it comes from
pan skills
pan skills list --project <key> --issue <id>
pan skills list --json

# Set a skill on, off, or back to inherit (global unless you pass a level)
pan skills set <skill> on|off|inherit [--project <key> | --issue <id>]
```

At the global level, `pan skills set <skill> on` clears the override, because on is the default. Setting a core skill, an unknown skill, an unregistered project, or an issue that no registered project owns fails with an error.

### From the dashboard

* **Skills page** (sidebar → Skills): every skill with a global on/off switch. Each row notes when projects or issues override it, and the **Overridden below** filter lists those skills.
* **Project settings → Skills**: Inherit / On / Off for every skill in that project. The Inherit button shows the value it inherits, for example `Inherit (off via global)`.
* **Issue view → Skills for this issue**: the same controls for one issue, in the issue's Overview. It opens filtered to skills overridden here or off at launch; select **All** to see the rest. The section is hidden for an issue that no registered project owns.

### When changes apply

Overrides are resolved when Overdeck launches an agent. They apply to Overdeck-managed **Claude Code** and **Codex** sessions at their **next launch** (a fresh start or a resume). A running agent keeps the skills it launched with.

* Claude Code launches receive `--settings '{"skillOverrides":{"<skill>":"off"}}'`, which hides every copy of the skill by name.
* Codex launches get `[[skills.config]] name = "<skill>" enabled = false` entries in the agent's own `$CODEX_HOME/config.toml`.

Overrides do not apply to other harnesses, to remote (Fly) launches, or to sessions you start yourself outside Overdeck. If the override step fails at launch, the agent starts with every skill and the launcher prints a warning.

`pan sync` still installs every skill everywhere; hiding happens per launch, and no skill files are copied, moved, or deleted.

## Skill packs

A **skill pack** is a third-party git repository of skills, such as [eltmon/skills](https://github.com/eltmon/skills), a fork of [mattpocock/skills](https://github.com/mattpocock/skills). Overdeck pins each pack to one commit you approve, caches that commit, and mounts the pack skills you turn on into each launch through the harness's own plugin system. Pack skills are never copied into `~/.claude/skills` or `~/.agents/skills`, so they cannot collide with Overdeck's own skills or leak into sessions you start outside Overdeck.

### Adding a pack

```bash theme={null}
pan skills pack add mattpocock https://github.com/eltmon/skills --ref v1.2.3
```

Overdeck fetches the repository, resolves the ref to a commit, reads the pack, and prints a preview before it writes anything:

```
Pack mattpocock
  Source       https://github.com/eltmon/skills @ v1.2.3 (6acc160)
  Adapter      claude-plugin
  License      MIT
  Skills       25 (1 opt-in: setup-matt-pocock-skills)
  Executables  skills/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh, skills/engineering/wizard/template.sh
  Not applied  executables (2), project-mutating skills (1)
Adding a pack trusts this commit and enables nothing. Turn it on with: pan skills set --pack mattpocock on
```

Adding a pack trusts the resolved commit and turns nothing on. In a terminal, Overdeck asks `Trust this commit? [y/N]`. Without a terminal, pass `--yes`; otherwise nothing is written. The pack id must match `[a-z0-9][a-z0-9-]*` and cannot be a core skill name. Overdeck picks the adapter itself (the known-pack default, else `claude-plugin` when the repo has `.claude-plugin/plugin.json`, otherwise `plain`); pass `--adapter plain|claude-plugin|deft-readonly` to choose. A repository cannot register a pack by committing a file; only `pan skills pack add` can.

### Pinning and updates

The registry stores the **ref** you asked for (a tag or a branch) and the **trusted commit** you approved. Every launch mounts exactly the trusted commit, even if the tag or branch moves.

```bash theme={null}
pan skills pack update mattpocock            # re-resolve the ref
pan skills pack update mattpocock --ref v1.3.0
```

`update` prints the preview again with the skills added, removed, and changed since the trusted commit, plus any capabilities that are new. It moves the trusted commit only after you confirm. `pan skills pack list` shows when the ref has moved (`update available`); `--offline` skips that network check.

### Matt Pocock's skills from a fork

Overdeck's default source for the `mattpocock` pack is the operator-controlled fork `eltmon/skills`, pinned to the `v1.2.3` commit. A fork lets the operator decide when upstream changes arrive: sync the fork on GitHub, then run `pan skills pack update mattpocock --ref <tag>` to preview and re-pin. Any url works here; `KNOWN_PACKS` applies the `mattpocock` defaults by pack id, not by url.

`setup-matt-pocock-skills` is opt-in: turning the pack on never turns it on. Only `pan skills set mattpocock/setup-matt-pocock-skills on [--project <key>|--issue <id>]` does.

```bash theme={null}
pan skills set --pack mattpocock on                              # global: on
pan skills set --pack mattpocock off                             # global: undo

pan skills set --pack mattpocock on --project <key>               # project: on
pan skills set --pack mattpocock inherit --project <key>          # project: undo

pan skills set --pack mattpocock on --issue <id>                  # issue: on
pan skills set --pack mattpocock inherit --issue <id>              # issue: undo
```

### Names: `pack/skill` and `pack:skill`

Overdeck names a pack skill `pack/skill`, for example `mattpocock/grilling`. You use that id in the CLI, the dashboard, and the override files. The agent sees the skill as `pack:skill` (`mattpocock:grilling`), because the harness namespaces plugin skills. Overdeck's own `grilling` and `mattpocock:grilling` can both be present in the same session.

### Turning packs and pack skills on

Pack skills are **off** until you turn them on. You can turn on a whole pack or single skills, at the same three levels as other skills:

```bash theme={null}
pan skills set --pack mattpocock on                      # the whole pack, globally
pan skills set --pack mattpocock off --issue PAN-12      # off for one issue
pan skills set mattpocock/grilling on --project myapp    # one skill in one project
```

For a pack skill, Overdeck checks the levels from narrowest to widest. At each level, a value for the skill itself beats that level's pack toggle, and the first level with any value decides. With no value anywhere, the skill is off.

| Global | Project | Issue | Result |
| - | - | - | - |
| pack on | `mattpocock/tdd` off | — | `tdd` off (project) |
| pack on | — | pack off | every skill off (issue pack) |
| — | `mattpocock/grilling` on | pack off | `grilling` off (the issue level decides first) |
| `mattpocock/grilling` on | — | — | only `grilling` on |
| pack on | — | — | `setup-matt-pocock-skills` off (opt-in) |

**Opt-in skills** are skills that change files Overdeck owns, such as `setup-matt-pocock-skills`, which edits `CLAUDE.md`/`AGENTS.md` and writes tracker docs. The pack toggle never turns them on; only a value for that skill does.

### What is not applied

Overdeck mounts skill directories only. If a pack also carries hooks, MCP servers, commands, agents, context injection, git hooks, or scripts, the preview and the dashboard list them as **Not applied**, and none of them reach the agent. Scripts inside a skill directory are copied with the skill but never run by Overdeck.

### Where pack state is stored

| What | Stored in |
| - | - |
| Registry (url, ref, trusted commit) | `~/.overdeck/config.yaml`, under `skills.packs.<id>` |
| Global pack toggle | `~/.overdeck/config.yaml`, under `skills.pack_overrides.<id>: true` |
| Project pack toggle | `~/.overdeck/projects.yaml`, under `projects.<key>.skill_pack_overrides.<id>` |
| Issue pack toggle | The issue's skill override file, under `packs.<id>` |
| Single pack skills | The same `skills.overrides`, `skill_overrides`, and issue `skills:` maps, with `pack/skill` keys |

The cache lives in `~/.overdeck/packs/` and can be rebuilt at any time: `pan skills pack sync [id]` re-fetches it, and `pan skills pack gc [--max-age-days <n>]` removes mounts no launch uses. `pan skills pack remove <id>` unregisters a pack, clears its global toggle and global skill values, and deletes its cache; project and issue values stay but do nothing until the pack is added again.

### When pack changes apply

Packs apply to Overdeck-managed **Claude Code** and **Codex** sessions at their next launch, like other skill changes. Claude Code receives the pack as `--plugin-dir`; Codex gets a local `overdeck-packs` plugin marketplace in the agent's own `$CODEX_HOME`. Remote (Fly) launches and other harnesses get no packs. A launch never touches the network: if the trusted commit is not cached, the launch skips that pack and prints `run pan skills pack sync <id>`. If Claude Code also has the same upstream plugin installed, the dashboard warns that its skills will appear twice.

In the dashboard, packs appear above the skill list on the Skills page, in project settings, and in the issue view. The dashboard can turn packs on and off but not add them; it shows the `pan skills pack add` command instead.

### SageOx

[SageOx](https://github.com/sageox/ox) records coding-agent sessions and syncs them to a team ledger. Overdeck offers it as the `sageox` pack, built from the operator's fork [eltmon/ox](https://github.com/eltmon/ox). The fork adds a **host-managed mode**: with `OX_HOST_MANAGED=1`, `ox` writes nothing into the repository (no `AGENTS.md`/`CLAUDE.md` markers, no `.claude/settings.json` hooks), adds no attribution to commits or PRs, never asks the agent to run `ox init`, and stays offline unless Overdeck allows the network.

SageOx is **off by default**, for every project and issue. It works with **Claude Code** launches only; Codex launches never get SageOx skills or hooks, and print a warning when the pack would have been on.

**What leaves the machine:**

> SageOx records agent sessions on this machine. With uploads off (the default) Overdeck runs `ox` with the network off: nothing is sent. With uploads on for a project, redacted session transcripts and session metadata are uploaded to the SageOx cloud ledger for that repo, and `ox` may fetch team context. Requires the eltmon/ox build; see `pan doctor`.

The Skills page shows the same text on the `sageox` pack row.

#### One-time setup

1. **Build `ox` from the fork**, at the commit the pack trusts. Overdeck never installs `ox`. The fork needs Go 1.26 (the default `GOTOOLCHAIN=auto` downloads it).

   ```bash theme={null}
   git clone git@github.com:eltmon/ox.git && cd ox
   git switch --detach <trusted commit>      # shown by: pan skills pack list
   go build -o ~/.local/bin/ox ./cmd/ox
   ox host-contract --json                   # must print "contract":"overdeck-host/1"
   ```

2. **Register the pack** (the ref is a branch or tag in the fork):

   ```bash theme={null}
   pan skills pack add sageox https://github.com/eltmon/ox --ref overdeck/host-managed
   ```

   The repo-writing skills (`ox-cli-init`, `ox-cli-attest`, `ox-cli-skill-manager`, `ox-cli-pr-header`, `ox-cli-plan`, and the `ox-cli-cart*` skills) are opt-in: the pack toggle never turns them on.

3. **In each repository you choose**, log in and initialize SageOx yourself, once. Overdeck never runs these commands. Host-managed `ox init` writes only `.sageox/` (no `AGENTS.md`/`CLAUDE.md` markers, no hook files, no git hooks). It registers the repository with SageOx, so it needs the network:

   ```bash theme={null}
   ox login
   OX_HOST_MANAGED=1 OX_HOST_NETWORK=on ox init
   ox status        # wait until it shows the project's ledger
   ```

   Session recording writes into a local clone of the project's SageOx ledger. The ox daemon that `ox init` starts clones it; wait until `ox status` shows the ledger. With uploads off, Overdeck keeps `ox` offline and no daemon runs, so without this clone SageOx records nothing.

4. **Turn the pack on** for that project (or one issue):

   ```bash theme={null}
   pan skills set --pack sageox on --project myapp
   ```

#### Uploads

Uploads are a second, separate opt-in per project. They are off until you turn them on:

```bash theme={null}
pan skills pack sageox upload on --project myapp    # writes sageox_upload: enabled in projects.yaml
pan skills pack sageox upload off --project myapp
pan skills pack sageox status [--project <key>] [--json]
```

`status` shows, for each project, whether the pack is on (and from which level) and whether uploads are enabled. With uploads off, Overdeck sets `OX_HOST_NETWORK=off` and `OX_SESSION_PUBLISHING=manual`, so sessions stay on this machine. With uploads on, it sets `OX_HOST_NETWORK=on` and `OX_SESSION_PUBLISHING=auto`.

#### What a launch gets

When the pack is on for a Claude Code launch, Overdeck checks two more things at launch time: the launch's git root has a `.sageox/` directory, and the `ox` on `PATH` answers `ox host-contract --json` within 2 seconds. When all hold, the launch's `--settings` JSON carries:

* the env `OX_HOST_MANAGED=1`, `OX_PROJECT_ROOT=<git root>`, `OX_HOST_NETWORK`, `OX_SESSION_PUBLISHING`, `SAGEOX_TELEMETRY=false`, `SAGEOX_FRICTION=false`, `SAGEOX_DAEMON=false`, and `OX_NO_DAEMON=1`;
* one `ox agent hook <event>` hook for each of `SessionStart`, `PreCompact`, `PostToolUse`, `Stop`, `SessionEnd`, and `UserPromptSubmit`, with the same env written inline in each hook command;
* the `sageox` pack skills you turned on.

These hooks come from Overdeck, not from the pack; the pack's own capabilities are still **Not applied**. If any check fails, or anything goes wrong, the launch continues without SageOx: no env, no hooks, no `sageox` skills, and one `[launcher] WARNING:` line naming the reason. Turning the pack off removes all of it at the next launch.

#### What `pan doctor` checks

When the `sageox` pack is registered, `pan doctor` adds a **SageOx (ox)** row. It is `ok` when `ox` answers the `overdeck-host/1` contract and was built from the pack's trusted commit. It warns, with the build command as the fix, when `ox` is missing, is upstream `ox` without the host contract, or was built from a different commit. Without the pack, there is no row.

### Deft

Deft's skills depend on its engine and project files, so Overdeck mounts only a read-only subset through the `deft-readonly` adapter; see [Deft Directive](#deft-directive).

## Deft Directive

[Deft Directive](https://github.com/eltmon/directive) is a process engine. `directive init` installs it by writing tracked files into a repository: an `AGENTS.md` managed section, agent hooks that call `deft-hook`, `.githooks/` with `core.hooksPath`, a `package.json` pin of `@deftai/directive`, `deft-directive-*` pointer skills, and an `xbrief/` tree. A repository with that deposit is a **Directive project**.

Overdeck never runs a Deft CLI, never installs the engine, and never writes a tracked file in any project. It offers three levels:

| Level | What you get |
| - | - |
| Off | No Deft skills. In a Directive project, an explicit off also turns the deposit's enforcement off for Overdeck launches (the kill switch below). |
| Methodology on | The read-only `deft` pack: seven Deft skills that need no engine, mounted per launch with a host notice. In a Directive project you can also turn on managed mode. |
| Full Deft | Deft owns worktrees, review, and merge. Overdeck does not target this level. |

### Adding the deft pack

```bash theme={null}
pan skills pack add deft https://github.com/eltmon/directive --ref <ref>
pan skills set --pack deft on
```

`deft` is a known pack, so Overdeck picks the `deft-readonly` adapter. The preview lists `Skills 7` and `Not applied hooks, context injection, git hooks, requires CLI (directive)`. The adapter reads `content/skills/deft-directive-<name>/SKILL.md` at the trusted commit and keeps only the read-only allowlist. Each skill is named by its stripped name, so the agent sees `deft:glossary`, never `deft:deft-directive-glossary`, and Overdeck's id is `deft/glossary`.

### Skill map

Every Deft skill has one class. Only `compatible` and `translated` skills are mounted. A skill that appears at a newer pinned commit and is not in this map is excluded as unreviewed. The map is verified at eltmon/directive 48e8cbf (v0.119.10-16).

| Deft skill | Class | Overdeck equivalent or reason |
| - | - | - |
| glossary | compatible | Conversation-only; does not write `UBIQUITOUS_LANGUAGE.md` unless asked |
| debug | translated | `task verify:investigation` is unavailable; the ledger goes to chat |
| design-critique | translated | `task issue:ingest` is unavailable; the next step is `pan issues` or the operator |
| gh-arch | translated | `task slice:record` is unavailable; file follow-ups in Overdeck's tracker |
| write-skill | translated | New skills go to `<project>/.pan/skills/<name>/SKILL.md` |
| probe | translated | Never writes `xbrief/proposed/`; results go to chat |
| cost | translated | Reads `xbrief/PROJECT-DEFINITION.xbrief.json` only when present |
| xbrief | conflicting | `write-xbrief` |
| swarm | conflicting | `pan-swarm` |
| pre-pr | conflicting | `work-complete` |
| review-cycle | conflicting | `pan-code-review` |
| refinement | conflicting | `pan-plan` |
| decompose | conflicting | `write-xbrief` |
| gh-slice | conflicting | `pan-plan` |
| build | conflicting | `pan-start` |
| setup | conflicting | `pan-new-project` (it runs `directive init`) |
| sync | conflicting | `pan-sync` (it runs an npm refresh of the deposit) |
| interview | runtime-dependent | Needs Deft interview state |
| issue-eval | runtime-dependent | Needs Deft Stage A tooling |
| portfolio-priority | runtime-dependent | Needs Deft triage and RFC state |
| product-signal | runtime-dependent | Consent and upload flow owned by Deft |
| feedback | runtime-dependent | Escalates gaps through Deft tooling |
| article-review | runtime-dependent | Feeds Deft's improvement backlog |
| release | excluded | Releases the Deft framework itself |
| triage | excluded | Withdrawn upstream |

### Host notice and CLI deny

The mount inserts a host notice after the frontmatter of every mounted Deft `SKILL.md`. It tells the agent not to run `directive init`, `directive update`, `directive bootstrap`, or `deft session:start`; not to install packages, change git hooks or `core.hooksPath`, edit `AGENTS.md`, or write under `xbrief/`; that Overdeck owns planning (`.pan/specs`), worktrees, review, and merge; to skip a `task` or `deft` step that is not installed and report in chat; and not to write repository files unless the operator asks. It also lists the Overdeck equivalent of each conflicting Deft skill.

When a Claude Code launch mounts any `deft/*` skill in a project that is **not** a Directive project, the launch settings also deny Deft's mutating CLIs:

```
Bash(directive:*)  Bash(deft:*)  Bash(deft-hook:*)  Bash(npx @deftai/directive:*)
Bash(npm install @deftai/directive:*)  Bash(npm i @deftai/directive:*)
Bash(pnpm add @deftai/directive:*)  Bash(git config core.hooksPath:*)
```

In a Directive project no deny is added, because Deft is that project's own tool. Codex has no equivalent deny setting, so on Codex the host notice is the only boundary.

### What a launch does in a Directive project

Each Overdeck-managed Claude Code or Codex launch detects a Directive project at the launch directory's repository root. Detection reads files only (`.deft/core/VERSION`, the `AGENTS.md` managed-section marker, or the `@deftai/directive` pin) and is never stored. **Explicit off** means the `deft` pack toggle resolves off at the issue or project level. The default (no value anywhere) is not explicit off, and the global level has no off value, so it never is.

| Directive project | `deft` toggle | Managed mode | Result |
| - | - | - | - |
| no | any | — | Nothing exported; Claude gets the CLI deny list when deft skills are mounted |
| yes | explicit off (issue or project) | any | Kill switch: `DEFT_DIRECTIVE_DISABLE=1`, the flag file in issue worktrees, and the deposit's `deft-directive-*` pointer skills hidden |
| yes | on, or default | managed | `DEFT_ORCHESTRATOR=overdeck` |
| yes | on, or default | not managed | Nothing exported; Deft runs as the project configured it |

The **kill switch** is Deft's own `.deft-directive-disable` root file, honored by engines from v0.92.0 when the file is untracked. Overdeck writes it only when the launch runs in an issue worktree (`workspaces/feature-<issue>/`). The file starts with `# overdeck:deft-directive-disable`, and Overdeck adds `/.deft-directive-disable` to the repository's `.git/info/exclude` when nothing ignores it yet, so `git status` stays clean. When the toggle goes back to on or inherit, Overdeck deletes the flag only if its first line is that marker; a flag you wrote yourself is never touched, and a tracked flag is never changed. Review agents, test agents, and conversations launched at the project root get the environment variable only.

A launch prints one provenance line to stderr, for example `[launcher] deft: pack master (48e8cbf0e781); project directive engine ^0.119.10; kill switch`. If anything in the Deft step fails, the launch prints `[launcher] WARNING: deft integration not applied: <message>`, removes the Deft env file, and continues with its other skill settings and packs.

### Managed mode

Managed mode is a per-project decision: Deft methodology on, with Overdeck owning worktrees, review, merge, and the pipeline xBRIEF.

```bash theme={null}
pan skills deft status [--project <key>] [--json]   # detection, pack, skill map, managed mode, ownership report
pan skills deft enable --project <key> [--yes]      # print the ownership plan, then store the decision
pan skills deft disable --project <key>             # remove the decision; project files untouched
```

`enable` refuses a project that is not a Directive project (Overdeck never runs `directive init`). It prints the ownership report, one owner per concern (xbrief, context, agent hooks, git hooks, worktrees, gates, task state, review, release, skills, workspace settings), and asks `Enable managed mode with this ownership plan? [y/N]`. Without a terminal, pass `--yes`; otherwise nothing is written. It stores only `projects.<key>.deft_integration: { mode: managed, plan_digest, enabled_at }` in `~/.overdeck/projects.yaml`, where `plan_digest` is the sha256 of the report text you saw. Launches in a managed project that is not off export `DEFT_ORCHESTRATOR=overdeck`.

### Environment contract

Overdeck exports at most these two literal lines, from a per-launch env file that the launcher reads with an allowlist and never sources:

| Variable | Value | Meaning to the engine |
| - | - | - |
| `DEFT_DIRECTIVE_DISABLE` | `1` | Same as an untracked root `.deft-directive-disable` |
| `DEFT_ORCHESTRATOR` | `overdeck` | External-orchestrator mode: Deft enforcement defers to the host; Deft contributes methodology only |

Both variables are a no-op until your project pins an engine that reads them ([PAN-4425](https://github.com/eltmon/overdeck/issues/4425)). The flag file works on every engine from v0.92.0.

### Limits

* **Git hooks.** The deposited `.githooks/pre-commit` runs `deft verify:branch` and does not check the kill switch; whether `verify:branch` itself reads it is unverified. Feature-branch commits pass `verify:branch`. Main-branch plan-artifact commits in a Directive plan home may be refused.
* **Workspace settings.** In a Directive project `.claude/settings.json` is a tracked Deft deposit, and Overdeck's workspace creation merges its own hooks into it, which leaves that file modified in the worktree.
* **Scope.** Detection runs at the launch directory's repository root only, not in polyrepo sub-repositories. There is no conversation-level toggle; conversations inherit global and project toggles.

## Subagents

Overdeck includes specialized subagent templates for common development tasks. Subagents are invoked via the Task tool or convoy orchestration for parallel execution.

### Code Review Subagents

| Subagent | Model | Focus | Output |
| - | - | - | - |
| `code-review-correctness` | haiku | Logic errors, edge cases, type safety | `.claude/reviews/<timestamp>-correctness.md` |
| `code-review-security` | sonnet | OWASP Top 10, vulnerabilities | `.claude/reviews/<timestamp>-security.md` |
| `code-review-performance` | haiku | Algorithms, N+1 queries, memory | `.claude/reviews/<timestamp>-performance.md` |
| `code-review-synthesis` | sonnet | Combines all findings into unified report | `.claude/reviews/<timestamp>-synthesis.md` |

**Usage Example:**

```bash theme={null}
/pan-code-review --files "src/auth/*.ts"
```

This spawns all three reviewers in parallel, then synthesizes their findings into a prioritized report.

### Planning & Exploration Subagents

Overdeck ships no custom planning or exploration subagent files. Planning runs as the `plan` role (`roles/plan.md`), and any role that needs parallel read-only exploration uses Claude Code's built-in `Explore` and `general-purpose` subagent types, which inherit the parent session's model and provider routing. Custom `.claude/agents/` files with a pinned `model:` broke under CLIProxy-routed sessions; see the "Why no ambient subagents" section in `docs/ROLES.md`.

## Best Practices

**When creating skills:**

* **Be specific** - Include exact commands, not just concepts
* **Include examples** - Show concrete usage patterns
* **Add checklists** - Help agents verify completion
* **Cross-reference** - Link to related skills and guides
* **Test thoroughly** - Verify skills work end-to-end

**When using skills:**

* **Invoke early** - Start with a skill, don't switch mid-task
* **Follow fully** - Don't skip steps or customize on-the-fly
* **Report issues** - If a skill doesn't work, improve it
* **Combine wisely** - Some skills complement each other, others conflict

## Related Guides

* [Creating Skills](/cli/core-commands#pan-skill-creator) - Detailed skill creation guide
* [Convoys](/features/convoys) - Parallel subagent execution
* [Subagents](/cli/core-commands#pan-subagent-creator) - Custom subagent templates


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.