Deterministically audit and optimise a published documentation page. Runs a 10-section quality audit, applies 5 rewrite rules for structure, terminology, link health, and completeness. Reads website analytics and GSC data per doc URL, produces a 75-point score delta (100 with analytics), commits changes, and updates the per-doc report. Load identity and brand-voice first.
Instalação
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Deterministically audit and optimise a published documentation page. Runs a 10-section quality audit, applies 5 rewrite rules for structure, terminology, link health, and completeness. Reads website analytics and GSC data per doc URL, produces a 75-point score delta (100 with analytics), commits changes, and updates the per-doc report. Load identity and brand-voice first.
metadata
{"version":"1.0.0","git_hash":"7f3e532"}
Documentation Optimiser
Run a deterministic, data-driven audit and rewrite on a single published documentation page. This skill is the complete lifecycle tool for documentation quality: audit, fix, score, commit, log. Every decision is grounded in a quantitative rule or a measurable signal. No vibes, no "use your judgement" gaps.
Critical rule: Section 10 (Search Appearance and Discoverability) is a critical override. If Section 10 fails, the entire audit fails regardless of how many other sections pass. Documentation that cannot be found has no value, regardless of how well it scores on technical criteria.
Dependencies
Load identity and brand-voice before this skill.
identity -- positioning, ICP, messaging hierarchy, what the brand actually stands for
brand-voice -- the cliche list, terminology rules, em-dash ban, and voice targets
Source of Truth
Read these before starting:
The documentation page itself at /var/www/html/systemprompt-web/services/content/documentation/{slug}/index.md
All pages linked from this doc (verify they exist on disk or resolve via HTTP)
/var/www/html/systemprompt-web/reports/content/documentation/{slug}/doc-report.md -- the per-doc report (accuracy log, link health, terminology compliance, action log, current scores). If this file does not exist, create it from the template in the "Per-Doc Report Template" section below before proceeding. Populate with available data from the documentation page and any GSC data pulled in Phase 0.
Inputs
Caller must provide:
Documentation slug (e.g. getting-started), OR the absolute path to the doc's index.md
Phases
The skill runs sequentially: 0 -> 1 -> 2 -> 2.5 -> 3. Do not skip. If any phase aborts, exit cleanly without committing.
Phase 0 -- Data Ingestion
Pull Google Search Console query data, run automated checks, and build the working set.
Authenticate
Use the service account at /var/www/html/systemprompt-web/.keys/gsc.json. Read scope is https://www.googleapis.com/auth/webmasters.readonly.
python3 <<'PY' > /tmp/gsc_token
import json, time, base64
from urllib.request import urlopen, Request
from urllib.parse import urlencode
from pathlib import Path
key = json.loads(Path('/var/www/html/systemprompt-web/.keys/gsc.json').read_text())
now = int(time.time())
claims = {
'iss': key['client_email'],
'scope': 'https://www.googleapis.com/auth/webmasters.readonly',
'aud': 'https://oauth2.googleapis.com/token',
'iat': now, 'exp': now + 3600,
}
try:
import jwt as pyjwt
token = pyjwt.encode(claims, key['private_key'], algorithm='RS256')
except ImportError:
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
h = base64.urlsafe_b64encode(json.dumps({'alg':'RS256','typ':'JWT'}).encode()).rstrip(b'=').decode()
p = base64.urlsafe_b64encode(json.dumps(claims).encode()).rstrip(b'=').decode()
pk = serialization.load_pem_private_key(key['private_key'].encode(), password=None)
sig = pk.sign(f'{h}.{p}'.encode(), padding.PKCS1v15(), hashes.SHA256())
token = f'{h}.{p}.{base64.urlsafe_b64encode(sig).rstrip(b"=").decode()}'
data = urlencode({'grant_type':'urn:ietf:params:oauth:grant-type:jwt-bearer','assertion':token}).encode()
resp = json.loads(urlopen(Request('https://oauth2.googleapis.com/token', data=data, method='POST')).read())
print(resp['access_token'], end='')
PY
Cache both files. If the doc has no rows, record no_gsc_data: true and proceed. Content rules still apply.
Automated Link Health Check
For every internal and external link in the documentation page:
Internal links: Verify the target file exists on disk. Check that the path resolves to a real page under /var/www/html/systemprompt-web/.
External links: Issue an HTTP HEAD request. Record status code. Flag 4xx and 5xx as broken.
Record results in link_inventory with columns: url, type (internal/external), anchor_text, status, line_number.
Terminology Scan
Scan the entire document against the terminology table:
Incorrect
Correct
prompt, template, instruction set
Skill
bot, assistant, AI helper
Agent
app, extension, add-on, package
Plugin
integration, bridge, adapter
Connector
API, service, endpoint (when referring to MCP)
MCP server
AI management, AI administration
AI governance
Record each violation with line number, incorrect term, and correct replacement in terminology_violations.
Build Working Set
Assemble the following data structures in memory:
page_metrics: {impressions, clicks, ctr, position} from the page aggregate (or no_gsc_data: true)
top_queries: sorted by impressions, filter impressions >= 20 (signal floor)
link_inventory: every link in the doc with type, status, anchor text, line number
terminology_violations: every terminology violation with line number, incorrect term, correct term
Initialise Doc Report
Read the per-doc report at reports/content/documentation/{slug}/doc-report.md. If it does not exist, create it from the template (see "Per-Doc Report Template" section below) and populate with:
GSC data just pulled (impressions, clicks, CTR, position)
Link inventory from the health check
Terminology violations found
Any existing metadata extractable from the doc's current content
This ensures every optimiser run has a doc report to work with, even for documentation created before this skill existed.
Phase 1 -- 10-Section Audit
Run the full 10-section checklist against the target documentation page. Record pass/fail per check. This phase writes nothing to disk. It produces a dict held in memory for Phase 2.5 scoring.
When Phase 1 produces a failing check, Phase 2 is responsible for fixing it only where the fix is covered by the rewrite rules below. Out-of-scope failures (e.g. broken external links pointing to third-party 404s) are reported but not auto-fixed.
Section 1: Structure Adherence
Breadcrumb navigation present
Exactly one H1 (page title, clear and descriptive)
Introduction paragraph present (2-3 sentences: what and why)
Introduction clearly states what page covers and why it matters
Learning outcomes specific and measurable (not "understand X" but "configure X to do Y")
Every step in procedure included (no gaps)
Every configuration field documented (type, required/optional, default, description)
Error scenarios and failure modes addressed
Edge cases documented where relevant
Reader can accomplish stated goal without external help
Section 4: Terminology Compliance
"Skill" not "prompt", "template", "instruction set"
"Agent" not "bot", "assistant", "AI helper"
"Plugin" not "app", "extension", "add-on", "package"
"Connector" not "integration", "bridge", "adapter"
"MCP server" not "API", "service", "endpoint" (when referring to MCP)
"AI governance" not "AI management", "AI administration"
No marketing language in documentation (no persuasion, no benefit-selling)
Section 5: Link Health
All internal links resolve to existing pages (no 404s)
All external links current and accessible
Anchor text descriptive (not "click here" or bare URLs)
Cross-links to related documentation pages present
No links to placeholder or example domains
Breadcrumb links correct
Section 6: Code Example Validity
Every code block specifies a language identifier
YAML examples syntactically valid
JSON examples syntactically valid
Bash/CLI commands correct for stated tool version
Configuration examples include comments explaining non-obvious fields
No placeholder values that look real (fake API keys, URLs)
OS-specific commands note alternatives where they differ
Section 7: Prerequisite Clarity
Prerequisites listed at top, before procedural content
Each prerequisite specific (version numbers, tools, permissions)
Prerequisites distinguish "must have" vs "recommended"
Links to prerequisite setup instructions where they exist
Assumed knowledge level stated
Section 8: Troubleshooting Coverage
Troubleshooting section exists (or justified as unnecessary for reference-only pages)
Each item follows Symptom / Cause / Solution format
Common failure modes from the feature's domain covered
Error messages quoted exactly as user would see them
Solutions specific and actionable (not "check your configuration")
Section 9: Learning Outcomes Quality
3-5 learning outcomes present
Each outcome specific and measurable
Each achievable by following page's content
Outcomes use action verbs ("Configure X", "Deploy Y", "Diagnose Z"), not passive ("Understand X")
Outcomes align with documented search intent
Section 10: Search Appearance and Discoverability (CRITICAL OVERRIDE)
If Section 10 fails, the entire audit result is FAIL regardless of how many other sections pass. Documentation that cannot be found has no value, regardless of how well it scores on technical criteria.
Title is discoverable: H1 contains terms users would search for
Meta description exists: under 160 chars, tells reader what they will learn to DO
Frontmatter keywords present: mapping to real search terms
Quick answer: Page answers title's implied question within first 300 words
Internal search findability: Title and intro contain vocabulary users would use (including common incorrect terms as context, e.g. mentioning "API" in a paragraph about MCP servers so searches for "API" still find the page)
Phase 2 -- Deterministic Rewrite
Five hard rules. Each is mechanically enforceable.
Handling docs without GSC data: When no_gsc_data: true, all five rules still apply. Unlike guides, documentation rewrites do not depend on search traffic data. GSC data enhances scoring but does not gate rewrites.
Missing sections: For each required section from the Section 1 audit that is absent, add it:
Introduction: 2-3 sentences stating what the page covers and why the reader needs it. No preamble, no "welcome to" language.
Learning outcomes: 3-5 bullet points. Each starts with an action verb ("Configure", "Deploy", "Diagnose"). Each is specific and measurable. Each is achievable by following the page's content.
Prerequisites: List every tool, version, permission, and dependency required. If none, state "None" explicitly. Distinguish "must have" from "recommended".
Troubleshooting: Minimum 3 items in Symptom / Cause / Solution format. Source symptoms from the feature's known failure modes, error messages in the codebase, and GSC error-style queries if available.
Related pages / next steps: Minimum 3 cross-links to other documentation pages. Use descriptive anchor text.
Heading hierarchy fix:
Demote any heading that skips a level (H1 followed by H3 becomes H1 > H2 > H3)
Promote any heading that is deeper than H3 (H4+ becomes H3)
No skipped levels anywhere in the document
Action-oriented headings:
Convert noun-phrase headings to action-oriented form: "Skill Creation" becomes "Creating a Skill", "Configuration" becomes "Configuring the Plugin", "Authentication" becomes "Authenticating with the API"
Exception: pure reference headings that name a thing ("CLI Commands", "Environment Variables") are acceptable
Sentence case enforcement:
All headings use sentence case ("Getting started with plugins" not "Getting Started With Plugins")
Exception: proper nouns retain capitalisation ("Configuring Claude Code" not "Configuring claude code")
Rule 2 -- Terminology Correction
Automated find-and-replace for all terminology violations identified in Phase 0. Fully mechanical. No judgement required.
Incorrect term
Correct term
Context
prompt
Skill
When referring to a systemprompt skill file
template
Skill
When referring to a systemprompt skill file
instruction set
Skill
When referring to a systemprompt skill file
bot
Agent
When referring to an AI agent
assistant
Agent
When referring to an AI agent (not Claude assistant)
AI helper
Agent
When referring to an AI agent
app
Plugin
When referring to a systemprompt plugin
extension
Plugin
When referring to a systemprompt plugin (not VS Code extensions)
add-on
Plugin
When referring to a systemprompt plugin
package
Plugin
When referring to a systemprompt plugin (not npm/cargo packages)
integration
Connector
When referring to a systemprompt connector
bridge
Connector
When referring to a systemprompt connector
adapter
Connector
When referring to a systemprompt connector
API
MCP server
When referring to a Model Context Protocol server
service
MCP server
When referring to a Model Context Protocol server (not cloud services generally)
endpoint
MCP server
When referring to a Model Context Protocol server (not HTTP endpoints generally)
AI management
AI governance
Always
AI administration
AI governance
Always
Context sensitivity: The "Context" column is critical. "API" is only replaced when it refers to an MCP server, not when discussing REST APIs generally. "Extension" is only replaced when it refers to a systemprompt plugin, not VS Code extensions. Apply the replacement only when the context matches.
Process:
For each violation in terminology_violations from Phase 0, apply the replacement.
Re-scan after replacement to catch any cascading issues (e.g. "the prompt template" becoming "the Skill Skill").
Record every replacement in the artifact report with line number, before, and after.
Rule 3 -- Link Repair
Fix broken and substandard links identified in Phase 0.
Broken internal links:
If the target page has moved, update the link to the new path
If the target page has been deleted and the link is non-essential, remove the link and inline any critical context that was being delegated
If the target page has been deleted and the link is essential, flag needs_content_review: true and note the missing dependency
Broken external links:
If a permanent redirect (301) exists, update to the final URL
If the page is gone (404, 410), remove the link. If the link supported a claim, flag the claim for re-sourcing
Do not silently remove links that substantiate technical claims
Anchor text fixes:
Replace "click here" with descriptive text: "click here for the CLI reference" becomes "the CLI reference"
Replace bare URLs with descriptive anchor text
Ensure every anchor text describes what the reader will find at the destination
Cross-link additions:
If the doc references a concept that has its own documentation page, add a link
Minimum 3 internal cross-links per documentation page
Use relative paths for internal links (/documentation/{slug})
Rule 4 -- Code Example Validation
Fix code examples identified as problematic in Phase 1 Sections 2 and 6.
Language identifiers:
Every fenced code block must specify a language: yaml, json, bash, rust, ```toml, etc.
If the language is ambiguous, infer from content (YAML has colons and indentation, JSON has braces, TOML has brackets and equals signs)
Syntax validation:
YAML: parse with a YAML parser or verify structure manually (consistent indentation, valid key-value pairs, no tabs)
JSON: verify balanced braces, proper quoting, no trailing commas
Bash: verify command exists and flags are valid for the stated tool version
TOML: verify section headers and key-value syntax
Explanatory comments:
Add comments to configuration examples explaining non-obvious fields
Comments should explain WHY, not WHAT (not # set the port but # default 8080, must match reverse proxy config)
OS-specific alternatives:
If a command differs across macOS, Linux, and Windows, note the alternatives
At minimum, note when a command is Linux/macOS-only
Placeholder cleanup:
Replace fake API keys (sk-abc123) with clearly marked placeholders (YOUR_API_KEY_HERE)
Replace fake URLs with example.com domain or clearly marked placeholders
Never leave a value that could be mistaken for a real credential
Rule 5 -- Completeness Gap Fill
Fill gaps identified in Phase 1 Section 3.
Missing learning outcomes:
Add 3-5 outcomes if absent
Each starts with an action verb
Each is specific: "Configure a plugin manifest with required fields and optional metadata" not "Understand plugins"
Each is achievable by following the page's content
Missing troubleshooting items:
Add minimum 3 items in Symptom / Cause / Solution format
Source symptoms from: the feature's error messages in the codebase, common user mistakes for this type of configuration, GSC error-style queries if available
Each solution must be specific and actionable: "Add version: 2 to the manifest header" not "Check your configuration"
Incomplete procedures:
If a procedure has gaps (e.g. "create the file" without showing the file content), fill them
Every step must be complete enough that the reader can execute it without guessing
SME review flag:
If a gap cannot be filled without domain expertise (e.g. undocumented API behaviour, unclear error conditions), flag the specific item as needs_sme_review: true in the report
Do NOT invent technical details. Flag and move on.
Phase 2.5 -- Scoring
Every documentation page gets a 75-point score (expandable to 100 when analytics are available). Compute both pre- and post-rewrite. The delta is the proof of work.
Rubric (75-point base)
Dimension
Max
Formula
Structure adherence
15
round(15 * (passing_checks / 12)) (12 checks in Section 1)
Accuracy
15
round(15 * (valid_items / total_items)) from Sections 2 + 6
Completeness
10
round(10 * (passing_checks / 7)) (7 checks in Section 3)
Terminology compliance
8
max(0, 8 - violation_count)
Link health
8
round(8 * (healthy_links / total_links))
Prerequisite clarity
5
1 point per passing check in Section 7 (5 checks)
Troubleshooting coverage
5
1 point per passing check in Section 8 (5 checks, max 5)
Learning outcomes quality
5
1 point per passing check in Section 9 (5 checks)
Search appearance
4
1 point per passing check in Section 10 (excluding the critical override, 4 remaining checks)
Analytics expansion (100-point scale)
When website analytics and GSC data are available, add:
Dimension
Max
Formula
Page engagement
15
Based on bounce rate + time-on-page. score = round(15 * (1 - bounce_rate) * min(1, avg_time_seconds / 180)). 3+ minutes with low bounce = 15. High bounce or < 30s = 0-3.
Re-run the 10-section audit. Section 10 must pass (critical override). Other sections must be no worse than the baseline from Phase 1.
Diff the markdown. If diff is empty or trivially whitespace-only, abort with no_material_change. Never commit a no-op.
Recompute the score. If post_score < pre_score, abort and roll back. This is a bug in the rules, not an improvement. Report the regression.
Commit with the message format above.
Write the structured per-doc artifact report to reports/content/artifacts/optimiser/YYYY-MM-DD/{slug}.md.
Update the canonical doc report at reports/content/documentation/{slug}/doc-report.md:
Append Action Log entry: date, "Optimised", "documentation-optimiser", "Score {pre} -> {post}", link to artifact report, commit SHA
Update "Current Scores > Optimiser Score" with the new score breakdown table
Update "Current Scores > Revision Audit" with the Phase 1 section results
Update "Link Health Snapshot" with current link inventory
Update "Terminology Compliance Snapshot" with current violation count (should be 0 after Rule 2)
Update "Accuracy Verification Log" with any items verified or flagged
Per-Doc Report Template
When a doc report does not exist, create it at reports/content/documentation/{slug}/doc-report.md using the following template. Populate what you can from the documentation page and Phase 0 data:
# Doc Report: {title}**Slug:** {slug}
**Path:** services/content/documentation/{slug}/index.md
**URL:** /documentation/{slug}
**Created:** {YYYY-MM-DD}
**Last updated:** {YYYY-MM-DD}
**Primary keyword:** {keyword}
**Status:** draft | published | needs-revision | optimised
## 1. Documentation Purpose and Audience### What does this page document?-**Feature/concept:** {what this page covers}
-**Target audience:** {who needs this: developer, admin, decision-maker}
-**Expected outcome:** {what the reader can do after reading}
-**Prerequisites assumed:** {what background knowledge is expected}
## 2. Accuracy Verification Log
Every verifiable claim in this documentation page is tracked here. Each item is verified or flagged on each optimiser run.
| # | Claim/Item | Type | Status | Last verified | Notes |
|---|-----------|------|--------|--------------|-------|
Types: CLI command, config example, API endpoint, version claim, file path, code example.
Status: verified, unverified, flagged, needs-sme-review.
## 3. Link Health Snapshot
| # | URL | Type | Anchor Text | Status | Line | Last checked |
|---|-----|------|------------|--------|------|-------------|
Types: internal, external.
Status: healthy (2xx), redirect (3xx), broken (4xx), error (5xx), not-found (file missing).
## 4. Terminology Compliance Snapshot
| # | Line | Found | Should be | Status |
|---|------|-------|----------|--------|
Status: fixed, outstanding.
After a clean optimiser run, this table should be empty (all violations fixed).
## 5. Action Log
Every action on this documentation page is recorded here. This is the audit trail. It must be complete.
| Date | Action | Skill | Details | Artifact Report | Commit |
|------|--------|-------|---------|----------------|--------|
Rules:
- Every skill run on this doc MUST append a row here
- Artifact reports are linked using relative paths
- Commit SHAs link to the actual code change
- This log is append-only. Rows are never edited or removed.
## 6. Current Scores### Optimiser Score: pending/75 (or /100 with analytics)
| Dimension | Score | Max |
|-----------|------:|----:|
| Structure adherence | - | 15 |
| Accuracy | - | 15 |
| Completeness | - | 10 |
| Terminology compliance | - | 8 |
| Link health | - | 8 |
| Prerequisite clarity | - | 5 |
| Troubleshooting coverage | - | 5 |
| Learning outcomes quality | - | 5 |
| Search appearance | - | 4 |
| Page engagement | N/A | 15 |
| Search traffic | N/A | 10 |
### Revision Audit: pending/10 sections passing
