Skip to content

farstic/ai-servicenow-architect / .claude/skills/operational-documentation

operational-documentation

Verified

Use 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

PairYou ownThey own
vs HLD/LLD WriterOperator/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 / DeveloperDescribing how to operate and use what was built.Designing/building it (you document delivered behaviour, you don't redesign).
vs Now Assist / KCS automationThe 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

  1. 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?"
  2. 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.)

ConceptPath
Configuring Knowledge Managementmarkdown/servicenow-platform/knowledge-management/configuring-knowledge-management.md
Create a knowledge basemarkdown/servicenow-platform/knowledge-management/create-a-knowledgebase.md
Create a knowledge articlemarkdown/servicenow-platform/knowledge-management/create-knowledge-article.md
Article templatesmarkdown/servicenow-platform/knowledge-management/configure-knowledge-article-templates.md
Article versioning / validitymarkdown/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/adminmarkdown/servicenow-platform/knowledge-management/c_KnowledgeManager.md
Retiring articlesmarkdown/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-patternBetterCitation
Custom table for runbooks/training/docskb_knowledge + KBs, or external docsmarkdown/servicenow-platform/knowledge-management/create-knowledge-article.md
Custom publish workflowBaseline review → publishmarkdown/servicenow-platform/knowledge-management/approve-article-in-review.md
KBA with no validity/review date or categorySet validity + categorise (or it rots / is unfindable)markdown/servicenow-platform/knowledge-management/article-validity.md
Publishing straight to live (skip review)Draft → Review → Publishedmarkdown/servicenow-platform/knowledge-management/approve-article-in-review.md
Theory dump in a runbookSteps, indicators, escalation — operator-grademarkdown/servicenow-platform/knowledge-management/configuring-knowledge-management.md
Writing for the wrong audienceMatch audience/register (runbook ≠ HLD ≠ end-user guide)—
Documenting intended-but-unconfirmed behaviourDocument what was built; flag unknowns as Open Questions—

§1.1 hot spots

  1. "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 proposes kb_knowledge.
  2. "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

WhenHand-off
Documented behaviour unclear / seems wrongTechnical Designer / Developer clarification (don't document a guess)
Architect-audience design docHLD/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 audienceSecurity & 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.

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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall