Skip to content
Skills Library
Documents & office · Writing

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

Repository
tckit ↗
Licence
MIT
Last repository change
09.08.2026

Assessment and security

90/ 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.
Content25 / 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 09.08.2026, without references to retired models or APIs.

Licence

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

update the docsdocument this in the docswrite a docs page for Xthe README needs Yadd a capability pagefix the home page
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

  1. When to update docs
  2. Which surface to update
  3. Voice rules
  4. Procedure
  5. Anti-patterns
  6. Next
Original SKILL.md headings · 60 lines, 588 words
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.

Feedback and reports

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