Agent Skill Installer

The installer copies this plugin's native agent workflow pack into a consuming project.

Codex:

1pmdocs install skill --agent codex2pmdocs install skill --codex

Claude:

1pmdocs install skill --agent claude2pmdocs install skill --claude

Local guidance only

The installer writes Markdown guidance files. It does not sync docs, call Payload, fetch remote docs, or run package manager commands.

Output Trees

Codex default output:

1.agents/2  skills/3    payload-markdown-docs/4      SKILL.md5      reference/6        docs-package.md7        frontmatter.md8        workflow.md9        sync.md10        routing.md11        admin.md12        troubleshooting.md13      examples/14        github-actions.md15    payload-markdown/16      SKILL.md17      reference/18        payload-markdown-directives.md19        formatting.md20        quality.md21      examples/22        docs-page.md

Claude default output:

1.claude/2  skills/3    payload-markdown-docs/4      SKILL.md5      reference/6        docs-package.md7        frontmatter.md8        workflow.md9        sync.md10        routing.md11        admin.md12        troubleshooting.md13      examples/14        github-actions.md15    payload-markdown/16      SKILL.md17      reference/18        payload-markdown-directives.md19        formatting.md20        quality.md21      examples/22        docs-page.md

The canonical payload-markdown-docs source artifacts live in this package:

1skills/payload-markdown-docs/codex/2skills/payload-markdown-docs/claude/

The payload-markdown skill is installed from the project's own payload-markdown package when it is installed (either package name), so the directive guidance matches the version the site renders with:

1node_modules/payload-markdown/skills/payload-markdown/<agent>/2node_modules/payload-markdown/skills/payload-markdown/<agent>/

Otherwise pmdocs uses the copy it bundles (skills/payload-markdown/ in this repository, vendored from the payload-markdown package and checked for drift in CI). Both skills are written next to each other so payload-markdown-docs can link straight into ../payload-markdown/.

Keeping Skills Current

Each installed skill has a skill.json manifest. When pmdocs or payload-markdown is upgraded:

1pmdocs skill check    # current, outdated, modified or missing; exit 1 unless current2pmdocs skill update   # replace outdated skills, keeping --docs-root and --package-manager

pmdocs validate and pmdocs plan also print a reminder when the installed skill is stale, and the skill itself tells agents to run pmdocs skill update on their own. Skills edited by hand are never replaced without pmdocs skill update --force.

install skill installs local agent guidance only. It does not publish skills, sync docs, install public routes, or call Payload.

Publishing Skill Assets

Those directories are safe to publish through the docs site. After pmdocs push syncs them as assets, the plugin serves standard skill routes and generated docs-set AI discovery routes:

1/plugins/payload-markdown-docs/llms.txt2/plugins/payload-markdown-docs/llms-full.txt3/plugins/payload-markdown-docs/skills/codex4/plugins/payload-markdown-docs/skills/codex/SKILL.md5/plugins/payload-markdown-docs/skills/codex.zip6/plugins/payload-markdown-docs/skills/codex/reference7/plugins/payload-markdown-docs/skills/claude8/plugins/payload-markdown-docs/skills/claude/SKILL.md9/plugins/payload-markdown-docs/skills/claude.zip10/plugins/payload-markdown-docs/skills/codex/reference/workflow.md

pmdocs push syncs these skill artifacts by convention when they live under ./skills/<source>/. They are sent as manifest assets, not as docs records, so skill files do not need docs frontmatter.

The public skill route contract is:

1/<group...>/<set>/skills/<agent>2/<group...>/<set>/skills/<agent>/<directory>3/<group...>/<set>/skills/<agent>/SKILL.md4/<group...>/<set>/skills/<agent>.zip5/<group...>/<set>/skills/<agent>/<path...>

/skills/<agent> serves a generated Markdown directory index for the synced skill bundle. /skills/<agent>/<directory> also serves a generated Markdown directory index when matching skill files exist below that prefix. /skills/<agent>/SKILL.md and /skills/<agent>/<path...> serve raw synced skill artifacts. /skills/<agent>.zip is generated on demand from the current synced text skill artifacts for that docs set; ZIP files are not uploaded, stored, or synced as static ZIP assets. Auto-resolved skill CTA buttons use the ZIP route by default.

The source layout remains ./skills/<sourceId>/<agent>/.... Generated archives strip that distributor prefix and expand to <sourceId>/SKILL.md plus supporting files. For example, skills/payload-markdown-docs/codex/reference/workflow.md is bundled as payload-markdown-docs/reference/workflow.md.

Generated llms.txt and llms-full.txt entries expose the skill index, raw SKILL.md, and ZIP archive routes. Public URL generation prefers NEXT_PUBLIC_SERVER_URL, then public site/Vercel URL environment values, before falling back to forwarded request headers, Payload serverURL, or req.url. Production output should not contain localhost when a public origin is configured.

Installing Public Asset Routes

For Next apps where the frontend catch-all owns those root URLs, install the public asset route files once:

1pmdocs install routes --payload-app "src/app/(payload)"

Commit and deploy the generated files. If they are missing, /api/... asset URLs can work while public /llms.txt and /skills URLs return HTML 404 pages.

Discovery

Raw agent artifacts are not listed in sitemap.xml by default. Use includeSkills: true when stored skill asset routes should appear in the docs sitemap, or pass explicit additionalRoutes for routes that are not synced assets. Use includeLlms: true only when llms.txt and llms-full.txt routes should be crawler-discoverable. The plugin also owns top-level /llms.txt and /llms-full.txt handlers generated from synced docs, docs set metadata, dependencies, and skills, while agents can consume native skill files directly through public route files.

sitemap.xml is crawler discovery, llms.txt is an AI-readable entrypoint, and skills are native workflow artifacts.

Options

1pmdocs install skill --agent codex \2  --out .agents/skills/payload-markdown-docs \3  --docs-root ./docs \4  --package-manager pnpm

Use --dry-run to preview files and --force to overwrite changed existing skill files. Unchanged existing files are accepted. When --out is set, it selects the payload-markdown-docs output directory; the payload-markdown companion is installed as a sibling directory.

What The Skills Teach

maintain docs in repo-local Markdown files
understand docs package layout, manifest files, and manifest assets
use .md files only unless future config explicitly enables another format
use supported payload-markdown-docs frontmatter only
defer Payload Markdown directive and formatting details to the companion payload-markdown skill
keep internal links route-aware and root-relative inside the docs set
run validate before finishing docs edits
run plan when sync behavior matters
use push only when explicitly requested
use --dry-run only for explicit dry-run checks
respect server-owned sync, publish, and hard-delete gates
avoid unsupported features and invented directives

The source split is deliberate: /docs is human documentation source rendered with Payload Markdown, while /skills is the agent-native workflow package.