Agent Skill Installer

The installer copies this plugin's native agent workflow pack plus the companion @valkyrianlabs/payload-markdown authoring skill into a consuming project.

Codex:

1pnpm exec payload-markdown-docs install skill --agent codex2pnpm exec payload-markdown-docs install skill --codex

Claude:

1pnpm exec payload-markdown-docs install skill --agent claude2pnpm exec payload-markdown-docs install skill --claude

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      agents/18        openai.yaml19      reference/20        payload-markdown-directives.md21        formatting.md22        automated-docs-workflow.md23        quality.md24      examples/25        docs-page.md26        reference-page.md27        release-notes.md28      scripts/29        check_payload_markdown_doc.py30AGENTS.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        automated-docs-workflow.md21        quality.md22      examples/23        docs-page.md24        reference-page.md25        release-notes.md26      scripts/27        check_payload_markdown_doc.py

The canonical source artifacts live in the package repository:

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

The companion skill source comes from:

1node_modules/@valkyrianlabs/payload-markdown/skills/payload-markdown/codex/2node_modules/@valkyrianlabs/payload-markdown/skills/payload-markdown/claude/

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 payload-markdown-docs 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

payload-markdown-docs 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:

1pnpm exec payload-markdown-docs 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

1pnpm exec payload-markdown-docs 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 customized, the companion payload-markdown skill 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.