dotfiles-docs
/dotfiles-docs
Author and maintain the Blume docs site (docs/, dotfiles.timmo.dev) in this repo. Use when editing or pruning docs pages, blume.config.ts navigation, README docs links or docs/AGENTS.md, or deciding whether a change needs a docs edit.
- Author
- timmo001 ↗
- Repository
- dotfiles ↗
- Licence
- Apache-2.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Author and maintain the Blume docs site (docs/, dotfiles.timmo.dev) in this repo. Use when editing or pruning docs pages, blume.config.ts navigation, README docs links or docs/AGENTS.md, or deciding whether a change needs a docs edit.
Original author description
Author and maintain the Blume docs site (docs/, dotfiles.timmo.dev) in this repo. Use when editing or pruning docs pages, blume.config.ts navigation, README docs links or docs/AGENTS.md, or deciding whether a change needs a docs edit.
How it works
- Purpose
- When to edit
- Upstream vs local
- Private overlay
- Generated catalogues
- Voice and shape
- Omarchy plugins (docs only)
- Verify
SKILL.md preview
---
name: dotfiles-docs
description: Author and maintain the Blume docs site (docs/, dotfiles.timmo.dev) in this repo. Use when editing or pruning docs pages, blume.config.ts navigation, README docs links or docs/AGENTS.md, or deciding whether a change needs a docs edit.
metadata:
author: timmo001
---
# Dotfiles docs
Repo-local contract for `docs/` (Blume site at `dotfiles.timmo.dev`). Reinforces the Documentation section in repo-root `AGENTS.md`; does not replace `docs/AGENTS.md` toolchain notes.
Load this whenever the work touches hand-written documentation in this repository. Pair with `maintain-docs` when catching docs up to code; this skill owns the local density and privacy rules that flow must follow here.
## Purpose
Short personal reference: what each major part of **these** dotfiles is, and why it exists. Not a product manual, install guide for others, or catalogue of every binding, flag, quirk, or script.
## When to edit
1. **Default: no hand-written update.** Ordinary behaviour changes do not need a page edit.
2. **Update a hand-written page only when a whole section's purpose changes** (major area added, removed, or renamed), not when an implementation detail changes.
3. **Do not add a page** for every new script, binding, layout, app, or one-off tool.
4. **Bare pages:** fill with unique local customisations when a section would otherwise be empty, without expanding into keybindings, close-first rules, edge cases, or runbooks that already live in source or `--help`.
5. **Done when:** the page states what-and-why for this setup, links upstream for product behaviour, and stays short.
## Upstream vs local
- Do **not** rewrite upstream product manuals (Herdr, Hyprland, Ghostty, Omarchy, OpenCode, Quickshell, etc.).
- Link to official docs for product behaviour; document only local customisations, package layout, and how this repo wires them.
- Name external applications with an upstream link. Use plain Markdown links (`[Name](https://example.com)`); `markdown.externalLinks` opens them in a new tab, so do not write HTML anchors.
## Private overlay
- Do **not** document private overlay apps, plugins, or config by name or personal detail.
- Broad wording only (for example: "a private overlay can add or override plugins").
- Exception: plain display output names (`HDMI-A-2`, `eDP-1`, `DP-1`) are fine.
## Generated catalogues
- Stay generated; never hand-edit:
- `docs/src/content/docs/dot/commands.md` ← `dot/src/cli/spec.ts` (CLI reference; sidebar nest under **dot**, not OpenCode)
- `docs/src/content/docs/agents/opencode/{agents,commands,plugins}.md` ← OpenCode assets (paths under `/agents/opencode/`; sidebar nest under top-level **OpenCode** with `display: "group"`, Pi/Cursor as top-level siblings)
- Shared skills are catalogued in [timmo001/skills](https://github.com/timmo001/skills/blob/main/SKILLS.md#skills-catalogue) (`SKILLS.md`). Document them on `/agents/skills` (link the catalogue, then list repo-local `.agents/skills/` only). Do not ship or regenerate `reference/skills`.
- After that link, optionally list **repo-local** skills under `.agents/skills/` only (name + short role from each `SKILL.md` description). Do not catalogue the shared skills or `dotfiles-skills/` there.
- After OpenCode or `dot` sources change: `mise run docs:gen` and commit the result.
- Keep `blume.config.ts`, site Overview, `agents/overview.mdx`, `agents/skills.mdx`, `agents/opencode/overview.mdx`, and README docs-map aligned: **paths** under `/agents/overview`, `/agents/skills`, `/agents/opencode/*`, `/agents/{pi,cursor}`; **sidebar** is **Agents** (flat Overview/Skills), **OpenCode** (`display: "group"`), then top-level **Pi** and **Cursor** (no Other agents wrapper). Machine-readable docs URLs live on the site Overview; `dot/commands` sits with `dot`. Sidebar labels: `/agents/overview` → **Overview**, `/agents/skills` → **Skills**, `/agents/opencode/overview` → **Overview**, `/agents/opencode/agents` → **Agents** (via generated page title). Desktop pages live under `/desktop/*`.
- Cursor has **no** generated command catalogue in this repo; do not invent one on Cursor pages.
- `README.md` stays a slim pointer to the docs site.
- Each `distro/*` branch publishes its own docs site. Follow `docs/AGENTS.md` (Distro Sites) when adding a distro or editing `distros.ts`, `current-distro.ts` or `wrangler.jsonc`.
## Voice and shape
- Prefer short sections with a blurb and/or a table.
- Spell out opaque jargon and abbreviations (for example write "mouse acceleration profile", not a bare acronym readers must decode).
- Prefer UK spelling in human-written docs prose; keep upstream product names unchanged.
- Include a personal-setup caution where install or cloning is discussed: this repo is for reference; wholesale installation on other machines is not recommended.
## Omarchy plugins (docs only)
When documenting third-party Omarchy bar plugins:
- Import via `omarchy plugin add` (backed by `dot omarchy plugin`); they land as submodules under `omarchy/.config/omarchy/plugins/`.
- Placement and config live in `omarchy-plugins.json`.
- A private overlay may extend that layout; say so broadly, without naming private plugins.
For shell/QML implementation work, use `omarchy-shell-quickshell` instead of this skill.
## Verify
After hand-written docs edits that should ship: `mise run docs:check` (or the narrower validate/build tasks in `docs/AGENTS.md`). Report drift on generated pages rather than patching them by hand.
Versions
The database has no other skills named dotfiles-docs.
Database snapshot: 13.11.2026 · package version fbd4c7f275e5 (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
- 86dotfiles
Use for changes, reviews, troubleshooting, validation, application, or publishing work in this dotfiles repository. Load the reference for the requested workflow and honor its apply, commit, push, and PR boundaries. - 100repo-docs
Shapes a repo's docs folder and GitHub wiki, their pages, names, order and links, with a template per page type and a link check. Use when adding, reorganizing or auditing docs or a wiki. Not for the README or CONTRIBUTING, use `readme` or `contributing`. Not for sentences, use `technical-writing`. - 90check-docs
Check if documentation (README.md, AGENTS.md, docs/) is up to date with recent code changes. Use when code has been modified and docs may be stale. - 100repo
Update repository documentation (README.md, docs/, CLAUDE.md) based on session changes by dispatching the up-docs-propagate-repo sub-agent. This skill should be used when the user runs /up-docs:repo. - 100docs
Authors, audits, and maintains project docs — CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees — in modes init, update, readme, and audit. Triggers on "init claude", "update docs", "docs drift", "write a README", "/docs". - 100writing-docs
Use when writing or editing a repository documentation surface — a README, an architecture document, a CLAUDE.md or AGENTS.md pointer file, or a surface the project has registered. Do NOT activate for code comments, commit messages, or PR descriptions.