Agent docs standards

What it isCopy Anchor Link

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). 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 PermDockCopy Anchor Link

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.

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 itCopy Anchor Link

What PermDock shipsCopy Anchor Link

Discovery and trustCopy Anchor Link

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:

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:

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.

Conventions the docs follow for agentsCopy Anchor Link

• 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: 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.
• 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 shapeCopy Anchor Link

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.

---
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 tableCopy Anchor Link

Docs MCPCopy Anchor Link

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.

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

Connect a client in one step:

• Cursor: add permdock-docs to Cursor.
• VS Code: add permdock-docs to VS Code.
• 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 listing.

Docs WebMCPCopy Anchor Link

Every docs page registers three 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.

SourcesCopy Anchor Link

• Top AI agent standards 2026 overview: 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 as an example of the convention in a specification site.