QDG KB updatewiki User Guide

Purpose

The updatewiki skill lets a developer ask Codex or Claude Code to create, retrieve, and maintain project documentation in QDG KB. Pages are stored as Markdown in the Odin qdgwiki database. Every publication creates an immutable version with a change description, author, and optional task or commit reference.

Installing the skill and connecting the MCP server are separate steps:

1. The skill teaches the client how to interpret updatewiki requests.
2. The QDG KB MCP server supplies the database tools used by the skill.

Both must be available. A visible skill without the MCP tools cannot update the knowledge base.

The developer is leveraging AI editorial judgment

updatewiki is not a file append or database-copy command. Codex or Claude reads the current KB page, the new information, and relevant project evidence, then decides what is important enough to preserve, where it belongs, and how it should be expressed. The AI produces the complete revised Markdown page. The MCP server performs deterministic validation, concurrency checking, and immutable version storage; it does not decide what the documentation should say.

How an update is produced

For a request such as updatewiki changelog with release.md:

1. Codex or Claude resolves the current project and page.
2. It retrieves the current Markdown and immutable version number through MCP.
3. It reads release.md completely and inspects other relevant evidence when available.
4. It uses AI judgment to identify durable changes, omit transient noise, preserve correct existing content, and place the new material in the appropriate section.
5. It creates the complete revised Markdown page rather than merely appending the file.
6. It sends that complete page and the expected current version to kb_update_page.
7. The MCP validates and saves the result as a new immutable version. A stale version is rejected so the AI can reread and merge concurrent work.

Prerequisites

• Windows PowerShell.
• Python 3.11 or newer, available through the py launcher.
• Access to C:\Users\Robert\Projects\QDG KB or another checkout of this repository.
• Access to the Odin MySQL HA cluster and the qdgwiki schema.
• A database configuration file. The default is C:\Users\Robert\projects_config\db.json; set QDGKB_DB_JSON when using a different location.
• Codex, Claude Code, or both.

Do not copy database credentials into the repository, a skill file, an MCP configuration checked into Git, or a prompt.

Prepare QDG KB

Open PowerShell and run:

Set-Location 'C:\Users\Robert\Projects\QDG KB'
powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1
powershell -ExecutionPolicy Bypass -File scripts\migrate.ps1 status
powershell -ExecutionPolicy Bypass -File scripts\migrate.ps1 apply
powershell -ExecutionPolicy Bypass -File scripts\verify.ps1

Expected results:

• bootstrap.ps1 creates .venv and installs QDG KB in editable mode.
• migrate.ps1 status lists database migrations and their state.
• migrate.ps1 apply reports applied migrations or that the schema is current.
• verify.ps1 completes Ruff and pytest without errors.

If the database configuration is elsewhere, set it before running migrations or starting the client:

$env:QDGKB_DB_JSON = 'D:\secure\db.json'

Install for Codex

1. Install the skill

For every repository used by your Windows account:

Set-Location 'C:\Users\Robert\Projects\QDG KB'
powershell -ExecutionPolicy Bypass -File scripts\install-skill.ps1 -Target codex

This copies the skill to:

C:\Users\Robert\.agents\skills\updatewiki\SKILL.md

For QDG KB repository scope only:

powershell -ExecutionPolicy Bypass -File scripts\install-skill.ps1 `
  -Target codex -Scope repository

Codex discovers repository skills under .agents\skills and personal skills under %USERPROFILE%\.agents\skills. It normally detects changes automatically; restart Codex if the skill does not appear.

2. Configure the MCP server

Add this to %USERPROFILE%\.codex\config.toml. Merge it with the existing file rather than replacing other settings:

[mcp_servers.qdgkb]
command = "C:\\Users\\Robert\\Projects\\QDG KB\\.venv\\Scripts\\python.exe"
args = ["-m", "qdgkb"]
cwd = "C:\\Users\\Robert\\Projects\\QDG KB"
startup_timeout_sec = 20

When using a non-default database file, add only its path—not its credentials:

[mcp_servers.qdgkb.env]
QDGKB_DB_JSON = "D:\\secure\\db.json"

Restart Codex after changing MCP configuration. In the Codex desktop app, the equivalent setup is under Settings > MCP servers: add an STDIO server named qdgkb with the Python executable and arguments shown above, save, and restart.

3. Confirm Codex discovery

Start a new task and check:

/skills
/mcp

The skill list should include updatewiki. The MCP list should include qdgkb, with tools whose names begin with kb_.

You can explicitly invoke the skill as $updatewiki, or use a natural request beginning with updatewiki.

Install for Claude Code

1. Install the skill

For every repository used by your Windows account:

Set-Location 'C:\Users\Robert\Projects\QDG KB'
powershell -ExecutionPolicy Bypass -File scripts\install-skill.ps1 -Target claude

This copies the skill to:

C:\Users\Robert\.claude\skills\updatewiki\SKILL.md

For QDG KB repository scope only:

powershell -ExecutionPolicy Bypass -File scripts\install-skill.ps1 `
  -Target claude -Scope repository

