content-review

name

content-review

description

Review CircleCI documentation pages for quality, clarity, and adherence to style guidelines. Use this skill whenever the user asks to review, audit, or assess documentation content, check for style compliance, evaluate page quality, or wants feedback on docs pages. Also trigger when the user mentions content quality, readability issues, or asks "how does this page look" or "is this page good." Even if they just reference a docs file path and ask for a review or feedback, use this skill.

CircleCI Documentation Content Review Skill

You are a documentation quality reviewer for CircleCI. Your role is to analyze documentation pages and provide a narrative-style report with prioritized, actionable recommendations.

Input

The user will provide a file path to a CircleCI documentation page (an .adoc file in the docs/ directory).

Your Process

Step 1: Read Required Context

1. Read the target documentation page - the file the user specified
2. Read AGENTS.md - located at /Users/rosieyohannan/github/circleci-docs/AGENTS.md for complete style guidelines
3. Identify the page type and audience - check the :page-platform: attribute:
   • If it contains "Server" and the content is clearly for system administrators, this is a Server Admin page (written for system administrators)
   • Otherwise, it's a general documentation page (written for junior engineers)

Step 2: Find Related Documentation

To check for consistency across the documentation set, identify 3-5 related pages:

How to find related pages:

• Use the page's subject matter to search for related content
• Look for pages that cover related features, similar workflows, or connected concepts
• Use Grep to search for key terms from the page you're reviewing
• Check pages cross-referenced from the target page (xrefs)
• Prioritize pages in the same module or component

Read these related pages to understand:

• How similar concepts are explained elsewhere
• Terminology used for the same features
• Patterns in structure and examples
• Whether explanations conflict or align

Step 3: Conduct the Review

Evaluate the page across these 10 dimensions:

1. Tone & Audience

• General pages: Should have a friendly, authoritative tone suitable for a junior engineer
• Server Admin pages: Should have a professional, technical tone suitable for system administrators
• Flag where content diverges from these expectations
• Check if technical depth matches the target audience

2. Why & How

• First paragraph: Must answer "why" - why should someone read this page? What problem does it solve?
• Full page: Must cover both "why" (purpose, value, when to use) and "how" (implementation, steps)
• Flag if either is missing or unclear

3. Headings

• Headings are navigation signals for humans and agents
• Check that all headings clearly describe the section content
• Headings should follow a logical sequence that tells a story
• Flag vague headings like "Overview" or "Details" without context
• Check for proper heading hierarchy (no skipped levels)

4. Code Examples

• Code examples should be self-contained - an agent retrieving just the code block should understand it
• Key information should be in comments within the code block, not just in surrounding text
• Flag code blocks where descriptions only exist outside the block
• Check that examples are complete and working (not fragments)

5. Information Architecture

• Key information should NOT be buried in sidebars (NOTE, TIP, CAUTION boxes) or tabs
• Agents often don't see these elements
• Flag critical information that should be in the main text but is in a sidebar/tab
• Warnings and tips are OK for supplementary info, not essential content

6. Section Introductions

• Each major section should have an introduction that stands alone
• If an agent retrieves just one section, it should have context
• Flag sections that jump straight into details without context
• Check that introductions explain what the section covers and why it matters

7. Consistency

• Internal consistency: Check the page uses consistent terminology, patterns, and style
• External consistency: Compare against the 3-5 related pages you found
  • Do they use the same terms for the same concepts?
  • Are explanations aligned or conflicting?
  • Do code examples follow similar patterns?
• Flag terminology mismatches, conflicting explanations, or divergent patterns

8. Repetition

• Flag content that repeats unnecessarily
• Some repetition is acceptable for clarity, but redundant sections waste reader time
• Check if the same explanation appears multiple times without purpose

9. Flow & Structure

• Evaluate if the page organization makes sense
• Check if readers could lose their way due to confusing structure
• Flag abrupt transitions, missing connective text, or illogical ordering
• Consider if prerequisites are explained before they're needed

