Skip to content
Skills Library
Programming · Review & audit

docs-maintainer

/docs-maintainer

Keep public Kandev docs current when code or behavior changes affect CLI commands, config keys, install/deploy flows, workflows, executors, APIs, screenshots, or user-facing terminology. Use this before finishing any change with public documentation impact, and when reviewing whether a change needs docs.

Author
kdlbs ↗
Repository
kandev ↗
Licence
AGPL-3.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Keep public Kandev docs current when code or behavior changes affect CLI commands, config keys, install/deploy flows, workflows, executors, APIs, screenshots, or user-facing terminology. Use this before finishing any change with public documentation impact, and when reviewing whether a change needs docs.

Original author description

Keep public Kandev docs current when code or behavior changes affect CLI commands, config keys, install/deploy flows, workflows, executors, APIs, screenshots, or user-facing terminology. Use this before finishing any change with public documentation impact, and when reviewing whether a change needs docs.

How it works

  1. Docs Boundaries
  2. When Docs Need Updates
  3. Workflow
  4. Diagrams for Public Docs
  5. Validation
  6. Final Report
Original SKILL.md headings · 130 lines, 1,161 words
SKILL.md preview
---
name: docs-maintainer
description: Keep public Kandev docs current when code or behavior changes affect CLI commands, config keys, install/deploy flows, workflows, executors, APIs, screenshots, or user-facing terminology. Use this before finishing any change with public documentation impact, and when reviewing whether a change needs docs.
---

# Docs Maintainer

Use this skill to decide whether public docs need updates and to make those updates in the right place.

## Docs Boundaries

- Public website docs source lives under `docs/public/**`.
- Repository-facing public docs also include the root `README.md` and
  `docs/screenshots.md`; search them for feature, integration, and screenshot
  changes even when the website source is unchanged.
- Product context, requirements, and system designs stay under `docs/specs/**`.
- Implementation plans and work orders stay under `docs/plans/**`.
- Architecture decisions stay under `docs/decisions/**`.
- Raw supporting notes can remain under `docs/**` outside `docs/public/**`, but do not publish them unless rewritten for users.
- `docs/public/meta.json` owns published-page order and navigation groups. Page paths own routes, and page frontmatter owns titles and descriptions.
- The landing/docs website generates its content from this directory. Do not hand-edit generated files in the landing repository.

## When Docs Need Updates

Check public docs when a change affects:

- CLI commands, flags, install commands, or runtime launch behavior.
- Configuration keys, environment variables, defaults, profiles, or feature flags.
- Workspaces, workflows, tasks, agents, executors, worktrees, Git behavior, or review flows.
- Docker, Kubernetes, service, desktop, remote environment, or Windows instructions.
- Public APIs, WebSocket messages, workflow import/export schemas, or integration contracts.
- Screenshots, visible UI labels, navigation, onboarding, or user-facing terminology.

Skip public docs when the change is:

- Purely internal refactoring with no behavior change.
- Test-only, fixture-only, or build-only without user-visible behavior.
- A speculative plan or design note that belongs in `docs/specs/**`, `docs/plans/**`, or `docs/decisions/**`.

## Workflow

1. Identify docs impact from the diff and changed behavior.
2. Search `docs/public/**`, the root `README.md`, and `docs/screenshots.md`
   first for affected terms, features, integrations, and screenshots.
   For behavior changes, also search the same contract and old precedence/reset
   wording across `docs/public`, `docs/specs`, and `docs/decisions`; ensure the
   introductory summary agrees with later upgrade and recovery sections.
3. If public docs exist, update them with the same PR as the behavior change.
4. If no public docs exist but the behavior is user-facing, add or propose the smallest useful public page/section.
   When adding a page, include `title` and `description` frontmatter and list its page slug or path without the `.md` extension in `docs/public/meta.json` exactly once, for example `cli`. See `docs/public/README.md`.
5. If the change only updates implementation intent or architectural history, update specs/plans/ADRs instead.
6. For operational recovery guidance, distinguish permission-denied, active-lock,
   and stale-lock failures before recommending a fallback. Verify that the
   fallback uses a different execution or resource path; if it shares the same
   worktree, state that it cannot bypass the contention.
7. Classify each public page by its primary Diátaxis content type:
   - **Tutorial:** teach a beginner by leading them through one successful outcome.
   - **How-to guide:** help a reader complete a known task, with focused steps, choices, and recovery paths.
   - **Reference:** provide accurate, complete lookup information such as fields, commands, defaults, limits, or protocol contracts.
   - **Explanation:** build understanding of a concept, boundary, rationale, or trade-off.
   Keep one dominant type per page. Link to another page when a long section changes from learning to procedure, lookup, or explanation; do not force every page into a generic tutorial-shaped opening.
