bugs-board
A pane with the project's own open bugs from BUGS.json, most severe first.
newpaneguardcommandtoolprocess
A pane with the project's own open bugs from BUGS.json, most severe first.
A small collection of reusable SKILL.md instructions for coding agents. The skills are plain Markdown, version-controlled, and portable across compatible agent tools.
This README is the reference: what the skills are, which platforms they support, and how to install them. The [wiki][wiki] answers the other question — why the project is built this way: why a Markdown repository contains Rust crates, why the dev shell compiles bash 3.2 from source, which design choices were made and what they cost, how to verify any of it yourself, and what does not work yet.
[wiki]: https://github.com/tschallacka/ai-skills/wiki
Pick whichever fits how you work. Any of these opens the same interactive installer, where you choose the skills and the agent destination(s).
npx — installs and runs in one step, nothing left on PATH afterward:
npx --yes --package @tschallacka/ai-skills ai-skills-installLinux / macOS — the one-command installer, no npm required:
curl -fsSL https://raw.githubusercontent.com/tschallacka/ai-skills/master/installer/bootstrap.sh | shWindows — the identical command, run inside Git Bash or WSL2 (both provide the POSIX sh it needs; there is no separate PowerShell/cmd installer):
curl -fsSL https://raw.githubusercontent.com/tschallacka/ai-skills/master/installer/bootstrap.sh | shSee "One-command installer" below for the full list of install destinations, and "npm installation" for a persistent ai-skills-install command on PATH instead of npx.
| Skill | Purpose | Documentation |
|---|---|---|
| Planning | Durable, resumable plans: goals, ordered steps, verification, progress trackers, handoff notes — plus a single-file HTML overview of any plan, and a live served version that updates in place. Steps complete with git-diff atomicity evidence, not decorative checkboxes. | docs |
| Bug report | A defect register in one JSON file: every entry carries its reproduction, observed vs expected, the mechanism, and the verification that fails without the fix. bugs add/bugs update write through shared validation; a closure without proof is refused. | docs |
| Todo | A work queue that outlives the conversation, in one JSON file: nested tasks, every closed item carries its evidence. todo add/todo update keep the register sound; read recipes print user-ready output. | docs |
| Brainstorm | Shapes an under-specified idea into a recorded, agreed picture (brainstorm.md) before planning, with an adversarial completion pass and a plan-vs-implement gate. | docs |
| Post-implementation review | After-the-fact review of built code with concrete proposed fixes, in three passes: implementer self-analysis, an independent solutions agent, and a critical-feedback agent that ranks every fix. | docs |
| Project-specific deviations | Records confirmed project behavior and environment quirks in per-project notes that future agents load instead of re-debugging. | docs |
| Resource-limited testing | Runs heavyweight commands (suites, builds, analyzers, browsers) under platform-appropriate CPU/memory caps, with honest degradation when a platform has no cap mechanism. | docs |
| Chat | RFC-1459 IRC-over-TLS message bus for agents: a rust server a standard TLS IRC client can join, a rust client with UDP discovery and TOFU cert pinning, channels, and additive history/delta reads. | docs |
| Interactive shell | Operates a full-screen terminal program an agent has never seen - nano, mc, lynx, a pager, a menu: a rust PTY wrapper publishing each screen change as one JSONL event, compact row views and deltas to keep context small, element discovery, and a unix-socket client for keys, combos, pastes, mouse and resize. POSIX only. | docs |
| Git worktrees | Parallel agents in one repository: isolated worktree verification, per-agent trees, and merging back in a conflict-aware order without trampling the main checkout. | docs |
| Git merge resolving | Conflicts resolved by what each side changed rather than by ours/theirs: reading intent from history, unions that look like choices, regenerated output, and attributing post-merge failures to the side that caused them. | docs |
| Merge request etiquette | Descriptions a reviewer can act on, in the author's voice: a one-paragraph TLDR, the defect/cause/change body, derived from the branch's commits, and the one case where a collapsible section earns its place. | docs |
| Text etiquette | Shorthand and a clipped register for an agent's prose - chat, dev talk, and its own thinking: facts first, a shared shorthand with an ask-don't-guess rule, praise capped at gj, and the people-please prose banned. Plain english on request. | docs |
| Question etiquette | Numbered questions, lettered options, never a bullet: a reply like Q7b is unambiguous, a partial answer names exactly which numbers are still open, and a lettered list always ends with "none of these, I'll say it myself." | docs |
| AI text editor | Server-owned agent editor tabs with explicit search, revision-aware edits, undo/redo, raw-byte and hex modes, SQLite metadata, and Unix/TCP transport. | docs |
| www | A brake the human can pull, and one the agent pulls on itself when it is thrashing: stop, answer what do we have / what are the values / what are we trying to achieve, in order, then continue with one reasoned step or a numbered question. | docs |
| CI failures | What actually failed in a CI run or pipeline, from a run/pipeline id, a PR/MR number, or a branch: GitHub and GitLab detected from the git remote, named rather than chosen silently, with just the failing lines extracted per job. | docs |
| Decisions | A register of non-blocking questions raised mid-work: Q# ids, lettered options, priority and the branch they came from as context, so a question can be stubbed and left open without blocking a turn. | docs |
| rjq | Parses, filters and searches JSON with the shipped rjq binary, a jq-compatible tool, on machines without jq. | docs |
| Tailpipe | A less/tail for agents: pipe a command's output into a named, server-held stream with chat-style message ids; a reader lists/reads/searches/tails it from anywhere, an MCP adapter offers the same as typed tools, and a board mod shows it to a human. Idle streams are gzip-snapshotted after 15 minutes. | docs |
Use a skill only when its frontmatter trigger matches the task or when the user explicitly requests it. Each skill documents when not to activate.
"Portable" elsewhere in this repository means portable across agent tools (Claude Code, Codex, OpenCode, OpenClaw, Cline). Operating-system support is separate and stated here:
Those tools do not identify the calling agent the same way, which matters to every per-agent feature here. src/agent-session-key/HARNESS-IDENTITY.md records what each one provides, how it was measured, and the procedure for contributing a harness that is not yet listed.
| Supported | |
|---|---|
| Linux | any distribution, bash 4 or 5, GNU userland |
| macOS | 11+ with the stock /bin/bash 3.2, BSD userland; Homebrew bash not required |
| Windows | Git for Windows' bash with its bundled coreutils, checked by CI legs, or WSL2, which is a Linux install. The evidence and the conventions are in .agents/MAINTAINER.md 1.16, which is in a full git checkout and not part of the installed package |
The one-command install needs a POSIX sh (bootstrap.sh has no bash-only constructs), plus curl, tar, awk, and standard coreutils; the installed skills' own helper scripts need bash, POSIX coreutils, awk, sed, grep, and git. The planning skill additionally needs rjq, and on macOS resource-limited-testing needs memlimit; the installer checks for both up front and prints a per-platform install hint rather than failing partway through. Those two are the only extra runtime dependencies any skill has — in particular python3 is not required by anything that gets installed, only by this repository's own benchmark harness. CODE-STYLE.md is the contract these scripts are held to; what CI proves on each platform is mapped in .agents/MAINTAINER.md section 3 (a full git checkout has both; the installed package has neither).
One skill is genuinely OS-scoped: resource-limited-testing enforces a hard RAM cap only on Linux, via a transient systemd --user cgroup v2 scope. On macOS it uses memlimit (MIT, by Jelle Besseling), which refuses allocations past the cap instead of killing the process — a best-effort cap on real resident memory over the process tree, not a cgroup-equivalent guarantee; SKILL.md lists what it does and does not promise. On Apple Silicon macOS the installer declares memlimit a soft requirement: without it the skill still installs and the run warns that the RAM cap is not enforced. The wrapper then degrades to nice plus cpulimit (CPU throttling only); on a Linux session without a user systemd instance it falls back to ulimit -v. memlimit is not asked for on Intel Macs at all — it does not support them. Every other skill behaves identically on both.
Run this command and choose the skills and agent destination interactively:
curl -fsSL https://raw.githubusercontent.com/tschallacka/ai-skills/master/installer/bootstrap.sh | shThe installer can install all the skills or one skill, and supports these global skill roots:
| Destination | Agent or standard |
|---|---|
~/.agents/skills | Universal Agent Skills root; recommended shared destination |
~/.codex/skills | Codex CLI |
~/.claude/skills | Claude Code |
~/.config/opencode/skills | OpenCode |
~/.openclaw/skills | OpenClaw managed skills |
~/.cline/skills | Cline |
The universal root is also discovered by OpenCode and OpenClaw. Installing the same skill into multiple roots can create duplicate definitions or precedence conflicts, so choose only the roots you need.
The interactive installer checks which supported agents are present and omits roots for agents it cannot detect. Custom roots are saved in ~/.config/tsch-ai-skills/custom-locations and are offered again when they still exist.
Install the package globally to expose the installer command. The npm package keeps the skills in this repository and links ai-skills-install directly to installer/bootstrap.sh, which fetches the matching compiled installer release for your platform on first run:
npm install -g @tschallacka/ai-skills
ai-skills-installFor a one-off run without a global install:
npx --yes --package @tschallacka/ai-skills ai-skills-installThe npm package does not install skills automatically as an npm lifecycle side-effect; run the installer command when you are ready to choose a target.
Run the installer again against the same root. It compares every managed file with the repository copy and reports one of three outcomes per destination: Up to date (nothing differed), Installed (files were written), or Skipped (you declined, or the destination needs manual review).
Each installed skill contains a .version marker identifying its tag, branch, and commit. If an installed file differs from the repository version, the installer asks before replacing it. For a managed version transition that the user approves — the .version marker differs, so the change came from a new release rather than from you — old files are replaced without backups; the previous version can be restored by running the installer against its tag with AI_SKILLS_REF. Unmanaged changes still receive <file>.bak backups (.bak.1, .bak.2, … if one already exists). A symlinked skill is skipped for manual review rather than following the link and modifying an unexpected location.
Interactively, choose that one skill at the menu. Headless, name it:
curl -fsSL https://raw.githubusercontent.com/tschallacka/ai-skills/master/installer/bootstrap.sh \
| sh -s -- install --skill planning --target "$HOME/.codex/skills"--skill may be given more than once, and each value may itself be a comma-separated list, so --skill planning --skill brainstorm and --skill planning,brainstorm install the same two. Repeats are collapsed, menu numbers work (--skill 1,4), and all selects everything wherever it appears.
Use --all, --skill, --target and --yes when the choices are already known. --target takes a single root, so installing into two roots is two runs.
# Install all skills into the shared Agent Skills root
curl -fsSL https://raw.githubusercontent.com/tschallacka/ai-skills/master/installer/bootstrap.sh \
| sh -s -- install --all --target "$HOME/.agents/skills"
# Unattended replacement: managed version transitions replace without backups,
# unmanaged changed files are still backed up as <file>.bak
curl -fsSL https://raw.githubusercontent.com/tschallacka/ai-skills/master/installer/bootstrap.sh \
| sh -s -- install --all --target "$HOME/.agents/skills" --yesEvery run ends with a summary block on stdout saying what was installed, what was not, and why; the progress and diagnostics go to stderr, so installer install … > summary.txt keeps the outcome and 2>/dev/null keeps it readable. A blocked skill is reported once — not once per root — with the commands that finish the job. This is what an --all run on a machine without rjq prints:
== Summary ==
Installed: /home/u/.agents/skills/project-specifics
Installed: /home/u/.agents/skills/resource-limited-testing
Installed: /home/u/.agents/skills/brainstorm
Installed: /home/u/.agents/skills/post-implementation-review
Skipped: planning — a hard requirement is missing, nothing was written
To install planning once its requirements are met:
1. install rjq:
sudo apt-get install -y rjq
2. replay this run:
installer install --skill planning --target /home/u/.agents/skills --yesThe install step is chosen for the detected platform and package manager, and the replay line carries the same target and flags as the run that printed it, naming the installer binary bootstrap.sh downloaded to run it. The exit status is non-zero, because four of five skills is a partial install and CI must not read it as success.
Dependencies are declared per skill, so one unsatisfiable dependency never stops the other skills from installing. Each skill ships a requires.tsv naming what it needs, on which platform and architecture, and how badly:
| Strength | Effect |
|---|---|
hard | The skill does not work without the tool. It is not installed, the run explains why and prints the replay commands, and the exit status is non-zero. |
soft | The skill works in a degraded form. It is installed, with a warning naming the tool and the capability that is lost. The exit status is unaffected. |
Currently:
planning requires rjq (hard, every platform) — without it validate-plan.sh refuses to run and the plan gates stop firing.resource-limited-testing names memlimit (soft, Apple Silicon macOS only) — see Supported platforms above for what the degraded path still does.No other skill has a runtime dependency.
| Code | Meaning |
|---|---|
| 0 | Everything requested was installed. Soft warnings do not change this. |
| 1 | A requested skill was blocked by a hard requirement, or any other error. |
| 2 | install-skill only: approval declined, nothing was written. |
| 3 | install-skill only: an unsafe collision (an existing file that is not a managed version upgrade, or a symlink). |
Codes 2 and 3 belong to the machine-facing install-skill subcommand that the planning skill's own tooling uses; the interactive, install --all, and install --skill paths only ever return 0 or 1.
Running the bare one-liner with no arguments, or installer interactive directly, opens a full-screen skill picker instead of the numbered menu:
| Key | Action |
|---|---|
↑/k, ↓/j, PageUp, PageDown, Home, End | move the cursor |
Enter / Space | toggle the skill under the cursor |
Tab / Shift-Tab | switch focus between the skill list and the info pane |
a / n | select all / select none |
d, r, m (info pane focused) | show dependency hints, re-verify requirements, cycle a skill's integration mode |
i | confirm and install the current selection |
q / Escape | quit without installing |
With neither --target nor --agent given, it also prompts to choose an auto-detected agent root, a saved custom directory, a new custom directory, or a for every listed root.
Review the installer before running it if you do not trust the source. Skills are instructions that may guide agents to run commands or access files.
install.sh retired in favor of a compiled Rust installer (src/installer/); installer/bootstrap.sh is the small, pure-POSIX-sh entry point (#!/usr/bin/env sh, no bash-only constructs) that detects the platform, downloads the matching release, and hands off to it — see CONTRIBUTING.md before editing either.
installer/bootstrap.sh always downloads a release archive, so it is not how a checkout installs its own local files. Build the installer and point it at the checkout with --source instead:
cargo build --release -p installer
./target/release/installer interactive --source .--package dev (also read from $PACKAGE_SELECTION) ships the MODE: DEV files too — tests, maintainer docs — instead of filtering them out, for installing a working development copy rather than the prod set.
installer/bootstrap.sh itself accepts AI_SKILLS_REPO_URL (a different owner/repo to resolve GitHub's "latest release" redirect against) and AI_SKILLS_RELEASE_URL (an exact archive URL, bypassing that redirect entirely — how RELEASE.md verifies one specific tag).
benchmark/planning/runtime/ makes the worker/reviewer/analyzer launch, session-id extraction, and token telemetry pluggable per CLI: the active agent defaults to codex and is selected with BENCHMARK_AGENT (opencode, claude), with a shared launcher (lib-agent.sh) owning all setsid/timeout/process-group control. See benchmark/planning/runtime/README.md for the contract and first-time setup.resource-limited-testing's platform behaviour is described under Supported platforms; its SKILL.md documents each fallback in detail.Distributed under the MIT License.
hooks/register.tsx 182 lines1import type { Register } from 'claude-code'
2
3// The project's own open bugs (BUGS.json), most severe first. The register is
4// read on every draw, so the pane always shows what is on disk. Open means not
5// closed: a bug closed as fixed, not-a-defect, wont-fix or obsolete is left
6// out. Split out of register-board, which showed bugs and tasks together in
7// one pane; this one is bugs only, todo-board is tasks only. Toggled by
8// `enabled` in settings.json pluginConfigs["bugs-board"].options.
9
10const PANE = 'bugs-board'
11const TOOL = 'show_bugs_board'
12const READ = 'read_bugs_board'
13
14// The part of `$.fs` the reading needs.
15type Fs = {
16 exists: (path: string) => Promise<boolean>
17 read: (path: string) => Promise<string>
18}
19
20// The part of `$.process.run` the resolution needs.
21type ProcessRun = (argv: readonly string[]) => Promise<{ exitCode: number; stdout: string; stderr: string }>
22
23type Bug = { id: string; title: string; status: string; severity?: string }
24
25const SEVERITY_ORDER = ['blocking', 'major', 'minor', 'cosmetic']
26const BUG_CLOSED = ['fixed', 'not-a-defect', 'wont-fix', 'obsolete']
27
28function rank(order: string[], value: string | undefined): number {
29 const index = order.indexOf(value ?? '')
30 return index === -1 ? order.length : index
31}
32
33// The bugs binary's own path, in the shared bin the installer puts it in --
34// the same resolution register-board's own bugsBin uses.
35function bugsBin(home: string, xdg: string): string {
36 const bin = xdg ? `${xdg}/tsch-ai-skills/bin` : `${home}/.config/tsch-ai-skills/bin`
37 return `${bin}/bugs`
38}
39
40// The directory `bugs` actually reads and writes BUGS.json in, resolved once
41// via `bugs resolve-path`. `resolve-path` prints a bare filename with no
42// directory component for today's unresolved/session-root case, so splitting
43// off the last path segment naturally falls back to `root` there too; a
44// process-run failure (the binary missing, for example) falls back to the
45// session root the same way.
46async function registersDir(run: ProcessRun, home: string, xdg: string, root: string): Promise<string> {
47 const result = await run([bugsBin(home, xdg), 'resolve-path']).catch(() => undefined)
48 if (!result || result.exitCode !== 0) return root
49 const file = result.stdout.trim()
50 const slash = file.lastIndexOf('/')
51 return slash === -1 ? root : file.slice(0, slash)
52}
53
54// The open bugs of the project, read from its own register.
55async function openBugs(fs: Fs, run: ProcessRun, home: string, xdg: string, root: string): Promise<Bug[]> {
56 const dir = await registersDir(run, home, xdg, root)
57 const bugs: Bug[] = []
58 const bugFile = `${dir}/BUGS.json`
59 if (await fs.exists(bugFile)) {
60 const register = JSON.parse(await fs.read(bugFile)) as { bugs?: Bug[] }
61 for (const bug of register.bugs ?? []) {
62 if (!BUG_CLOSED.includes(bug.status)) bugs.push(bug)
63 }
64 }
65 bugs.sort((a, b) => rank(SEVERITY_ORDER, a.severity) - rank(SEVERITY_ORDER, b.severity))
66 return bugs
67}
68
69// Exposes the pure functions above for a unit test to call directly, without
70// spawning the binary or driving the mod runtime -- nothing here is read by
71// Claude Code itself, which only ever reads the `register` export below.
72export const __test = {
73 rank,
74 bugsBin,
75 registersDir,
76 openBugs,
77}
78
79export const register: Register = (on, options) => {
80 if (options.enabled === false) return
81
82 on('session.start', async ($, e, next) => {
83 await $.command.register({
84 name: 'bugs-board',
85 description: 'Show the project’s open bugs in a pane; `/bugs-board close` hides it',
86 })
87 await $.tool.register({
88 name: TOOL,
89 description: 'Show the project’s open bugs to the person, in a pane, and return them as text for the chat.',
90 inputSchema: { type: 'object', properties: {} },
91 })
92 await $.tool.register({
93 name: READ,
94 description: 'Read the project’s open bugs as text, without opening the pane.',
95 inputSchema: { type: 'object', properties: {} },
96 })
97 return next(e)
98 })
99
100 on('command.run', { command: 'bugs-board' }, async ($, e) => {
101 if (e.args.trim().toLowerCase() === 'close') {
102 await $.ui.close({ id: PANE })
103 return { text: 'Bugs board closed.' }
104 }
105 await $.ui.open({ id: PANE, title: 'Open bugs' })
106
107 return { text: 'Bugs board opened.' }
108 })
109
110 on('tool.call', { tool: `mcp__bugs-board__${TOOL}` }, async $ => {
111 const root = await $.session.root()
112 const home = (await $.env.get('HOME')) ?? ''
113 const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
114 const fs: Fs = {
115 exists: path => $.fs.exists(path),
116 read: path => $.fs.read(path),
117 }
118 const bugs = await openBugs(fs, argv => $.process.run(argv), home, xdg, root)
119 await $.ui.open({ id: PANE, title: 'Open bugs' })
120
121 return {
122 result: [
123 `Open bugs: ${bugs.length}`,
124 ...bugs.map(bug => `${bug.id} [${bug.severity ?? 'major'}] ${bug.title}`),
125 ].join('\n'),
126 }
127 })
128
129 // The agent's read of the open bugs. Read-only; the pane is not opened.
130 on('tool.call', { tool: `mcp__bugs-board__${READ}` }, async $ => {
131 const root = await $.session.root()
132 const home = (await $.env.get('HOME')) ?? ''
133 const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
134 const fs: Fs = {
135 exists: path => $.fs.exists(path),
136 read: path => $.fs.read(path),
137 }
138 const bugs = await openBugs(fs, argv => $.process.run(argv), home, xdg, root)
139 const live = await $.ui.selection().catch(() => undefined)
140
141 return {
142 result: [
143 `Open bugs: ${bugs.length}`,
144 ...bugs.map(bug => `${bug.id} [${bug.severity ?? 'major'}] ${bug.title}`),
145 `Highlighted in the board: ${live?.text ?? 'none'}`,
146 ].join('\n'),
147 }
148 })
149
150 on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
151 const { Box, Button, Text } = $.ui.resolve(e)
152 const root = await $.session.root()
153 const home = (await $.env.get('HOME')) ?? ''
154 const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
155 const fs: Fs = {
156 exists: path => $.fs.exists(path),
157 read: path => $.fs.read(path),
158 }
159 const bugs = await openBugs(fs, argv => $.process.run(argv), home, xdg, root)
160
161 return (
162 <Box flexDirection="column">
163 <Box flexDirection="row" justifyContent="space-between">
164 <Text bold inverse>
165 Open bugs
166 </Text>
167 <Button role="dismiss" onPress={() => $.ui.close({ id: PANE })}>
168 Close
169 </Button>
170 </Box>
171 <Text> </Text>
172 {bugs.length === 0 && <Text dimColor>No open bugs.</Text>}
173 {bugs.map(bug => (
174 <Text key={bug.id} color={bug.severity === 'blocking' || bug.severity === 'major' ? 'yellow' : undefined}>
175 {`${bug.id} ${bug.severity ?? 'major'} ${bug.title}`}
176 </Text>
177 ))}
178 </Box>
179 )
180 })
181}
182