Suggest docs skills to write

In one sentence: Scan their docs repo, read their actual documentation content, learn how they work, then return a justified, prioritized list of agent skills worth authoring (optional SKILL.md drafts only if they ask).

This skill answers one question well: given this documentation repository and this writer, which new skills are worth writing next — and why? Generic lists miss the point; the suggestions come from what the docs say and how they are organized, from mechanical and git signals, plus a short conversation about friction and gaps.

The skill is self-contained through the recommendation slate (Phases 1–3), including the Phase 1 bash recipes and the required content-reading pass below. Phase 4 exists only if the writer explicitly asks you to draft SKILL.md files.

What you deliver

Primary (always): A prioritized slate of skills to write — each with a clear name, what problem it solves, when it should trigger, and why it fits this repo and this writer. Every line ties to:

1. Evidence from the repo — structure, content types, bodies of real documentation (prose, examples, headings), commit patterns, ownership, gaps.
2. The writer's account — how they work, where friction is, what they wish existed.

Optional: If they ask, draft SKILL.md files (Phase 4) to a location they specify. Do not draft unprompted; the job is usually done after the slate.

Governing principles

Read these before starting. They govern the scan, the interview, and especially the slate of skills to write.

• Evidence before opinion. Every recommendation should trace to a repo signal and to how the writer works (their words). Git history and file counts are not enough — at least part of the signal must come from reading documentation content (see Phase 1). When one leg is thin — no git, read-only snapshot, or they gave a structured written brief instead of a live interview — say so explicitly on that row (for example: Evidence: repo-only — interview thin) or treat their written bullets as Phase 2. If you truly cannot anchor a row to either leg, drop it.
• Dimensions are generated, not prescribed. The list of areas you explore in Plan Mode comes from what the repo reveals and what the writer says — not from a fixed taxonomy. The seed list later in this file is inspiration, not a boundary.
• Adaptive, not linear. Follow pulls. Cross between areas. Probe contradictions. If a single question opens a more important thread, follow it and rebalance.
• Multi-dimensional thinking. The best skill recommendations usually live at the intersection of two areas (docs-from-code × release notes; IA × SEO; reuse × versioning; AI-assisted authoring × review workflow).
• Detect existing skills first. If the repo already has a skill catalog, read it before recommending. Don't propose what the writer already has.
• Respect governance. If the repo has a catalog, staging folders, review rules — honor them. Ask before modifying shared files like CATALOG.md.
• Restraint on the slate. Recommend fewer, sharper skills to write. Five to eight strong candidates beat fifteen vague ideas they will never author.
• Plain language. Even with a technical writer, crisp briefs and direct questions beat a lecture.

---

Phase 1 — Repository Understanding

Do the mechanical analysis and read real documentation pages before asking the writer anything beyond "where is the repo." The point of going first is to enter Plan Mode already informed — questions land better when grounded in what you've actually seen and read, not only in commit metadata.

Before you scan

1. Set the analysis root — Replace every <repo> with the path you will analyze (absolute or git -C-safe). In a monorepo, prefer the docs package root (for example apps/docs/ or documentation/) if that is where prose and tooling live; otherwise use repo root and note the split in the brief.
2. Check for git — Run git -C <repo> rev-parse --is-inside-work-tree (or equivalent). If not a git repo, skip all # Git: blocks below and state Git unavailable in the brief so Phase 3 does not pretend churn or ownership data exists.
3. Remote or read-only — If you only have a URL or partial checkout, say what you could not run and lean on whatever tree you have plus the writer's answers.

Scan in this order

1. Structure — folder hierarchy, depth, naming conventions, monorepo vs product-separated, presence of README.md per folder.
2. Content types — file extensions (.md, .mdx, .rst, .ipynb, .yaml), prose vs code-embedded mix, OpenAPI/Swagger specs, config files that reveal the doc platform (Docusaurus, MkDocs, ReadMe, Sphinx, Hugo, VitePress, Mintlify).
3. Git signals — commit frequency per path, ownership concentration, churn hotspots, stale areas, single-committer files, commit message quality (only when git is available).
4. Patterns and gaps (mechanical) — missing frontmatter, obvious metadata drift, tooling/config mismatches (shell-backed where possible).
5. Documentation bodies (required) — Open full pages and read them end-to-end (several representative files, not only headings or frontmatter). From that reading, notice orphaned pages, duplicate or near-duplicate topics, inconsistent terminology, missing version or applies-to tags, suspicious internal links, and copy that no longer matches the product — cite the files you opened. Git tells you where activity is; prose tells you what is painful, vague, duplicated, or unmaintainable. This layer is mandatory for Phase 3 — do not recommend skills from structure and git alone.

