# Docs Document Pr

> >

- **Type:** Skill
- **Install:** `agentstack add skill-zio-zio-skills-docs-document-pr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zio](https://agentstack.voostack.com/s/zio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [zio](https://github.com/zio)
- **Source:** https://github.com/zio/zio-skills/tree/main/plugins/documentation/skills/docs-document-pr

## Install

```sh
agentstack add skill-zio-zio-skills-docs-document-pr
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill: docs-document-pr

## Description

Generates documentation from a GitHub pull request. Automatically gathers related issues, commits, and PR metadata, then writes a new docs page or appends a subsection to an existing page based on the content type.

**Trigger:** User says something like "document PR #123", "write docs for PR 456", "generate documentation from this PR", or "doc this PR".

---

## Phase 1: Collect PR Data

### Step 1a — Get PR metadata and commits

Use the `gh` CLI to fetch the PR number (the user provides this):

```bash
gh pr view  \
  --json title,body,labels,commits,closingIssuesReferences \
  --repo 
```

**What to extract:**
- **PR title**: The main feature/fix name
- **PR body**: Context, motivation, and any additional notes
- **Labels**: Look for `feat`, `enhancement`, `new-module`, `schema-*`, `fix`, etc.
- **Commits**: List of commit messages (useful for "What changed" section)
- **Closing issues**: Issue references the PR closes/fixes/resolves

### Step 1b — Fetch linked issue details

For each issue referenced in the PR (via `closingIssuesReferences` or found via regex scan of PR body):

```bash
gh issue view  \
  --json title,body,labels \
  --repo 
```

**What to extract:**
- Issue title and body (motivation, requirements, discussion)
- Issue labels (helps understand priority, feature area)

### Step 1c — Optional: Regex scan PR body

If the PR body mentions issues via keywords like:
- `[Cc]loses?|[Ff]ixes?|[Rr]esolves?|[Rr]elates? to|see #`

Extract issue numbers and fetch them. This catches manually-added issue references.

---

## Phase 2: Decide — New Page or Subsection?

**Create a NEW PAGE** if:
- The PR introduces a **new module, data type, or substantial feature** (e.g., "Add XML support", "Add new codec type")
- **No existing doc page** closely covers the topic
- Labels include `new-module`, `feat` (not `enhancement`), or the PR title suggests something brand-new
- The PR is **significant enough** to warrant its own documentation space

**Add a SUBSECTION** if:
- The PR is an **enhancement or bug fix** to an existing feature
- An existing page in `docs/reference/` or `docs/guides/` already covers the parent topic
- Labels include `enhancement`, `fix`, or the PR touches an already-documented area
- You can logically fit the new content under an existing section

### Heuristics

1. **Match PR title against existing doc filenames:**
   - Scan `docs/reference/` and `docs/guides/` for `.md` files
   - Extract the `id` field from each file's frontmatter
   - If the PR topic matches an existing `id`, plan for a subsection

2. **Check PR labels:**
   - `schema-*` labels → likely fits under `docs/reference/schema.md` (if it exists)
   - `feat` + new name → likely a new page
   - `enhancement` + existing area → likely a subsection
   - `fix` → usually a subsection (documents the fix under an existing feature)

3. **Example decisions:**
   - PR: "Add XML support" → New page: `docs/reference/schema-xml.md`
   - PR: "Fix schema derivation" → Subsection in: `docs/reference/schema.md` → add under "Schema derivation"
   - PR: "Add new module: Temporal" → New page: `docs/reference/temporal.md`

---

## Phase 3: Write Documentation

### Decision: Delegate to Specialized Skills

**Do NOT write documentation directly.** Instead, determine the doc type and use the appropriate ZIO project documentation skill:

#### Path 3a — NEW REFERENCE PAGE (API / Data Type)

**When:** PR introduces a new data type, module, codec, or technical feature
- Labels: `feat`, `new-module`, `schema-*`
- No existing parent doc to extend

**Invoke:** Use the **`docs-data-type-ref`** skill

```
User: "Create a reference page for this new Schema type from PR #1234"
```

**The skill will:**
- Gather the feature info from the PR (title, body, linked issues)
- Write a structured reference page with Overview, Usage, Examples, API Reference
- Follow ZIO project documentation conventions (style, code blocks, frontmatter)
- Return the file path

#### Path 3b — NEW HOW-TO GUIDE

**When:** PR introduces a workflow, pattern, or tutorial-style feature
- Labels: `guide`, `enhancement`, `tutorial`
- Teaches "how to accomplish X" with the new feature

**Invoke:** Use the **`docs-how-to-guide`** skill

```
User: "Create a how-to guide for the new temporal processing feature from PR #1234"
```

**The skill will:**
- Extract motivation and use-cases from PR and linked issues
- Write a step-by-step guide with concrete examples
- Follow ZIO project style and code block conventions
- Return the file path

#### Path 3c — ADD SUBSECTION to existing page

**When:** PR enhances an existing feature or fixes a documented area
- Labels: `enhancement`, `fix`
- Existing doc page covers the parent topic

**Manual process:**
1. Read the existing page at `docs/reference/.md` or `docs/guides/.md`
2. Extract PR context (issues, motivation, commits)
3. Append a new section using this structure:
   ```markdown
   ## 

   

   ### Changes in this PR

   - 
   - 

   ### Example

   \`\`\`scala
   
   \`\`\`

   ### API Reference

   
   ```
