skills

Status: planned Phase: 1

PermDock ships two Agent Skills so a coding agent can wire 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.

Install

Either path works; both write the same files.

# from skills.sh (no PermDock install required)
npx skills add ScaleDockHQ/PermDock

# from the installed permdock package
pnpm exec permdock skills install
pnpm exec permdock skills install --agent cursor --agent claude   # choose target folders
pnpm exec permdock skills list
pnpm exec permdock skills update

install copies the skills 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.

The skills

wire-permdock

Walks an agent through adding PermDock to an existing app:

1. Detect the framework (Next.js, Vite, Expo, Hono, Express, tRPC, MCP server, AI SDK, Claude Agent SDK) and the validator already in use (Zod, Valibot, ArkType).
2. Create src/permissions.ts with definePermissions() over the app's existing schemas, splitting actions and collection per resource.
3. Create src/policy.ts with definePolicy(), roles as allow / deny arrays, portable where conditions first, closures only when necessary.
4. Create the factory file for the framework (src/permdock/server.ts with createPermDock from permdock/<framework>), following the naming convention.
5. Add the first check (assert in a server handler), the first UI guard (usePermission or Protected), and the decision endpoint where closures exist.
6. Run permdock collect, permdock usage and permdock doctor, fix findings, and add collect --check to CI.

The skill contains the exact import paths and code shapes from the quick start and one section per adapter, and states the invariants an agent must not violate: never string keys in public APIs, never not-applicable, never import the policy in a client entry, never trust a model-supplied subject.

audit-permissions

A review skill for an existing PermDock installation. It runs permdock usage --json and permdock doctor --json, reads the catalog, and produces a report covering:

• permissions with no grants or no tests;
• roles that grant delete or publish actions without approval: 'human' on agent-reachable surfaces;
• closures that could be portable conditions (so RLS and snapshots would cover them);
• MCP and AI SDK tools whose permission is a collection action but whose handler touches a specific row;
• policies with validate: 'never';
• the OWASP Agentic Top 10 mapping for ASI02 and ASI03 (OWASP Agentic).

The report is written as a Markdown checklist an agent can turn into pull requests.

Versioning

Skills are versioned with permdock. A skill references docs pages by /docs/<path> URL and the .md variant of each page, so an agent with network access can read the full page 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.md lists this rule for maintainers.

For maintainers

AGENTS.md in the repository root (with CLAUDE.md as a symlink) is the maintainer-facing guide: repo layout, commands, invariants and "when you change X also update Y". The consumer skills above are for apps that use PermDock; the two are kept separate on purpose.

Open questions

• Whether to ship a third skill, review-permissions-pr, that runs on pull requests and comments on permission surface changes using the catalog diff.

Related

• For AI agents
• Agent docs standards
• doctor
• Agent standards 2026