update-polykybd-docs

Updates the PolyKybd Astro Starlight documentation site when user-facing firmware or host features change.

5|1|Updated Aug 18, 2023
One-click install
npx skills add https://github.com/thpoll83/PolyKybdHost --skill update-polykybd-docs-thpoll83
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: update-polykybd-docs
Source: https://github.com/thpoll83/PolyKybdHost/tree/main/.claude/skills/update-polykybd-docs
Command: npx skills add https://github.com/thpoll83/PolyKybdHost --skill update-polykybd-docs-thpoll83

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? User-facing changes to the PolyKybd firmware or host software (new HID commands, polyctl subcommands, settings, keyboard features, languages) silently drift out of sync with the public documentation site, leaving pages wrong or new capabilities undocumented. ## Core Features & Use Cases - Feature-to-page mapping: Routes each change type (HID protocol, polyctl CLI, host settings, keyboard features, languages) to the exact docs page that must be updated, including sidebar registration in astro.config.mjs. - Cross-repo PR workflow: Guides creating a separate branch and PR in the polykybd-docs repo, keeping docs changes out of firmware/host PRs. - Verification pipeline: Provides link-integrity checks and an Astro build procedure, including a fallback for sharp install failures and rules for image handling. - Use Case: After bumping PROTOCOL_VERSION and adding a HID command in the firmware, use this Skill to update the command table and version history in reference/hid-protocol.mdx, verify the build, and open a companion docs PR. ## Quick Start Update the PolyKybd docs site to cover the new polyctl subcommand I just added and open a PR in the polykybd-docs repo.

Frequently Asked Questions about update-polykybd-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I update PolyKybd docs after adding a firmware feature?

Create a branch in the polykybd-docs repo from origin/main, edit the page matching your change type from the feature-to-page map, verify internal links and run npx astro build, then open a separate PR against main in polykybd-docs.

Which docs page do I update for a new HID command or PROTOCOL_VERSION bump?

Update reference/hid-protocol.mdx: both the command table and the per-version history list, plus the wording stating the current version. This page is the most prone to silent drift, so all three spots must change together.

Does a new docs page appear in the navigation automatically?

No. The sidebar is hand-curated in astro.config.mjs using slug-based entries, so a new page must be added there explicitly or it stays invisible. Adding a cross-link from a related page is also recommended.

Why does npm ci fail when building the Astro docs site?

Historically sharp's postinstall could fail to fetch its prebuilt binary, but plain npm ci now works and should be tried first. Only as a fallback use npm ci --ignore-scripts with a temporary passthrough image service, and never for image changes since it disables resizing and WebP conversion.

When should I skip updating the PolyKybd documentation?

Skip docs updates for internal refactors, bug fixes with no user-visible effect, and firmware or host build plumbing. The skill applies only to user-facing changes such as new commands, settings, features, languages, or changed defaults.