Skip to content

Project Scaffolder User Guide

Project Scaffolder transforms project context—a PRD file, existing project directory, or free-text description—into a ranked Bundle of Claude Code artifacts ready to deploy. Use it to bootstrap new projects with matched artifacts or add a feature to an existing project without re-deploying what you already have.

Overview

Project Scaffolder automates artifact discovery and Bundle assembly. Instead of manually browsing the marketplace or spending hours selecting skills, agents, and commands, you describe your project once and Scaffolder returns a curated, ranked Bundle of artifacts that fit your tech stack and requirements.

What it does: - Analyzes your project context (extracts technology intents, architecture patterns, and required capabilities) - Optionally interviews you if intent confidence is low (≤3 clarifying questions) - Searches local and marketplace artifact sources with semantic and metadata ranking - Deduplicates and ranks candidates deterministically - Creates a Bundle and optionally deploys it to your project

Timeline: 5 minutes from context to deployed artifacts (vs 2+ hours manual setup).

For complete technical details, see .claude/skills/project-scaffolder/SKILL.md.

When to Use

Use Project Scaffolder in these scenarios:

  • Starting a new project from a PRD — You have a product requirements document and want a complete artifact set to begin development.
  • Adding a feature to an existing project — You want artifacts for a new feature without re-deploying existing skills and agents already in your project.
  • Exploring available artifacts — You describe a tech stack and want to see what artifacts the collection recommends.
  • Scaffolding from an implementation plan — You have a detailed plan file describing architecture and want matched artifacts.
  • Quick bootstrap with free text — You describe your stack in natural language and Scaffolder assembles a Bundle.

Two Ways to Invoke

Use Claude Code's interactive /scaffold commands for high-quality intent extraction and real-time curation. These commands invoke the Project Scaffolder skill with full subagent orchestration.

For new projects: 

/scaffold:project

Claude Code will prompt you for project context (PRD path, directory, or description) and guide you through the full pipeline interactively.

For adding a feature to an existing project: 

/scaffold:feature

Scaffolder reads your existing .claude/ inventory and excludes already-deployed artifacts before recommending new ones.

Mode differences: | Mode | Input | Output | Use When | |------|-------|--------|----------| | Project | PRD, directory, or description | Whole-project Bundle (all capabilities) | Starting fresh | | Feature | Feature description, PRD, or plan | Feature-scoped Bundle (excludes deployed artifacts) | Adding to existing project |

Option 2: CLI (Deterministic, Scriptable)

Use the CLI for non-interactive, scriptable scaffolding. The CLI applies deterministic heuristic-based intent detection instead of LLM analysis.

Basic syntax: 

skillmeat scaffold --from-context <path-or-text> --project <target-dir> [options]

Required arguments: - --from-context — Path to PRD/plan file, project directory, or free-text description - --project — Target directory where artifacts will be deployed

CLI Flags Reference

Flag Type Default Description
--from-context path or string (required if no --from-repo or --bundle) PRD file, implementation plan, project directory, or free-text description
--from-repo HTTPS URL or shorthand (optional) Clone a remote git repository (HTTPS URL or owner/repo shorthand); shallow clone with --depth=1. Temp directory is removed after command completes. Mutually exclusive with --from-context and --bundle.
--project path (required) Target project directory
--scope choice whole-project Curation scope: whole-project or feature
--auto-confirm flag false Skip interactive confirmation (useful for CI/scripts)
--dry-run flag false Preview intent detection and candidate artifacts without writing files
--intent-set-dir path project dir Directory where the Intent Set YAML sidecar is written
--use-llm-analyzer / --no-llm-analyzer flag auto-detect Explicitly control LLM-powered project analysis. Omit both to auto-detect based on Claude Code environment (CLAUDECODE or CLAUDE_CODE_ENTRYPOINT env vars). --use-llm-analyzer always uses the project-analyzer agent. --no-llm-analyzer always uses heuristic fallback.
--output-pr owner/repo or GitHub URL (optional) Create a pull request on the specified GitHub repository instead of writing files locally. Only valid with --from-context or --from-repo. Accepts shorthand (owner/repo) or full URL. Local deployment is skipped; PR is created against repo's default branch.
--bundle bundle ID (optional) Bundle ID to scaffold using legacy direct Bundle deployment. Mutually exclusive with --from-context and --from-repo.

