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, 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.
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
# 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 --checkinstall 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
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
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) |
permdock-approvals | Human approval: approval options, quorum and distinct approvers, version and staleOn, the store and handler, resuming with the token (approvals) |
permdock-tenancy | Named scopes, memberships, ownership and decideRoleChange, custom roles from a RoleSource (scopes) |
permdock-data | where() and toWhere for Drizzle, Prisma, Kysely and Convex, generated or adopted RLS, relationship graphs, ormParity and rlsParity (RLS) |
permdock-credentials | subjectFromJwt and introspection, API keys through decideCredential, service accounts, share links (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
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
- 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-auditruns 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 inpermdock-auditrather 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'sdocs/decisions/0017-permdock-skill-prefix.md.
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
Last updated on
config
Check permdock.config.ts for keys PermDock does not read, or print the effective config with every default filled in.
cloud
permdock cloud push publishes the catalog (permissions, hostable flags, roles, plans and relations) to a PermDock Cloud environment so its dashboard and hosted grants follow the code.