Mechanical scan (bash)

Use bash for structure, content-type counts, tooling fingerprints, frontmatter presence, and git stats (items 1–3 plus item 4). Then run the Read documentation content pass below for item 5 (and any prose-only gaps from item 4).

# Structure and extensions
find <repo> -type f -not -path '*/\.git/*' -not -path '*/node_modules/*' | \
  awk -F. '{print $NF}' | sort | uniq -c | sort -rn | head -20
find <repo> -maxdepth 2 -type d -not -path '*/\.git*' -not -path '*/node_modules*'

# Tooling detection
find <repo> -maxdepth 3 \( -name 'docusaurus.config.*' -o -name 'mkdocs.yml' \
  -o -name 'conf.py' -o -name 'readme.yaml' -o -name 'mint.json' \
  -o -name 'hugo.toml' -o -name 'openapi.yaml' -o -name 'openapi.json' \)

# Frontmatter coverage across .md/.mdx (GNU grep; if `rg` is installed, you can use:
#   rg --files-without-match '^---' -g '*.md' -g '*.mdx' <repo> | wc -l
grep -rL '^---' --include='*.md' --include='*.mdx' <repo> | wc -l

# Git: top churn files in last 12 months
git -C <repo> log --since='12 months ago' --name-only --pretty=format: | \
  grep -v '^$' | sort | uniq -c | sort -rn | head -25

# Git: stale files — doc files not touched in 12 months
# Cutoff works on macOS (BSD date -v) and Linux (GNU date -d).
# Run find from inside <repo> so paths match `git log -- <path>`.
CUTOFF=$(date -v-12m +%s 2>/dev/null) || CUTOFF=$(date -d '12 months ago' +%s)
( cd <repo> && find . \( -name '*.md' -o -name '*.mdx' -o -name '*.rst' \) -type f ) | \
  while read f; do \
    last=$(git -C <repo> log -1 --format=%at -- "${f#./}" 2>/dev/null); \
    [ -n "$last" ] && [ -n "$CUTOFF" ] && [ "$last" -lt "$CUTOFF" ] && echo "$f"; \
  done | head -25

# Git: single-owner files
git -C <repo> log --since='12 months ago' --pretty=format:'%an' --name-only | \
  awk '/^[A-Za-z]/ {author=$0; next} NF {print author"|"$0}' | \
  sort -u | awk -F'|' '{print $2}' | sort | uniq -c | awk '$1==1 {print $2}' | head -25

Read documentation content (required)

bash and git triage where to look; they do not replace reading the docs.

1. Open whole files — Not only the first screen: scroll through body, examples, callouts, and navigation sidebars if the format embeds them.
2. Stratify the sample — Aim for breadth (adjust counts if the repo is tiny or huge):
   • Entry points: root README, docs index, or “Get started.”
   • One path git shows as high-churn (if git exists) — read several pages in that area.
   • One path that is stale or quiet in git — check whether prose aged out.
   • One reference-style page (API, CLI, config) and one tutorial/narrative page.
   • If OpenAPI / hand-written API docs both exist, read both and note drift or overlap.
3. Capture substance, not vibes — Note concrete issues: duplicate explanations, conflicting terminology, missing prerequisites, outdated product names, copy-paste drift, tables or steps that no longer match the product, tone inconsistency across sections.
4. Feed Phase 3 — When you recommend a skill, Why for you should cite at least one content observation (path + what you saw) whenever possible — not only “high churn in guides/” without saying what is wrong in the text.

If the corpus is very large, state your sampling rule (“read N files per top-level section”) and stick to it; do not skip reading entirely.

Turn the scan into a brief

