Scaffolding

Name: Scaffolding
Author: owlmeans

ASecurity

How to scaffold a new OwlMeans Common project — the @owlmeans/create-app CLI (npm/bun/yarn create), its flags, what it generates, and the manual alternative. Use when asked to create/bootstrap/start a new OwlMeans app or set up a fresh project.

3 stars

0 votes

0 copies

0 views

Added 9/22/2026

developmentshellreactnodegitapidatabasefrontendfullstack

Works with

claude codecliapi

Security Analysis

A100/100

Scanned 9/22/2026

Install to Claude Code

$npx -y skills add owlmeans/common --skill scaffolding --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Scaffolding?

Add the live security badge to your README — it updates automatically with every re-scan.

[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/owlmeans-scaffolding/badge)](https://www.skillsdirectory.com/skills/owlmeans-scaffolding)

More formats (shields.io, HTML) on the badges page.

Download Zip

Files

SKILL.md

---
name: scaffolding
description: How to scaffold a new OwlMeans Common project — the @owlmeans/create-app CLI (npm/bun/yarn create), its flags, what it generates, and the manual alternative. Use when asked to create/bootstrap/start a new OwlMeans app or set up a fresh project.
user-invocable: true
metadata:
  scope: general
---

# Scaffolding a new OwlMeans Common project

Two paths produce the same minimal fullstack project (`common` + `api` + `web`, shadcn UI
navigation/layout, **no auth**, a **session-scoped in-memory resource**). The full reference is the
[OwlMeans getting-started guide](https://github.com/owlmeans/common/blob/main/docs/getting-started.md);
the framework shape is [[getting-started]].

## Path 1 — `@owlmeans/create-app` (one command)

```sh
npm create @owlmeans/app@latest my-app
bun create @owlmeans/app my-app
yarn create @owlmeans/app my-app
npx @owlmeans/create-app@^0.1.18-rc.38 my-app
```

By default it copies the template, runs `git init`, installs dependencies, and **deploys agent
guidance** into the project (`.agents/skills/`). `@owlmeans/agent-skills` is a dependency of the
scaffolder and runs in-process, so the deploy happens whatever `--pm` is. With `--no-install` it
still runs — the installer's own bundled extras give the project its general/harness guidance;
only the package-specific skills wait for `npx @owlmeans/agent-skills@^0.1.18-rc.30` after the
install.

Flags: `--name <name>`, `--slug <slug>`, `--lang <code>` (default `en`), `--description <text>`,
`--bare`, `--pm <bun|npm|yarn>` (default `bun`), `--no-install`, `--no-skills`, `--no-git`,
`--yes`/`-y`, `--help`.

`--slug` overrides the slug derived from the directory name and must match
`^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$`; `--lang` sets the generated `<html lang>`;
`--description` becomes the one-line blurb in `README.md`, `AGENTS.md`, the Home screen and the
`index.html` meta tags. The four values reach the template as `__APP_SLUG__`, `__APP_NAME__`,
`__APP_LANG__` and `__APP_DESCRIPTION__`.

Then run:

```sh
cd my-app && bun run dev      # API :3000, web :3001
```

**When an agent should use this:** the user asks to start/bootstrap/create a new OwlMeans app from
nothing. Prefer it over hand-writing boilerplate. After it runs, point the user at the **Session**
screen and the getting-started guide — or, with `--bare`, straight at
`sources/common/src/entrypoints.ts`.

## `--bare` — the shell without the demo

`--bare` generates the same three workspaces, config/context/entrypoint wiring, layout, nav and a
single Home screen, and leaves out every piece of example code: the `SessionItem` types and
schemas, the api's `app/session/**` handlers and its static resource, and the About/Session
screens with their nav entries. `sources/common/src/entrypoints.ts` then exports an immutable
`appProtocols` protocol tree with an empty `api` branch; the first feature adds a declaration
there, a server implementation bound in the api and a screen bound to a frontend route in the web.
Use it whenever the app is being generated for someone (or something) that will write the real
features immediately; use the full template when the user wants a worked example to read.

The bare inventory is **data in the template**, never a list in the CLI code:
`template/_bare.json` holds `remove` (template-relative paths, directory subtrees or `*`/`**`
globs) and `overrides` (target path → a sibling source carrying a `.bare.` infix, whose CONTENT is
written to the target). Files with `.bare.` in the name are filtered out of the copy in **both**
modes, so the normal template still compiles as one project. Adding demo code therefore means
adding its path to `remove`, or shipping a `foo.bare.ts` beside `foo.ts` and mapping it — the
scaffolder itself does not change.

## Driving create-app from another tool

`@owlmeans/create-app` also exports a programmatic entry that does the filesystem copy and nothing
else — no `git init`, no install, no agent-skills deploy, no output — so a generator can own those
steps itself. The destination may already exist.

```ts
import { scaffold } from '@owlmeans/create-app'

scaffold({ dir, slug: 'my-app', name: 'My App', lang: 'en', description: '…', bare: true })
```

`templateDir()`, `copyTemplate(src, dest, replacements, { bare })` and `isEmptyDir(dir)` are
exported alongside it for callers that need the pieces; `run(args)` is the whole CLI flow.

## Path 2 — manual

Follow **Option B** in the
[OwlMeans getting-started guide](https://github.com/owlmeans/common/blob/main/docs/getting-started.md): create the bun
workspace, then `common` (shared `entrypoints.ts`/schemas/config), `api` (`@owlmeans/server-app` +
`appendStaticResource` handlers + `main`), and `web` (`@owlmeans/web-panel` + shadcn `@`-provided
primitives + layout/nav/screens). Finish with `npx @owlmeans/agent-skills@^0.1.18-rc.30` to add agent guidance.

## What gets generated

```
my-app/
├── package.json            # bun workspaces: sources/*, plus a `prepare` script
├── bunfig.toml             # [install] linker = "hoisted"
├── AGENTS.md               # git/reporting/memory/self-education rules + project-purpose placeholder
├── CLAUDE.md               # thin bridge: imports AGENTS.md, documents the skill symlinks
├── .agents/skills/         # seeded harness skills (+ deployed ones)
├── .agents/scripts/link-skills.sh  # links local + installed-package skills for every agent
├── .agents/linked-skills/  # generated on install, git-ignored — see below
├── .agents/memory/MEMORY.md      # starter shared memory graph index
├── sources/common/         # consts, types, schemas, config, entrypoints.ts
├── sources/api/            # context.ts (appendStaticResource), app/session/*, entrypoints.ts, index.ts
└── sources/web/            # vite + tailwind v4, components/ui/*, layout, nav, screens, render.tsx
                            # context.ts registers a @owlmeans/state resource the screens read
```

`bunfig.toml` pins the **hoisted** linker, the same one every OwlMeans monorepo uses: React and the
`@owlmeans/*` singletons must resolve to one copy across the workspaces, and the default isolated
linker gives each workspace its own. Keep it even in a project that adds no further workspaces.

The root `prepare` script runs `.agents/scripts/link-skills.sh` on every install, so the links
exist for whoever checks the project out with no agent session needed to create them. Claude Code's
committed `SessionStart` hook runs the same script again. The script does two passes:

- **Local** — one symlink per `.agents/skills/<name>` into `.claude/skills/<name>`, which is the
  only place Claude Code discovers skills. Copilot and Codex read `.agents/skills/` directly.
- **Installed packages** — it finds every `node_modules/@owlmeans/<pkg>/agent-meta/skills/<name>`
  in the project (the root scope and each workspace's own, since bun keeps a package's deps under
  `sources/<pkg>/node_modules` when they are not hoisted; the same physical package is counted
  once) and links each into **both** `.agents/linked-skills/<name>` — where Copilot and Codex read
  it — and `.claude/skills/<name>`. It writes a skill / origin / description table to
  `.agents/linked-skills/INDEX.md`, prunes links that no longer resolve, and removes the directory
  entirely when nothing is linked. A local skill of the same name always shadows a linked one.

`.agents/linked-skills/` is generated and git-ignored (the generated `.gitignore` lists it), so it
is never edited or committed — re-run the script instead.

Memory lives **only** in `.agents/memory/` (see [[agent-memory]]; [[memory-recompact]] folds a
per-agent memory directory back into it).

**Routing is OwlMeans-native.** The generated app has no `react-router` dependency and no
`react-router` override: `makeContext` registers `@owlmeans/web-router` and `PanelApp` resolves
its compiler from the active plugin, so `render.tsx` passes no `provide` prop. Layouts take
`children` — the renderer supplies the plugin's `Outlet` — and navigation is `useNavigate()` from
`@owlmeans/web-panel`. An app that genuinely wants react-router opts in per [[router-plugins]];
never re-add it to the template.

The session demo stores items server-side in `@owlmeans/static-resource`, namespaced by a
client-generated `sid` kept in `localStorage` — no database, no authentication. The `list` handler
asks the resource the whole question (`list({ sessionId }, { sort })`) rather than filtering
afterwards. On the client the screen reads a `@owlmeans/state` resource registered by `makeContext`,
subscribed as a live query through `useStoreList`; the fetch calls the entrypoint
(`ctx.entrypoint(session.list).call({ params })` → the items) and installs them with
`store.replace(items)` rather than keeping them in component state. See [[static-resource]],
[[state]], [[server-app]], [[web-panel]].

## Generated agent guidance

`AGENTS.md` carries the same four mandatory sections as a real OwlMeans monorepo — **Git
Workflow**, **Reporting**, **Memory** (the `.agents/memory/` graph store), **Self-Education** —
plus the mandatory [[reuse-code]] section and a **project-purpose placeholder**
(`<!-- OWLMEANS:PROJECT-PURPOSE -->`). On the first agent session that block instructs the agent to
ask the user what the project is for and replace it. `CLAUDE.md` is a thin bridge that imports
`AGENTS.md` and keeps the gitignored `.claude/skills/` symlinks fresh through a `SessionStart`
hook. Copilot and Codex need no bridge file: they read `AGENTS.md`, `.agents/skills/` and
`.agents/linked-skills/` natively, which is why `AGENTS.md` carries its own
`<!-- OWLMEANS:LINKED-SKILLS -->` section describing where the linked skills come from.

The harness guidance is **seeded into the template** as generated, banner-carrying copies, so a
project has it even before the installer runs: [[agent-memory]], [[memory-promotion]],
[[memory-recompact]], [[self-education]], [[skill-authoring]], `git`, [[reuse-code]],
[[getting-started]]. Regenerate the seed with `sync-agent-meta --seed-only` in the library-manager;
never hand-edit a seeded copy. The installer adds the remaining general skills
([[scaffolding]], [[router-plugins]], [[shadcn-web]], [[shadcn-versions]], [[consent]],
[[login-methods]], [[login-plugins]], [[agent-skills]]) and every package-specific one. After adding any `@owlmeans/*` dependency, re-run `npx @owlmeans/agent-skills@^0.1.18-rc.30`
— discovery scans **every** `node_modules/@owlmeans` in the workspace (root and nested under
`sources/*`), so package-specific skills are picked up even though bun nests them.

Attribution

owlmeans

View source More from owlmeans →

SSkills DirectorySkills Directory

Ship a skill? Prove it's safe.

Free 120-pattern security scan, letter grade, and an embeddable README badge.

Submit a skill

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

Comments (0)

No comments yet. Be the first to comment!

--- name: scaffolding description: How to scaffold a new OwlMeans Common project — the @owlmeans/create-app CLI (npm/bun/yarn create), its flags, what it generates, and the manual alternative. Use when asked to create/bootstrap/start a new OwlMeans app or set up a fresh project. user-invocable: true metadata: scope: general --- # Scaffolding a new OwlMeans Common project Two paths produce the same minimal fullstack project (`common` + `api` + `web`, shadcn UI navigation/layout, **no auth**, a **session-scoped in-memory resource**). The full reference is the [OwlMeans getting-started guide](https://github.com/owlmeans/common/blob/main/docs/getting-started.md); the framework shape is [[getting-started]]. ## Path 1 — `@owlmeans/create-app` (one command) ```sh npm create @owlmeans/app@latest my-app bun create @owlmeans/app my-app yarn create @owlmeans/app my-app npx @owlmeans/create-app@^0.1.18-rc.38 my-app ``` By default it copies the template, runs `git init`, installs dependencies, and **deploys agent guidance** into the project (`.agents/skills/`). `@owlmeans/agent-skills` is a dependency of the scaffolder and runs in-process, so the deploy happens whatever `--pm` is. With `--no-install` it still runs — the installer's own bundled extras give the project its general/harness guidance; only the package-specific skills wait for `npx @owlmeans/agent-skills@^0.1.18-rc.30` after the install. Flags: `--name <name>`, `--slug <slug>`, `--lang <code>` (default `en`), `--description <text>`, `--bare`, `--pm <bun|npm|yarn>` (default `bun`), `--no-install`, `--no-skills`, `--no-git`, `--yes`/`-y`, `--help`. `--slug` overrides the slug derived from the directory name and must match `^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$`; `--lang` sets the generated `<html lang>`; `--description` becomes the one-line blurb in `README.md`, `AGENTS.md`, the Home screen and the `index.html` meta tags. The four values reach the template as `__APP_SLUG__`, `__APP_NAME__`, `__APP_LANG__` and `__APP_DESCRIPTION__`. Then run: ```sh cd my-app && bun run dev # API :3000, web :3001 ``` **When an agent should use this:** the user asks to start/bootstrap/create a new OwlMeans app from nothing. Prefer it over hand-writing boilerplate. After it runs, point the user at the **Session** screen and the getting-started guide — or, with `--bare`, straight at `sources/common/src/entrypoints.ts`. ## `--bare` — the shell without the demo `--bare` generates the same three workspaces, config/context/entrypoint wiring, layout, nav and a single Home screen, and leaves out every piece of example code: the `SessionItem` types and schemas, the api's `app/session/**` handlers and its static resource, and the About/Session screens with their nav entries. `sources/common/src/entrypoints.ts` then exports an immutable `appProtocols` protocol tree with an empty `api` branch; the first feature adds a declaration there, a server implementation bound in the api and a screen bound to a frontend route in the web. Use it whenever the app is being generated for someone (or something) that will write the real features immediately; use the full template when the user wants a worked example to read. The bare inventory is **data in the template**, never a list in the CLI code: `template/_bare.json` holds `remove` (template-relative paths, directory subtrees or `*`/`**` globs) and `overrides` (target path → a sibling source carrying a `.bare.` infix, whose CONTENT is written to the target). Files with `.bare.` in the name are filtered out of the copy in **both** modes, so the normal template still compiles as one project. Adding demo code therefore means adding its path to `remove`, or shipping a `foo.bare.ts` beside `foo.ts` and mapping it — the scaffolder itself does not change. ## Driving create-app from another tool `@owlmeans/create-app` also exports a programmatic entry that does the filesystem copy and nothing else — no `git init`, no install, no agent-skills deploy, no output — so a generator can own those steps itself. The destination may already exist. ```ts import { scaffold } from '@owlmeans/create-app' scaffold({ dir, slug: 'my-app', name: 'My App', lang: 'en', description: '…', bare: true }) ``` `templateDir()`, `copyTemplate(src, dest, replacements, { bare })` and `isEmptyDir(dir)` are exported alongside it for callers that need the pieces; `run(args)` is the whole CLI flow. ## Path 2 — manual Follow **Option B** in the [OwlMeans getting-started guide](https://github.com/owlmeans/common/blob/main/docs/getting-started.md): create the bun workspace, then `common` (shared `entrypoints.ts`/schemas/config), `api` (`@owlmeans/server-app` + `appendStaticResource` handlers + `main`), and `web` (`@owlmeans/web-panel` + shadcn `@`-provided primitives + layout/nav/screens). Finish with `npx @owlmeans/agent-skills@^0.1.18-rc.30` to add agent guidance. ## What gets generated ``` my-app/ ├── package.json # bun workspaces: sources/*, plus a `prepare` script ├── bunfig.toml # [install] linker = "hoisted" ├── AGENTS.md # git/reporting/memory/self-education rules + project-purpose placeholder ├── CLAUDE.md # thin bridge: imports AGENTS.md, documents the skill symlinks ├── .agents/skills/ # seeded harness skills (+ deployed ones) ├── .agents/scripts/link-skills.sh # links local + installed-package skills for every agent ├── .agents/linked-skills/ # generated on install, git-ignored — see below ├── .agents/memory/MEMORY.md # starter shared memory graph index ├── sources/common/ # consts, types, schemas, config, entrypoints.ts ├── sources/api/ # context.ts (appendStaticResource), app/session/*, entrypoints.ts, index.ts └── sources/web/ # vite + tailwind v4, components/ui/*, layout, nav, screens, render.tsx # context.ts registers a @owlmeans/state resource the screens read ``` `bunfig.toml` pins the **hoisted** linker, the same one every OwlMeans monorepo uses: React and the `@owlmeans/*` singletons must resolve to one copy across the workspaces, and the default isolated linker gives each workspace its own. Keep it even in a project that adds no further workspaces. The root `prepare` script runs `.agents/scripts/link-skills.sh` on every install, so the links exist for whoever checks the project out with no agent session needed to create them. Claude Code's committed `SessionStart` hook runs the same script again. The script does two passes: - **Local** — one symlink per `.agents/skills/<name>` into `.claude/skills/<name>`, which is the only place Claude Code discovers skills. Copilot and Codex read `.agents/skills/` directly. - **Installed packages** — it finds every `node_modules/@owlmeans/<pkg>/agent-meta/skills/<name>` in the project (the root scope and each workspace's own, since bun keeps a package's deps under `sources/<pkg>/node_modules` when they are not hoisted; the same physical package is counted once) and links each into **both** `.agents/linked-skills/<name>` — where Copilot and Codex read it — and `.claude/skills/<name>`. It writes a skill / origin / description table to `.agents/linked-skills/INDEX.md`, prunes links that no longer resolve, and removes the directory entirely when nothing is linked. A local skill of the same name always shadows a linked one. `.agents/linked-skills/` is generated and git-ignored (the generated `.gitignore` lists it), so it is never edited or committed — re-run the script instead. Memory lives **only** in `.agents/memory/` (see [[agent-memory]]; [[memory-recompact]] folds a per-agent memory directory back into it). **Routing is OwlMeans-native.** The generated app has no `react-router` dependency and no `react-router` override: `makeContext` registers `@owlmeans/web-router` and `PanelApp` resolves its compiler from the active plugin, so `render.tsx` passes no `provide` prop. Layouts take `children` — the renderer supplies the plugin's `Outlet` — and navigation is `useNavigate()` from `@owlmeans/web-panel`. An app that genuinely wants react-router opts in per [[router-plugins]]; never re-add it to the template. The session demo stores items server-side in `@owlmeans/static-resource`, namespaced by a client-generated `sid` kept in `localStorage` — no database, no authentication. The `list` handler asks the resource the whole question (`list({ sessionId }, { sort })`) rather than filtering afterwards. On the client the screen reads a `@owlmeans/state` resource registered by `makeContext`, subscribed as a live query through `useStoreList`; the fetch calls the entrypoint (`ctx.entrypoint(session.list).call({ params })` → the items) and installs them with `store.replace(items)` rather than keeping them in component state. See [[static-resource]], [[state]], [[server-app]], [[web-panel]]. ## Generated agent guidance `AGENTS.md` carries the same four mandatory sections as a real OwlMeans monorepo — **Git Workflow**, **Reporting**, **Memory** (the `.agents/memory/` graph store), **Self-Education** — plus the mandatory [[reuse-code]] section and a **project-purpose placeholder** (``). On the first agent session that block instructs the agent to ask the user what the project is for and replace it. `CLAUDE.md` is a thin bridge that imports `AGENTS.md` and keeps the gitignored `.claude/skills/` symlinks fresh through a `SessionStart` hook. Copilot and Codex need no bridge file: they read `AGENTS.md`, `.agents/skills/` and `.agents/linked-skills/` natively, which is why `AGENTS.md` carries its own `` section describing where the linked skills come from. The harness guidance is **seeded into the template** as generated, banner-carrying copies, so a project has it even before the installer runs: [[agent-memory]], [[memory-promotion]], [[memory-recompact]], [[self-education]], [[skill-authoring]], `git`, [[reuse-code]], [[getting-started]]. Regenerate the seed with `sync-agent-meta --seed-only` in the library-manager; never hand-edit a seeded copy. The installer adds the remaining general skills ([[scaffolding]], [[router-plugins]], [[shadcn-web]], [[shadcn-versions]], [[consent]], [[login-methods]], [[login-plugins]], [[agent-skills]]) and every package-specific one. After adding any `@owlmeans/*` dependency, re-run `npx @owlmeans/agent-skills@^0.1.18-rc.30` — discovery scans **every** `node_modules/@owlmeans` in the workspace (root and nested under `sources/*`), so package-specific skills are picked up even though bun nests them.