agentleFS
Sign inStart free
SentryKnown publishergetsentry/junior/.agents/skills/public-docs/SKILL.md

public-docs

Skill394 starsChanged 7 months agoApache-2.0View on GitHub

Create and maintain public, user-facing product documentation for this repo's `packages/docs` app. Use when asked to write, revise, or review docs pages (tutorial/concept/reference/troubleshooting), improve docs information architecture, fix docs frontmatter/linking issues, or align docs quality with Vercel/Sentry-style standards.

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 11 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this workflow to produce docs that are crisp, task-oriented, and trustworthy for external users.

    line 8
  2. Distinctive:

    Keep docs audience-facing: explain user outcomes, not internal implementation chatter.

    line 20
  3. Distinctive:

    Prefer minimal runnable examples over long conceptual exposition.

    line 25
  4. Distinctive:

    Keep prose present around lists.

    line 26
  5. Very specific:

    Read neighboring docs in the same section (start-here, concepts, extend, operate, reference, contribute).

    line 43
  6. Very specific:

    If navigation is involved, read packages/docs/astro.config.mjs (sidebar and redirects).

    line 44
  7. Distinctive:

    If public interfaces are involved, verify the exported TypeScript surface and its code comments directly.

    line 45
  8. Distinctive:

    Follow depth and section guidance from documentation guidelines.

    line 50
  9. Distinctive:

    Keep wording direct and plain.

    line 51
  10. Distinctive:

    Use titled code fences for file snippets.

    line 52
  11. Distinctive:

    Prefer internal links that advance the reader to the next concrete action.

    line 53
  12. Distinctive:

    Run the narrowest meaningful checks:

    line 57
  13. Distinctive:

    When structure, sidebar, or redirects change, also run:

    line 63

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Public Docs

Use this workflow to produce docs that are crisp, task-oriented, and trustworthy for external users.

Load only the references needed for the request:

TaskRead
Understand docs app layout and constraintsreferences/api-surface.md
Draft or revise common docs pagesreferences/common-use-cases.md
Diagnose docs quality/build failuresreferences/troubleshooting-workarounds.md

Core invariants

  1. Keep docs audience-facing: explain user outcomes, not internal implementation chatter.
  2. Match the local docs contract in packages/docs/src/content/docs/contribute/documentation-guidelines.md.
  3. For new or substantially edited pages, require frontmatter fields: type, summary, prerequisites, related.
  4. Include concrete verification steps for tutorial/troubleshooting content.
  5. End each page with an explicit "next step" path through internal links.
  6. Prefer minimal runnable examples over long conceptual exposition.
  7. Keep prose present around lists; avoid heading-plus-bullets-only sections.

Workflow

1. Classify the request

Select one primary path:

  • New page authoring
  • Existing page refactor/clarification
  • Information architecture update (sidebar/redirects/navigation)
  • Docs quality pass (accuracy, scannability, consistency)
  • Troubleshooting/build-fix for docs app

2. Gather local context

  1. Read packages/docs/src/content/docs/contribute/documentation-guidelines.md.
  2. Read neighboring docs in the same section (start-here, concepts, extend, operate, reference, contribute).
  3. If navigation is involved, read packages/docs/astro.config.mjs (sidebar and redirects).
  4. If public interfaces are involved, verify the exported TypeScript surface and its code comments directly.

3. Author or edit with the right page shape

  1. Pick doc type (conceptual, tutorial, reference, troubleshooting) from intent.
  2. Follow depth and section guidance from documentation guidelines.
  3. Keep wording direct and plain; remove filler or internal-only caveats.
  4. Use titled code fences for file snippets.
  5. Prefer internal links that advance the reader to the next concrete action.

4. Validate changes

Run the narrowest meaningful checks:

pnpm docs:check

When structure, sidebar, or redirects change, also run:

pnpm docs:build

5. Report completion

Return:

  1. Changed files and what each change improves for readers
  2. Validation commands executed and outcome
  3. Residual risks (for example, missing screenshots, unverified env-specific setup)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free