Skip to content
Skills Library
Programming · Writing

docs-pr-subsection

/docs-pr-subsection

Turn a GitHub pull request into one subsection appended to a page that already documents the area it touches — no new page, no sidebar edit. Use for a PR that only enhances or fixes something already documented, or when the docs-document-pr skill names this as the subsection case.

Author
zio ↗
Repository
zio-skills ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Turn a GitHub pull request into one subsection appended to a page that already documents the area it touches — no new page, no sidebar edit. Use for a PR that only enhances or fixes something already documented, or when the docs-document-pr skill names this as the subsection case.

Arguments

/docs-pr-subsection <PR number>
Original author description

Turn a GitHub pull request into one subsection appended to a page that already documents the area it touches — no new page, no sidebar edit. Use for a PR that only enhances or fixes something already documented, or when the docs-document-pr skill names this as the subsection case.

How it works

  1. What you do
  2. When to stop without writing anything
  3. What you are not
  4. Reporting
Original SKILL.md headings · 90 lines, 658 words
SKILL.md preview
---
name: docs-pr-subsection
description: >
  Turn a GitHub pull request into one subsection appended to a page that already
  documents the area it touches — no new page, no sidebar edit. Use for a PR
  that only enhances or fixes something already documented, or when the
  docs-document-pr skill names this as the subsection case.
argument-hint: "<PR number>"
allowed-tools: Read, Edit, Grep, Bash(gh:*), Bash(sbt:*), Bash(git:*)
---

You turn a GitHub pull request into one subsection appended to a page that already documents the area
it touches. You write no new page and you touch no other page's sidebar entry — the target page is
already in the sidebar, and staying there is the point.

This is the small half of "document this PR." The other half — a PR introducing a genuinely new
module, type, or feature, with nothing existing to extend — is a full new page: use the
`docs-document-pr` skill instead. Reach for this skill only when something already documents the area
the PR lands in.

## What you do

1. **Fetch the PR.** `gh` infers the repo from the checkout, no `--repo` needed:

   ```bash
   gh pr view <N> --json title,body,state,labels,commits,closingIssuesReferences | head -c 6000
   ```

   For every issue in `closingIssuesReferences`, and any additional issue number the body mentions via
   "closes/fixes/resolves/relates to/see #" that the JSON field missed:

   ```bash
   gh issue view <N> --json title,body,labels | head -c 6000
   ```

   The PR title becomes your subsection's context, the body and linked issues give you the motivation,
   the commit list gives you what actually changed, and the labels are a tiebreaker in the next step.

2. **Confirm this belongs on an existing page.** It does when: the PR is an enhancement or fix to
   something already documented, labels read `enhancement`/`fix` rather than `feat`/`new-module`, and
   a page in `docs/reference/` or `docs/guides/` already covers the parent topic. Find that page by
   matching the PR title and labels against the `id` in each candidate page's frontmatter — a
   `schema-*` label points at `docs/reference/schema.md` if it exists, "Fix schema derivation" points
   at the page whose `id` is `schema`, and so on.

   If nothing matches — the PR is a new module, type, or substantial feature with no existing home —
   stop. Say so, and name `docs-document-pr` as the right skill for it.

3. **Write the subsection**, appended near the end of the target page (after its last `##` section,
   before a trailing "Running the Examples" section if the page has one):

   ```markdown
   ## <Feature Name>

   <One or two sentences of context, drawn from the linked issue's motivation — what problem this
   solves, not a changelog restatement of the commit list.>

   ### Changes in this PR

   - <what changed, one bullet per material change>

   ### Example

   <a prose sentence ending in `:`, then a runnable `mdoc:compile-only` block demonstrating the change>

   ### API Reference

   <new types or methods, if any — link to their reference page with a relative path if one exists>
   ```

   Drop "API Reference" entirely when the PR added no new public surface. Follow `docs-writing-style` for
   the prose and `docs-mdoc-conventions` for the code block.

4. **Insert it.** Exactly one blank line above the new `##` heading, exactly one blank line after its
   last line of content. Nothing else on the page changes — no sidebar edit, because the page is
   already there.

5. **Verify.** `sbt "docs/mdoc --in <path> --out website/<path>"` — never bare `sbt docs/mdoc`. Zero
   `[error]` lines.

6. **Commit.** `docs(<doc-stem>): document PR #<n> — <short feature name>`.

## When to stop without writing anything

- **The request names no PR number.** Ask, and stop.
- **No existing page covers the PR's area.** This is a new-page case — say so, name `docs-document-pr`,
  and stop rather than forcing a subsection onto an unrelated page.
- **The PR is a dependency bump or internal refactor with nothing a reader would look up.** Say so and
  stop; not every merged PR earns documentation.

## What you are not

You do not rewrite the rest of the target page, fix unrelated issues you notice on the way (note them
in your report instead), or touch `sidebars.js` — that file is for pages, and this PR did not add one.

## Reporting

PR title, linked issues found, the target page, the subsection heading you wrote, and whether mdoc
compiled clean. If you stopped instead of writing, say which condition applied.

Versions

The database has no other skills named docs-pr-subsection.

Database snapshot: 13.11.2026 · package version 733fb0849f20 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100docs-document-pr
    Decide, from a bare PR number, whether it needs a full new page, a subsection on an existing page, or nothing at all — then name the right skill for the job, writing nothing itself. Use when the user asks to document a PR and it is not already clear whether that means a new page…
  • 100pr-map
    Turn a GitHub pull request into an interactive review map with AI insights, reviewed in the browser. Use when the user asks to review, map, or visualize a PR.
  • 100docs-edit
    Edit a docs page that already has an open pull request, or revise a page in place. Covers checking out the PR's own branch instead of cutting a new one, forked cross-repository PRs, reading the real diff, checking the edit against related pages, and the verification to run…
  • 90digest-subsection
    Write one topical markdown subsection of the daily digest (macro, alt-data, institutional, asset-classes, or US equities). Fan-out under Phase 7; the stitcher assembles the briefing. Research-only. Triggered internally by the pipeline orchestrator — not a user-facing session skill.
  • 85gh
    When the user wants a pull request, its discussion, its checks, or another GitHub record read, or a reply posted without a code change.
  • 100adversarial-implementation
    Implement TODO.md items via isolated subagents, then adversarially verify correctness. Drives a phased loop that implements one checkbox at a time, runs independent lint/test/review subagents, handles human verification, and commits per subsection. Use when the user asks to…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.