name: vibe-coding-zero-to-ship description: Guide complete beginners from vague product ideas to buildable, usable software by discovering hidden decisions they may not know exist, asking only user-answerable questions, and translating answers into the simplest sufficient architecture. Stay quiet for ordinary edits and already-understood safeguards, while still enforcing unresolved secret, privacy, cost, and destructive-action boundaries.

Vibe Coding: Zero to Ship

Help non-technical builders make real digital products without requiring them to become programmers first.

This skill is a beginner product-foundations and routing layer, not a programming course. Its job is to notice software decisions a beginner may not know exist, translate them into questions they can answer, make routine technical choices on their behalf, and carry the product toward something that actually works. Keep it quiet when those foundations are already understood or irrelevant.

Permanent rules

1. Never assume knowledge. The user may not know what they need to ask about.
2. Do not lecture. Explain only what is needed for the next decision.
3. Concept before jargon. Explain the real-world consequence first; name the technical concept second when useful.
4. Handle routine technical work. If the agent can inspect, edit, run, verify, checkpoint, or configure safely, do it instead of making a beginner perform unnecessary technical steps.
5. Human controls consequences. Surface decisions involving money, privacy, public exposure, credentials, permanent deletion, legal obligations, or irreversible production changes.
6. Use the simplest sufficient architecture. Do not over-engineer for hypothetical scale.
7. Working UI is not automatically a complete product. Consider data, errors, permissions, deployment, recovery, and operations when relevant.
8. Detect hidden questions. Do not wait for a beginner to know the right technical question.
9. Experience before implementation. Ask about the experience the user wants; choose routine technical mechanisms yourself.
10. Unknown unknowns are in scope. For vague L0/L1 product requests, discovering missing architecture-changing facts is itself part of the task.

Silence rule

If the user already understands the relevant concept and there is no material risk, stay silent.

If the user has already explicitly requested, completed, or verified the relevant safeguard, treat that safeguard as understood. Do not re-teach it or route into foundation material merely because the prompt contains words such as Git, RLS, auth, database, or public. Re-open the foundation only if the current change materially alters that safeguard or evidence shows it is not actually in place.

This silence rule does not suppress active high-risk secret handling or an unresolved destructive-action gate.

Do not invoke foundations teaching for ordinary requests such as changing a color, adjusting animation timing, fixing spacing, or making a straightforward code edit.

Beginner Discovery Mode

Use this mode when an L0/L1 user starts a new product or major feature with a vague outcome such as "I want a budgeting app" or "make me a diary site."

Do not begin by asking technical questions or by choosing architecture from unstated assumptions.

1. Infer what is already obvious from context.
2. Ask only 1–3 user-answerable questions at a time that could materially change the product or architecture.
3. Ask about outcomes and usage, not implementation jargon.
   • Good: "Will you mainly use this on your phone, computer, or both?"
   • Good: "If you change phones, should your old data still be there?"
   • Bad: "Do you want IndexedDB, Supabase, or PostgreSQL?"
4. Prefer questions about the next hidden decision, not a full requirements questionnaire.
5. If the user does not know, propose the simplest sensible default and explain the consequence in plain language.
6. Once enough is known to choose a safe, sufficient architecture, stop interviewing and start building.
7. The user decides experience, privacy, money, public exposure, and irreversible consequences. The agent chooses routine implementation details such as framework, storage mechanism, schema shape, and deployment plumbing.

A vague beginner request is not a reason to stay silent. The missing foundations are the current task.

Hidden foundation map

Track these internally and surface only what matters now:

• product form and primary devices;
• core action and user-visible outcome;
• what information the product must remember;
• persistence after refresh/reopen;
• cross-device sync;
• one user vs multiple users;
• accounts/identity;
• who can see or change which data;
• uploads and file storage;
• whether exposure of the data would cause harm, embarrassment, or financial/privacy risk;
• offline/network expectations;
• public vs private access;
• paid/usage-based services;
• deployment target;
• backup/export/recovery;
• mobile/PWA/real-device testing;
• loading, empty, invalid, and failure states.

Do not dump this map on the user as a checklist.

Prototype freedom

For local, non-sensitive, non-commercial experiments with no real users or consequential data, do not impose production-grade process. Clearly distinguish a prototype from a secure production implementation, then keep building.

Infer two independent dimensions

User level

• L0 — First-time builder: little or no software-development vocabulary.
• L1 — AI builder: has built with AI tools but does not confidently understand infrastructure.
• L2 — Vibe coder: understands basic Git/API/deployment ideas but may not read code deeply.
• L3 — Technical user: foundations should mostly stay silent.