8. Keep public docs task-oriented and scan-friendly:
   - Tutorials should lead with prerequisites and a linear first success; how-to guides should lead with the task, expected result, and only the prerequisites it needs.
   - Reference pages should lead with scope and the contract readers need to look up; explanation pages should lead with the question or concept and why it matters.
   - Use short paragraphs (one idea, normally three sentences or fewer) and bullets for choices, limits, and consequences.
   - Prefer a link to the page that owns a detailed contract over repeating it.
   - Use native `<details>` / `<summary>` disclosures for non-essential edge cases, exhaustive option lists, and advanced configuration. Keep required steps, security warnings, destructive effects, and eligibility limits visible.
   - Use tables only for genuine comparisons, not narrative text.
   - Treat drafts or substantial rewrites over about 3,000 words as a structure-review trigger, not a word limit. Check that the page serves one main audience, content type, and reader goal; remove repeated explanations; move secondary detail to its owning page or a disclosure; and keep the common path near the top. Add a short grouped topic index when a long page needs to remain together. Preserve supported behavior, limits, security warnings, and recovery requirements instead of deleting them to reduce word count. See `docs/public/README.md` for the full long-page review rule.
9. Preserve internal links inside `docs/public/**` where possible. Link to source-only raw docs only when the raw note is intentionally not published.
10. Note docs impact and the page's primary content type in the PR body.

## Diagrams for Public Docs

When a page explains architecture, lifecycle, data flow, state, trust
boundaries, ownership, or a multi-step workflow, decide whether a visual
teaches more than prose, a table, or bullets. If it does, use
`/diagram-design` and load its
`references/kandev-public-docs.md` integration guide.

- Choose a semantic pattern first when behavior, state, ownership, trust, or
  risk carries the meaning. Then choose and load the nearest visual-type
  reference.
- Use `doc-inline`, `balanced`, and `mixed` for normal docs-column figures
  unless the page or source requires another output dial.
- Author a self-contained HTML source, run the diagram self-check, geometry
  check, and skin check, then export a reviewed local SVG. Use PNG only when a
  raster fallback is required. Store the published image under
  `docs/screenshots/` and reference it relatively.
- If labels are dense at docs-column width, tighten the SVG viewBox and raise
  the readable type ramp before publishing. Use a plain Markdown image so the
  landing publisher copies it to `/docs/screenshots`; do not nest it inside a
  Markdown link. Add a separate reference-style Markdown link targeting
  `../../docs/screenshots/<file>.svg` so readers can open the full-size vector.
- Give every image precise alt text and explain the diagram's essential result
  in nearby prose. Use real Kandev names from authoritative source material.
- For an existing Mermaid diagram, use the skill's Mermaid import workflow
  before revising it. Redraw for quality instead of reproducing Mermaid's
  automatic layout, and keep Mermaid only when the publication constraints
  make it the better source.
- Keep the diagram within its complexity budget. Split an overview from detail
  when the reader needs more than one focused figure.

## Validation

Run the checks relevant to your change:

```bash
# Replace SEARCH_TERM with the command, config key, or terminology that changed.
rg -n "SEARCH_TERM" docs/public docs/specs docs/decisions
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
```

Run both public-doc validators when the root README or screenshot catalog is
updated, not only when `docs/public/**` changes.

For website docs publishing changes, also run from the landing repo:

```bash
pnpm install --frozen-lockfile
pnpm --filter @kandev/docs fetch-docs
pnpm exec vitest run apps/docs/lib/docs-processing.test.ts apps/docs/lib/public-docs.test.ts
pnpm --filter @kandev/docs build
```

## Final Report

State one of:

- `Public docs updated:` with changed `docs/public/**` files.
- `Internal docs updated:` with changed specs/plans/decisions.
- `No docs change needed:` with one concrete reason.

Versions

The database has no other skills named docs-maintainer.

Database snapshot: 13.11.2026 · package version 98c770feb3b3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-kandev-plugin
    Create, modify, debug, test, package, or publish a Kandev runtime plugin in its dedicated repository. Use only when the requested work targets a Kandev plugin implementation or its release and marketplace lifecycle, including fixing a bug in an existing plugin. Do not use for…
  • 95docs-update
    Assess documentation impact and update affected docs for a code, API, config, or operator workflow change. Use when a change affects documented behavior, when asked to update stale docs or reconcile docs with code, or when a decision or status recorded in plans or ADRs changed.…
  • 100update-docs
    This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what docs need updating", "sync docs with code", "scaffold docs for this feature", "document this feature", "review docs completeness", "add docs for this change",…
  • 100docs-as-definition-of-done
    Use when finishing any code change that modifies behavior, public API, CLI flags, config shape, defaults, error messages, or anything a reader-of-the-docs would model — before committing, pushing, or declaring "done." Forbids deferring doc updates to a follow-up commit, ticket, or "cleanup later.
  • 100update-docs
    Update public documentation in docs/public/ when features or tools change. Triggers on "/update-docs", "update docs", "update documentation".
  • 100debug
    Diagnose Kandev bugs, running-instance issues, UI/browser failures, and runtime behavior. Use when the user reports unexpected behavior, asks to investigate, asks to add logs/instrumentation, or when a fix needs root-cause evidence before implementing. Triage first, gather…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.