Why I Built a 26-Skill Framework Instead of Writing Better Prompts

Every developer using Claude Code starts the same way. They write a prompt, get something back, write a better prompt, get something better back, and gradually accumulate a personal library of phrases that work. "Act as a senior engineer." "Read the codebase before suggesting anything." "Don't change files I didn't ask you to change." The prompts get more sophisticated. The outputs get more reliable. And then you hit the ceiling.

The ceiling is not a model problem. The model keeps getting better. The ceiling is a session problem. Every time you open a new Claude Code session, you start from zero. The model does not know what project you are working on, what phase you are in, what decisions have been made, what the client signed off on last week, or what the naming conventions are. You spend the first 10 minutes of every session re-establishing context that you already established in the last session. And the session after that. And the one after that.

Better prompts do not solve this. A prompt is instructions for one session. A skill is a system that works across all sessions — because it reads your actual project files before doing anything, grounds every output in what already exists, and writes structured artefacts that the next session can pick up without you having to explain anything.

That distinction — session instructions versus a session-persistent system — is the reason vibe-* exists.

A vibe-* skill is a markdown instruction set that lives in ~/.claude/skills/ and is loaded automatically by Claude Code when the matching trigger fires. Skills are not scripts. They do not run external processes. They do not require servers or npm packages. They run entirely inside Claude Code's context window, which means they work on any project in any language on any machine where Claude Code is installed.

Every skill in the framework does four things before it does anything else: it reads your actual project files (SPEC.md, TASKS.md, DECISIONS.md, ARCHITECTURE.md, git history), it establishes what already exists before proposing what should change, it defines what a complete output looks like rather than stopping at a partial answer, and it writes structured artefacts that the next skill in the sequence can consume without re-establishing context.

The trigger model is natural language. You type feature: add CSV export for invoices and Claude Code fires the vibe-add-feature skill. It reads your codebase, produces a FEATURE_SPEC.md with acceptance criteria and out-of-scope items, a FEATURE_PLAN.md with the implementation approach, and a FEATURE_TASKS.md with a sized task breakdown. You say go and it builds. No re-explaining what the project is. No re-establishing naming conventions. No context overhead.

What makes a skill different from a prompt

• Grounded in real files: Every skill reads your actual TASKS.md, SPEC.md, DECISIONS.md, git history before doing anything. Nothing is invented. If a section has no data source, the skill says so rather than fabricating content.
• Complete output, not partial: A skill produces everything needed for its phase — spec, plan, task list — in one trigger. You do not need to ask follow-up questions to get the full picture.
• Phase-gated by design: Skills enforce quality gates. Phase N cannot proceed to Phase N+1 until review: passes with zero P0 issues. The gate is structural, not advisory.
• Two audiences, always: Client documents (DELIVERY.md, CHANGELOG_CLIENT.md) are plain English with no task IDs, no framework names, no file paths. Developer documents are precise and technical. The skill knows which is which.

The framework covers the complete software development lifecycle in six phases. Each skill has one job and does it completely.

The framework is designed so that the output of each skill feeds naturally into the next. BRIEF.md from brainstorm feeds architect. ARCHITECTURE.md from architect feeds new-app. FEATURE_SPEC.md from add-feature feeds review. CHANGELOG from changelog feeds handoff. The sequence is not rigid — you can enter at any point using vibe-init — but the lifecycle is complete.

The vibe-review skill is the gate that makes this more than a workflow. Phase N cannot proceed to Phase N+1 until review passes with zero P0 issues. The final phase review must clear all P0 and P1 findings before deploy. This is enforced structurally, not by convention. It is the difference between a framework that produces shippable code and one that produces generated code.

Six principles shaped every skill in the framework. They are worth stating explicitly because they explain decisions that would otherwise look arbitrary.

• Skills are instruction sets, not scripts: They run inside Claude Code's context window. No external processes, no servers, no npm packages required for the framework itself. Install once, work everywhere.
• Everything is grounded: Every skill reads actual project files before doing anything. SPEC.md, TASKS.md, DECISIONS.md, git history. Nothing is invented. If a section has no data source, the skill says so.
• Docs are first-class: The framework produces documents that serve real audiences — developers, clients, PMs. CHANGELOG_CLIENT.md is readable by a business owner. DELIVERY.md can be sent directly to a client. ONBOARDING.md gets a new developer running in 30 minutes.
• Cost is visible: Every session is tracked. Every task has a cost. The ledger shows where money went. Waste patterns are flagged before they compound. The summary.json bridges raw cost data and human-readable reports.
• The gate is real: vibe-review is not optional. Phase gates are enforced. P0 issues block progress. This is what makes the output shippable rather than just generated.
• Two audiences, always: Client documents are plain English — no task IDs, no framework names, no file paths. Developer documents are precise and technical. The framework never conflates the two.

vibe-* is open source and free to use. Install via git clone — no npm, no pip, no package manager required.

git clone https://github.com/aakashdhar/vibe-skill.git /tmp/vibe-skill && mv /tmp/vibe-skill/vibe-* ~/.claude/skills/ && rm -rf /tmp/vibe-skill

Restart Claude Code. All 26 skills are active immediately. Skills trigger from natural language — no slash commands, no configuration required. Type brainstorm: I want to build a SaaS tool for freelancers and you are in the framework.

For existing projects, vibe-init reads your actual source files, infers the architecture, and generates the full vibe/ folder. You do not need to start a new project to get value from the framework. You can onboard any codebase you are already working on.

The full README — with examples for every skill, the complete cheat sheet, the file structure reference, and the deploy platform guide — is at github.com/aakashdhar/vibe-skill.

Built and maintained by me at BetaCraft, where it runs on every live client project. Issues, suggestions, and skill contributions are welcome — skills are just markdown files with a consistent structure. Open a PR with your skill in its own folder following the existing naming convention.