Write a brief for the writer: 5–10 bullets, plain language, signal-first. Don't bury insights. Don't mention everything.

Each bullet should imply a question or an action. Structure: <observation> — <what it implies>. <optional hook>.

Good bullets. Mix git/structure with prose: "80% of commits touch guides/ but reference/auth.md still describes the legacy login flow — worth asking if release notes or a skill should own drift detection." "Every file has frontmatter except tutorials/ — and two tutorials repeat the same install block verbatim." "One committer owns sdk/python/ alone — bus-factor; the SDK quickstart also assumes v1 types that the repo no longer exports."

Bad bullets. "There are 347 files." "The repo uses Markdown." Those are facts, not signals. If a line doesn't imply a question or an action, cut it.

How to read signals

Quick cheats for common patterns:

• Churn cluster in one folder + stale elsewhere → rotation imbalance. Ask what's driving the imbalance.
• High commit volume + commit messages like "wip," "typo," "fix" → low-signal history. Changelog generation will be painful.
• Every .md has frontmatter except one folder → carve-out or gap. Ask which.
• Deep nesting (5+ levels) + large folder count → IA likely hurts findability. Ask the last time they restructured.
• Single author dominates a path → specialization or bus-factor. Ask which.
• _generated/, autodoc/, or similar path present → existing docs-from-code pipeline. Ask what feeds it and who maintains it.
• OpenAPI spec present + hand-written API reference elsewhere → potential drift. Ask how they reconcile.
• Many screenshots/GIFs → visual-maintenance burden. Ask how they refresh.

Don't recite these to the writer. Use them to form the brief.

---

Phase 2 — Plan Mode (interactive, open-ended)

Plan Mode is an adaptive, role-based interview. Not a quiz, not a survey, not a fixed questionnaire. The areas a writer's work touches are discovered, not prescribed — what matters for a solo API writer is different from what matters for a content-ops lead at a fifty-person docs org.

If the writer pastes a structured written brief (bullets on friction, tools, and gaps) instead of answering live, treat that as Phase 2 — probe only what is still ambiguous.

Ground rules

• Role-based, never personal. Ask about the work. How they work, where friction is, what they wish existed. Never about personality, demographics, tenure.
• Generative dimensions, not a checklist. Don't open with a fixed taxonomy. After you've read the repo brief, brainstorm which areas of a writer's work are most likely to matter here, then pick 4–6 to explore. The list below is a seed, not a boundary.
• Turn-by-turn, not bulk. One or two questions per turn, then listen. Good follow-ups outweigh blanket coverage.
• Multi-dimensional. Cross between areas. The intersections are where the most useful skills live.

Before asking the first question — brainstorm

Given the repo brief, do a quick internal pass: what 8–12 areas of this writer's work are most likely to have leverage or friction? Expect to combine seed ideas from below with what the repo specifically revealed.

Then prioritize 4–6 for the opening of Plan Mode. Keep the rest in reserve — you'll reach them if the conversation pulls there.

Seed ideas for dimensions (inspiration only, not limits)

These are starting points. For any given repo + writer, expect to add, remove, and invent. If the repo has a /compliance/ tree, ask about compliance. If it has video scripts, ask about video. If the writer mentions onboarding, follow it.

• Docs-as-code maturity
• DocOps and release automation
• Git and review workflow
• Docs-from-code (generation, extraction, drift detection)
• Information architecture
• Cross-team collaboration (PM, Engineering, UX, Support, Marketing, Legal, Localization)
• Discoverability (SEO, AEO, GEO, internal search)
• Content reuse and modularity
• Versioning, migrations, release notes, changelogs
• Analytics, feedback loops, content observability
• Style and terminology consistency
• Accessibility and inclusive language
• Localization and internationalization
• AI-assisted authoring workflows
• Writing for LLM consumption vs human consumption
• Developer experience of docs infrastructure
• Onboarding new writers
• Content lifecycle — archiving, deprecation, pruning
• Security and compliance review of docs content
• Visual/media workflows (diagrams, screenshots, video)
• Community contribution workflows (external PRs, contributor guides)

Whatever else the repo surfaces that you didn't expect — follow it.

How to open Plan Mode

