# skills

Source: https://permdock.com/docs/cli/skills

Install the PermDock Agent Skills (permdock, permdock-wire, permdock-audit and the topic skills) from the permdock package or from skills.sh.

PermDock ships eight Agent Skills so a coding agent can wire, extend and audit permissions without reading library source. Skills follow the `SKILL.md` format governed by the Agentic AI Foundation, are published on [skills.sh](https://skills.sh), and are bundled in the `permdock` npm package under `skills/` so the version an agent reads always matches the version the app runs. See [Agent docs standards](/docs/standards/agent-docs-standards).

`permdock skills install` copies the bundled skills from `node_modules/permdock/skills/` into the folders your agent reads. You can still install from skills.sh.

## Install [#install]

```bash
# from skills.sh (no PermDock install required)
npx skills add ScaleDockHQ/PermDock
npx skills add ScaleDockHQ/PermDock --skill permdock-approvals

# with permdock installed
pnpm exec permdock skills install
pnpm exec permdock skills install --agent cursor --agent claude
pnpm exec permdock skills list
pnpm exec permdock skills update
pnpm exec permdock skills install --check
```

`install` copies every skill from `node_modules/permdock/skills/` into the folders the detected agents read (`.agents/skills/`, `.claude/skills/`, `.cursor/skills/`) and records the installed version in a lock entry so `permdock doctor` can report drift (`PD005`). `skills.sh` installs land in the same folders, and `--skill <name>` picks one.

Without `--agent`, `install` and `update` on a terminal ask which agents to install for, with the agents whose folder (`.agents`, `.claude`, `.cursor`) the project already has preselected; cancelling exits `2` and writes nothing. In CI, in a pipe or with `--json` there is no prompt and every folder is written, as before.

An agent folder may be a symlink to another one (`.claude/skills` to `.agents/skills`), and so may a single skill folder (`.claude/skills/permdock` to `.agents/skills/permdock`). `install` follows the link and writes the files once, at the target, and reports the linked folder as `linked .claude/skills/permdock to .agents/skills/permdock`. A link whose target does not exist yet gets the target created.

## Check [#check]

`install --check` (or `update --check`) compares every installed skill file with the one this version ships and writes nothing. It exits `0` when they match and `1` with the list of missing or changed files otherwise, so CI can fail when someone upgrades `permdock` without reinstalling the skills. Without `--agent` it checks the agent folders the project has (`.agents`, `.claude`, `.cursor`), or every folder when it has none, and it never prompts. A linked folder is checked once, through its target.

## The skills [#the-skills]

Every skill has the same shape: the inputs to find out first, numbered invariants, a numbered workflow whose steps each end in a check, a "Verify before done" list and a reference index. Longer material sits in `references/` next to `SKILL.md`. Protocol rules (OAuth, JWT, MCP authorization, A2A, Problem Details) are deferred to the matching skill in `ScaleDockHQ/scaledock-skills` rather than repeated.

| Skill | Use it for |
| --- | --- |
| `permdock` | The mental model and invariants, reading a `Decision`, `explain` for an unexpected denial, `doctor`, the docs MCP, and which skill to load next |
| `permdock-wire` | Adding PermDock to an app: detect the framework and validator, `permissions.ts`, `policy.ts`, the factory file, the first check and UI guard, CLI checks in CI; one reference section per framework adapter |
| `permdock-audit` | Reviewing an installation or a pull request: ungranted and unused leaves, validation and identity, test gaps, the ASI02 and ASI03 mapping, and each topic skill's Verify list |
| `permdock-agents` | Agent tool calls: principal and actor, policy `delegations`, one permission per tool, AI SDK, Claude Agent SDK, Eve, OpenAI, MCP, A2A, WebMCP and Web Bot Auth ([delegation](/docs/security/delegation)) |
| `permdock-approvals` | Human approval: `approval` options, quorum and distinct approvers, `version` and `staleOn`, the store and handler, resuming with the token ([approvals](/docs/security/approvals)) |
| `permdock-tenancy` | Named scopes, memberships, ownership and `decideRoleChange`, custom roles from a `RoleSource` ([scopes](/docs/concepts/scopes)) |
| `permdock-data` | `where()` and `toWhere` for Drizzle, Prisma, Kysely and Convex, generated or adopted RLS, relationship graphs, `ormParity` and `rlsParity` ([RLS](/docs/adapters/rls)) |
| `permdock-credentials` | `subjectFromJwt` and introspection, API keys through `decideCredential`, service accounts, share links ([authentication](/docs/concepts/authentication)) |

`permdock-wire` states the invariants an agent must not violate while wiring: never string keys in public APIs, never import the policy in a client entry, never trust a model-supplied subject. `permdock-audit` writes its report as a Markdown checklist an agent can turn into pull requests; its pull request step compares `usage` and `collect` between the base and head branches, asks for a `describePolicy` row for every widened grant, and posts one comment per finding on the changed line.

## Versioning [#versioning]

Skills are versioned with `permdock`. A skill links docs pages by absolute `https://permdock.com/docs/<path>` URL, so an agent with network access can read the full page (or its `.md` variant) and an agent without it still has the skill's inline recipe. When an adapter's API changes, its docs page, its skill section and its example app change in the same pull request; `.agents/rules/change-checklist.mdc` lists this rule for maintainers.

## Why [#why]

* **One skill per topic; pull request review stays in the audit skill.** A single wiring skill that covered agents, approvals, tenancy, RLS and credentials loaded hundreds of lines an agent did not need for the task in front of it. Each topic skill now carries its own workflow and Verify list, and `permdock-audit` runs those lists instead of repeating them, so a check lives in one place. Reviewing a pull request uses the same checks as auditing an app, limited to the diff, so it stays a step in `permdock-audit` rather than a separate skill that would drift from it.
* **A `permdock-` prefix on every name.** Installed skills share one folder with skills from other packages; the prefix groups them in a picker and makes their origin obvious. The decision is recorded in the repository's `docs/decisions/0017-permdock-skill-prefix.md`.

## For maintainers [#for-maintainers]

`AGENTS.md` in the repository root (`CLAUDE.md` imports it) is the maintainer-facing guide: repo layout, commands, the invariants and an index of the topic rules in `.agents/rules` (naming, docs, "when you change X also update Y", testing, skills, prose). The consumer skills above are for apps that use PermDock; the two are kept separate on purpose.

## Related [#related]

* [For AI agents](/docs/for-ai-agents)
* [Agent docs standards](/docs/standards/agent-docs-standards)
* [doctor](/docs/cli/doctor)
* [Watch list](/docs/standards/watch-list)