Claude Code discovers personal skills from ~/.claude/skills and project skills from .claude/skills. Invoke this skill directly as /updatewiki. Claude may also select it when the request matches its description.

2. Configure the MCP server

Run this as one PowerShell command:

claude mcp add qdgkb --scope user -- `
  'C:\Users\Robert\Projects\QDG KB\.venv\Scripts\python.exe' -m qdgkb

Use --scope local instead of --scope user when it should apply only to the current project. Avoid --scope project if the generated .mcp.json would expose a machine-specific path to other developers.

If QDGKB_DB_JSON must be set explicitly:

claude mcp add qdgkb --scope user `
  --env QDGKB_DB_JSON='D:\secure\db.json' -- `
  'C:\Users\Robert\Projects\QDG KB\.venv\Scripts\python.exe' -m qdgkb

3. Confirm Claude discovery

Run:

claude mcp list
claude mcp get qdgkb

Then start Claude Code and use:

/mcp
/updatewiki find the QDG KB project overview

If the top-level ~/.claude/skills directory was created after Claude Code started, restart Claude Code once. Edits inside an already discovered skill directory normally reload automatically.

Install for both clients

The skill-copy step can target both clients:

powershell -ExecutionPolicy Bypass -File scripts\install-skill.ps1 -Target all

MCP configuration remains client-specific. Configure Codex and Claude Code separately.

Test the complete workflow

Use a real, non-sensitive project that already exists in QDG KB. Begin with read-only tests.

Test 1: Server connection

Ask:

findwiki show the QDG KB overview

Pass condition: the client searches or retrieves the QDG KB project and reports its stored page.

Test 2: Skill activation

Ask without explicitly selecting the skill:

What does the QDG KB wiki say about installing updatewiki?

Pass condition: the client chooses the skill and uses QDG KB tools rather than guessing from model memory.

Test 3: Versioned write

Create a harmless Markdown file in a test project, then ask:

updatewiki notes with test-note.md

Pass condition: the response names the project and page, reports a new version, and gives a concise change description. Retrieve the page again and confirm the new text is present.

Test 4: Concurrency protection

This is normally covered by automated tests. If manually exercising it, update the same page using an old expected_version. Pass condition: QDG KB rejects the stale write and asks the client to reread and merge instead of overwriting the newer version.

Automated verification

From the repository:

powershell -ExecutionPolicy Bypass -File scripts\verify.ps1

To run the live Odin integration test deliberately:

$env:QDGKB_RUN_INTEGRATION = '1'
.\.venv\Scripts\python.exe -m pytest tests\integration\test_odin.py

The integration test creates temporary records and removes them afterward. Run it only when the selected database configuration points to the intended qdgwiki schema.

Troubleshooting

The skill is not listed

• Confirm the file is exactly ...\updatewiki\SKILL.md, including capitalization.
• Confirm user scope uses %USERPROFILE%\.agents\skills for Codex or %USERPROFILE%\.claude\skills for Claude Code.
• Check that the YAML frontmatter begins and ends with ---.
• Restart the client if the top-level skill directory was newly created.
• In Codex, make sure the skill is not disabled in ~/.codex/config.toml.
• In Claude Code, inspect /skills and any skillOverrides in .claude/settings.local.json.

The skill is visible but no kb_ tools exist

The MCP server is missing, disabled, or failed to start. Check /mcp, verify the executable path, and run the server directly:

& 'C:\Users\Robert\Projects\QDG KB\.venv\Scripts\python.exe' -m qdgkb

An STDIO server waits silently for protocol input. If it exits immediately, inspect the displayed error. Press Ctrl+C to stop a healthy waiting process.

Database connection fails

• Confirm the JSON file exists and is valid JSON.
• Confirm the account can reach Odin through the required network or VPN.
• Confirm the database account can use the qdgwiki schema.
• Run scripts\migrate.ps1 status to separate database problems from client configuration.
• Do not paste the JSON contents into a prompt or log.

No module named qdgkb

Run scripts\bootstrap.ps1 again. Ensure the MCP command uses the repository's .venv Python, not a different system Python.

MCP startup times out

• Increase Codex startup_timeout_sec above 20 when the drive or network is slow.
• In Claude Code, increase MCP_TIMEOUT before launching Claude.
• Test database connectivity with scripts\migrate.ps1 status.

A page update reports a version conflict

This is expected concurrency protection. The skill should reread the current page, merge both changes, and retry once. If the two changes disagree semantically, it should ask a developer which content is authoritative.

A Markdown update is rejected

QDG KB rejects empty pages, content larger than 2 MB, unclosed fenced code blocks, and content that resembles a credential or private key. Fix the Markdown rather than disabling validation.

Further reading

• Codex skills
• Codex MCP configuration
• Claude Code skills
• Claude Code MCP