Vibecoder Skill

A kickoff ritual for Claude Code. Discovery, stack selection, living docs, and a tailored CLAUDE.md, all before the first line of product code.

Quick start

npx vibecoder-skill

That's it. The skill installs into ~/.claude/skills/ and activates the next time you start a new project in Claude Code. See Install for project-scoped and manual options.

Why

Starting a project in an agent usually means improvising: code first, structure later, decisions undocumented, and the occasional "wait, I didn't ask for that." Vibecoder Skill turns the kickoff into a deliberate sequence. It activates when you start something new, agrees on the plan with you, lays down documentation that grows with the code, and writes the working rules into the project itself.

What it does

The skill runs five phases:

| Phase | What happens | |-------|--------------| | 1. Discovery | Claude asks about the idea, problem, product type, features, and constraints, then proposes a stack and the external services/APIs the product needs (flagging which are paid and where keys come from). | | 2. Obsidian decision | You choose how ./docs is maintained: an Obsidian wiki (cross-linked notes, knowledge graph, note-per-module) or plain markdown. The choice shapes every document. | | 3. Scaffold ./docs | Claude creates a living doc set adapted to the product type: project idea, stack, roadmap, todo, decision log, and when relevant UI/UX flow, marketing flow, architecture, data model, API. | | 4. CLAUDE.md | Claude generates a project-root CLAUDE.md with code conventions, stop points, prohibitions, and authorship rules tailored to the product. | | 5. During development | Baseline rules stay active: decisions go to you, commits happen only with confirmation, nothing risky happens silently, docs stay alive. |

Rules baked in

• You make the decisions. At every fork, Claude states the options, recommends one, and waits for your choice.
• Ask, don't guess. If Claude is blocked by something unknown or restricted, it asks instead of working around it.
• Commits on confirmation. No automatic commits or pushes; Claude proposes them after each major action and waits.
• Your authorship. No "Generated with Claude" or "Co-Authored-By" traces in commits, code, or docs.
• Don't surprise the user. If an action would make you say "wait, I didn't ask for that," Claude asks first.

Install

Via npm (recommended)

Install for your user account (available in every project):

npx vibecoder-skill

Install into the current project only:

npx vibecoder-skill --project

This copies the skill into ~/.claude/skills/vibecoder-skill/ (or ./.claude/skills/vibecoder-skill/ with --project). Start a new Claude Code session and it is detected automatically.

Via the .skill file

Download vibecoder-skill.skill from the releases and drag it into Claude Code, or unzip it into your skills directory.

Manually

git clone https://github.com/remdee13/vibecoder-skill.git
cp -r vibecoder-skill/SKILL.md vibecoder-skill/references ~/.claude/skills/vibecoder-skill/

How to trigger it

Just start something new. Prompts like "let's build a new app", "I want to spin up a Telegram bot", or "scaffold a new service" activate the skill, and it takes the kickoff from there.

Structure

vibecoder-skill/
├── SKILL.md                    # The five-phase protocol and baseline rules
├── references/
│   ├── docs-templates.md       # Templates for every ./docs document
│   ├── claude-md.md            # Base for the generated CLAUDE.md
│   └── obsidian.md             # Obsidian wiki mode conventions
├── bin/
│   └── cli.js                  # npx installer
├── package.json
├── README.md
└── LICENSE

Contributing

Issues and pull requests are welcome. If you adapt the skill for a specific stack or workflow, a PR describing the change is appreciated.

License

MIT