Skip to content
Skills Library
Programming · Writing

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.

Repository
dotfiles ↗
Licence
Apache-2.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
2
Deprecation

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

Licence

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

  1. Purpose
  2. When to edit
  3. Upstream vs local
  4. Private overlay
  5. Generated catalogues
  6. Voice and shape
  7. Omarchy plugins (docs only)
  8. Verify
Original SKILL.md headings · 65 lines, 696 words
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.

Feedback and reports

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