Something like the following (paraphrase, don't read it off):

"Based on the repo, here's what stood out: [3–4 bullets from the brief]. Before I suggest which skills are worth writing, I want to understand how you actually work. I'll ask a few focused questions — skip or redirect anything that doesn't fit."

Question patterns that work

Don't memorize a question bank. Use these patterns to generate questions that fit the specific writer and repo:

• Friction probe. "What's the most painful part of [X]? Walk me through a recent example."
• Automation appetite. "If you could hand off [Y] to a machine, what would you give up first?"
• Contradiction probe. "The repo shows [signal], but I'd have expected [X]. What's going on?"
• Missing-capability probe. "Is there something you wish your docs system did that it doesn't?"
• Jealousy probe. "What's a capability you've seen another team have that you don't?"
• Silence probe. "Is there a topic we haven't touched that's actually a bigger deal for you than any of this?"

Avoid: yes/no questions. Generic "tell me about your process" openers. Questions that imply you've already decided on the answer.

Adapting on the fly

• When the writer opens a new area, follow it before returning to your planned list.
• When a signal and an answer disagree, probe the gap directly but gently.
• When answers go short, ask more open. When they go long, focus.
• When the writer pushes back on a question, drop it and pivot — they know their context.

When to exit Plan Mode

Exit when you have enough signal to name which skills they should write and defend each one. Usually that means 4–6 areas substantively covered, specific friction points and gaps you can name, and diminishing returns from one more question. Ten good answers beat thirty shallow ones. Don't over-interview.

---

Phase 3 — Which skills to write (the main deliverable)

Synthesize Phase 1 evidence — including what you read in the documentation bodies — with Phase 2 answers into a prioritized slate of skills worth writing. This is not feature ideas for the product docs — each item is an agent skill they could author (for example a Cursor SKILL.md, a Claude Code skill, or a team AGENTS.md-style rule pack): automatable workflow, clear triggers, clear inputs/outputs. Each line should be specific enough that they could open an editor and start the file that week.

List order means impact priority — item 1 is the highest-leverage skill to write first unless you say otherwise; when two are equal, put the smaller scope / faster win first and say so in one line at the top of the slate.

First: check for existing coverage

If the repo contains a skill catalog (categories/, skills/, CATALOG.md, a docs-from-code/ pack), read it before drafting recommendations. Don't propose duplicates. If the writer already has an api-doc-generator, either propose a narrower variant their repo actually needs or skip that slot entirely.

Per-skill format

### <index>. <skill-name>
**Priority:** P0 | P1 | P2   # P0 = write first; align with list order unless you explain a swap
**What:** <one sentence>
**Why for you:** <specific repo signal — include a doc-content observation with path when possible> + <specific writer input from Phase 2 — interview or written brief>; if one leg is thin, label per governing principles
**When to use:** <trigger phrases and contexts>
**I/O:** <inputs> → <outputs>
**Example workflow:**
  1. <step>
  2. <step>
  3. <step>
**Dependencies:** <tools, skills, files it relies on>

The Why for you line is load-bearing. It must show what in the repo — preferably including what you read in the documentation bodies (file + observation) — and what the writer said (or wrote in Phase 2) that motivates writing this skill. A row justified only by git churn, with no content observation, is weak unless the skill is purely about git workflow. If you find yourself writing a generic rationale ("useful for any writer"), cut that row — it is not worth writing yet.

How many skills

Five to eight is usually right. Fewer feels thin; more overwhelms. Err toward fewer, highly tailored ones. If you're stretching to fill a slot, drop it.

Naming

Match the writer's repo naming convention if detectable. If their other skills are kebab-case noun-phrases (content-audit-runner, doc-coverage-mapper), use that. If they use verb-noun (audit-content, map-coverage), use that.

If their catalog expects the folder name to match the skill id, use the same kebab-case string for both the folder and the name field in any SKILL.md you draft in Phase 4.

Close the phase

After presenting the slate, you are done unless they want drafts. Optional add-on:

"If you want, I can draft SKILL.md files for any of these — tell me which numbers and where they should live. Otherwise you can author them yourself from this list."

---

Phase 4 — Draft SKILL.md files (opt-in only)

Only run this phase if the writer explicitly asks you to draft skills (e.g. "draft #2 and #5," "generate the SKILL.md files"). Never draft without that opt-in; suggesting what to write is already the core outcome.

Always ask where to put them

There is no default location. Ask every time. A good prompt:

"Where should these go? Some options I noticed in your repo: [list only the ones that apply — writers-picks/<your-handle>/, categories/skills/<category>/, a new folder you name]. Which do you want?"

Respect what the writer chooses, even if it seems suboptimal — they know their governance.

How to write each generated SKILL.md

Use the template at the end of this section. Follow these rules:

Frontmatter. Two fields: name (kebab-case, matching repo convention) and description (one paragraph). The description is the trigger — spend real effort on it. Two parts in one paragraph: what the skill does, plus when to trigger. Include indirect phrasings, not just literal matches. Err slightly pushy; Claude tends to under-trigger skills with bland descriptions. Example of the right flavor:

Use this skill when the writer wants to audit frontmatter across their docs repo — checking for missing description, applies-to, or title fields, or inconsistent schemas across folders. Triggers on requests like "check my frontmatter," "audit metadata," "why aren't these pages tagged." Also fires when the writer is preparing for a search or SEO review, even without naming frontmatter directly.

Body. Imperative voice. Explain the why, not just the what — rationale lets the model generalize. Avoid all-caps MUST/NEVER unless genuinely essential; if you reach for them, first try explaining why the thing matters. Keep the body under 500 lines.

Progressive disclosure. If depth is needed beyond ~500 lines, push it into references/<topic>.md or scripts/<n>.py. Reference those files at the bottom of SKILL.md with a one-line purpose each.

Bundle scripts for mechanical work. If the skill does deterministic, repeatable parsing or counting or extraction, bundle it as a Python script. Don't make the model rewrite the same logic on every invocation.

Examples are load-bearing. One realistic example beats three paragraphs of abstract description.

Check for tool assumptions. Before specifying that the skill uses ripgrep, jq, tree, etc., confirm those are actually available in the writer's environment. Fall back to portable tools if not.

Template for generated SKILL.md

Copy this as the starting point for each generated skill, then fill in:

---
name: <kebab-case-name>
description: <What the skill does in one sentence.> Use this skill when <primary trigger scenario>. Triggers on requests like "<example phrase 1>," "<example phrase 2>," or "<example phrase 3>." Also consider this skill when <indirect trigger — a context where the writer needs this but wouldn't name it>. Do not use this skill for <a near-miss so it doesn't over-trigger>.
---

# <Skill Name>

<One paragraph: what problem this solves, and why it matters for this repo and this writer.>

## When to use

- <Concrete trigger or context 1>
- <Concrete trigger or context 2>
- <Concrete trigger or context 3>

## Inputs

<What this skill needs to run. Files, paths, parameters, or context.>

## Workflow

1. <Step 1 — imperative, with one line of why>
2. <Step 2 — imperative, with one line of why>
3. <Step 3 — imperative, with one line of why>

## Output

<What the skill produces — a file, a report, a set of changes.>

## Example

**Input:** <realistic input, not a toy>
**Action:** <what the skill does>
**Output:**
\```
<realistic output>
\```

## Principles

- <Why this skill takes this approach — the "why" behind the workflow>
- <A principle that helps the model adapt to edge cases>
- <A principle that tells the model when to stop or defer>

## Reference files (delete if none)

- `references/<file>.md` — <one-line purpose>
- `scripts/<script>.py` — <one-line purpose>

After generating

Produce a summary: which skills were created, where each file is, and any pending catalog or index updates. List the full paths to every new or updated SKILL.md (and bundled files) so the writer can open them immediately. If the repo has governance artifacts the writer should update (CATALOG.md, deduplication tracker), flag them — but do not modify shared governance files yourself without asking.

Self-check before declaring done

For each generated skill, do one silent pass:

1. Does the description say both what and when?
2. Is the body under 500 lines?
3. Is there rationale in the body, not just instruction?
4. Do bundled resources (if any) have clear pointers?
5. Would this skill fire when the writer actually needs it?

If any answer is "no," revise before moving on.