tc-docs-write
/tc-docs-write
Use when writing or updating the TcKit documentation site or the README — anything under docs/content/ or README.md. Triggers on requests like "update the docs", "document this in the docs", "write a docs page for X", "the README needs Y", "add a capability page", "fix the home page", or before editing any file under docs/content/ or README.md. Enforces the user-facing-behaviour update checklist (which surface to update), the voice rules (no ADR references on user-facing surfaces, no history paragraphs, README as voice reference for the home page, no marketing scaffolding), and the "docs are a
- Author
- georgeturneruk ↗
- Repository
- tckit ↗
- Licence
- MIT
- Last repository change
- 09.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 09.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when writing or updating the TcKit documentation site or the README — anything under docs/content/ or README.md. Triggers on requests like "update the docs", "document this in the docs", "write a docs page for X", "the README needs Y", "add a capability page", "fix the home page", or before editing any file under docs/content/ or README.md. Enforces the user-facing-behaviour update checklist (which surface to update), the voice rules (no ADR references on user-facing surfaces, no history paragraphs, README as voice reference for the home page, no marketing scaffolding), and the "docs are a
Triggers from the description
Original author description
Use when writing or updating the TcKit documentation site or the README — anything under docs/content/ or README.md. Triggers on requests like "update the docs", "document this in the docs", "write a docs page for X", "the README needs Y", "add a capability page", "fix the home page", or before editing any file under docs/content/ or README.md. Enforces the user-facing-behaviour update checklist (which surface to update), the voice rules (no ADR references on user-facing surfaces, no history paragraphs, README as voice reference for the home page, no marketing scaffolding), and the "docs are a
How it works
- When to update docs
- Which surface to update
- Voice rules
- Procedure
- Anti-patterns
- Next
SKILL.md preview
---
name: tc-docs-write
description: Use when writing or updating the TcKit documentation site or the README — anything under docs/content/ or README.md. Triggers on requests like "update the docs", "document this in the docs", "write a docs page for X", "the README needs Y", "add a capability page", "fix the home page", or before editing any file under docs/content/ or README.md. Enforces the user-facing-behaviour update checklist (which surface to update), the voice rules (no ADR references on user-facing surfaces, no history paragraphs, README as voice reference for the home page, no marketing scaffolding), and the "docs are a bug when stale" stance. Do NOT use for ADR writing (that is tc-adr) or for in-code docstrings on ST POUs (that is tc-write-st).
allowed-tools: Read, Edit, Write, Grep, Glob
---
# Writing TcKit docs
The TcKit docs site lives under `docs/content/` (MkDocs). The README at the repo root mirrors a slice of it. Both are user-facing surfaces and follow the same voice rules.
## When to update docs
A change touches user-facing behaviour, and therefore needs a docs update in the same PR, if any of the following are true:
- MCP tool names, arguments, or return shapes changed
- CLI commands or flags changed
- Config keys changed (`config.json`, `~/.tckit/permissions.json`, `.env`)
- Install or setup steps changed
- Ports, adapters, or the one-rule architecture statement changed
- An ADR moved to `Implemented` for a design decision that has now shipped
If none of those apply, the change does not need a docs update. Don't invent one.
## Which surface to update
- **README** — only when the surface shown on the README itself has changed. The README is a slice, not the whole story; many real-behaviour changes affect `docs/content/` only.
- **`docs/content/`** — the default. Find the page that owns the changed surface (capability page for tool/argument changes, getting-started for install, architecture page for the one-rule statement, etc.) and edit there.
If the README and the relevant `docs/content/` page both need to change, both go in the PR.
## Voice rules
The home page (`docs/content/index.md`) takes its voice from the README. When editing the home page, match the README's structure, density, and tone. (The capability and adapter pages under `docs/content/capabilities/` are denser reference material and have their own appropriate voice — don't apply this rule to them.)
For every user-facing page:
- **No ADR references.** ADRs are an internal design store. `docs/content/`, the README, MCP tool descriptions, and CLI help text describe current behaviour, not the history of how it got there. If a passage needs more context than fits inline, link to the PR. Never link to `adrs/`.
- **No history paragraphs.** Don't chronicle what something used to be. "The port had two more methods in an earlier draft" belongs on the ADR or in the commit message, not on a page describing the current shape.
- **No marketing scaffolding on the home page.** Specifically, do not add:
- problem/solution framing tables that repeat the capabilities list (e.g. "What TcKit solves")
- redundant capability summaries ("X at a glance" next to a capabilities table)
- "Design philosophy" or similar sections that duplicate the architecture page
- feature-pitch bullet lists
State what it does, link where it can be verified, move on.
## Procedure
1. Identify which surface(s) changed (use the "Which surface to update" guide above).
2. Read the page you intend to edit so the change matches the surrounding voice, structure, and link conventions.
3. Edit. Prefer `Edit` over `Write`; never rewrite a page wholesale when a section edit will do.
4. If the change touches the home page, re-read the README first and match its voice.
## Anti-patterns
- Linking from `docs/content/` or the README to `adrs/` to explain "why". The PR or commit message is the right pointer; the docs describe current behaviour.
- Adding a "History" / "Background" / "Previously" section to a user-facing page.
- Padding the home page with capability blurbs that the capabilities table already covers.
- Updating the README for an internals-only change (e.g. a refactor of an adapter that doesn't surface to users).
- Leaving the docs stale because "the diff is the truth" — stale docs are a bug.
## Next
After the docs edit, return to the calling task (commit, PR, etc.). No further handoff.
Versions
The database has no other skills named tc-docs-write.
Database snapshot: 13.11.2026 · package version 883d8179b546 (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
- 85write-the-docs
Write or edit project documentation. Use when writing a README, design doc, or module doc. - 95docs-manager
Documentation management workflow for MkDocs sites and standalone markdown files — initialize, generate, update docs, and create change summaries. Use when asked to "create docs", "write README", "update documentation", "generate docs site", "write CONTRIBUTING", "manage… - 95docs-manager
Documentation management workflow for MkDocs sites and standalone markdown files -- initialize, generate, update docs, and create change summaries. Use when asked to "create docs", "write README", "update documentation", "generate docs site", "write CONTRIBUTING", "manage… - 90ns-docs-writer
(NS) Human-facing project docs — README, docs/ guides, runbooks, contributor markdown. Use whenever the user asks for documentation, README updates, how-to guides, or docs/ content — even if they say \"explain how to use\" instead of \"write docs\". Do NOT use for code comments,… - 100wr
Use for writing any English text like docs, notes, summaries, explanations, answers, README sections. - 90documenting
Writes project docs in the right place. Use when the user asks to document something, record a decision, write an ADR, or update the README or docs. Not for code comments, commit messages or reviews.