Payload Markdown Docs

---
name: payload-markdown-docs
description: Use this skill when maintaining Git-backed documentation for a project that uses `@valkyrianlabs/payload-markdown-docs`.
---

# Payload Markdown Docs Skill

Use this skill in Claude when maintaining Git-backed documentation for a project
that uses `@valkyrianlabs/payload-markdown-docs`.

Edit repo-local source files first. Treat generated Payload docs records and
synced raw assets as server-owned output, not as source of truth.

This skill may be installed at `.claude/skills/payload-markdown-docs` by the
native `pmdocs` CLI or served from the package
`skills/payload-markdown-docs/claude` directory.

This skill owns the docs package structure, plugin sync workflow, routing,
frontmatter, and plugin-specific safety rules. It intentionally does not define
Payload Markdown directive syntax or renderer formatting details. Use the
sibling `payload-markdown` skill for those:

- `../payload-markdown/SKILL.md`
- `../payload-markdown/reference/payload-markdown-directives.md`
- `../payload-markdown/reference/formatting.md`
- `../payload-markdown/reference/quality.md`

The `pmdocs install skill --agent claude` installer writes this sibling skill.
If it is missing, reinstall the skill bundle before guessing directive names,
props, themes, or formatting rules.

## Current Model

- Human docs records live in `./docs` by default.
- Native agent skill assets live in `./skills/<source>/<agent>/`; this package
  uses `./skills/payload-markdown-docs/codex/` and
  `./skills/payload-markdown-docs/claude/`.
- AI discovery files are generated by the plugin at `/llms.txt`,
  `/llms-full.txt`, and each docs set route base from synced docs and skills.
- `validate`, `manifest`, `plan`, and `push` read that conventional package
  layout by default.
- Manifest `files` are docs records.
- Manifest `assets` are skill files and optional custom static files.
- Skill files are not docs records and do not need docs frontmatter.
- Payload Markdown directive and formatting guidance comes from the sibling
  `payload-markdown` skill, not this skill.
- `push` defaults to sync mode. Use `--dry-run` only for an explicit dry-run.
- `--publish` is separate from sync mode and only requests published output.
- Server config owns writes, publishing, drafts, hard delete, auth, and route
  collision behavior.
- Public raw asset URLs require committed Next route files from
  `pmdocs install routes`.
- `/api/...` asset URLs are implementation/internal fallback URLs, not public
  canonical docs URLs.
- The npm package is the Payload plugin/runtime package only. Use native
  `pmdocs`, not `pnpm exec payload-markdown-docs`, for operator CLI commands.

## Authoring Rules

- Keep human docs in repo-local `.md` files under `./docs` unless configured
  otherwise.
- Do not introduce MDX unless a future project config explicitly enables it.
- Use the sibling `payload-markdown` skill before adding or changing renderer
  directives, directive props, theme names, or general Markdown formatting.
- Use only the docs frontmatter supported by this plugin.
- Keep internal docs links route-aware and root-relative inside the docs set,
  such as `/getting-started/quick-start`.
- Run validation before finishing docs edits.
- Run plan when sync behavior, route changes, publishing, archive behavior, or
  delete behavior matters.
- Do not directly mutate generated Payload records unless the user explicitly
  asks for admin-side overrides.
- Do not invent directives, frontmatter fields, CLI flags, sync modes, runtime
  features, route helpers, or publishing behavior.
- Do not describe unsupported features as implemented.

## Negative Rules

- Do not create `index.ai.yml`.
- Do not create `index.ai.yaml`.
- Do not create a single consolidated AI Markdown export file.
- Do not maintain `/plugins/<name>.md` AI export routes.
- Do not maintain root `llms.txt` or `llms-full.txt` files unless the user
  explicitly asks for custom static fallback assets.
- Do not duplicate Payload Markdown directive references in this skill.
- Do not invent unsupported Payload Markdown directives or props; use the
  sibling `payload-markdown` skill as the source of truth.
- Do not treat generated Payload records as source of truth.
- Do not tell users to run `pnpm exec payload-markdown-docs`; the supported CLI
  is the native `pmdocs` binary.

## Source ID Safety

`main-docs` is only a quick-start example source id. The real `--source` value
is the user's upstream docs id, which must match the Payload docs set slug.

When adding or installing a GitHub Actions OIDC workflow:

- Always include `--source <users-upstream-docs-id>` on `validate`, `plan`, and
  `push` commands.
- Do not infer the source id from the repository name, package name, branch,
  docs directory, or `GITHUB_REPOSITORY`.
- If the user did not provide the source/docs id, stop the task before editing
  the workflow. Explain that there is not enough context to add OIDC safely and
  ask for the Payload docs set slug/source id.
- Do not use `main-docs` unless the user explicitly says their docs set slug is
  `main-docs`.

## Default Workflow

```bash
pmdocs validate --source <users-upstream-docs-id>
pmdocs plan --source <users-upstream-docs-id>
```

If the project does not use the conventional `./docs` location, add
`--docs {{docsRoot}}`.

Only push when the user asks for an upload and provides endpoint/auth context.
GitHub OIDC sync:

```bash
pmdocs push \
  --endpoint "$DOCS_SYNC_ENDPOINT" \
  --source <users-upstream-docs-id> \
  --github-oidc
```

Explicit dry-run:

```bash
pmdocs push \
  --endpoint "$DOCS_SYNC_ENDPOINT" \
  --source <users-upstream-docs-id> \
  --github-oidc \
  --dry-run
```

Ed25519 sync:

```bash
pmdocs push \
  --endpoint "$DOCS_SYNC_ENDPOINT" \
  --source <users-upstream-docs-id> \
  --key-id github-actions-main \
  --private-key-env DOCS_SYNC_PRIVATE_KEY
```

Publishing request, only when the user explicitly wants published output:

```bash
pmdocs push \
  --endpoint "$DOCS_SYNC_ENDPOINT" \
  --source <users-upstream-docs-id> \
  --github-oidc \
  --publish
```

Sync writes require `sync.allowWrites: true`. Publishing additionally requires
`sync.allowPublish: true` and a draft-enabled docs collection.

Install public raw asset route files in a Next app when the user needs generated
`/llms.txt`, `/llms-full.txt`, docs-set `llms` files, or skill URLs to work
outside `/api`:

```bash
pmdocs install routes --payload-app "src/app/(payload)"
```

## References

- `reference/docs-package.md`
- `reference/frontmatter.md`
- `reference/workflow.md`
- `reference/sync.md`
- `reference/routing.md`
- `reference/admin.md`
- `reference/troubleshooting.md`
- `examples/github-actions.md`

Payload Markdown companion references:

- `../payload-markdown/reference/payload-markdown-directives.md`
- `../payload-markdown/reference/formatting.md`
- `../payload-markdown/reference/quality.md`
- `../payload-markdown/examples/docs-page.md`

## Safety Checklist

Before finishing:

1. Confirm changed docs live under the configured docs root, normally `./docs`.
2. Confirm changed docs have valid plugin frontmatter.
3. Confirm internal links are root-relative and route-aware.
4. If directives changed, confirm them against the sibling `payload-markdown` skill.
5. Run validate.
6. Run plan when sync behavior matters.
7. Report validation or plan failures instead of guessing.