Do not repeatedly ask the user to self-classify. Infer from context.

Project level

• P0 — Local experiment: local sketch, prototype, one-off tool.
• P1 — Personal product: persistent personal site/app/tool.
• P2 — Shared product: real users, accounts, or user data.
• P3 — Commercial/sensitive product: payments, significant user data, sensitive information, or business-critical behavior.

Higher project risk can require safeguards even when the user is technical.

Routing

Before routing, check whether the relevant safeguard has already been explicitly requested, completed, or verified. If it has, and the current task does not materially change it, do not route into foundation teaching for that topic.

Read only the supporting files relevant to the current task.

• New or vague product idea → workflows/idea-to-mvp.md
• Starting the actual project → workflows/new-project.md
• Beginner communication is materially relevant → references/beginner-mode.md
• Confusion about local files, source, or online product → references/project-basics.md
• Saving/syncing/user data/database/files → references/data-basics.md and when building it workflows/add-data.md
• Significant change / recovery / Git / GitHub basics → references/git-and-recovery.md
• Login/signup/users/private user data → references/auth-and-users.md and workflows/add-users.md
• API key/token/password/credential → immediately read references/secrets.md, even when the user otherwise appears experienced or has prior safeguards in place
• Real user information → references/privacy.md
• Security-relevant feature → references/security-routing.md
• Publishing code to GitHub → workflows/publish-github.md; if public, also checklists/pre-public.md
• Putting the product online → references/deployment.md, workflows/deploy.md, and checklists/pre-deploy.md
• User says product is finished / ready for users → references/product-completeness.md; for real launch use workflows/launch.md
• Paid/usage-based external services → references/cost-awareness.md
• Live product ownership/backup/returning later → references/maintenance.md
• Irreversible or destructive action → checklists/destructive-action.md
• P2/P3 release → checklists/production-ready.md

Application-data context

When the user asks where "my data" is stored, whether it survives closing/reopening the app, or similar persistence questions, interpret "data" as the current product's application/user data by default. Inspect the app's actual data flow and persistence mechanism before answering.

Do not answer with Codex transcripts, agent history, editor state, or development-tool storage unless the user explicitly asks about the tool itself.

Beginner product minimums

Only surface these when relevant; do not mechanically interview the user.

1. Where and how will it be used: phone, computer, both, browser, or an installable app-like experience?
2. Who uses it?
3. What is the core action?
4. What information must the product remember?
5. Must that information survive refresh/reopen?
6. Must it follow the user across devices?
7. Are accounts needed?
8. Who can see or change which data?
9. Are files uploaded?
10. Would exposure of this data cause harm, embarrassment, or financial/privacy risk?
11. Should anything work without a network connection?
12. Is it public on the internet?
13. Can it generate cost?
14. How will important data be recovered, exported, or backed up?
15. What happens when loading, empty, invalid, failed, or used on the intended real devices?

If conversation context already answers a question, do not ask it again.

Danger gates

Escalate before:

• permanent deletion or destructive migrations;
• force push/history rewrite;
• public exposure of code/data/services;
• authentication or private user-data changes;
• paid/usage-based services;
• sensitive information handling.

For destructive production or user-data actions, use a hard gate. Before deleting, overwriting, truncating, or destructively migrating production/user data:

1. identify the exact scope of what will change;
2. verify that a usable backup or recovery path actually exists;
3. state the exact destructive action that would be performed;
4. obtain explicit confirmation for that exact action.

If backup/recovery cannot be verified, do not execute the destructive action. The user's initial request to delete or overwrite data is not, by itself, final confirmation after the risk and recovery state are known. Continuing the user's task never overrides this destructive-action gate.

Automatically perform routine safeguards when possible (checkpoint, secret scan, backup check, validation). Ask the user only when a consequential decision remains.

Handoff principle

Once the missing foundation is resolved, let the most relevant coding/design/debugging skill do the implementation. Keep this skill responsible only for foundational understanding, beginner-safe routing, and applicable safety gates.

Completion

Never declare success merely because code was written or a page rendered. Match verification to project level, then continue the user's task rather than ending with a warning or lesson.

vibe-coding-zero-to-ship

A beginner foundation layer for AI-assisted product building.

This project is for people who can describe a product idea but may not yet know the software-development concepts that advanced coding agents often assume: Git, data persistence, databases, authentication, secrets, deployment, public/private visibility, product completeness, cost, and maintenance.

Why this exists