4. Follow `docs-writing-style` for prose (refer to the skill for rules)
5. Follow `docs-mdoc-conventions` for code block syntax (refer to the skill for modifiers and admonitions)

### Guidelines Across All Paths

1. **Source content from the PR:**
   - PR title → doc title
   - PR body + linked issue bodies → motivation, use-cases, context
   - Commit messages → what changed (summarize key commits)
   - Labels → doc type and categorization

2. **Integrate with existing skills:**
   - Consult **`docs-writing-style`** for prose rules and tone
   - Consult **`docs-mdoc-conventions`** for code block modifiers (`:mdoc` markers) and Docusaurus admonitions (:::note, :::warning)
   - These skills provide shared guidelines used across all ZIO project docs

3. **File naming and frontmatter:**
   - Use kebab-case for file names and `id` fields
   - Always include frontmatter: `id`, `title`, optional `sidebar_label`
   - Example:
     ```markdown
     ---
     id: schema-xml
     title: "XML Schema Support"
     sidebar_label: "XML"
     ---
     ```

---

## Phase 4: Integrate with Docs Site

### For new reference or how-to pages:

After the `docs-data-type-ref` or `docs-how-to-guide` skill returns the file path, use **`docs-integrate`** to finalize:

```
User: "Integrate the new schema-xml docs page"
```

**The skill will:**
- Check that frontmatter (id, title) is correct
- Verify the page exists at the correct path
- Update `docs/sidebars.js` in the appropriate category
- Confirm the sidebar entry is in alphabetical or logical position
- Provide verification steps

**Manual backup:** If you need to update the sidebar yourself:

1. Open `docs/sidebars.js`
2. Find the appropriate category (e.g., "Reference", "Guides")
3. Insert the `id` in correct alphabetical or logical position
4. Example:
   ```javascript
   {
     type: 'category',
     label: 'Reference',
     items: [
       'schema',
       'schema-xml',       // `
   - Linked issues: `#123, #456, ...` or "None found"
   - Commits included: `` commits
   - Key labels: ``

2. **Decision made:**
   - "Created new page: `docs/reference/schema-xml.md`"
   - *or* "Added subsection to: `docs/reference/schema.md`"

3. **File(s) written:**
   - Path(s) to the created or modified file(s)
   - Sidebar changes (if any)

4. **Next steps (optional):**
   - "You can now review the generated docs and make refinements."
   - "Consider adding code examples if the PR includes complex changes."

---

## Phase 6: Verify Lint (If Examples Created)

If documentation involved creating or modifying `.scala` example files in `schema-examples/`, stage them in git first, then verify that all Scala code passes the CI formatting gate before reporting completion:

```bash
git add schema-examples/src/main/scala/**/*.scala
sbt fmtChanged
```

If any files were reformatted, commit the changes:

```bash
git add -A
git commit -m "docs(): apply scalafmt to examples"
```

Then verify the CI lint gate locally:

```bash
sbt check
```

**Success criterion:** zero formatting violations reported.

**If no `.scala` files were created or modified**, skip this phase.

---

## Implementation Checklist

When you invoke this skill:

- [ ] **Phase 1:** Use `gh pr view` to fetch PR metadata and commits
- [ ] **Phase 1:** Use `gh issue view` for each linked issue (max ~5 issues per PR is typical)
- [ ] **Phase 2:** Check existing docs in `docs/reference/` and `docs/guides/` to decide new page vs. subsection
- [ ] **Phase 2:** Use PR labels and title as tiebreakers
- [ ] **Phase 3a:** If new reference/API page → invoke `docs-data-type-ref` skill with PR context
- [ ] **Phase 3b:** If new how-to guide → invoke `docs-how-to-guide` skill with PR context
- [ ] **Phase 3c:** If subsection → manually edit existing page, consult `docs-writing-style` and `docs-mdoc-conventions` skills
- [ ] **Phase 4:** If new page → invoke `docs-integrate` skill to update sidebar
- [ ] **Phase 5:** Report findings and file paths to user
- [ ] **Phase 6:** If `.scala` examples were created, run `sbt fmt` and `sbt check` to verify lint compliance

---

## Example Invocations

For worked examples covering the common PR shapes (new reference page, new how-to guide, subsection addition, behaviour-change bugfix, and ambiguous PRs), load **[`references/example-invocations.md`](references/example-invocations.md)**. Use it when you've identified the PR's shape in Phase 2 and want to confirm the workflow, or when a PR doesn't fit one of the obvious patterns.

---

## Notes

- **Auto-detect repo:** Use `git remote -v` to find the GitHub repo URL if needed
- **PR numbers:** Assume user provides `#123` format; extract the number
- **No commits/issues:** If a PR has no linked issues, use only PR title and body
- **Ambiguous cases:** If unsure whether to create a new page or subsection, default to a new page (easier to reorganize later) or ask the user

---

## Final Verification

Before reporting back to the user, walk through every item in the sibling **[`CHECKLIST.md`](CHECKLIST.md)**. It covers PR analysis, doc-type routing, per-doc quality (delegated), integration, and reporting.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zio](https://github.com/zio)
- **Source:** [zio/zio-skills](https://github.com/zio/zio-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zio-zio-skills-docs-document-pr
- Seller: https://agentstack.voostack.com/s/zio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.