🧩 skills

Agent skills by Titus Kirch — installable via skills.sh in Claude Code, Codex, Cursor, OpenCode and friends

---

npx skills add TitusKirch/skills        # npm
pnpm dlx skills add TitusKirch/skills   # pnpm
yarn dlx skills add TitusKirch/skills   # yarn
bunx skills add TitusKirch/skills       # bun

That's it. Every skill in this bundle is now discoverable inside your agent — no manifest editing, no symlink dance.

📦 Install & run

The skills.sh CLI is the path for users — the four package-manager forms are the hook above. Set DISABLE_TELEMETRY=1 to opt out of its anonymous install-count telemetry.

Then invoke a skill by name or trigger phrase:

/write-readme draft a README for my new Laravel package

Your agent picks the right one from the description: field in each SKILL.md — write that field tight and it routes correctly.

Two other install paths — symlink locally, or copy a single skill by hand

Symlink locally (recommended when developing on this repo)

git clone https://github.com/TitusKirch/skills.git
cd skills
pnpm install
pnpm skills:link        # symlinks every skill into ~/.claude/skills/ and ~/.agents/skills/
pnpm skills:list        # lists every SKILL.md in the repo
pnpm skills:unlink      # removes only the symlinks pointing back into this repo

Both destinations, every run: ~/.claude/skills/ is the only user-scope path Claude Code reads, and ~/.agents/skills/ is the vendor-neutral one Codex, Cursor, OpenCode and Gemini CLI read — Codex reads nothing else this repo links to. skills:unlink clears both.

Restart your agent (Claude Code: /reload-plugins). Because the skills live as symlinks, edits in the working copy are picked up live.

Install a single skill by hand

Copy one skill folder into:

• User scope — ~/.claude/skills/<skill-name>/ (Claude Code) or ~/.agents/skills/<skill-name>/ (Codex, Cursor, OpenCode, Gemini CLI) — available in every project.
• Project scope — .claude/skills/<skill-name>/ or .agents/skills/<skill-name>/ — committed alongside the consuming project.

✨ Features

• 🧩 Self-contained skills — each folder under skills/ ships a SKILL.md (YAML frontmatter + body) plus optional templates, references and scripts. No runtime code.
• ⚙️ Configurable per repo — one committed .tituskirch-skills.json tells every skill which forge, tracker, branch and language this repo uses. Absent config means built-in defaults.
• 🔁 Two AI work loops — an implement loop that builds and pushes, a review loop that judges the result as an independent agent; the issue's label is the entire handover.
• 🛡️ Lint-clean by construction — oxlint + oxfmt (markdown-first) gated by husky + commitlint + lint-staged. CI runs the same checks, plus a conformance check against the Agent Skills spec.
• 📥 Three install paths — skills.sh CLI for users, pnpm skills:link for live local dev, hand-copy for one-off picks.
• 📋 House-style enforced — the write-readme skill prescribes the README layout, section emojis and badge palette so every kirchDev repo looks the same.
• 🚀 Release-please ready — Conventional Commits drive automated versioning + CHANGELOG via release-please on main.

🧩 Available skills

Repository & release

Commits, pull requests, releases and dependency updates — each driven by the repo's own conventions.

Skill	Description
atomic-commit	Commits session work as atomic Conventional Commits (or just plans).
merge-deps	Triages a repo's open dependency-bot requests, verifying each on its own branch before merging.
prune-branches	Reports a repo's stale branches grouped by why they are stale, and deletes the ones confirmed.
prune-comments	Reports comments that only restate the code, and removes them after confirmation.
pull-request	Opens a pull request (GitLab, a merge request) from the current branch; forge and host chosen by config.
release	Drives the release-please flow to a shipped release — promotes the integration branch, then merges the release PR. GitHub-only.
update-deps	Updates a repo's dependencies via its own updater — minor by default, honouring gates and pins.

Tracked work

Issues, the two AI work loops (implement and review), handing work between sessions, and summarising one.

