agentleFS
maurice-jobstmaurice-jobst/ai-workbench/skills/workbench-scaffold/SKILL.md

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.

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
  1. Distinctive:

    Never overwrite an existing file.

    line 50
  2. Distinctive:

    Leave the domain rules placeholder empty.

    line 65
  3. Distinctive:

    If the folder is not a git repository yet, run git init first.

    line 69
  4. Distinctive:

    Create no other folders. Git does not hold empty directories, and the layout section documents what appears on first use.

    line 84
  5. Very specific:

    Run git config core.hooksPath .githooks, then scripts/check.

    line 89

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. $WORKBENCH_HOME, if it contains templates/AGENTS.md and scripts/workbench_lint.py.
  2. This skill's own directory with symlinks resolved (realpath), walked upward until a directory holds both.
  3. 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.py exists → audit.
  • AGENTS.md exists, or the folder has content → adopt.
  • Otherwise → fresh.

Audit. Compare the repo against the source and report, in this order:

  1. Drift in every copied file, using cmp and diff -u against 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.
  2. scripts/check output; every finding is an audit item.
  3. AGENTS.md sections missing against templates/AGENTS.md, and any placeholder (<...>) still unfilled.
  4. Whether git config core.hooksPath prints .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:

  1. Project name.
  2. Purpose, in two to four lines: what the repo is and produces, and the one thing an agent would get wrong without being told.
  3. The tracker, if any: where issues live. This becomes a line under ## Context.
  4. Which existing folders are non-obvious enough to earn a line under ## Layout.
  5. 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.

TargetSource and treatment
AGENTS.mdtemplates/AGENTS.md, placeholders filled from the interview, unfilled placeholders deleted. Must stay under 100 lines.
CLAUDE.mdtemplates/CLAUDE.md, verbatim. A real file, never a symlink.
STATUS.mdtemplates/STATUS.md, project name filled, everything else left as the empty shape.
DECISIONS.mdtemplates/DECISIONS.md, project name filled, example entry kept as the format reference.
scripts/workbench_lint.pyCopied with cp, never retyped or edited.
scripts/checkCopied with cp, executable.
.githooks/pre-commitCopied with cp, executable.
.claude/skills/session-open/SKILL.mdCopied with cp.
.claude/skills/session-close/SKILL.mdCopied with cp.
.gitignoreEnsure 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.