# Agent docs standards

Source: https://permdock.com/docs/standards/agent-docs-standards

AGENTS.md, Agent Skills and llms.txt as the formats coding agents read, and what PermDock ships in each so an agent can wire and audit permissions without reading source.

## What it is [#what-it-is]

Three conventions have converged into the way coding agents learn a codebase or a library:

* **AGENTS.md** is a Markdown file at the repository root with instructions for agents working in the repo: layout, commands, invariants, conventions. Since December 2025 it is governed by the **Agentic AI Foundation** (AAIF) under the Linux Foundation, alongside Agent Skills ([overview](https://blog.agentailor.com/posts/top-ai-agent-standards-2026)). `CLAUDE.md` is the older Claude-specific name for the same idea. PermDock keeps one source: `CLAUDE.md` is the single line `@AGENTS.md`, which Claude Code expands as an import. A symlink would work for Claude Code too, but tools that read both names (Cursor does) would load the full guide twice on every request.
* **Agent Skills** are directories containing a `SKILL.md` with frontmatter (`name`, `description`) and a body of step-by-step instructions, optionally with supporting files. Agents load a skill when its description matches the task. Skills are distributed through **skills.sh** and installed with `npx skills add <source>`. Also under the AAIF.
* **llms.txt** is a root-level Markdown file that gives language models a curated index of a site's documentation, with `llms-full.txt` as the concatenated full text. Docs sites also increasingly serve a `.md` version of every page so an agent can fetch exactly one page as plain text.

## Why it matters for PermDock [#why-it-matters-for-permdock]

PermDock's audience is TypeScript product teams *and the coding agents working in their repos*. The success metric in the plan is "agent time to first check": how fast an agent can go from `npm install permdock` to a passing `can()` in an unfamiliar codebase. That depends on the agent finding instructions in the places it already looks, in formats it already parses. Inventing a PermDock-specific docs format would defeat the purpose. See [for AI agents](/docs/for-ai-agents).

The same rule applies to the maintainer side: an agent contributing to PermDock reads `AGENTS.md` for the "when you change X also update Y" list (adapter, docs page, skill, example, catalog), so the convention is used in both directions.

## How PermDock uses it [#how-permdock-uses-it]

### What PermDock ships [#what-permdock-ships]

| Artefact | Location | Audience |
| --- | --- | --- |
| `permdock` skill | `packages/permdock/skills/permdock/SKILL.md`, also on skills.sh | Any agent working with PermDock: the mental model, reading a decision, `explain`, the docs MCP, and which skill to load next |
| `permdock-wire` skill | `packages/permdock/skills/permdock-wire/SKILL.md`, also on skills.sh | Agents adding PermDock to an app: define, policy, `createPermDock`, first adapter, first test |
| `permdock-audit` skill | `packages/permdock/skills/permdock-audit/SKILL.md`, also on skills.sh | Agents finding unguarded routes and tools, unused or ungranted permissions (wraps `permdock usage`) |
| Topic skills | `packages/permdock/skills/permdock-{agents,approvals,tenancy,data,credentials}/SKILL.md`, also on skills.sh | Agents working on one area: delegation, human approval, tenants and roles, queries and RLS, tokens and keys |
| Claude Code plugin marketplace | `.claude-plugin/marketplace.json`, one `permdock` plugin whose `skills` are the folders above | Claude Code users: `/plugin marketplace add ScaleDockHQ/permdock` |
| `AGENTS.md` | Repository root, under 12 KB not counting the block `turbo` appends | Agents contributing to PermDock: layout, commands, the invariants index and the rule index |
| `.agents/rules/*.mdc` | Repository root; `.cursor/rules` symlinks the folder and `.claude/rules/<name>.md` symlinks each file | The same maintainers: invariants, naming, docs conventions, the change checklist, testing, deployment, skills and prose rules, each attached by path |
| `CLAUDE.md` | Repository root, the one line `@AGENTS.md` | Claude Code and other tools that look for this name |
| `llms.txt`, `llms-full.txt` | Docs site root, and the same files under `/docs` | Models indexing the documentation |
| `.md` per docs page | Docs site, same path with `.md` | Agents fetching one page as text |
| Docs MCP server | `POST /mcp` on the docs site; `server.json` in this repository | Agents querying the docs through MCP tools |
| Docs WebMCP tools | Every docs page, through `document.modelContext` | The browser's agent searching and reading the docs on the open page; [Docs WebMCP](#docs-webmcp) |
| JSON Schema catalog | `permdock catalog --format json-schema` | Agents and tools reading the permission model without TypeScript |

### Discovery and trust [#discovery-and-trust]

Three channels put PermDock in front of an agent before it reads a page, and each is a configuration or a publishing step rather than code:

| Channel | What PermDock does | Why |
| --- | --- | --- |
| npm provenance (Sigstore) | Every release after the first is published from the Release workflow through npm trusted publishing (OIDC, no npm token) with provenance, so the registry shows the source commit and workflow; `permdock doctor` warns when an installed copy lacks an attestation | An agent (or its human) can check that the `permdock` it installed was built from this repository, which matters for a library that decides authorization |
| JSR | `permdock` is also published to [JSR](https://jsr.io) from the same commit, with the TypeScript source and generated docs | Deno users import without an npm shim; JSR renders the API reference from source, which agents read well |
| Context7 and similar docs indexes | The docs site is registered with [Context7](https://context7.com) and serves `llms.txt`, `llms-full.txt` and `.md` per page so any index can pull it; the `permdock` skill points agents at the docs MCP and `llms.txt` | Coding agents resolve "how do I use permdock" to current docs instead of training data; a `Status` line tells them what does not exist yet |
| MCP Registry | `server.json` at the repository root (`io.github.scaledockhq/permdock-docs`); Streamable HTTP at `https://permdock.com/mcp` | Agent hosts discover the docs server by name instead of a pasted URL |

None of these changes an API. They are listed here so the release checklist and the skill agree on them.

Install the skills into a project:

```bash
npx skills add ScaleDockHQ/PermDock
```

The skills are also shipped inside the `permdock` npm package so `permdock skills` can install them offline. By default it writes to `.agents/skills`, `.claude/skills` and `.cursor/skills`; `--agent` narrows the targets, and nothing is detected from the repository. `permdock-audit` stays one skill so a single description covers routes, tools and definitions; it runs each topic skill's Verify list rather than repeating it. See [CLI skills](/docs/cli/skills).

### Conventions the docs follow for agents [#conventions-the-docs-follow-for-agents]

* Every docs page has frontmatter `title` and `description`, one topic per page, plain Markdown bodies, so `.md` and `llms-full.txt` are lossless.
* A page for something not built yet carries a `Status: planned` or `Status: tracking` line, so an agent knows whether an import path exists; a page without one describes code that exists.
* `llms.txt` follows [llmstxt.org](https://llmstxt.org): one `##` section per sidebar section, an absolute link to each page's `.md` URL with its description, and the research pages under `## Optional`.
* `llms-full.txt` carries the full text. Table padding is dropped from it and from every `.md` page.
* Each HTML page links its Markdown as `<link rel="alternate" type="text/markdown">`.
* Error messages and Problem Details `detail` text are written so a model can act on them (what was denied, why, what is permitted instead); see [Problem Details](/docs/standards/problem-details).
* Code examples use the exact public identifiers (`createPermDock`, `permissions.post.update`) and never placeholders an agent might copy literally.
* `permdock doctor` reports the same findings the `permdock-audit` skill looks for, so the skill and the CLI cannot drift.

### `SKILL.md` shape [#skillmd-shape]

Every skill opens with what it does (pickers show about 57 characters of the description), then the inputs to find out, 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/` and is linked from the step that needs it; another skill is named with its install command, never linked across folders.

```md
---
name: permdock-wire
description: Adds PermDock authorization to a TypeScript app, from definitions to the first guard. Use when installing permdock, adding permissions, roles or access control, or guarding a route, tool or component.
license: MIT
metadata:
  author: ScaleDockHQ
  homepage: https://permdock.com/docs/getting-started/quick-start
  repository: https://github.com/ScaleDockHQ/permdock
---

## Inputs

## Invariants

## Workflow

1. **Detect.** The framework and the validator in use.
   ✓ Both are named.

## Verify before done

## Reference index
```

## Mapping table [#mapping-table]

| Convention | PermDock artefact |
| --- | --- |
| `AGENTS.md` (AAIF) | Repository-root maintainer guide |
| Path-scoped rules (Cursor `.mdc`, Claude Code `.claude/rules`) | `.agents/rules/*.mdc`, linked into both tools |
| `CLAUDE.md` | The one line `@AGENTS.md` |
| Agent Skill `SKILL.md` | `permdock` and the `permdock-*` skills, with `license: MIT` and `metadata` in the frontmatter |
| Claude Code plugin marketplace | `.claude-plugin/marketplace.json` |
| skills.sh + `npx skills add` | `npx skills add ScaleDockHQ/PermDock` |
| Skills bundled with a package | `packages/permdock/skills/`, installed by `permdock skills` |
| `llms.txt` / `llms-full.txt` | Generated by the docs app from the MDX tree |
| npm provenance, JSR, Context7 | Publishing and registration steps in the release checklist; see "Discovery and trust" |
| `.md` per page | Served by the docs app for every route: append `.md`, or send an `Accept` header that lists `text/markdown` before `text/html` |
| MCP docs server | `POST /mcp`: `search`, `list_pages` and `get_page` (read-only; no subject) |
| WebMCP | Every docs page: `search_docs`, `read_page` and `open_page` through `document.modelContext` |
| Machine-readable model | `permdock catalog` JSON and JSON Schema output |

## Docs MCP [#docs-mcp]

`POST /mcp` is a public Streamable HTTP MCP server. Tools are `search` (full-text, the same index as the docs search box), `list_pages` and `get_page` (Markdown by URL), from `fumadocs-core/mcp` on `@modelcontextprotocol/server`. It never accepts a subject, a token or a policy, and it does not wrap `permdock/mcp`: the documentation is public and a missing page is a tool error, not an anonymous grant.

```json
{
  "mcpServers": {
    "permdock-docs": {
      "url": "https://permdock.com/mcp"
    }
  }
}
```

Connect a client in one step:

* Cursor: [add `permdock-docs` to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=permdock-docs\&config=eyJ1cmwiOiJodHRwczovL3Blcm1kb2NrLmNvbS9tY3AifQ==).
* VS Code: [add `permdock-docs` to VS Code](vscode:mcp/install?%7B%22name%22%3A%22permdock-docs%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fpermdock.com%2Fmcp%22%7D).
* Claude Code: run `claude mcp add --transport http permdock-docs https://permdock.com/mcp`. In Claude Desktop, add `https://permdock.com/mcp` as a custom connector.

Locally the same handler is `http://localhost:3000/mcp` while `pnpm dev:docs` is running. The repository-root `server.json` is the [MCP Registry](https://registry.modelcontextprotocol.io) listing.

## Docs WebMCP [#docs-webmcp]

Every docs page registers three [WebMCP](https://webmachinelearning.github.io/webmcp/) tools with the browser's own agent through `document.modelContext`: `search_docs` (the docs search index), `read_page` (a page's Markdown) and `open_page` (navigate to a page). `read_page` and `open_page` accept only a `/docs` path on the same origin. The component comes from the Fumadocs WebMCP feature, not `permdock/webmcp`, which registers permission-gated actions for a signed-in subject. WebMCP is experimental: it needs Chrome 149 or later with the `#enable-webmcp-testing` flag, and the page registers nothing in a browser without `document.modelContext`.

## Sources [#sources]

* [Top AI agent standards 2026 overview](https://blog.agentailor.com/posts/top-ai-agent-standards-2026): AGENTS.md and Agent Skills under the Agentic AI Foundation, skills.sh and `npx skills add`.
* Product plan, differentiator 13 ("Agent-native") and the `AGENTS.md` outline.
* [MCP llms.txt](https://modelcontextprotocol.io/llms.txt) as an example of the convention in a specification site.