Create Project Template
Interactive workflow for creating new project templates at Level 1, 1.5, or 2 by cloning and customizing a parent template.
Prerequisites
$PROJECT_TEMPLATES_DIR— directory where template repos live- Git access to the GitHub org in
$PROJECT_TEMPLATES_GITHUB_ORGfor cloning parent templates - For plugin search: access to
$PLUGINS_PUBLIC_SOURCE_DIRand$PLUGINS_PRIVATE_SOURCE_DIR(optional — set in~/.claude/settings.json env)
Step 1: Gather Information
Ask the user (skip questions already answered):
Template level — What are you creating?
- Level 1 — Stack template (e.g.,
project-directus-nextjs). Reusable base for multiple demos and client projects. - Level 1.5 — Demo app (e.g.,
demo-directus-nextjs). Working showcase with sample data. - Level 2 — Client project (e.g.,
acme-website). Final project with real credentials.
- Level 1 — Stack template (e.g.,
Stack name — What technologies? (e.g.,
directus-nextjs,supabase-n8n,nocodb-trigger) Ask for each layer:- Data layer (database, CMS, BaaS): e.g., Directus, NocoDB, Supabase, NocoBase, PostgreSQL
- Logic layer (backend, automation, jobs): e.g., Next.js, n8n, Trigger.dev, Node.js
- Interface layer (frontend, UI): e.g., Next.js, Nuxt, React, Vue
Parent template — Which parent to clone from?
- Level 1 → defaults to
project-template - Level 1.5 → defaults to
project-{stack} - Level 2 → defaults to
project-{stack}(ordemo-{stack}if forking from demo)
- Level 1 → defaults to
Client name (Level 2 only) — e.g.,
acme,widgets-inc,globexProject description — One sentence describing the project purpose
Step 2: Generate Template Name
Apply naming convention:
| Level | Pattern | Example |
|---|---|---|
| 1 | project-{stack} |
project-directus-nextjs |
| 1.5 | demo-{stack} |
demo-directus-nextjs |
| 2 | {client}-{project} |
acme-website |
Confirm the name with the user before proceeding.
Step 3: Clone Parent Template
3a. Locate parent
PARENT_NAME="project-template" # from Step 1
# Check local
if [ -d "$PROJECT_TEMPLATES_DIR/$PARENT_NAME" ]; then
PARENT_DIR="$PROJECT_TEMPLATES_DIR/$PARENT_NAME"
else
# Clone from GitHub
echo "Cloning parent template from GitHub..."
git clone "git@github.com:$PROJECT_TEMPLATES_GITHUB_ORG/$PARENT_NAME.git" "$PROJECT_TEMPLATES_DIR/$PARENT_NAME"
PARENT_DIR="$PROJECT_TEMPLATES_DIR/$PARENT_NAME"
fi
3b. Create new template
NEW_NAME="project-directus-nextjs" # from Step 2
NEW_DIR="$PROJECT_TEMPLATES_DIR/$NEW_NAME"
# Clone parent into new directory
git clone "$PARENT_DIR" "$NEW_DIR"
# Reset git for fresh history
cd "$NEW_DIR"
rm -rf .git
git init
3c. Set up remote (optional)
git remote add origin "git@github.com:$PROJECT_TEMPLATES_GITHUB_ORG/$NEW_NAME.git"
Ask the user if they want to create the GitHub repo now or later.
Step 4: Customize stack.json
Generate stack.json based on user input from Step 1:
{
"stack": "{stack-name}",
"version": "1.0.0",
"level": {level},
"parent": "{parent-name}",
"description": "{project-description}",
"layers": {
"data": ["{data-layer-technologies}"],
"logic": ["{logic-layer-technologies}"],
"interface": ["{interface-layer-technologies}"]
},
"plugins": {
"technology": [],
"process": [],
"stack": []
}
}
The plugins arrays are filled in Step 7 after searching for matching plugins.
Layer Classification for Full-Stack Frameworks
Many frameworks serve multiple layers. When a single technology handles both backend logic (API routes, server middleware) AND frontend rendering, list it in BOTH layers:
| Framework | data | logic | interface | Reason |
|---|---|---|---|---|
| Next.js | — | nextjs |
nextjs |
API routes + React SSR/CSR |
| Nuxt | — | nuxt |
nuxt |
Server routes + Vue SSR/CSR |
| SvelteKit | — | sveltekit |
sveltekit |
Endpoints + Svelte SSR |
| Remix | — | remix |
remix |
Loaders/actions + React |
| Rails | — | rails |
rails |
Controllers + views |
Dedicated backend-only or frontend-only tools go in a single layer:
- Data only: Directus, Supabase, NocoDB, PostgreSQL
- Logic only: n8n, Trigger.dev, Inngest, Express
- Interface only: React (SPA), Vue (SPA without Nuxt)
This matters because plugins are searched per-layer. A framework in both logic and interface ensures the right plugins are found for both backend and frontend capabilities.
See references/stack-json-schema.md for the complete field documentation.
Step 5: Customize AGENTS.md and CLAUDE.md
AGENTS.md holds the shared rules every coding tool reads; CLAUDE.md begins with @AGENTS.md and adds Claude-specific lines (see template-reference/references/conventions.md). Edit whichever file already holds a section and keep @AGENTS.md as the first line of CLAUDE.md. Never generate AGENTS.md from CLAUDE.md. If the parent is a template from the older layout (AGENTS.md generated from CLAUDE.md), migrate it now: move the shared sections into AGENTS.md and import it from CLAUDE.md.
Update the project memory for the new template level:
Level 1 Changes
- Replace project name placeholder with stack name (e.g., "Directus + Next.js Stack Template")
- Add "Level 1 stack template. Fork this for client projects (Level 2)." at top
- Fill Tech Stack section with actual technologies and their roles
- Fill Installed Plugins section (populated in Step 7)
- Add stack-specific Quick Commands (e.g.,
docker compose up dev,pnpm dev) - Add Gotchas section with known stack-specific pitfalls
- Remove all remaining placeholder comments
- Keep under 100 lines in total, imported
AGENTS.mdincluded (this system's own limit; Anthropic's guidance is under 200). Do not pull@docs/...imports in to save space — imports load at launch; point todocs/architecture.mdby plain path instead
Level 1.5 Changes
- Same as Level 1, plus note that it's a demo
- Add demo-specific commands (seed data, reset demo)
Level 2 Changes
- Replace with client project name
- Run the equivalent of
/init-stackPhase 2-4 to fill project-specific content
Step 6: Customize Template Files
For Level 1
.env.example — Uncomment relevant variables, remove irrelevant ones:
# Keep only the variables for the selected stack
# Add stack-specific variables not in the L0 template
.mcp.json — Add the stack's MCP servers. The file is committed, so it holds ${VAR} references only; every variable goes into .env.example (and the env block of .claude/settings.local.json.example), the real values stay in the gitignored .env / .claude/settings.local.json:
{
"mcpServers": {
"{data-service}": {
"type": "http",
"url": "${DATA_SERVICE_URL}/mcp",
"headers": { "Authorization": "Bearer ${DATA_SERVICE_TOKEN}" }
}
}
}
A literal URL is acceptable only for a published product endpoint that is the same for every user.
docs/architecture.md — Fill with stack-specific architecture:
- Overview of the stack (what each layer does)
- Directory structure for the stack
- Data flow between layers
docs/code-style.md — Add stack-specific style rules (e.g., Next.js component patterns, Directus SDK usage patterns)
docs/api-conventions.md — Fill authentication method, pagination pattern based on the stack
Stack-specific config files — Use references/stack-templates.md for ready-made configuration snippets (nuxt.config.ts, next.config.ts, docker-compose.yml, Dockerfile, trigger.config.ts, .editorconfig). Adapt these to the specific stack rather than writing from scratch.
Stack-specific skills — Create skills for common stack operations. See the level checklist at references/level-checklist.md for suggestions per stack.
Stack-specific config files — Add files appropriate to the stack:
package.json(if Node.js-based)next.config.ts(if Next.js)docker-compose.yml(if using Docker)tsconfig.json(if TypeScript)- etc.
For Level 1.5
Everything from Level 1, plus:
- Sample data / seed scripts
- Working pages consuming data
- Configured UI components
- Docker Compose for full local environment
For Level 2
Run the init-stack command flow (Phases 2-4):
- Configure
.envwith real credentials - Populate
project-configskill with resource IDs - Fill project documentation
- Create domain-specific skills if needed
Step 7: Search for Matching Plugins
Search for Agents Store plugins that match the selected technologies:
# Search both plugin directories
for TECH in {data-layer} {logic-layer} {interface-layer}; do
echo "=== Searching for $TECH plugins ==="
# Public plugins
if [ -d "$PLUGINS_PUBLIC_SOURCE_DIR" ]; then
ls "$PLUGINS_PUBLIC_SOURCE_DIR" | grep -i "$TECH" || echo " (none in public)"
fi
# Private plugins
if [ -d "$PLUGINS_PRIVATE_SOURCE_DIR" ]; then
ls "$PLUGINS_PRIVATE_SOURCE_DIR" | grep -i "$TECH" || echo " (none in private)"
fi
done
For each found plugin, read its plugin.json to get the name and classify by type (technology, process, stack). Note which directory it was found in: a plugin from $PLUGINS_PUBLIC_SOURCE_DIR is public (it is in the Agents Store marketplace), one found only in $PLUGINS_PRIVATE_SOURCE_DIR is private.
Update stack.json plugins arrays with found plugins. Stack plugins are named stack-{name}; technology plugins {tool}-{process}. Use the name from each plugin's plugin.json (it can differ from the directory name); a retired or renamed name is not a plugin.
Update CLAUDE.md Installed Plugins section with plugin names and descriptions.
Write .claude/settings.json (committed) from the public plugins in that list, so they are offered to everyone who clones the template:
{
"extraKnownMarketplaces": {
"agents-store-claude-plugins": {
"source": { "source": "github", "repo": "Agents-Store/claude-plugins" }
}
},
"enabledPlugins": {
"directus-dev@agents-store-claude-plugins": true
}
}
Add one "<name>@agents-store-claude-plugins": true entry per public plugin from stack.json. Plugins found only in the private source stay in stack.json and in the CLAUDE.md Installed Plugins section, but are NOT written to .claude/settings.json: they do not exist in the public marketplace, and a committed file must never name a private marketplace. The owner installs them separately from their own marketplace. Keep any other keys the parent already has; never put env values or tokens in this file.
Report:
Plugins found:
technology: directus-dev, nextjs-dev, nextjs-provision, vercel-dev
stack: stack-directus-nextjs
Plugins NOT found:
(none — all technologies have matching plugins)
OR:
nuxt — no plugin found. Author one as a Claude Code plugin (for example with /plugin-dev:create-plugin from the official plugin-dev plugin)
Step 8: Validate
Run the validate skill to check the generated template:
Read ${CLAUDE_PLUGIN_ROOT}/skills/validate/SKILL.md and execute all checks against the new template directory.
Fix any issues found before proceeding.
Step 9: Initial Commit
cd "$NEW_DIR"
git add -A
git commit -m "feat: scaffold $NEW_NAME from $PARENT_NAME
Level $LEVEL template for $STACK_DESCRIPTION.
Technologies: $DATA_LAYER + $LOGIC_LAYER + $INTERFACE_LAYER.
Plugins: $PLUGIN_LIST."
Present summary:
Template created: {new-name}
Location: $PROJECT_TEMPLATES_DIR/{new-name}
Level: {level}
Parent: {parent-name}
Stack: {stack-name}
Plugins: {count} found, {count} missing
Next steps:
1. Review generated files
2. Install the public plugins: `.claude/settings.json` enables them, but each person still runs `claude plugin install <name>@agents-store-claude-plugins --scope project` once (add the marketplace first with `claude plugin marketplace add Agents-Store/claude-plugins`). Private plugins: install them yourself from their own marketplace
3. Push to GitHub: git remote add origin git@github.com:$PROJECT_TEMPLATES_GITHUB_ORG/{new-name}.git && git push -u origin main