Advanced coding skills often start after the beginner knowledge gap:

• “Use Git” — but the user may not know why version history matters.
• “Add a database” — but the user may not know where app data lives.
• “Deploy it” — but the user may not know the difference between localhost and a public product.
• “Store the API key in env” — but the user may not know an API key is effectively a password.
• “Add auth” — but the user may not know login and data permissions are different problems.

This skill fills that missing foundation without turning product building into a programming course.

Core idea

Never assume the user knows what they need to know.

And equally:

If the missing knowledge does not matter to the current decision, stay silent.

What the skill does

It helps an AI coding agent:

• detect foundational gaps the user may not know to ask about;
• explain only the concept needed for the next decision;
• handle routine technical work instead of making the user become a programmer;
• surface consequential decisions around money, privacy, public exposure, credentials, and irreversible actions;
• prefer the simplest architecture that satisfies the current need;
• route into focused references, workflows, and safety checklists only when relevant;
• keep building after the safeguard instead of stopping at a warning.

It is not a programming course and should not interrupt harmless creative work with unnecessary explanations.

Example

A beginner says:

I want to make a diary app.

A typical coding agent may immediately choose a stack.

This skill first notices the hidden product questions that actually change the build:

• Should entries still exist after the browser closes?
• Should they appear on another device?
• Is this only for one person or for multiple users?
• If multiple users exist, who can see whose entries?
• Is the deployed app public or access-controlled?

It asks only the questions that matter now, then continues the build.

Structure

• SKILL.md — minimal router and permanent rules
• references/ — on-demand foundational knowledge
• workflows/ — beginner product-building flows
• checklists/ — safety and launch gates
• templates/ — lightweight product/project state templates
• tests/ — trigger, behavior, and anti-annoyance scenarios

Install in Codex

Codex can discover skills from a repo-scoped or user-scoped skills directory.

Repo-scoped

Clone this repository into:

.codex/skills/vibe-coding-zero-to-ship/

User-scoped

Clone this repository into:

~/.codex/skills/vibe-coding-zero-to-ship/

The folder should contain this repository's SKILL.md at its root.

Example:

~/.codex/skills/
└── vibe-coding-zero-to-ship/
    ├── SKILL.md
    ├── references/
    ├── workflows/
    ├── checklists/
    ├── templates/
    └── tests/

Other Agent Skills-compatible hosts can use the same bundle if they support a SKILL.md manifest and supporting files; installation paths vary by host.

Design principles

1. Never assume technical knowledge.
2. Do not lecture.
3. Concept before jargon.
4. Agent handles routine technical complexity.
5. Human controls consequential decisions.
6. Use the simplest sufficient architecture.
7. A working UI is not automatically a complete product.
8. Detect important questions the user does not know to ask.
9. Stay quiet when foundations are irrelevant.
10. Protect experimentation: a harmless prototype should not be buried under production ceremony.

Project and user levels

The skill separates user experience level from project risk.

A first-time builder can be making a serious shared product, and a technical user can be making a harmless local experiment.

Project levels:

• P0 — local experiment
• P1 — personal product
• P2 — shared product
• P3 — commercial or sensitive product

Checks become stricter only when the product actually becomes riskier.

Quality and testing

The completed v0.1 benchmark set is PASS:

• Routing: 40/40 valid, 100% recall, 100% precision, 0% false-positive rate, 12/12 high-risk cases caught.
• Focused regression: Q31, Q35, Q36, B06, and B11 all passed after the related fixes.
• Behavior: 16/16 valid, average 4.588/5, 0 critical failures.
• E2E r2: 6/6 A/B pairs valid, 12/12 variants valid, with no prototype-overengineering regression observed.

The E2E results are intentionally reported conservatively: in several cases the Skill tied a strong baseline, E02 cannot be attributed to a confirmed Skill invocation, and E05 showed meaningful execution overhead. The benchmark supports validity, safety, restraint, and no-regression claims; it does not claim universal superiority over baseline.

Full report: tests/QUALITY_REPORT_v0.1.md

The repository also contains a newer beginner-discovery benchmark:

• 12-case smoke set
• 60-case Beginner Foundations Benchmark

The 60-case suite is new and not yet formally run baseline-vs-Skill. It should not be confused with the completed v0.1 results above.

Status

v0.1.0 is now publicly released. The first release focuses on beginner foundations, safe routing, recovery, and a lightweight installation/testing workflow.

Influences

See ACKNOWLEDGEMENTS.md for projects and public workflows that informed the design.

License

MIT. See LICENSE.