Skip to content
Skills Library
AI & agents · Building & coding

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

Repository
skills ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

set up optimiziramsi-skills herescaffold the agent workspacewire up the .agent layoutinitialize the toolkit in this project
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

  1. Why it's shaped this way
  2. Steps
  3. .agent/README.md template
  4. What NOT to do
Original SKILL.md headings · 107 lines, 872 words
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

RepositoryScoreLicence
This page · optimiziramsi/skills100MIT
jeremylongshore/tons-of-skills-marketplace100MIT
jkaloger/lazyspec100MIT
genkovich/sdlc100MIT
DnsQueen/orcinus-skills100MIT
duc01226/EasyPlatform100MIT
duc01226/EasyPlatform100MIT
chuckplayer/claude-agent-pack100MIT
dan323/easier-life-skills100MIT

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.…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.