touchstone

Marco Brieden's shared agent skills — the standard engineering work is tested against. One source of truth for cross-repo conventions, instead of copy-pasted CLAUDE.md/AGENTS.md sections that drift.

(The git repo is still named agent-skills; the plugin is touchstone.)

Install

This repo is a Claude Code plugin. Its SessionStart hook prints a trigger index built from each skill's frontmatter, so every skill's load condition reaches context — skill descriptions are not reliably surfaced otherwise, and a skill nobody is reminded of never fires.

Skills are namespaced by the plugin name once installed: /touchstone:adr.

If you are developing these skills — use the skills directory

ln -s /path/to/this/repo ~/.claude/skills/touchstone

Any folder under a skills directory containing .claude-plugin/plugin.json is discovered on the next session and loads as touchstone@skills-dir, in place — no copy, no marketplace, no install step.

That is why this is the author's route: a marketplace install copies the repo into ~/.claude/plugins/cache/ and pins a commit, so your edits would not be live. See Updates for what takes effect when.

If you are consuming these skills — use the marketplace

/plugin marketplace add git@git.k-net.ca:marco/agent-skills.git
/plugin install touchstone@touchstone

(Or claude plugin marketplace add … + claude plugin install … from a shell, for non-interactive setup.)

This install does not update itself by default — see Updates.

Updates

The two install routes get updates completely differently, and the marketplace one is silent about being stale — which is the failure worth knowing about.

