scaffold
/scaffold
One-time bootstrap of a project for the optimiziramsi-skills toolkit: create the `.agent/` workspace layout with an index (`.agent/README.md`), add a single pointer to it from the entrypoint (CLAUDE.md / AGENTS.md), and optionally link the machine-local `.agent/bin/loop` + `.agent/bin/grind` runners. Use when setting up a new or existing repo to use these plugins — "set up optimiziramsi-skills here", "scaffold the agent workspace", "wire up the .agent layout", "initialize the toolkit in this project". Idempotent; confirms before editing the entrypoint. Does NOT register individual skills (they
- Author
- optimiziramsi ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
One-time bootstrap of a project for the optimiziramsi-skills toolkit: create the `.agent/` workspace layout with an index (`.agent/README.md`), add a single pointer to it from the entrypoint (CLAUDE.md / AGENTS.md), and optionally link the machine-local `.agent/bin/loop` + `.agent/bin/grind` runners. Use when setting up a new or existing repo to use these plugins — "set up optimiziramsi-skills here", "scaffold the agent workspace", "wire up the .agent layout", "initialize the toolkit in this project". Idempotent; confirms before editing the entrypoint. Does NOT register individual skills (they
Triggers from the description
Original author description
One-time bootstrap of a project for the optimiziramsi-skills toolkit: create the `.agent/` workspace layout with an index (`.agent/README.md`), add a single pointer to it from the entrypoint (CLAUDE.md / AGENTS.md), and optionally link the machine-local `.agent/bin/loop` + `.agent/bin/grind` runners. Use when setting up a new or existing repo to use these plugins — "set up optimiziramsi-skills here", "scaffold the agent workspace", "wire up the .agent layout", "initialize the toolkit in this project". Idempotent; confirms before editing the entrypoint. Does NOT register individual skills (they
How it works
- Why it's shaped this way
- Steps
- .agent/README.md template
- What NOT to do
SKILL.md preview
---
name: scaffold
description: >-
One-time bootstrap of a project for the optimiziramsi-skills toolkit: create the `.agent/`
workspace layout with an index (`.agent/README.md`), add a single pointer to it from the
entrypoint (CLAUDE.md / AGENTS.md), and optionally link the machine-local `.agent/bin/loop` +
`.agent/bin/grind` runners. Use when setting up a new or existing repo to use these plugins —
"set up optimiziramsi-skills here",
"scaffold the agent workspace", "wire up the .agent layout", "initialize the toolkit in this
project". Idempotent; confirms before editing the entrypoint. Does NOT register individual skills
(they auto-trigger) and does NOT generate anything on an ongoing basis.
---
# Scaffold — bootstrap the `.agent/` workspace
A **one-time** setup. The plugin keeps everything it creates under `.agent/` (so they don't
clutter the repo root). This skill makes that layout legible: it writes a static `.agent/README.md`
index and adds **one** pointer to it from the project's entrypoint. That's all — skills discover
themselves via their descriptions, and the `session-start` hook keeps live state fresh, so there's
nothing to generate or re-sync afterward.
## Why it's shaped this way
- **Skills don't need to be listed in CLAUDE.md to work** — Claude Code auto-triggers them on their
descriptions when the plugin is enabled. So this skill does NOT enumerate skills into the
entrypoint (that would duplicate the plugin manifests and drift).
- **The index is static**, not generated from enabled plugins. It describes the standard layout; a
dir simply won't exist until you use the matching skill. Nothing to keep in sync.
- **It's the only step that touches your entrypoint**, and it asks first.
## Steps
1. **Find the entrypoint.** Prefer `CLAUDE.md`, else `AGENTS.md`, at the repo root. If neither
exists, tell the user and offer the **`scaffold-claude-md`** skill — it writes a house-style
CLAUDE.md (a slim router of the hard rules), then this skill adds the pointer. (Claude Code's
built-in `/init` writes a full codebase-doc CLAUDE.md instead, if they'd rather.) Never silently
create one.
2. **Write `.agent/README.md`** (if absent — never overwrite an existing one without asking). Use
the template below. Create the `.agent/` dir if needed; do NOT pre-create the working sub-dirs
(`plan/`, `loop/`, …) — each skill makes its own on first use.
3. **Add one pointer to the entrypoint** (idempotent — skip if a link to `.agent/README.md` is
already there). Insert near the top or in a "Conventions"/"Layout" section:
```markdown
**Agent workspace:** this project uses the optimiziramsi-skills `.agent/` layout — see
[`.agent/README.md`](.agent/README.md) for what lives where.
```
**Show the user the exact edit and confirm before writing it.**
4. **Mention the commit choice** (don't decide it): `.agent/` can be **committed** (team-shared
continuity — handoff, lessons, plans travel with the repo) or **gitignored** (private working
notes). Ask which they prefer; if gitignore, add `.agent/` to `.gitignore` (but consider keeping
durable knowledge like `lessons/` and `patterns/` committed even then).
5. **Offer the runner links** (`.agent/bin/loop` + `.agent/bin/grind`) — optional, ask first. They
make the runners launchable as `.agent/bin/loop` from the repo root instead of a pasted
absolute path into the plugin cache. They are **symlinks, machine-local, never committed** —
each person working in the repo makes their own:
```bash
mkdir -p .agent/bin
ptr="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/data/optimiziramsi-runners/current"
ln -sfn "$ptr/bin/loop" .agent/bin/loop
ln -sfn "$ptr/bin/grind" .agent/bin/grind
```
Then **gitignore them**: add `.agent/bin/` (skip if `.agent/` is ignored wholesale). Skip this
step entirely if the project doesn't use `looper` / `grind`.
**Why the pointer and not a direct link into the cache:** `…/data/optimiziramsi-runners/current`
is one stable path per machine that the `runners` plugin's SessionStart hook re-stamps at whatever version
is actually loaded, so the links survive plugin updates and encode no version. Committing them
instead would publish one person's `$HOME` to everyone. A pre-existing `bin/loop` from the old
committed-wrapper era can be deleted once these exist.
6. **Stop.** Do not register individual skills, do not create a cron/generator, do not add more than
the one pointer. Setup is done.
## `.agent/README.md` template
```markdown
# `.agent/` — the agent workspace
Everything [optimiziramsi-skills](https://github.com/optimiziramsi/skills) creates lives here, so it
stays out of your repo root. Files/dirs appear as you use the matching skill — not all will exist.
| Path | What it holds | Owned by (skill/plugin) |
|---|---|---|
| `handoff.md` | next-session continuity notes (≤4k) | `handoff` / session |
| `bin/` | your own symlinks to the runners — machine-local, gitignored | `scaffold` / runners |
| `FEEDBACK.md` | agent-owned ledger of processed `.todo` items | `feedback` / flow |
| `lessons/` | durable, hard-won lessons + a README index | `lessons` / instructions |
| `instructions-changelog.md` | tier-tagged log of instruction changes | `retro` / instructions |
| `milestones.md` | active-milestones index (what's in flight) | `milestone` / flow |
| `milestone/{date}_{slug}/` | strategic multi-session initiatives | `milestone` / flow |
| `plan/` | single-topic implementation plans | `plan` / flow |
| `loop/` | background job queue + logs | `looper` / flow |
| `grind/` | grind missions + cross-iteration memory logs | `grind` / flow |
| `reviews/` | point-in-time review/audit outputs | `review` / review |
| `patterns/` | the per-topic pattern registry (blessed code shapes) | `manage-patterns` / patterns |
| `worktrees.md` | the parallel-work board | `worktree` / worktree |
**Not here (on purpose):** `.docs/` is your own architecture/specs (skills *link* to it, never write
it); `.todo` / `.todo-inbox` are your parking lot at the repo root; `.claude/rules/` is Claude config.
Closed plans/milestones move to an `archive/` subdir — kept as a frozen record, never edited again.
```
## What NOT to do
- **Don't enumerate skills into the entrypoint** — they auto-trigger; listing them duplicates the
manifests and drifts.
- **Don't overwrite** an existing `.agent/README.md` or re-add a pointer that's already there.
- **Don't create the working sub-dirs** — the skills make them on demand.
- **Don't set up any ongoing generation** — this is a one-time bootstrap.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · optimiziramsi/skills | 100 | MIT |
| jeremylongshore/tons-of-skills-marketplace | 100 | MIT |
| jkaloger/lazyspec | 100 | MIT |
| genkovich/sdlc | 100 | MIT |
| DnsQueen/orcinus-skills | 100 | MIT |
| duc01226/EasyPlatform | 100 | MIT |
| duc01226/EasyPlatform | 100 | MIT |
| chuckplayer/claude-agent-pack | 100 | MIT |
| dan323/easier-life-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 3939d3bcbd8a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100scaffold-claude-md
Write a house-style `CLAUDE.md` for a project — a slim router carrying only routing + the hard rules that bind every session, in the optimiziramsi-skills convention (session bootstrap, never-push / never-commit-on-the-protected-branch git, commit-as-you-go, verified done-gate,… - 100claude-md
Write a house-style `CLAUDE.md` for a project — a slim router carrying only routing + the hard rules that bind every session, in the optimiziramsi-skills convention (session bootstrap, never-push / never-commit-on-the-protected-branch git, commit-as-you-go, verified done-gate,… - 100scaffold-init
Initialize an AI-native development workspace with spec-driven workflow infrastructure. Use when starting a new project, setting up Claude Code on a codebase for the first time, or when the user says scaffold, initialize, set up AI workflow, onboard this repo, or similar. Do not… - 100plugin-scaffold
Scaffolds a Claude Code / Cowork plugin bundle from a short YAML spec or from an existing agent definition''s skills list. Produces the canonical bundle layout (.claude-plugin/plugin.json, settings.json with default agent, agents/, commands/, skills/ as symlinks to canonical… - 100skills-toolkit
Create and validate Claude Code skills and agents. Runs a real deterministic script for quality checks, never a self-scored rubric. Use when adding a skill or agent, or checking one against this repo's standards. - 90Project Scaffolding
This skill should be used when the user wants to set up Claude for a project, create a CLAUDE.md file, scaffold the .claude directory, initialize an AI workflow, configure a project for Claude, set up dev intelligence, initialize a new project, or do a new project setup.…