Mutual exclusivity rules: - One of --from-context, --from-repo, or --bundle is required - --from-context and --from-repo are mutually exclusive with each other and --bundle - --output-pr is only valid with --from-context or --from-repo (not with --bundle)

Complete Walkthroughs

Example 1: Scaffold a New Project from a PRD

You have a PRD describing a FastAPI backend with React frontend and PostgreSQL database.

skillmeat scaffold --from-context ./prd.md --project ./my-project --dry-run

What happens:

  1. Loading context — Scaffolder reads your PRD file (up to 10K tokens)
  2. Detecting intents — Analyzer extracts capabilities: "python-backend", "web-frontend", "sql-database", "async-workers"
  3. Confidence check — If aggregate confidence > 0.65 and <2 high-priority intents are below 0.5, proceeds directly to curation
  4. Searching — Curator searches local and marketplace for artifacts matching each capability
  5. Ranking — Candidates ranked by: 50% semantic match + 30% metadata + 20% marketplace popularity
  6. Preview — Displays table of ranked artifacts:
TYPE      NAME                   SOURCE      CONFIDENCE  INTENT
skill     fastapi-server-core    local       0.92        python-backend
skill     postgres-migrations    local       0.88        sql-database
agent     backend-developer      local       0.85        python-backend
skill     react-typescript       marketplace 0.79        web-frontend
command   deploy-to-railway      marketplace 0.71        devops
  1. Confirm or abort — You review the list and confirm. Files are previewed but not written (due to --dry-run)

To proceed and write files: 

skillmeat scaffold --from-context ./prd.md --project ./my-project

Example 2: Scaffold a Feature in an Existing Project

You're adding OAuth2 authentication to your existing project.

skillmeat scaffold --from-context "add oauth2 authentication with google and github" \
  --project . \
  --scope feature \
  --auto-confirm

What happens:

  1. Reading inventory — Scaffolder checks your .claude/ directory and notes existing artifacts: 8 skills, 3 agents, 2 commands
  2. Detecting intents — Analyzer extracts: "authentication", "oauth2", "google-oauth", "github-oauth"
  3. Excluding deployed — Any existing auth skills/agents are marked as excluded (will not be re-recommended)
  4. Searching — Curator searches for auth-specific artifacts not already in your project
  5. Auto-confirming — With --auto-confirm, skips the preview step
  6. Deploying — Creates a Feature Bundle and deploys selected artifacts to .claude/

Example 3: Dry-Run with Free-Text Context

You describe your stack in natural language:

skillmeat scaffold --from-context "fastapi postgres react tailwind" \
  --project /tmp/test \
  --dry-run \
  --auto-confirm

Output preview: 

Loading context...
Detecting intents from free-text description...

Intent Set Summary:
┌─────────────────────────────────┐
│ SCAFFOLD_RUN_ID: scaf_20260408_a7b2 │
│ SOURCE: fastapi postgres react tailwind   │
│ AGGREGATE_CONFIDENCE: 0.72      │
│ INTENTS EXTRACTED: 5            │
└─────────────────────────────────┘

Searching for candidates...

Candidates Found (5 intents, 12 artifacts):
  TYPE      NAME                   CONFIDENCE  INTENT
  skill     fastapi-boilerplate    0.91        python-backend
  skill     postgres-alembic       0.87        sql-database
  skill     react-components       0.84        web-frontend
  skill     tailwind-config        0.79        css-framework
  command   dev-server             0.68        devops

Dry run complete — 5 candidate(s) would be deployed.

No files are written; you can review and adjust before running again without --dry-run.

Scope Variants

Whole-Project Mode (Default)

