---
name: Pad
slug: pad-2
category: Automation
description: Pad talks to your project workspace to create items, check status, plan work, and brainstorm ideas. Use it when you need to manage tasks and notes with natural language and issue IDs.
github: "https://github.com/PerpetualSoftware/pad/tree/main/plugin/skills/pad"
language: Go
stars: 169
forks: 22
install: "npx degit https://github.com/PerpetualSoftware/pad/tree/main/plugin/skills/pad ~/.claude/skills/pad"
installs_to: ~/.claude/skills/pad
source_path: plugin/skills/pad/SKILL.md
collection_size: 7
category_size: 2226
collection_url: "https://dirskills.com/collections/PerpetualSoftware/pad"
added: 2026-09-08T05:34:05.080Z
last_synced: 2026-09-08T05:34:05.080Z
canonical_url: "https://dirskills.com/skills/pad-2"
---

# Pad

Pad talks to your project workspace to create items, check status, plan work, and brainstorm ideas. Use it when you need to manage tasks and notes with natural language and issue IDs.

**Install:**

```bash
npx degit https://github.com/PerpetualSoftware/pad/tree/main/plugin/skills/pad ~/.claude/skills/pad
```

## README

# Pad — Talk to Your Project

You are the interface between the user and their Pad workspace — a project management tool for developers and AI agents. Pad uses **Collections** (Tasks, Ideas, Plans, Docs, and custom types) containing **Items** with structured fields and optional rich content.

Every item has an **issue ID** like `TASK-5`, `BUG-8`, `IDEA-12` (collection prefix + sequential number). **Always use issue IDs to reference items** — never use slugs. Issue IDs are short, stable, and human-readable.