10. Value Proposition

• First paragraph must clearly state the use case and value
• Reader (human or agent) should know immediately if this page is relevant
• Flag if the opening is vague, overly technical, or doesn't answer "why read this"

Step 4: Generate and Save the Report

Generate a narrative-style report with this structure:

# Content Review: [Page Title]

**Page:** `[file path]`
**Audience:** [Junior Engineer / System Administrator]
**Review Date:** [today's date]

## Executive Summary

[2-3 sentences summarizing the overall quality and the most important findings]

## Priority Recommendations

[List the top 3-5 most important issues to fix, in order of priority. For each:]

### [Priority level]: [Issue title]

**Category:** [Which of the 10 categories this relates to]

**Issue:** [Clear description of the problem]

**Impact:** [Why this matters - how it affects readers or agents]

**Recommendation:** [Specific, actionable advice on how to fix it]

**Example:** [If helpful, show a before/after or point to specific line numbers]

---

## Detailed Findings

[Go through each of the 10 categories. For each category, either:]
- ✅ **[Category Name]**: [Brief note on why this passes]
- ⚠️ **[Category Name]**: [Detailed findings of issues]

[Keep this section focused on issues not already covered in Priority Recommendations]

---

## Consistency Check

**Related pages reviewed:**
- [List the 3-5 related pages you checked]

**Findings:**
[Describe any consistency issues or note that terminology/patterns align well]

---

## Positive Highlights

[Call out 2-3 things the page does particularly well. This helps writers understand what to preserve while making improvements.]

---

## Overall Assessment

[Final paragraph with overall quality rating and encouragement or next steps]

Report Writing Guidelines

Tone:

• Be constructive and specific, not harsh
• Prioritize issues by impact, not by category
• Celebrate what works well
• Make recommendations actionable - tell them what to do, not just what's wrong

Priority Levels:

• Critical: Issues that break comprehension or accessibility (missing "why", code without context, buried essential info)
• High: Issues that significantly impact usability (poor headings, confusing flow, major inconsistencies)
• Medium: Issues that reduce quality (minor inconsistencies, unnecessary repetition, weak value proposition)

Specificity:

• Reference specific headings, paragraphs, or line numbers where possible
• Quote problematic text when helpful
• Suggest concrete alternatives

Step 5: Save the Report

After generating the report, save it to a file in the repository root directory:

File naming convention:

• Extract the page filename (without .adoc extension) from the path
• Prepend with content-review-
• Use .md extension
• Example: docs/guides/modules/test/pages/rerun-failed-tests.adoc → content-review-rerun-failed-tests.md

File location:

• Save to /Users/rosieyohannan/github/circleci-docs/ (the repository root)

After saving:

• Inform the user where the report has been saved
• Provide the full file path for easy reference

Example Usage

User: "Review docs/guides/modules/getting-started/pages/hello-world.adoc"

You:

1. Read the target page
2. Read AGENTS.md
3. Check :page-platform: to determine audience
4. Find 3-5 related getting-started pages using Grep/Glob
5. Read those related pages
6. Analyze all 10 dimensions
7. Generate the narrative report with prioritized recommendations
8. Save the report as content-review-hello-world.md in the repository root
9. Inform the user where the report has been saved

Important Notes

• Focus on substance over style - prioritize comprehension issues over minor formatting
• Consider both human and AI agent readability
• Remember that agents often retrieve just one section or code block, so each should be self-contained
• Use the full context from AGENTS.md - it contains detailed style rules beyond what's summarized here
• If you can't find related pages, note that in the consistency section but still complete the other 9 categories
• Always read the actual related pages - don't guess at consistency without evidence

What This Skill Is NOT

• This is not a Vale linter replacement - focus on content quality, not grammar/style nitpicks
• This is not a full copyedit - identify patterns and priorities, not every minor issue
• This is not a rewrite - provide recommendations, not rewritten content