Skills directory (the author's route)

Nothing to do. The plugin loads in place from the symlinked repo, so git pull is the update.

Changed	Takes effect
A skill's SKILL.md	immediately
Hooks, agents, plugin.json	/reload-plugins, or next session

Marketplace (everyone else)

Auto-update is off by default, and nothing tells you that. From the Claude Code docs:

Official Anthropic marketplaces have auto-update enabled by default. Third-party and local development marketplaces have auto-update disabled by default.

touchstone is a third-party marketplace, so a fresh install is pinned to the commit it was installed at until someone acts. Two ways to act:

Turn it on once, per marketplace: /plugin → Marketplaces → select touchstone → Enable auto-update. For a team, an admin can set it centrally with "autoUpdate": true on the extraKnownMarketplaces entry in managed settings.

Or pull by hand, whenever you want it:

/plugin marketplace update touchstone
/plugin update touchstone

Two caveats that apply even with auto-update enabled:

• The check runs after session start, with a random delay of up to ten minutes, and the running session keeps whatever it loaded at launch. You get a prompt to run /reload-plugins, or the new version loads next launch.
• DISABLE_AUTOUPDATER=1 disables plugin updates too, not just Claude Code's own. To keep plugins updating while pinning Claude Code, also set FORCE_AUTOUPDATE_PLUGINS=1.

Removing the marketplace uninstalls anything installed from it.

Hooks

Hook	Fires	Does
SessionStart	session start	Prints the trigger index — every skill's name and load condition — so skills fire on their conditions rather than on memory
PreToolUse (Bash)	before a git push	Blocks a push unless the repo's real gate passed on the commit being pushed. Opt-in per repo: a .claude-gate file names the one command CI runs, .git/claude-gate-ok records the SHA it last passed on. Repos without .claude-gate are untouched

The push gate exists because a 21-commit deploy failed on lint regressions that the documented pre-push command did not run — the docs and the pipeline had drifted, and ship-discipline already said "run the gate CI runs" and was not invoked. A reminder that can be skipped is what failed, so it blocks.

Skills

Skill	Covers
adr	ADR conventions + a scaffolding script (numbering, template, index, supersede flow)
decision-brief	How a decision gets made before it is recorded: full option set, honest costs, measured-vs-inferred evidence, an invitation to reframe. Feeds adr
merge	Landing branches: append-only/generated-file conflict rules, semantic collisions git can't see, gate every merge
plans	Implementation plans: decision-free, adversarial pre-flight, deleted on completion
commit-style	Commit message conventions and commit granularity
working-agreements	Minimal change, narrow scope, dependency approval, never extrapolate a precise spec
doc-freshness	Keep repo docs true in the same change as the code
code-shape	File splits behind facades, anchor functions, arg structs, tests-next-to-code
director-loop	Director/implementer working mode: main session directs, cheap-model subagents implement; dispatch discipline, measurement rules, escalation. Pairs with the agent defs in agents/ (see below)
parallel-worktrees	Multiple agents in one repo: worktree + branch per track, director-serialized integration, collision rules
ship-discipline	Pre-push shipping: verified suite exit codes (no test && push chains), package-build checks when dependencies change, one deploy per green batch, watched deploys
autonomous-work	Unattended/overnight sessions: standing-orders-only scope, stall guards on every background task, watched deploys, risk asymmetry, serialized test resources, the morning report
research-first	Evidence base before implementation in researched domains (reward mechanics, sound, UX psychology, health logic…), or when the research is itself the deliverable (report, briefing, purchase evaluation): dispatch decision-feeding research with graded citations, then adversarially verify (refutation pass, deep-reads on load-bearing claims, completeness critic) before the applied ruleset file becomes binding spec — or before a report reaches a human who acts on it

Repo-specific facts (invariants, commands, numeric ceilings, enforcement tools) stay in each repo's CLAUDE.md/AGENTS.md; every skill defers to the repo file on conflict.

Agents

agents/ holds Claude Code agent definitions (not skills — they install to a different directory). They power the director-loop skill:

Agent	Model	Role
implementer	Sonnet (high reasoning)	Executes director briefs: code changes, runs, diagnostics. Continue the same one via SendMessage to keep its context
scout	Haiku	Cheap recon: inventories, shortlists, filename-level scans. Its judgment calls get verified by the director
reviewer	Sonnet (high reasoning)	Fresh-context adversarial pre-flight of plans/ADRs before approval. Reports findings; changes nothing

Installing (superseded)

The old per-skill symlink setup:

ln -s "$PWD"/skills/* ~/.claude/skills/
ln -s "$PWD"/agents/* ~/.claude/agents/

Do not use this. It symlinks each skill individually, so a skill added here is invisible until someone adds another symlink — two skills sat unreachable that way, and the agents/ never got linked at all, so director-loop was dispatching to agents that did not exist. Symlink the repo into ~/.claude/skills/ instead (see Install); the plugin manifest then carries skills, agents and hooks together and nothing can be half-installed.

Setting up the director-loop working mode

To make director-loop the default (not just available), add this to your global ~/.claude/CLAUDE.md — or just tell Claude Code: "read the director-loop skill in my agent-skills repo and set it up as my default working mode" and it can do the steps itself:

# Default working mode: director loop
For substantive multi-step work (features, iteration loops, migrations,
audits), default to the `director-loop` skill: act as director, dispatch
`implementer` (Sonnet/high) and `scout` (Haiku) subagents, reserve main-
session tokens for planning, review, and decisions. Skip it for trivial
edits and pure Q&A.

What you get: the main (expensive-model) session plans, reviews, and makes accept/revert calls; cheap-model subagents do implementation and recon; you only get pulled in for real decisions, credentials, and sign-offs. The skill file (skills/director-loop/SKILL.md) carries the discipline rules that make it reliable — one change per measured run, interpretation agreed before results, evidence over assertion.

Attention bell (optional)

Have Claude ring a bell — at its own discretion — when it finishes a substantive task or needs your input. Discretionary beats a Stop/Notification hook: a hook rings on every turn end, which is spam; a missed ring is cheap.

One-time setup (run from this repo's root):

cp assets/bell.wav ~/.claude/bell.wav

Add to your global ~/.claude/CLAUDE.md (personal — not a project file):

# Attention bell
When finishing a substantive task or genuinely needing my input
(escalation, blocked, long turn done), ring the bell:
`paplay ~/.claude/bell.wav || aplay -q ~/.claude/bell.wav`
(macOS: `afplay ~/.claude/bell.wav`; Windows: PowerShell Media.SoundPlayer)
Use judgment — don't ring for quick Q&A replies or minor steps. Missing a
ring is fine; spamming is not.

And allow the command in ~/.claude/settings.json so it never prompts:

"permissions": { "allow": ["Bash(paplay ~/.claude/bell.wav*)", "Bash(aplay -q ~/.claude/bell.wav*)"] }

Only the main session rings — subagents don't. Prefer deterministic every-turn ringing instead? Wire the same play command into Stop/ Notification hooks in settings.json.

Editing

Refine a rule here once; every repo picks it up. Don't copy rule text into repo instruction files — add repo-specific deltas there instead.