TheBlackCat Site Skill

Why I saved this#

The full Hermes Agent skill that operates this site, mirrored into the library itself so the operating manual lives next to the thing it operates. The older BlackCat Bookmark Skill entry documented an early, bookmark-only version; this bundle is the current skill in full — SKILL.md plus every reference file.

The verbatim files are browsable in the repo: SKILL.md and the references/ folder. Hugo page bundles don’t publish non-index Markdown to the built site, so the links below point at the repo copies. The gist is inline here.

Hard rules (from SKILL.md)#

Sync first: git pull --ff-only the clone before any work.
Never push fixes without Nik’s approval — diagnose read-only, propose, wait. Pre-authorized exceptions: bookmark saves, blog draft/publish per workflow, weekly triage. Everything else (templates, CSS, config, menu, CI, scripts, docs, deletions) needs an explicit OK; approved code changes go through a pull request by default.
Reserved front matter: source NOT url; contenttype NOT type; draft: true silently hides a page; dates from date +%F, never invented.
Reuse existing tags/topics case-insensitively; write lowercase kebab-case (python3 scripts/lint_content.py --vocab lists what exists).
New items start in content/inbox/ with status: inbox — promotion is triage’s job. Inbox pages are public but unlisted.
Commit only touched files; never mix content + template/config commits.
Lint before you push content: python3 scripts/lint_content.py <files>.
Verify after every push: commit on origin/main → CI run success → live URL 200 (drafts: 404). Template/CSS changes additionally need make check and, for visual changes, make test / screenshots.
CI owns deploys; run hugo locally only where it installs cleanly.
Never commit public/ or resources/ (gitignored — CI builds fresh).

What’s in the bundle#

File	Purpose
SKILL.md	Router, hard rules, repo facts at a glance (defers to the repo’s `AGENTS.md`)
bookmark-workflow.md	11-step bookmark pipeline: dedupe by URL, real metadata, inbox placement, CI-gated verify
blog-workflow.md	Draft-flag publishing (`draft: true` on push, “publish X” flips live) + Willison-voice style guide
content-model.md	Front matter recipes, reserved-key table, statuses and dates, taxonomy rules, weekly triage procedure
site-model.md	Custom layouts, styles, config, what is visible where, deploy pipeline and checks (verified 2026-09-29)
link-check.md	The Monday lychee link-check job, rot classes, and the rule that dead references are fixed in `content/`, not in the issue thread
projects-sync.md	`content/projects/` is generated by `scripts/sync_projects.py` — eligibility, generated fields, never hand-add a page
theblackcat-rendering-incident.md	Case study: four rendering defects, minimal-site bisection technique
theblackcat-reserved-key-incident.md	Case study: the `url:` reserved-key build failure that produced the `source:` rule

Notes#

The live copy of this skill is maintained in the agent’s skill store; this mirror is refreshed whenever the skill changes. 2026-10-25 (v1.3.0): rules 10-13 added (dead-link debt is content work, rebase-not-stash for a moving main, a visible pulse during long verifies, content/projects/ is generated) plus the link-check.md and projects-sync.md references, and the mirror section now says to copy the whole references/ directory instead of a remembered count. 2026-09-29 (v1.1.0): updated for the site redesign (new asset/layout structure, visibility rules for inbox and drafts, dates, collect: collections, content lint, PR-aware CI) and to defer to the repo’s expanded AGENTS.md. Copy the changed files back into the agent’s skill store when merging. It is contenttype: skill per the repo contract: reusable agent skill plus its supporting files, preserved in one page bundle.