Skill	Description
handoff	Hands off in-progress work to another agent or session via a committed handoff document.
issue	Creates/updates/searches issues across GitHub (gh), GitLab (glab), Linear (MCP) or local files, tracker chosen by config.
refine-issue	Takes one filed issue to the point a human can approve it for the AI loop — finds the open decisions and closes them.
tldr	Summarises the last answer, the task just finished, or the whole session into a fixed section order.
work-implement	Implements one tracked issue and pushes it for AI review — claim, implement, verify, push, hand off.
work-implement-queue	Drains the ready/changes-requested queue — implements each issue to a pushed, reviewable state.
work-review	Reviews one issue's pushed work as an independent agent — verdict routes to done, changes, needs-human, or blocked.
work-review-queue	Drains the awaiting-review queue — reviews each pushed issue with a fresh agent, routing to done/changes/needs-human.

Docs & READMEs

Generate and maintain project documentation, READMEs and terminal demos in the house style.

Skill	Description
compact-readme	Slims down an existing overstuffed README without losing information.
vhs-demo	Creates and maintains a reproducible terminal-demo GIF from a VHS tape.
write-contributing	Writes and reconciles CONTRIBUTING.md in the house style, deriving every repo fact from the file that owns it.
write-docs	Scaffolds, extends and reconciles a project's docs/ tree — ADRs included — in the TitusKirch docs format.
write-readme	Generates project READMEs in the kirchDev house style.

Meta

Configure the skills themselves, per repo.

Skill	Description
tituskirch-skills-config	Sets up, reconciles, and drift-checks .tituskirch-skills.json, the shared config the other TitusKirch skills read.
validate-skills	Validates skills against the Agent Skills spec via skills-ref, separating spec violations, client extensions and house-style deviations.

⚙️ Configuration

Most skills read an optional, committed .tituskirch-skills.json at the consuming repo's root — the one place that says which forge, tracker, branch and language that repo uses:

{
  "$schema": "https://raw.githubusercontent.com/TitusKirch/skills/main/tituskirch-skills.schema.json",
  "forge": "github",
  "language": "de",
  "verify": "pnpm verify",
  "pr": { "base": "dev" }
}

Resolution per setting is config → detected → built-in default, so a repo without the file keeps today's behaviour. Run /tituskirch-skills-config to have that skill write and reconcile the file rather than hand-rolling it. Every key and its allowed values live in tituskirch-skills.schema.json — point $schema at the raw URL and your editor completes them; which skill reads which key is listed in skills/README.md.

🔁 The AI work loop

Eight of the skills above form two loops: implement (work-implement and its queue) claims an issue, builds, verifies and pushes; review (work-review and its queue) judges the pushed result as a structurally fresh agent. Nothing passes between them in memory — the issue's ai: label is the entire handover, which is why a crashed run resumes instead of restarting and why both loops can drain at the same time.

ai: ready → ai: working → ai: review requested → ai: done
                  ↑                  ↓
          ai: changes requested ←────┘

ai: ready is the only label a human sets by hand — that opt-in is what makes the drains unattended. Full vocabulary, escalation states and loop ownership: AI work lifecycle.

➕ Adding a new skill

Drop a skills/<category>/<name>/SKILL.md, run pnpm skills:sync — it regenerates every derived artifact from your frontmatter, from the table above and the category README.md to .claude-plugin/plugin.json, skills.sh.json's groupings and the shared blocks mirrored into each skill. Hand-editing any of them is pointless: pnpm skills:check fails the gate on drift.

Then commit as feat(<name>): add skill. The frontmatter contract is in skills/README.md; what spans more than one skill lives in docs/.

💡 Inspiration

The local pnpm skills:link / :list / :unlink scripts are modelled on mattpocock/skills.

🤝 Contributing

PRs welcome — branch off dev and target dev. Conventional Commits required (enforced via commitlint). Husky runs oxlint + oxfmt on git commit — primarily on markdown, since that's what skills are made of.

Tip

Run pnpm verify before pushing. It is the whole gate — lint, format, artifact drift, types and tests — and CI runs on: pull_request only, so nothing checks a commit that reaches dev any other way.

The full workflow is in CONTRIBUTING.md, the disclosure process in SECURITY.md, and why things are shaped the way they are in docs/99.adr/.

🛣️ Versioning

Semantic Versioning via release-please — see CHANGELOG.md.

📄 License

MIT © Titus Kirch / IT-Dienstleistungen Titus Kirch