Flag: --scope whole-project (or omit; it's the default)

Scaffolder considers all available artifacts in your collection and marketplace. Use this for new projects or when you want a complete re-evaluation of your artifact set.

skillmeat scaffold --from-context ./prd.md --project ./new-project --scope whole-project

Feature Mode

Flag: --scope feature

Scaffolder reads your existing .claude/ directory, excludes already-deployed artifacts, and recommends only new ones. Use this when adding a feature to an existing project without risk of duplicating or overwriting what you already have.

skillmeat scaffold --from-context "./feature-plan.md" --project . --scope feature

Interview Flow

When intent confidence is low, Scaffolder asks clarifying questions before proceeding.

Interview triggers when: - Aggregate confidence is below 0.65, OR - Two or more high-priority intents have confidence below 0.5

Example interaction:

Confidence is moderate (0.61). I have a few clarifying questions:

1. Your PRD mentions "async processing" but doesn't specify Celery, ARQ, or RQ. 
   Which task queue will you use? (or skip if not needed)
   > Celery

2. I see PostgreSQL mentioned, but also some key-value cache patterns. 
   Will you use Redis, or a simpler in-memory cache?
   > Redis

3. Your architecture mentions webhooks. Will you rely on a specific webhook framework, 
   or build them from FastAPI routes?
   > FastAPI routes (skip specialized framework)

Confidence updated to 0.78. Proceeding to curation...

Answers are fed back to the analyzer for a refined Intent Set before artifact search begins.

Intent Set YAML Sidecar

Each Scaffolder run generates and persists an Intent Set YAML file alongside your Bundle manifest. This captures:

  • Run metadata — Run ID, timestamp, scope variant
  • Extracted intents — Capability, stack, confidence score, source citation, priority
  • Aggregate confidence — Weighted mean confidence across all intents
  • Interview history — Questions asked and answers (if triggered)

File location: scaf_YYYYMMDD_<hash>.intent-set.yaml (by default in your project root, or --intent-set-dir <path>)

Example: 

scaffold_run_id: scaf_20260408_a7b2c1d9
generated_at: 2026-04-08T14:32:15Z
source_summary: "FastAPI + React + PostgreSQL with Redis for caching"
scope_variant: whole-project
intents:
  - id: int_001
    capability: python-backend
    stack: fastapi
    confidence: 0.95
    source: "PRD §2 — Tech Stack (FastAPI explicitly named)"
    priority: high
  - id: int_002
    capability: web-frontend
    stack: react
    confidence: 0.91
    source: "PRD §3 — Frontend Framework (React explicitly named)"
    priority: high
  - id: int_003
    capability: sql-database
    stack: postgresql
    confidence: 0.88
    source: "PRD §2 — Database (PostgreSQL explicitly named)"
    priority: high
  - id: int_004
    capability: caching
    stack: redis
    confidence: 0.72
    source: "PRD §5 — Performance patterns (Redis mentioned once)"
    priority: medium
aggregate_confidence: 0.87
interview_triggered: false

Uses: - Audit trail — see what Scaffolder extracted and why - Re-run — edit intents and re-run with the same file to refine recommendations - Future features — context packing, marketplace analytics, recommendation refinement

Troubleshooting

"No candidate artifacts found"

Cause: The collection is sparse, or the intent query didn't match available artifacts.

Solution: 1. Check that your collection is seeded with at least 20 artifacts: skillmeat list | wc -l 2. Review the Intent Set YAML to see what intents were extracted. Are they accurate? 3. Try broadening the scope: remove --scope feature if present, or use --from-context with a longer, more detailed description 4. Search manually for your stack keywords in the marketplace: skillmeat search fastapi

"Marketplace timeout"

Cause: The marketplace API is unreachable or responding slowly.

Behavior: Scaffolder logs a warning and continues with local-only search results. No error; just fewer candidates.

Solution: 1. Verify the SkillMeat API is running: skillmeat web dev in another terminal 2. Check your network connection to the marketplace (if using a remote instance) 3. Retry with --dry-run to skip marketplace and use local results only: skillmeat scaffold --from-context ... --dry-run

"API unavailable in dry-run"

Behavior: In --dry-run mode, if the API is unavailable, Scaffolder synthesizes an empty candidate list and still shows the Intent Set YAML. No error; just an empty artifact table.

Solution: 1. Start the API: skillmeat web dev 2. Re-run without --dry-run to perform the full curation and deployment

Interview loop or unclear questions

Solution: 1. Simplify your input — instead of a long free-text description, provide a structured file (PRD or implementation plan) 2. Use --auto-confirm to skip interview and proceed with current confidence 3. Edit the generated Intent Set YAML manually, then re-run with --from-context <yaml-file> for fine-tuned recommendations