Doc
Write or update the documentation the caller needs, grounded in the current
repository and its accepted intent. A small explanation needs no interview,
coverage ledger or separate report. Select only the mode relevant to the task.
Modes
| Need |
Scope and reference |
| Explain an API, command, code-map or architecture |
Inspect its consumers, source and tests, and write to the existing document owner. A coverage percentage needs a numerator and denominator from one enumerated, checked entity set (validation techniques). How the code works is Research's repository tracing; Doc writes it down when a document is requested. |
| Create or improve a README |
Lead with the user's problem and a working first-use path; preserve useful depth. See README craft. |
| Check an advertised install, upgrade or first-success path |
Follow the selected package and current instructions in an authorized disposable environment. See developer journey. |
| Audit or scaffold OSS documentation |
Compare existing docs with the requested pack. Create missing files; revise existing files only within the authorized request. See OSS pack. |
| Initialize missing entry documents |
Create only explicitly requested missing files; report existing paths as skipped. See setup examples. |
| Bring docs current after a change, describe a change for reviewers, or write release notes for a range |
Start from the exact diff and its public surface; fix what it proves wrong and ask about judgment calls. See change-driven docs. |
| Preserve a session for another context, or resume from one |
Read the handoff reference before writing or resuming one. A handoff records only facts you observed: anything else is unknown or the caller's unverified claim, and a note saying HOLD or paused is not state. |
| Get facts or decisions only another person holds |
Write one questionnaire they can answer alone; the caller sends it. |
These are optional task shapes, not successive phases. Detailed references
supply techniques and formats; they do not add interviews, approval checkpoints,
reports or files beyond the accepted request. Existing authorization to revise
specified documents is sufficient.
<skill-dir> is the directory that contains this SKILL.md. Claude Code shows it
as "Base directory for this skill"; Codex lists this skill's SKILL.md path; in
an AgentOps source checkout it is skills/doc. Replace <skill-dir> with that
absolute path before running a command. The working directory stays the user's
repository. If the host did not show where this skill is installed, use the
directory of the SKILL.md you read. If you cannot determine it, do not guess a
path or run a same-named script from the current repository; say the bundled
script is unavailable and compare the repository's documentation files with the
requested pack by hand.
Grounded writing
- Identify the audience, question and existing document owner. Reuse accepted
intent; ask only for missing content that materially changes the document.
Name the reader's need: learning from scratch, doing one task, looking up a
fact, or understanding why. A reference list does not show how to do the
task it exists for. For a reader who learns from it, explain each idea before
a section relies on it (ordering).
- Read the relevant declarations and verify them against code, configuration,
command help or executable behavior. Use the caller's domain terminology.
Take steps in another vendor's interface (menus, settings, where a value
appears) from its current docs or the caller, or mark them unverified; never guess.
For a larger surface, retain enough source references to disclose what was
inspected and what remains unknown; do not imply whole-repository coverage.
- Make the smallest useful edit. Explain non-obvious rules, ordering and tradeoffs
when they help the reader; a reference page need not manufacture a lesson.
Preserve operator policy and history outside the authorized scope. Edit an
existing document in its own shape, from a fresh read if a person may have
changed it (their edits win): extend the passage that already says it, under
any heading, rather than add a duplicate section, and do not reorder or
restyle it into a template unless asked for a rewrite. When rewriting
existing prose, keep every fact, number, name, citation and identifier,
and keep each claim's certainty: "may" does not become "does".
When condensing (a summary, handoff or release notes), keep every failure,
caveat, open question and request, and sound no more finished, positive or
certain than the source; say where it is vague or contradicts itself.
Leave code blocks, quotes and link targets untouched unless they are the
thing to fix.
- Check links, cited commits and paths, leftover drafting scaffold, examples
and the repository's documentation build or validator (techniques).
Remove empty claims and redundant prose; prose guidance
can help when the requested output is substantial.
A link handed to a reader (in a document, report, handoff or change
description) must open the exact item it names for that reader. Build
repository URLs from Git rather than by hand, and point them at a ref that
already contains the pushed content: a main-branch link to a file that exists
only on a feature branch is dead. Link the item itself (the pull request, the
file and line), not its parent page. When no direct link can be verified, say
where to find the item instead of giving a guessed link.
- Return changed paths and check results, plus unresolved factual gaps. Write a
separate report only when the caller requests one or an existing consumer
requires it.
Missing-document setup
Create only the requested missing documents, such as PRODUCT.md, GOALS.md
or AGENTS.md; a collision is skipped, not overwritten by setup. Verify the
created paths and report created, skipped and failed writes. Setup does not
install tools, run ao session bootstrap, initialize Git or trackers, start a
runtime, add hooks, or infer a repository workflow. AgentOps verdict storage is
created only on explicit request; see AgentOps internals.
Reference menu
Load these only for the document being written. They supply examples and
techniques under the kernel's accepted scope, not additional workflow gates.
- Writing and checks: prose workmanship (cleanup, learner order, diagrams, one live statement), validation techniques.
- After a change: change-driven docs for doc drift, reader-need coverage and change descriptions.
- Explicit context configuration: context routing.
- AgentOps itself (vocabulary, evidence routing, handoff commands): AgentOps internals.
1---2name: doc3description: "Write source-checked docs, READMEs, change descriptions and handoffs. Use when: documenting a change, leaving or resuming a handoff, or drafting a questionnaire for someone else."4practices:5- wiki-knowledge-surface6- code-complete7- pragmatic-programmer8hexagonal_role: supporting9consumes:10- repo-context11produces:12- documentation13- session-handoff14context_rel: []15skill_api_version: 116user-invocable: true17metadata:18 source: https://skillmd.com/skills/hashgraph-online/doc19 capabilities: [doc, initialize_missing_docs, write_session_handoff]20 effects: [write_documentation, write_requested_handoff, create_requested_evidence_directory]21 canonical_status: canonical22 disposition: keep_specialist23 tier: product24 dependencies: []25output_contract: requested documentation or handoff with source references, check results and explicit gaps26---2728# Doc2930Write or update the documentation the caller needs, grounded in the current31repository and its accepted intent. A small explanation needs no interview,32coverage ledger or separate report. Select only the mode relevant to the task.3334## Modes3536| Need | Scope and reference |37|---|---|38| Explain an API, command, code-map or architecture | Inspect its consumers, source and tests, and write to the existing document owner. A coverage percentage needs a numerator and denominator from one enumerated, checked entity set ([validation techniques](references/validation-rules.md)). How the code works is [Research](../research/SKILL.md)'s repository tracing; Doc writes it down when a document is requested. |39| Create or improve a README | Lead with the user's problem and a working first-use path; preserve useful depth. See [README craft](references/readme-craft.md). |40| Check an advertised install, upgrade or first-success path | Follow the selected package and current instructions in an authorized disposable environment. See [developer journey](references/developer-journey.md). |41| Audit or scaffold OSS documentation | Compare existing docs with the requested pack. Create missing files; revise existing files only within the authorized request. See [OSS pack](references/oss-pack.md). |42| Initialize missing entry documents | Create only explicitly requested missing files; report existing paths as skipped. See [setup examples](references/bootstrap/examples.md). |43| Bring docs current after a change, describe a change for reviewers, or write release notes for a range | Start from the exact diff and its public surface; fix what it proves wrong and ask about judgment calls. See [change-driven docs](references/change-driven-docs.md). |44| Preserve a session for another context, or resume from one | Read [the handoff reference](references/handoff.md) before writing or resuming one. A handoff records only facts you observed: anything else is `unknown` or the caller's unverified claim, and a note saying HOLD or paused is not state. |45| Get facts or decisions only another person holds | Write one [questionnaire](references/questionnaire.md) they can answer alone; the caller sends it. |4647These are optional task shapes, not successive phases. Detailed references48supply techniques and formats; they do not add interviews, approval checkpoints,49reports or files beyond the accepted request. Existing authorization to revise50specified documents is sufficient.5152`<skill-dir>` is the directory that contains this SKILL.md. Claude Code shows it53as "Base directory for this skill"; Codex lists this skill's SKILL.md path; in54an AgentOps source checkout it is `skills/doc`. Replace `<skill-dir>` with that55absolute path before running a command. The working directory stays the user's56repository. If the host did not show where this skill is installed, use the57directory of the SKILL.md you read. If you cannot determine it, do not guess a58path or run a same-named script from the current repository; say the bundled59script is unavailable and compare the repository's documentation files with the60requested pack by hand.6162## Grounded writing63641. Identify the audience, question and existing document owner. Reuse accepted65 intent; ask only for missing content that materially changes the document.66 Name the reader's need: learning from scratch, doing one task, looking up a67 fact, or understanding why. A reference list does not show how to do the68 task it exists for. For a reader who learns from it, explain each idea before69 a section relies on it ([ordering](references/prose-and-report-workmanship.md#order-ideas-for-a-learner)).702. Read the relevant declarations and verify them against code, configuration,71 command help or executable behavior. Use the caller's domain terminology.72 Take steps in another vendor's interface (menus, settings, where a value73 appears) from its current docs or the caller, or mark them unverified; never guess.74 For a larger surface, retain enough source references to disclose what was75 inspected and what remains unknown; do not imply whole-repository coverage.763. Make the smallest useful edit. Explain non-obvious rules, ordering and tradeoffs77 when they help the reader; a reference page need not manufacture a lesson.78 Preserve operator policy and history outside the authorized scope. Edit an79 existing document in its own shape, from a fresh read if a person may have80 changed it (their edits win): extend the passage that already says it, under81 any heading, rather than add a duplicate section, and do not reorder or82 restyle it into a template unless asked for a rewrite. When rewriting83 existing prose, keep every fact, number, name, citation and identifier,84 and keep each claim's certainty: "may" does not become "does".85 When condensing (a summary, handoff or release notes), keep every failure,86 caveat, open question and request, and sound no more finished, positive or87 certain than the source; say where it is vague or contradicts itself.88 Leave code blocks, quotes and link targets untouched unless they are the89 thing to fix.904. Check links, cited commits and paths, leftover drafting scaffold, examples91 and the repository's documentation build or validator ([techniques](references/validation-rules.md)).92 Remove empty claims and redundant prose; [prose guidance](references/prose-and-report-workmanship.md)93 can help when the requested output is substantial.94 A link handed to a reader (in a document, report, handoff or change95 description) must open the exact item it names for that reader. Build96 repository URLs from Git rather than by hand, and point them at a ref that97 already contains the pushed content: a main-branch link to a file that exists98 only on a feature branch is dead. Link the item itself (the pull request, the99 file and line), not its parent page. When no direct link can be verified, say100 where to find the item instead of giving a guessed link.1015. Return changed paths and check results, plus unresolved factual gaps. Write a102 separate report only when the caller requests one or an existing consumer103 requires it.104105## Missing-document setup106107Create only the requested missing documents, such as `PRODUCT.md`, `GOALS.md`108or `AGENTS.md`; a collision is skipped, not overwritten by setup. Verify the109created paths and report created, skipped and failed writes. Setup does not110install tools, run `ao session bootstrap`, initialize Git or trackers, start a111runtime, add hooks, or infer a repository workflow. AgentOps verdict storage is112created only on explicit request; see [AgentOps internals](references/agentops-internal.md).113114## Reference menu115116Load these only for the document being written. They supply examples and117techniques under the kernel's accepted scope, not additional workflow gates.118119- Writing and checks: [prose workmanship](references/prose-and-report-workmanship.md) (cleanup, learner order, diagrams, one live statement), [validation techniques](references/validation-rules.md).120- After a change: [change-driven docs](references/change-driven-docs.md) for doc drift, reader-need coverage and change descriptions.121- Explicit context configuration: [context routing](references/bootstrap/context-routing.md).122- AgentOps itself (vocabulary, evidence routing, handoff commands): [AgentOps internals](references/agentops-internal.md).