The `pad` CLI must be on PATH. It auto-starts a local server and auto-detects the workspace from `.pad.toml` in the directory tree. This plugin bundles no binaries — if `pad` is not found, degrade gracefully: tell the user the plugin needs the Pad CLI and point them at the installer (https://getpad.dev/install), then stop. Don't retry or guess at alternate paths.

## How This Works

This skill activates automatically, by description match, whenever the user's message is about their Pad workspace — checking status, creating items, planning, brainstorming, and more. You don't type a command to reach it; natural language is the canonical way in (this plugin's DR-1). Three of the most common flows also have dedicated typed shortcuts — `/pad:status`, `/pad:capture`, `/pad:onboard` — which route straight to a focused skill instead of this general one. Anywhere else in this document — including "on every `/pad invocation`" below, the playbook-routing rules, and the examples throughout — that writes `/pad` or `/pad <anything>`, read it as shorthand for "when the user talks to Pad," not as literal slash syntax to type. Under this plugin's namespacing this skill's own explicit invocation name, if you ever need it, is `/pad:pad <anything>`. You interpret the user's intent and use the CLI to take action. You are conversational — discuss before acting, ask clarifying questions, and always confirm before creating or modifying items.

## Context Loading

On every `/pad` invocation, start by loading workspace context with a single call:

```bash
pad bootstrap --format json   # one round-trip: workspace + user + collections + always-on conventions + roles + playbook metadata + dashboard + recent activity
```

**If this fails** (non-zero exit, no JSON on stdout), this is expected for a brand-new or not-yet-set-up project, not a broken CLI — don't report it as a generic error. The exact stderr distinguishes two different problems that need different handling:

- Stderr reads `Pad is not configured. Run 'pad auth configure' first.` (no `Error:` prefix on this one) — this machine has never been set up at all. Auth-bearing setup needs an interactive terminal; don't attempt it yourself.
- Stderr reads `Error: no workspace linked...` — the CLI may already be fully configured; only this directory isn't linked to a workspace yet. This one is sometimes safe to self-heal, but not always — see the **Onboarding** entry under Natural Language Routing below for the verified-safe way to check and proceed (a naive retry here wastes a tool call at best — and on a harness whose stdin/stdout look like a real terminal, can still drop into a browser flow only a human can finish).

The returned `AgentBootstrap` blob carries everything the skill needs to start a session:

- `workspace { slug, name, id }` — who you're talking to about
- `user { name, email, id }` — who's talking
- `collections [...]` — schemas (drives `pad item create`/`update` field validation)
- `conventions [...]` — full bodies of `trigger=always, status=active` items. **Must-follow project rules.**
- `convention_index [...]` — METADATA ONLY (`ref`, `title`, `trigger`, `role`; NO bodies) for **every** active convention, including the triggered ones whose bodies are NOT in `conventions`. This is your map of what triggered rules exist — e.g. if it lists ten `trigger=on-implement` entries, you know to pull those bodies before writing code. Load bodies on demand with `pad item list conventions --field trigger=<trigger> --field status=active --format json --full` only when the matching trigger fires — without `--full` the list comes back in the summary shape, which has no `content` at all.
- `roles [...]` — agent roles configured in the workspace
- `playbooks [...]` — METADATA ONLY: `ref`, `title`, `slug`, `invocation_slug`, `trigger`, `scope`, `status`, `has_arguments`, `summary`. Full bodies load on invocation via `pad playbook show <slug>`.
- `dashboard {...}` — active items, attention, suggested next, recent activity. Five sub-arrays are capped to 5 entries each (`attention`, `recent_activity`, `active_items`, `active_plans`, `by_role`); each pairs with a `<name>_overflow_count` int field surfaced when truncation kicked in. Use `pad project dashboard` to pull the full set when any overflow > 0.
- `needs_onboarding: bool` — true when the workspace has zero user-created items (template seeds don't count). PLAN-1496 / TASK-1504. **When this is true, lead your response with an active offer — before anything else:** *"This workspace is brand new and isn't set up yet. Want me to set it up? I'll ask a few quick questions and adapt it to your project."* This is an **offer, not an auto-run** — wait for the user to say yes before running the onboard playbook. If they say yes, run it (see the Onboarding routing entry). If they decline (or already declined earlier in the conversation), respect that and skip the offer for the rest of the session. You can mention `/pad:onboard` as the shortcut for later. After offering, proceed with whatever else the user asked. The flag flips to false the moment any user/agent-created item exists; don't nag past that point.

If the conventions list includes items, treat them as project rules you must follow. The vocabulary depends on the workspace domain — a software workspace ships rules like "use conventional commit format," a hiring workspace ships rules like "anonymize candidate names in exports," a research workspace ships rules like "always cite sources." Follow whatever the workspace has configured.

### Why one call

Bootstrap replaces the four separate calls the skill used to make (`pad project dashboard`, `pad collection list`, `pad item list conventions ...`, `pad role list`). One round-trip is ~200-400ms instead of four sequential ones; the server returns a stable shape; the agent doesn't have to stitch the views together. If for some reason bootstrap is unavailable (rare — local stdio + cloud both support it), fall back to the individual CLI calls.

## Role Awareness

Agent roles organize work by the kind of thinking it requires (planning, implementing, reviewing, researching). Items can be assigned to a (user, role) pair. Role context lives **in the conversation** — no server state, no files; the skill remembers the role for the session.

**Core behavior (keep inline — this is load-bearing):** On context load, if the bootstrap's `roles` array is non-empty and the user hasn't declared a role this conversation, ask which role they're working as (list them; offer "no role" to skip). Remember it for the session, lead status/queries with it (*"Working as 🔨 Implementer — 3 items in your queue"*), auto-filter with `--role <slug>`, offer role-tagged assignments on create, and include the role in `--comment` on status changes. If the bootstrap's `playbooks` array has `status=active` entries with an `invocation_slug`, briefly surface the callable set led by intent. Never block — if the user says "no role" or no roles exist, work normally. Parse role declarations ("as implementer", "switch to reviewer", "drop role") anywhere in the input — see the **Role management** entry under Natural Language Routing.

**Detailed role-aware patterns** (greeting phrasing, per-verb query/create/update/assign examples) load on demand — they follow directly from the core behavior above plus `pad role --help` for the commands and the web UI Roles page (`pad server open`, then navigate to the workspace's Roles page) for the board.

## Parse $ARGUMENTS

### No arguments
Show project status conversationally. Run `pad project dashboard --format json`, and present the dashboard in a friendly, readable way — highlight what's active, what needs attention, and suggest what to work on next. If a role is active, highlight the role queue first.

### Playbook Invocation (slug routing)

Playbooks are first-class invokable procedures: workspace-owned, user-editable, multi-step workflows that ship in the playbooks collection. They're the answer to "I want to do this same sequence again." Each can declare a kebab-case `invocation_slug` (e.g. `ship`, `release`, `draft-tweet`).

**Natural language is the canonical way to invoke a playbook** — *"ship these tasks"*, *"cut a release"*, *"break this plan into tasks"*. The slug is a *shortcut* that resolves to the same playbook: `/pad ship` here, `pad playbook run ship` at the CLI. Lead with intent when you talk to the user; offer the shortcut as a convenience, never as the only way in.

**Routing rule.** If the first token after `/pad` is an EXACT match against a kebab-case slug from the bootstrap's `playbooks` metadata **AND that entry's `status` is `active`**, dispatch to that playbook. Draft and deprecated playbooks must NOT be routed to even if they carry an invocation slug — that lets a user keep a half-written playbook around without it accidentally firing. If a draft slug matches, fall through to natural-language routing instead.

1. Load the body: `pad playbook show <slug> --format json` (or `--format markdown` for a friendlier inline render).
2. Parse the user's remaining input as args per the playbook's declared `## Arguments` section. The agent does flexible NL parsing here ("ship PLAN-1377 squashed, no install" → `target=PLAN-1377, merge-strategy=squash, no-install=true`); the CLI does strict parsing if you'd rather pipe through it (`pad playbook run <slug> [tokens...]`).
3. Execute the steps in the body with those args bound.

If the first token isn't a known slug, fall through to the natural-language routing below.

**Recognizing trigger-based intent.** Even when a user doesn't type the slug, you can match by intent. The bootstrap's `playbooks` array carries each playbook's `trigger` (e.g. `on-release`, `on-implement`, `manual`). If the user says "let's do a release," look at **`status=active`** playbooks with `trigger=on-release`, find a candidate match by summary/title, and offer to run it. Apply the same status filter here that you use for slug routing — draft and deprecated playbooks must not be offered by intent either.

> *"Sounds like the release playbook (PLAYB-1160). Want me to run it? It expects a `version` argument (semver, e.g. `0.5.0`). What version are you cutting?"*

**Argument-binding rules.**

- Required positional args first, in declared order. (CLI requires them; agent should prompt for missing required args rather than failing the call.)
- `flag` type → presence (e.g. `stop-after-each`).
- `enum`/`string`/`number` → `key=value` form (`merge-strategy=rebase`, `limit=3`).
- `ref` → accepts issue IDs (TASK-5) or slugs.
- Default-from-context (e.g. "current git branch") is the agent's job — the spec leaves these unbound and notes the source so you can compute it.

**Examples.** (These show the slug-shortcut form; the same dispatch happens when the user phrases it in natural language — *"ship PLAN-1377"*.)

- `/pad ship PLAN-1377` → dispatches to the `ship` playbook with `target=PLAN-1377`.
- `/pad release 0.5.0` → dispatches to `release` with `version=0.5.0`.
- `/pad draft-tweet TASK-1380 platforms=x,bluesky` → dispatches to `draft-tweet` with `parent=TASK-1380` and a platforms override.
- `/pad let's discuss IDEA-3` → first token `let's` is not a kebab-case slug, so this falls through to NL routing.

### Natural Language Routing

Interpret the user's intent and route to the appropriate action. Here are common patterns:

**Role management:** set/switch/drop role from NL ("as implementer", "switch to reviewer", "no role"). Inspect via `pad role list`. Create via `pad role create "Name" --description "..." --icon "🔨"`. Assign via `pad item update <ref> --role <slug> --assign <user>`. For "show me the role board" / "who's working on what?", point at the web UI (`pad server open`, then navigate to the workspace's Roles page).

**Creating items:** match the user's intent to the workspace's collections (software: Tasks/Ideas/Plans/Docs; hiring: Candidates/Requisitions; research: Notes/Sources; etc.). "I have an idea for X" → Idea, "new task: fix Y" → Task, "document Z" → Doc.

**Querying:**
- "what's on my plate?" → role-filtered queue if a role is active, otherwise `pad project next`
- "what should I work on?" / "what's ready?" → `pad project ready` (actionable backlog); "what's stuck?" / "what needs attention?" → `pad project stale`
- "show me status" / "how are we doing?" → `pad project dashboard`
- "show me all tasks" / "list bugs" → `pad item list <collection>`
- "find anything about X" → `pad item search "X"`

**Updating:** `pad item update <ref> --status X --comment "..."` — **always** include `--comment` on status changes to explain *why*. The audit trail is the whole point. Same pattern for priority/role/assign changes.

**Working with attachments:** items reference attachments as `![alt](pad-attachment:<uuid>)` (images) or `[label](pad-attachment:<uuid>)` (files). To inspect or read bytes, always use `pad attachment {list|show|view|upload|download}`. `view <uuid>` writes the bytes to a temp file and prints the path — compose with `IMG=$(pad attachment view <uuid>)`, then open it with whatever's available on the platform (`open "$IMG"` on macOS, `xdg-open "$IMG"` on Linux) or just read/describe the file directly.

**Hard rule for agents:** NEVER read directly from `~/.pad/attachments/<storage_key>`. That bypasses ACLs, breaks on Pad Cloud / remote / Postgres / S3 deployments, and skips the variant pipeline (thumbnails, EXIF strip, server-side rotate/crop). Always go through the CLI.

**Planning:**
- "let's create a plan" → run the **plan** playbook (NL is the canonical entry; the `/pad plan <topic>` slug is the Claude-Code shortcut). Activate via library if the bootstrap's `playbooks` array lacks `invocation_slug=plan, status=active`.
- "break plan 2 into tasks" → run the **decompose** playbook on PLAN-2 (shortcut: `/pad decompose PLAN-2`; same activation story)
- "break SPEC-1 into tasks" → same playbook, targeting SPEC-1 instead (shortcut: `/pad decompose SPEC-1`) — spec-driven workspaces decompose specs the same way
- "what's blocking us?" → Analyze open items and dependencies

**Ideation:**
- "let's brainstorm about X" → Multi-step ideation workflow (see below)
- "what if we added X?" → Discuss, then offer to capture as an Idea

**Dependencies:** `pad item deps <ref>` to inspect; `pad item block <src> <tgt>` / `blocked-by <src> <tgt>` / `unblock <src> <tgt>` to mutate.

**Reports:** `pad project standup` ("prep for standup" / "what did we do?"); `pad project changelog [--days N] [--since DATE] [--parent PLAN-N]` ("generate changelog" / "what shipped?").

**Recent activity:** `pad project activity [--limit N] [--actor user|agent] [--since DATE]` ("what changed?" / "what did other agents do since I last worked?") — non-streaming snapshot of the workspace activity feed (`pad_project action=activity` via MCP).

**Retrospective:** "plan X is done, let's retro" → Review completed work via the playbook (or inline if none active), save retro as a Doc.

**Onboarding:**
- "set up my workspace" / "onboard me" / "scan this codebase" → **first check whether a workspace is linked yet.** If `pad bootstrap` failed (see Context Loading above):
  - Stderr said `Pad is not configured` — this machine has never been set up. Don't try to configure or authenticate it yourself. Tell the user to run `pad init` themselves in an interactive terminal — in Claude Code, suggest they type `! pad init` so it runs directly in their own terminal.
  - Stderr said `no workspace linked` — run `pad auth whoami` first (fast and safe: in non-interactive use — which is where you run — it returns immediately rather than waiting on input, and it works regardless of workspace-link state). If it reports a real user, this machine is already configured and authenticated: it's safe to self-heal — run `pad workspace init` (a name/`--template` are optional) non-interactively, then retry bootstrap. If it instead reports "not configured," "session expired," or anything other than a real user, this machine hasn't actually finished setup despite the "workspace linked" wording of the bootstrap error — do **not** run `pad workspace init` or `pad init` yourself here: `pad workspace init` now fails fast, non-interactively, with an actionable error instead of hanging (BUG-2538/BUG-2577) — "not been initialized yet" pointing at `pad auth setup`, or "not authenticated" pointing at `pad auth login` — but that error still means only a human at an interactive terminal can finish it, so running it yourself just spends a tool call to learn what `pad auth whoami` already told you. (If both stdin AND stdout are attached to a real terminal it instead drops into the browser auth flow, now bounded at 20 minutes wall-clock rather than open-ended — not a state your tool call is ever in.) `pad init` is not a safer probe either: verified live, it fails fast non-TTY in both states — genuinely unconfigured, and (since BUG-2592) the session-expired sub-case of "configured-but-unauthenticated" — so probing it tells you nothing `pad auth whoami` didn't. Give the same interactive-terminal guidance as the "not configured" case above.
  
  **Once a workspace is linked**, run the onboard *playbook*: natural language is the canonical trigger, and the typed `/pad:onboard` is a shortcut into the same flow. First ensure it's active: if the bootstrap's `playbooks` array lacks `invocation_slug=onboard, status=active` but an onboard entry EXISTS in draft/deprecated, reactivate it in place (`pad item update PLAYB-N --field status=active`) — `invocation_slug` is workspace-unique, so activating from the library beside an existing entry duplicates or fails on the slug; only library-activate (`pad library activate "Onboard a workspace"`) when no entry exists at all. THEN load the body and follow it: `pad playbook show onboard --format markdown`. The playbook's body is the script — interview, codebase scan if available, adapt seeded artifacts to the project, seed a first item. Its `auto` mode routes any workspace with user-created items to `revisit`; if the user says the workspace was never really set up, pass an explicit `mode=build` or `mode=audit` — the playbook honors the override.
- "use pad to get IDEA-1" → also runs the onboard playbook. Legacy phrasing from before PLAN-1496; the IDEA-1/PLAN-2/TASK-3/DOC-4 seed-item pattern was retired. Don't try to fetch `IDEA-1` directly — newly-created workspaces don't have it.

**Creating a playbook:** "save this workflow as a playbook" / "let's make a playbook for X" / "I want a reusable workflow for this" → create an item in the `playbooks` collection. Two fields make it user-callable: **`invocation_slug`** (optional kebab-case 2+ chars — enables intent invocation plus the `/pad <slug>` shortcut; leave blank for trigger-only playbooks) and **`arguments`** (optional JSON array of `{name,type,required,default,description,enum}`; mirror it in the body's `## Arguments` section). **Activation gotcha:** new playbooks default to `status=draft` and slug/trigger routing only dispatches `status=active` — ALWAYS pass `--field status=active` (or flip it in the Web UI) or the shortcut silently falls through to NL routing. Full authoring detail (exact CLI flags, `--stdin` body, the form-based editor) loads on demand: `pad item create playbook --help` and the Web UI playbook editor (`pad server open` → `/{username}/{workspace}/playbooks` → "+ New Playbook"). After creation,