Updating the Docs

This page covers how to update the internal knowledge base using the update-internal-docs skill in Claude Code. Whether you're fixing a typo, refreshing a stale section, or adding a brand-new page, the flow is the same: describe what you want in plain English, iterate with Claude, and the skill opens a PR for you.

Install (one-time per machine)

In Claude Code:

/plugin marketplace add hvlabs/claude-hv-tools
/plugin install hv-internal-docs@hyperverge

After that, typing /up in Claude Code should surface /update-internal-docs in the slash-command autocomplete.

You'll need:

• gh CLI authenticated (run gh auth login if you haven't)
• Push access to hvlabs/internal-documentation (your HV GitHub team membership handles this)
• git available in PATH

Updating an existing page

Open Claude Code from wherever you happen to be working — your feature repo, your home directory, anywhere. You don't need to be in the docs repo. Then either:

/update-internal-docs

or use natural language:

I want to update the screenshot retention page to reflect the new 72-hour default.

The skill will:

1. Find the right page by searching the docs repo for keywords from your description
2. Show you the current content of the relevant section
3. Draft the update inline — you iterate until it reads right
4. Open the PR with the page owner auto-tagged as reviewer

On first use per machine, the skill asks where your local docs clone lives (or where to clone it fresh). That answer is saved to ~/.config/claude-hv-tools/config.yaml and reused on future invocations.

Adding a new page

Same command — /update-internal-docs or natural language ("I want to add a page documenting the Event Replay tool").

The skill proposes a location based on your topic and existing structure (e.g., docs/internal-tools/event-replay.md), runs a duplicate check to catch parallel pages, and drafts the content with you.

For a page in a brand-new category (a folder under docs/ that doesn't exist yet), the skill also creates the folder's _category_.json — it asks where the new category should slot into the sidebar order and generates the standard fields (label, position, collapsible, collapsed).

What the skill handles automatically

• Ensuring your local clone is up to date (git pull before starting)
• Auto-switching from a leftover branch to main when the working tree is clean
• Generating frontmatter (title, owner, owner_github, last_reviewed_on) for new pages
• Picking a clean branch name following the convention edit/<topic-slug>-<your-username>-<yyyymmdd>
• Writing the commit message and PR body
• Tagging the page owner as PR reviewer (read from the page's owner_github frontmatter)
• Offering a Docusaurus dev server preview for substantial changes

One thing the skill deliberately doesn't do: it doesn't update last_reviewed_on on edits. That field is reserved for deliberate page reviews (stale-content audits, accuracy attestation), not incidental edits — git history captures the modification time on its own.

What you provide

• The intent: a description of what you want to change, in plain English
• Iteration: reviewing the drafted changes and telling Claude what to adjust
• Approval: confirming the final diff before the PR opens
• For new pages where someone else should be the long-term owner: their GitHub username

Images and videos

Images. Paste them into the Claude Code conversation, give a local file path, or provide a URL. The skill saves them under static/img/<category>/<page-slug>-<descriptor>.<ext>, prompts you for alt text, inserts the markdown reference, and commits them alongside the page change.

Videos (Loom). Paste a Loom share URL. The skill converts it to an embed URL and inserts the iframe. Best for ad-hoc screen recordings.

Videos (local file). Upload the file yourself to the HV Internal Docs Media shared Drive folder (the skill gives you the direct link when prompted), set sharing to "Anyone at HyperVerge with the link can view," and paste the share URL back. The skill embeds the /preview iframe so viewers watch inline.

Where to get help

If the skill itself misbehaves — wrong diagnosis, broken flow, confusing prompts — open an issue against hvlabs/claude-hv-tools. For questions about the docs content or reviewer routing, ping the page owner directly (their GitHub handle is in the page's owner_github frontmatter).