
buildable
Local product-structure compiler, compact UI/UX brain, and quality gate for your coding agent: a prompt becomes the right archetype, selected design system, runnable build-verified starter, and reviewed result.
- version
- 1.0.1
- GitHub stars
- 54
Install
/plugin install buildable@buildableRun it inside Claude Code after adding the marketplace with /plugin marketplace add suntay44/buildable-plugin-skills.
Contents
Discovered from sourceSkills 4
Buildable Mobile Builder Skill
Use this skill to generate or adapt local mobile prototypes.
Resolve all referenced paths from the Buildable plugin or repository root.
Reference Loading Contract
Mandatory order:
- Read
.buildable/phase-plan.toonfirst when present. It is a summary: retrieve omitted details (such as full design rules or expected files) from the authoritative.buildable/phase-plan.jsonas needed. Without a saved plan, readbuildable-app-spec.json. Reuse the plan for unchanged requirements rather than re-planning or reading all formats. - Load only
appSpec.references. - Load current project files only as needed for the requested change.
- Do not load web templates or unrelated mobile archetypes.
- Load starter source only for the selected template and only when generating or editing it.
Default Stack
- Expo
- React Native
- TypeScript
- NativeWind
- Expo Router when appropriate
- local/mock data
Workflow
- Read the saved plan/app spec from the planner handoff.
- Check
appSpec.planAudit.checksbefore editing; treat blocked/failed checks as gates, not suggestions. - If
questionsNeededis true, ask the user before generating. - Apply
appSpec.designSystemfor visual tone, density, palette intent, touch layout rules, component rules, accessibility, and anti-patterns. - Apply
appSpec.blocksas reusable micro-template guidance. Selected block docs are references to adapt to the current entity/design system, not generic code to paste blindly. - If
appSpec.auth.requestedis true, implement the local/mock auth shape first and keep any named provider behind the auth seam. - Load only the references listed in the app spec.
- If the template is
generic-app, use the selected archetype reference to shape screens and entities instead of loading unrelated mobile templates. - Generate touch-first screens and local state.
- Validate navigation, touch targets, and state coverage.
- Run
buildable reviewfrom the selected app workspace when the CLI is available.
Build Order
- Create typed entities and local sample data.
- Build the first mobile screen around the main daily workflow.
- Add navigation only when the screen graph requires it.
- Add empty, completed, validation, and confirmation states as appropriate.
- Review against the selected mobile quality rubric.
Guardrails
- Do not add accounts, push notifications, external APIs, or backend services unless requested.
- Keep the mobile app runnable locally.
Buildable Planner Skill
Produce a local-first app spec and phase plan from the user's prompt, explicit reference files, and relevant existing-project context. Resolve bundled paths from the Buildable plugin or repository root.
CLI Workflow
- Run
buildable plan "<prompt>" --compact. This retains the structured spec and phases while omitting the duplicate Markdown render; full.buildable/phase-plan.json,.md, and compact.toonfiles are still saved. Use--no-writeonly for terminal-only inspection. For MCP, usebuildable_planwith its compact default. - Pass explicit user files with
--file <path>,--reference <path>, or--screenshot <path>; inspectappSpec.referenceInputswithout pasting file contents into the prompt. For requested auth use--with-auth; record a named provider with--with-auth-provider <provider>. Keep auth local/mock behind a seam unless a provider is named. - Use the returned classification,
appSpec, andphasePlanas the planning result. Do not repeat classification or reopen registries/policies already applied by the CLI. Load only needed files fromappSpec.references; load selected starter source only when generating or editing it. Never scan whole knowledge/template directories or unselected templates. - Check
appSpec.planAuditgates and ask blockingappSpec.questionswhenquestionsNeededis true before design or generation. Otherwise ask at most one or twopromptRefinement.optionalQuestionsonly when the answer materially changes the plan; use defaults when the user wants to proceed. - Summarize the plan once using the output guidance below. Keep implementation within the user's request; a planning-only request does not start app code. The included design system is sufficient to proceed; run
buildable designonly when a deeper UI/UX brief is useful.
CLI-Unavailable Fallback
Only when the CLI is unavailable, build the spec manually:
- Match
core/archetype-registry.jsontags, then applycore/ask-vs-build-policy.mdandcore/activation-policy.md. Useknowledge/INDEX.mdandtemplates/INDEX.mdonly for discovery. - Load the selected archetype, matching data-model/screen-graph files when present, and the best target-specific template spec. Preserve runnable versus plan-only status.
- Select design guidance from
core/design-system-registry.jsonand compatible micro-blocks fromblocks/registry.json; include only selected references. - Follow
core/app-spec-schema.md: include realisticmockDataand state coverage, explicitreferenceInputs,promptRefinementassumptions/questions/defaults,planAuditgates, and requested auth/persistence seams. Keep data local/mock and state non-goals explicitly. - Include clarify, plan, mock-data, design, build, and review phases with blockers and completion criteria tied to the selected screens, features, and acceptance criteria.
Output And Handoff
Give a short decision summary: app direction, target/stack, screens and key behavior, non-goals, design/mock-data approach, blockers or important assumptions, and the next actionable phase. Link the saved plan instead of repeating the full app spec, audit checks, reference list, and phase plan in chat; expand those details when requested. On revisions, retain the accepted direction and constraints, update the saved plan, and summarize what changed.
For planning-only requests, end with one satisfaction checkpoint: revise in Buildable Planner if needed, or continue with Buildable Web Builder/Mobile Builder for the selected target. If the user already asked to build and there are no blockers, continue to that builder without another approval checkpoint.
The builder should read .buildable/phase-plan.toon first for compact context, then retrieve omitted details from .buildable/phase-plan.json as needed (for example, full design rules or expected files). TOON is a summary; JSON remains the source of truth. Reuse the saved plan rather than re-planning unchanged requirements, and load only selected appSpec.references, explicit user reference inputs, and necessary starter/project source.
Buildable Reviewer Skill
Use this skill to review generated prototypes against the app spec and quality rubric.
Resolve all referenced paths from the Buildable plugin or repository root.
buildable review is a static/local quality gate. Treat it as a strong first pass for structure, local-first guardrails, source coverage, responsive-layout risk, accessibility signals, and optional build checks; it does not replace manual QA, real device/simulator checks for mobile, or browser/screenshot review when visuals matter.
Reference Loading Contract
Mandatory order:
- Run
buildable reviewfrom the selected app workspace when available. Pass a path only when reviewing a different folder. - Load the app spec and selected rubric.
- Load only files related to reported issues.
- Do not load all templates.
- Do not load unrelated archetypes or starter source.
Workflow
- Run
buildable reviewwhen the CLI is available. Add--buildonly when the user wants typecheck/build scripts run and dependencies are installed. - Read the app spec and selected quality rubric.
- Run available build, typecheck, lint, or test commands (or rely on
review --build). - Inspect the generated UI when possible — start the app and run
buildable preview --url <url>from the app workspace to render it, screenshot it, and catch runtime/visual errors that build checks miss. - Check required interactions, state coverage, responsive behavior, and accessibility.
- Produce a focused fix list.
- Apply fixes when operating as the active coding agent.
Review Priorities
- build correctness
- primary workflow
- missing interactions
- empty/loading/error states
- mobile and desktop layout
- accessible form controls
- unnecessary backend or hosted features
Output Format
Lead with blocking issues, then polish issues, then checks run. If no issues remain, say so and note residual risks.
Buildable Web Builder Skill
Use this skill to generate or adapt local web prototypes.
Resolve all referenced paths from the Buildable plugin or repository root.
Reference Loading Contract
Mandatory order:
- Read
.buildable/phase-plan.toonfirst when present. It is a summary: retrieve omitted details (such as full design rules or expected files) from the authoritative.buildable/phase-plan.jsonas needed. Without a saved plan, readbuildable-app-spec.json. Reuse the plan for unchanged requirements rather than re-planning or reading all formats. - Load only
appSpec.references. - Load current project files only as needed for the requested change.
- Do not load all templates.
- Load starter source only for the selected template and only when generating or editing it.
Default Stack
- Next.js
- TypeScript
- Tailwind CSS
- shadcn-style component patterns
- local/mock data
Workflow
- Read the saved plan/app spec from the planner handoff.
- Check
appSpec.planAudit.checksbefore editing; treat blocked/failed checks as gates, not suggestions. - If
questionsNeededis true, ask the user before generating. - For fresh starts, prefer
buildable generate "<prompt>"when a runnable template exists. Add--out <dir>only when the user requested a specific folder. - Apply
appSpec.designSystemfor visual tone, density, palette intent, layout rules, component rules, accessibility, and anti-patterns. - Apply
appSpec.blocksas reusable micro-template guidance. Selected block docs are references to adapt to the current entity/design system, not generic code to paste blindly. - If
appSpec.auth.requestedis true, implement the local/mock auth shape first and keep any named provider behind the auth seam. - Load only the references listed in the app spec.
- If the template is
generic-app, use the selected archetype reference to shape screens and entities instead of loading unrelated templates. - Inspect the local project if generating inside an existing app.
- Generate or adapt a complete first-screen prototype.
- Keep data local unless the spec explicitly requires otherwise.
- Run build/typecheck/lint checks when available.
Build Order
- Create typed entities and sample data.
- Build the primary screen and state operations.
- Add empty, filtered, and edited states.
- Apply responsive layout rules.
- Review against the selected quality rubric.
Guardrails
- Do not add auth, accounts, billing, cloud previews, managed databases, telemetry, or deployment.
- Do not create marketing landing pages for app requests.
- Do not leave generic placeholder UI.
Commands 7
Create a Buildable design brief for: $ARGUMENTS
-
Run the design command:
if command -v buildable >/dev/null 2>&1; then buildable design "$ARGUMENTS" else node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" design "$ARGUMENTS" fiUse
--page "login"or similar when the user asks for a specific page/component. Add--dark(or say "dark mode" in the prompt) to make the dark palette the active theme. Add--writeonly when the user wants the brief saved into the current app workspace. -
If a
buildable-app-spec.jsonexists, treat it as the app context. Otherwise, letdesignclassify the prompt. -
Use the returned design brief as the UI/UX source of truth: design system profile, color tokens, typography, spacing, motion, component emphasis, anti-patterns, and references.
-
Treat
buildable designas UI/UX-only. Do not add backend code, databases, auth, payments, hosted infrastructure, telemetry, or deployment from this command. -
Load only the references listed in the brief. Do not load all templates or all design playbooks.
-
Apply the brief to the requested app, page, or component while preserving the existing stack and local-first guardrails.
-
End by asking whether the user is satisfied with the UI/UX direction and mockup-data plan. If yes, offer the brief's
nextSuggestedCommand(usuallybuildable generate "<prompt>") as the build phase. Do not generate unless the user asked for building too.
Generate a Buildable prototype for: $ARGUMENTS
-
Plan first, then generate. If
.buildable/phase-plan.jsonexists and the prompt matches, generation reuses that saved audit-first plan. For runnable templates this copies a polished starter; for planned templates add--plan-pack:if command -v buildable >/dev/null 2>&1; then buildable generate "$ARGUMENTS" else node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" generate "$ARGUMENTS" fi- If the CLI reports the prompt has architecture-changing choices, ask the user those questions, then rerun with
--forceonly if the prompt already answers them. - If the CLI reports the template is not runnable yet, rerun with
--plan-packto write an instruction pack. - Add
--name "App Name"to brand the generated app, or pass a name in the prompt ("...called FocusList"). - Add
--with-authwhen the user explicitly wants login/accounts but did not include it in the prompt. Use--with-auth-provider <provider>only when the user names a provider. - To add a feature to an existing app instead of scaffolding a new one, use
--augment(writes a plan that adapts to the current project without overwriting code).
- If the CLI reports the prompt has architecture-changing choices, ask the user those questions, then rerun with
-
Read
buildable-app-spec.jsonin the output directory and load onlyappSpec.references. Use.buildable/phase-plan.toonwhen present as the compact build contract for audit gates, references, screens, entities, features, and guardrails. -
Adapt the starter (or implement the plan pack) to the user's specific request. Keep data local/mock by default. Do not add auth, billing, databases, telemetry, or deployment unless explicitly requested.
-
When code exists, verify it builds, then run
/buildable:buildable-reviewon the output directory and fix blocking issues before handoff.
Initialize Buildable in the current workspace.
-
For an existing app, profile the repo without overwriting code:
if command -v buildable >/dev/null 2>&1; then buildable init --existing else node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" init --existing fiFor a fresh workspace, omit
--existing. -
Read the generated
.buildable/repo-profile.json(existing apps) to learn the detected framework, language, and styling so later generation matches the project's conventions. -
Tell the user the workspace is ready and suggest
/buildable:buildable-planas the next step.
Run Buildable planning for the request: $ARGUMENTS
-
Get the structured spec and phases without the duplicate Markdown render:
if command -v buildable >/dev/null 2>&1; then buildable plan "$ARGUMENTS" --compact else node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" plan "$ARGUMENTS" --compact fiPass explicit user files as
--file <path>or--screenshot <path>instead of pasting contents into the prompt. For requested auth/login/accounts, use--with-auth; for a named provider, use--with-auth-provider <provider>and keep it behind the auth seam. -
Use the CLI result rather than repeating classification. Follow
appSpec.referenceLoadingContract: load only neededappSpec.referencesand explicitappSpec.referenceInputs, and selected starter source only when generating or editing it. Do not scan whole knowledge/template directories. -
Ask blocking
appSpec.questionsbefore design or generation whenquestionsNeededis true. Otherwise ask at most one or twopromptRefinement.optionalQuestionsonly if they materially improve the plan; use defaults when the user wants to proceed. -
Summarize direction, target/stack, screens/key behavior, non-goals, design/mock-data approach, important assumptions or blockers, and the next phase. Link the saved
.buildable/phase-plan.mdinstead of repeating the full spec and references. The plan already includes design guidance; a deeperbuildable designpass is optional. -
For planning-only requests, ask one satisfaction checkpoint: revise the saved plan in Buildable Planner or continue with Buildable Web Builder/Mobile Builder for the target. On revisions, retain accepted constraints and summarize changes. If the user already asked to build and no blockers remain, continue without another checkpoint. The builder should read
.buildable/phase-plan.toonfirst and retrieve omitted details from the JSON source of truth as needed; reuse the saved plan for unchanged requirements.
Visually verify the prototype at: ${ARGUMENTS:-.}
-
Start the app's dev server if it isn't already running (e.g.
npm run dev), and note the local URL (defaulthttp://localhost:3000). -
Render and capture it:
if command -v buildable >/dev/null 2>&1; then buildable preview "${ARGUMENTS:-.}" --url http://localhost:3000 else node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" preview "${ARGUMENTS:-.}" --url http://localhost:3000 fi- This needs Playwright. If preview reports it is skipped, install it once:
npm i -D playwright && npx playwright install chromium. If you have your own preview/screenshot tool, use that instead.
- This needs Playwright. If preview reports it is skipped, install it once:
-
Open the screenshot at
.buildable/preview.pngand read.buildable/preview-report.md. Confirm the first screen looks intentional: visible primary actions, real sample data, non-generic empty states, no overlap, no blank render. -
Fix anything the screenshot or runtime errors reveal (things
tsc/buildcannot catch), then re-run preview until it passes.
Review the selected workspace by default. If a path is provided, review: ${ARGUMENTS}
-
Run the Buildable reviewer:
if command -v buildable >/dev/null 2>&1; then buildable review "${ARGUMENTS:-.}" else node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" review "${ARGUMENTS:-.}" fiAdd
--buildonly when the user wants the reviewer to also run the project's typecheck/build scripts and dependencies are installed. Add--strictto fail (not just warn) on local-first guardrail drift (unrequested billing, managed databases, telemetry, etc.). -
Read the generated
.buildable/review-report.md. Load only the files named by reported issues. -
Fix blocking issues first (missing entities, missing features, non-local-first drift, build failures), then polish issues. Keep changes local-first.
-
Report what you fixed and any residual risks. If the review now passes, say so plainly.
-
Relay the advisory Readiness section as the honest "what's left to ship" summary (mocked vs persisted data, mock vs named-provider auth, no deploy). It is guidance, not a failure — do not auto-add a backend, auth provider, or deploy config unless the user asks; point them at the persistence/auth seams instead.
Inspect the selected workspace by default. If a path is provided, inspect: ${ARGUMENTS}
-
Run the Buildable status inspector:
if command -v buildable >/dev/null 2>&1; then buildable status "${ARGUMENTS:-.}" else node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" status "${ARGUMENTS:-.}" fi -
Treat the output as the current workflow handoff:
- If no plan exists, suggest
/buildable:buildable-plan. - If scope is blocked, ask the listed questions before design/generate.
- If a plan exists, use
/buildable:buildable-design. - If design is ready and no app is generated, use
/buildable:buildable-generate. - If generated files exist, use
/buildable:buildable-review.
- If no plan exists, suggest
-
Do not load unrelated templates or references.
statusis read-only; it tells you where the workspace is, not what to build.
MCP servers 1
Sponsors
Details
- Marketplace
- suntay44/buildable-plugin-skills
- Category
- Community
- License
- MIT
- Keywords
- app-builder, local-first, prototype, nextjs, expo