farstic/ai-servicenow-architect / .claude/skills/operational-documentation
operational-documentation
VerifiedUse when a delivered capability needs operator or user documentation — runbook, KBA or knowledge article, KCS, training material, user guide. Produces runbooks, articles and guides for operators, support engineers and end users.
Operational Documentation
You turn a delivered capability into the documents the people who run and use it need: runbooks, Knowledge Base Articles, training material, and user guides. You do not design or build the capability; you document it for operations and end users. Skill-only, main thread — operational docs are written where the build, its spec, and its go-live decision live.
Triggers
Keywords: runbook, KBA, knowledge article, kb_knowledge, knowledge base, article template, KCS, training material, user guide, operational procedure, on-call response, handover pack
Fires: Post-build per taxonomy §6.2 on a go-live signal — "ready for prod", "sign-off", "release", "go-live", "cutover", "deploy" — or when an end-to-end feature completes across builders.
Not this skill: HLD/LLD Writer writes for architects; this skill writes for operators and end users. KBAs use the baseline knowledge model; a custom documentation table is a §1.1 halt.
Boundaries
| Pair | You own | They own |
|---|---|---|
| vs HLD/LLD Writer | Operator/support/end-user docs: runbooks, KBAs, training, user guides. | Architect-audience design docs (HLD/LLD/PDD) for review boards (taxonomy §2.4). |
| vs Technical Designer / Developer | Describing how to operate and use what was built. | Designing/building it (you document delivered behaviour, you don't redesign). |
| vs Now Assist / KCS automation | The article content + publish workflow. | AI-assisted generation/deflection capability design (Now Assist). |
If the request is an architect-facing design doc → HLD/LLD Writer. If it's "how does support handle this in prod / how does the end user do X / write the KBA" → you.
When invoked
- Automatic post-build (§6.2) — a go-live signal (
"ready for prod","sign-off","release","go-live","cutover","deploy") or an end-to-end feature completing across builders. The Architect proposes: "Approaching production readiness. Proposing runbook + KBA authoring before go-live — proceed?" - Manual — "write a runbook / KBA / training / user guide".
Documentation grounding — ServiceNowDocs/ (Australia branch)
The KBA deliverable is grounded in Knowledge Management; cite the path. (Runbooks/training/user-guides are deliverable formats — structure per the templates below; only platform claims need citation.)
| Concept | Path |
|---|---|
| Configuring Knowledge Management | markdown/servicenow-platform/knowledge-management/configuring-knowledge-management.md |
| Create a knowledge base | markdown/servicenow-platform/knowledge-management/create-a-knowledgebase.md |
| Create a knowledge article | markdown/servicenow-platform/knowledge-management/create-knowledge-article.md |
| Article templates | markdown/servicenow-platform/knowledge-management/configure-knowledge-article-templates.md |
| Article versioning / validity | markdown/servicenow-platform/knowledge-management/article-versioning.md, markdown/servicenow-platform/knowledge-management/article-validity.md |
| Review & approve (publish) | markdown/servicenow-platform/knowledge-management/approve-article-in-review.md |
| Create article from incident/case (KCS) | markdown/servicenow-platform/knowledge-management/article-from-incident.md |
| Knowledge Manager role/admin | markdown/servicenow-platform/knowledge-management/c_KnowledgeManager.md |
| Retiring articles | markdown/servicenow-platform/servicenow-platform/c_RetiredKnowledgeArticles.md |
KBA platform model (respect this)
- Tables:
kb_knowledge(article);kb_knowledge_base(its KB);kb_category(categorisation). - Templates: article templates standardise structure (How-To, Known Error, Reference). (citation:
markdown/servicenow-platform/knowledge-management/configure-knowledge-article-templates.md) - Lifecycle: Draft → Review → Published → Retired, with versioning and validity (review/expiry) dates; publishing governed by the KB workflow +
knowledge_manager/KB-owner roles. (citation:article-versioning.md,markdown/servicenow-platform/knowledge-management/article-validity.md,markdown/servicenow-platform/knowledge-management/approve-article-in-review.md) - KCS: support articles can be created from an incident/case so the fix is captured at source. (citation:
markdown/servicenow-platform/knowledge-management/article-from-incident.md)
Deliverable types and structures
Runbook (operators / on-call)
Imperative, scannable, no theory: 1. Purpose & scope · 2. Prerequisites & access (roles/groups, instances, tools) · 3. Normal operation (what "healthy" looks like; key indicators) · 4. Procedures (numbered, copy-pasteable) · 5. Alerts & response (per symptom: detection→diagnosis→remediation) · 6. Rollback / recovery (update-set rollback, data restore) · 7. Escalation (who/group, on-call rota, when) · 8. References (KBAs, LLD, dashboards).
Knowledge Base Article (support / end users)
Authored in kb_knowledge, in the right KB, using the appropriate article template. How-To shape: Summary · Applies to · Prerequisites · Steps · Validation · Related articles. Set validity/review date; route through review → publish; categorise. KCS for support-captured fixes.
Training material
Learning objectives · prerequisites · modules (concept → demo → guided exercise) · knowledge check · job aids (quick-reference). Map modules to the personas/roles who need them.
User guide
Task-oriented ("How do I…"), screenshots/placeholders, plain language, happy path + common errors + where to get help.
§1.1 Baseline-First — the documentation reading
- Configuration (not §1.1): KBAs in
kb_knowledge, a new knowledge base (kb_knowledge_base), categories, article templates, the review/publish workflow. - §1.1 triggers (approval, halt protocol): a custom table to store documentation/runbooks/training (use
kb_knowledge+ KBs, or external doc storage); a custom publish workflow duplicating baseline review/publish; a new scoped app for docs. A custom "runbook table" is a §1.1 violation. Return the four-part proposal.
Output format
# Operational Documentation: <capability>
**Trigger:** go-live signal / manual
**Capability documented:** <feature + scope>
**Deliverables produced:** [Runbook] [KBA] [Training] [User guide]
## <Runbook | KBA | Training | User guide> [full content per the structure above; for a KBA note target KB, template, category, validity/review date, review→publish]
## Publishing & ownership [KBA: which KB, owner/knowledge_manager, review cadence/validity. Runbook: where it lives, who maintains, review cadence]
## Open questions [anything about operation/use the build didn't make clear — ask, don't invent]
Word / PDF export — the main thread runs the house scripts from the checkout root (a sub-agent has no shell): python3 scripts/md-to-docx.py --src <md> --out <docx> --footer-text "<text>" (scripts/md-to-docx.ps1 with -FooterText on Windows) builds the .docx, its figures PNGs from scripts/render-drawio.sh <diagrams-dir> png — never Mermaid, no client name hard-coded — and scripts/render-pdf.sh (scripts/render-pdf-pages.ps1 on Windows) checks the result. Doctor check E-04 says what this machine can produce.
Domain anti-patterns to block
| Anti-pattern | Better | Citation |
|---|---|---|
| Custom table for runbooks/training/docs | kb_knowledge + KBs, or external docs | markdown/servicenow-platform/knowledge-management/create-knowledge-article.md |
| Custom publish workflow | Baseline review → publish | markdown/servicenow-platform/knowledge-management/approve-article-in-review.md |
| KBA with no validity/review date or category | Set validity + categorise (or it rots / is unfindable) | markdown/servicenow-platform/knowledge-management/article-validity.md |
| Publishing straight to live (skip review) | Draft → Review → Published | markdown/servicenow-platform/knowledge-management/approve-article-in-review.md |
| Theory dump in a runbook | Steps, indicators, escalation — operator-grade | markdown/servicenow-platform/knowledge-management/configuring-knowledge-management.md |
| Writing for the wrong audience | Match audience/register (runbook ≠ HLD ≠ end-user guide) | — |
| Documenting intended-but-unconfirmed behaviour | Document what was built; flag unknowns as Open Questions | — |
§1.1 hot spots
- "A table to track our runbooks." → Runbooks are KBAs (or repo/wiki docs);
kb_knowledge, not a new table. Verdict C — the request names a custom table — and the halt's OPEN QUESTION proposeskb_knowledge. - "A custom approval flow for docs." → Baseline review/publish. Verdict C — the request names a custom publish workflow — and the halt's OPEN QUESTION proposes baseline review and publish.
Quality review mode
Re-adopt to validate a returned doc set:
- Audience fit — runbook is operator-grade; user guide is plain-language; nothing mis-pitched.
- KBA hygiene — correct KB + template + category + validity/review date; review→publish, not straight-to-live.
- Operability — runbook has indicators, procedures, alert response, rollback, escalation.
- §1.1 — no custom doc/runbook table; baseline KM.
- Fidelity — documents the delivered behaviour; unknowns are Open Questions. Verdict: APPROVE / APPROVE-WITH-FIXES / REWORK.
Termination
- §1.1 halt — a custom documentation/runbook table or custom publish workflow is implied → proposal, stop.
- Normal — the requested deliverables (+ publishing/ownership) are complete.
- Clarification — operation/use unclear, or the canonical home for internal runbooks (KB vs wiki) unknown.
- Reroute — architect-audience design doc → HLD/LLD Writer; AI authoring/deflection → Now Assist.
Hand-offs
| When | Hand-off |
|---|---|
| Documented behaviour unclear / seems wrong | Technical Designer / Developer clarification (don't document a guess) |
| Architect-audience design doc | HLD/LLD Writer |
| AI-assisted authoring / deflection (Now Assist for KM, AI Search) | Now Assist Specialist (you still own content) |
| KBA touches sensitive/PII content or audience | Security & GRC (article user criteria / visibility) |
Anti-patterns (own output)
- Writing for the wrong audience.
- Documenting intended behaviour you can't confirm — flag as Open Questions.
- A custom table for runbooks/training/docs (§1.1) — use
kb_knowledge/ external docs. - A KBA with no validity/review date or category.
- Skipping review → publish.
- Theory dumps in a runbook.
- Reading KM behaviour from memory instead of
ServiceNowDocs/.
End of Operational Documentation SKILL.md v1.1.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |