workbench-scaffold
Skill0 starsChanged 47 days agoMITView on GitHub
Lay out a file-first AI workbench in the current folder from a clone of the ai-workbench repo, bring an existing repo up to the pattern, or audit a workbench for drift between its copied files and the source. Use before session-open in a repo that has no AGENTS.md, and to check a workbench that may have fallen behind the source.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- session-closeSkill
- session-openSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 50
Never overwrite an existing file.
- Distinctive: line 65
Leave the domain rules placeholder empty.
- Distinctive: line 69
If the folder is not a git repository yet, run git init first.
- Distinctive: line 84
Create no other folders. Git does not hold empty directories, and the layout section documents what appears on first use.
- Very specific: line 89
Run git config core.hooksPath .githooks, then scripts/check.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Workbench scaffold
Turn a folder into a workbench: the operating agreement, the desk file, the lint, the
check, the hook and the two session skills. This skill is installed globally because it
runs in folders that hold nothing yet: either as a symlink from the user's skills
directory to skills/workbench-scaffold inside a clone of ai-workbench, or as a copy
with WORKBENCH_HOME pointing at that clone. Everything it writes comes from the clone,
never from memory.
1. Resolve the source
First hit wins:
$WORKBENCH_HOME, if it containstemplates/AGENTS.mdandscripts/workbench_lint.py.- This skill's own directory with symlinks resolved (
realpath), walked upward until a directory holds both. - Neither: stop, say the ai-workbench clone is missing, and name both options as the fix.
Say which source was used and its path before going on; a stale clone copies stale files.
2. Pick the mode
Take the first case that fits and say which, and why, before touching anything:
scripts/workbench_lint.pyexists → audit.AGENTS.mdexists, or the folder has content → adopt.- Otherwise → fresh.
Audit. Compare the repo against the source and report, in this order:
- Drift in every copied file, using
cmpanddiff -uagainst the source:scripts/workbench_lint.py,scripts/check,.githooks/pre-commit,.claude/skills/session-open/SKILL.md,.claude/skills/session-close/SKILL.md. Offer to re-copy each drifted file; offer nothing else for it. Local changes to these files are the drift, not a customisation. scripts/checkoutput; every finding is an audit item.AGENTS.mdsections missing againsttemplates/AGENTS.md, and any placeholder (<...>) still unfilled.- Whether
git config core.hooksPathprints.githooks.
Offer each fix separately and change nothing without a yes.
Adopt. Report what already exists. Ask only what the missing pieces need, reading answers off the repo wherever it already states them. Write only what is missing. Never overwrite an existing file.
Fresh. Interview, then write.
3. Interview
One question at a time, and only these:
- Project name.
- Purpose, in two to four lines: what the repo is and produces, and the one thing an agent would get wrong without being told.
- The tracker, if any: where issues live. This becomes a line under
## Context. - Which existing folders are non-obvious enough to earn a line under
## Layout. - The commands that matter, and which of them write or cost money.
Leave the domain rules placeholder empty. Rules get earned by mistakes.
4. Write
If the folder is not a git repository yet, run git init first.
| Target | Source and treatment |
AGENTS.md | templates/AGENTS.md, placeholders filled from the interview, unfilled placeholders deleted. Must stay under 100 lines. |
CLAUDE.md | templates/CLAUDE.md, verbatim. A real file, never a symlink. |
STATUS.md | templates/STATUS.md, project name filled, everything else left as the empty shape. |
DECISIONS.md | templates/DECISIONS.md, project name filled, example entry kept as the format reference. |
scripts/workbench_lint.py | Copied with cp, never retyped or edited. |
scripts/check | Copied with cp, executable. |
.githooks/pre-commit | Copied with cp, executable. |
.claude/skills/session-open/SKILL.md | Copied with cp. |
.claude/skills/session-close/SKILL.md | Copied with cp. |
.gitignore | Ensure it lists __pycache__/, .DS_Store, .claude/settings.local.json, .claude/worktrees/. |
Create no other folders. Git does not hold empty directories, and the layout section documents what appears on first use.
5. Prove it and commit
Run git config core.hooksPath .githooks, then scripts/check. Show the output and
confirm it ends in check: clean. In fresh mode the scaffold is the repository's first
commit, on its default branch; there is nothing to open a pull request against yet. In
adopt mode, and for every fix accepted in an audit, commit on a branch and open a pull
request like any other change. The commit message names the scaffold. Close by naming
session-open as the command for the next session.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

