foryourhealth111-pixel/vibe-skills

Start with vibe. The runtime handles scoping, task breakdown, skill coordination, and verification so the agent can finish multi-step work with less manual steering.

 

 

 

 

 

🧠 Planning · 🛠️ Engineering · 🤖 AI · 🔬 Research · 🎨 Creation

 

Install  →  vibe | update  →  Structured Workflow  →  Local Skill Binding  →  TDD / Verification  →  Persistent Context

📋 Table of Contents

• Runtime at a Glance
• Practice Demos
• One runtime entry, small public surface
• What makes it different
• Who is it for
• Work Organization
• Memory System
• Representative Work Areas
• Installation & Management
• Getting Started

[!IMPORTANT]

🎯 Core Vision

VibeSkills is built for agents that need more than a tool list.

The runtime clarifies the request, plans the work, binds local Skills where they fit, records the actual binding in work_binding, and keeps the proof needed for review or continuation.

In the current release, the public entry stays narrow: vibe is the public entry, additional Skills are discovered only from declared local skill roots, duplicate skill ids follow host root priority, and work_binding is the runtime record of what was actually bound.

---

🛰️ Runtime at a Glance

Start with vibe. The runtime freezes the request, builds bounded work, scans the local skill roots declared by the host, binds relevant Skills when needed, verifies the result, and saves context for the next session. That matters most when the task is composite and needs more than one local Skill to finish well.

flowchart LR
    accTitle: VibeSkills Harness Flow
    accDescr: User intent enters the vibe harness. The harness freezes intent, builds a work model, binds helpful Skills late, verifies evidence, and preserves workspace context.

    user["User Intent"]
    vibe["vibeRuntime Entry"]
    freeze["FreezeRequirement"]
    plan["BuildWork Model"]
    route["Bind SkillsLate"]
    skills["Declared local Skills onlyreal SKILL.md required"]
    future["Local skill folders can growwhile the public entry stays the same"]
    verify["VerifyTests + Evidence"]
    memory["RememberWorkspace Context"]

    user --> vibe --> freeze --> plan --> route --> verify --> memory
    route --> skills --> verify
    route --> future --> verify

    classDef core fill:#ede9fe,stroke:#7B61FF,stroke-width:2px,color:#1f1147
    classDef stage fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0c4a6e
    classDef proof fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
    classDef user fill:#fff7ed,stroke:#f97316,stroke-width:1.5px,color:#7c2d12

    class vibe core
    class freeze,plan,route,skills,future stage
    class verify,memory proof
    class user user

The normal closeout path should stay small: prove the governed runtime, entry truth, execution proof, release consistency, and repo cleanliness before reaching for wider audit gates.

---

🎬 Practice Demos: Real Work You Can See

People asked what VibeSkills looks like in real work. These examples are easier to judge than a feature list: each one starts with a plain goal, goes through a governed vibe run, and ends with something you can open, inspect, or rerun.

Keep the public proof story narrow and explicit:

• installed locally: run py -3 -m vgo_cli.main check --repo-root --skills-dir .
• runtime coherent: after a real vibe run returns a session_root, inspect host-launch-receipt.json, runtime-input-packet.json, governance-capsule.json, stage-lineage.json, and runtime-summary.json.
• delivery accepted: inspect delivery-acceptance-report.json or delivery-acceptance-report.md.

Release proof bundles stay as explicitly named local operator artifacts. check proves only installed locally; it does not prove task completion, runtime coherent, or delivery accepted.

A useful demo should show both the result and the path that produced it:

flowchart LR
    accTitle: VibeSkills Practice Demo Flow
    accDescr: A user goal moves through scope confirmation, planning, skill handoff, execution checks, and an openable result.

    goal["Plain Request"]
    freeze["Confirmed Scope"]
    plan["Work Plan"]
    route["Skill Handoff"]
    work["Build / Analyze / Render"]
    proof["Checks + Evidence"]
    show["Openable Result"]

    goal --> freeze --> plan --> route --> work --> proof --> show

    classDef goal fill:#fff7ed,stroke:#f97316,stroke-width:1.5px,color:#7c2d12
    classDef flow fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0c4a6e
    classDef proof fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d

    class goal goal
    class freeze,plan,route,work flow
    class proof,show proof

Inspired by the VibeSkills 3.1.0 community practice cases: a GPT-image workbench, a video-editing run, and an ML experiment that produced a paper. The best examples link to concrete outputs: a running app, a rendered clip, a compiled paper, or the commands and evidence used to produce them.

---

🧬 One runtime entry, small public surface

Projects like Superpowers show the value of stronger development habits: clarify before coding, design before implementation, and test before claiming success. GSD / Get Shit Done shows the value of specs, milestones, context, and steady project flow.

VibeSkills applies the same discipline at the runtime entry. The public entry is vibe. During a run, it can bind relevant local Skills from declared roots when those entries have readable SKILL.md files and match the current bounded work. The distinguishing part is the organization step: on composite tasks, the runtime can decompose the request and let different local Skills cover different bounded units inside the same run.

---

✨ What makes it different?

VibeSkills focuses on the execution path after a user gives a request. The runtime clarifies the task, plans it, binds local Skills where needed, and asks for evidence before it claims delivery.

Its main advantage is local-skill coordination. When a task is composite, the runtime does not have to funnel the whole job through one Skill. It can split the request into bounded units, then bind the right local Skill to each unit.

The operating model is intentionally simple:

---

👥 Who is it for?

VibeSkills is for people who want AI agents to be easy to start, useful across many kinds of work, and less exhausting to manage.

---

🔀 Work Organization: How Skills Become Bounded Work

vibe owns the workflow. It decides when the agent should clarify, when it should plan, how a composite task should be split, which local Skills can help with each work unit, when tests or checks should run, and when delivery can be claimed.

The discovery rules stay narrow:

• additional Skills are discovered only from declared local skill roots
• a skill without a readable SKILL.md can be diagnostic only, never selected or locked
• work_binding is still the first runtime truth for what was bound

How the runtime works in practice

• Start with one governed entry: Most work enters through vibe, so the user does not have to choose a workflow tree manually.
• Freeze intent before execution: Requirements and plans become stable artifacts.
• Split composite tasks before binding Skills: The runtime turns one large request into bounded units that can be owned and checked separately.
• Bind Skills only where needed: Requirement work, planning, implementation, testing, review, and cleanup can each use different Skills when they fit the bounded unit.
• Drive toward evidence: TDD, targeted checks, artifact review, and delivery acceptance keep completion claims grounded.
• Preserve context: The runtime stores enough structure for another session or agent to continue.
• Record the actual binding: work_binding records which skill was actually chosen for each bounded unit.

---

Why many local Skills can still coexist

• Different Skills serve different stages: clarifying, planning, implementation, review, and verification.
• Different Skills also serve different domains: code, research, data, writing, design, documents, and operations.
• A single delivery can mix several local Skills, as long as each one has a clear bounded unit.
• The runtime keeps workflow control, so each Skill stays scoped to the work it was selected for.

---

M / L / XL Work Sizes

After the runtime has a bounded work model, it still chooses how large the run should be:

Even in XL, the runtime still bounds the work first, then attaches Skills to each bounded unit under the same coordinator.

---

---

🧠 Memory System: Resume Context Across the Same Workspace

Work state decides what still needs doing. Memory keeps the next session from starting cold.

VibeSkills stores just enough governed context to make work easier to continue:

• Resume the same project: confirmed background, conventions, and decisions can be picked up again inside the same workspace.
• Continue long tasks: progress, handoff notes, and evidence anchors stay available after interruptions.
• Reduce repeated explanation: the agent can recover useful context without asking you to restate the same setup every session.
• Stay scoped: recall is bounded to the current workspace and task, so unrelated history does not flood the prompt.

Memory helps the next session continue. Git, README files, requirement docs, execution plans, and verification receipts remain the source of record. Memory writes stay governed, and missing memory support is surfaced as a real issue.

See workspace memory plane design for the technical contract and non-regression proof bundle for the release/operator closeout proof contract.

---

✦ Representative Work Areas

Use this table to judge whether VibeSkills fits your task. It groups the kinds of work that the vibe entry can organize.

The capability column gives examples of the kind of local Skills the runtime can use. The actual available Skills still depend on the local skill roots declared on your host.

---

📊 What the runtime core does

The runtime core behind VibeSkills is VCO. It keeps workflow control in a small runtime, leaves domain-specific work to local Skills, and keeps extension boundaries explicit.

---

⚙️ Installation & Skills Management

Public installation starts from a published release zip. Download the release zip, extract it, and run the wrappers from that extracted directory.

The public release asset is a host-neutral, SkillsDir-centered bundle such as vibe-skills-3.2.0-public.zip. The installer writes Vibe-owned files under /vibe. The public release installs the vibe runtime itself. It does not add a separate built-in skill catalog. After install, the public entry is vibe, and additional Skills are discovered separately from that shared skills directory and any configured local skill roots.

The default target is ~/.agents/skills, so the shortest Windows install from a published release zip is:

.\install.ps1
.\check.ps1

To install into a specific skills directory, pass it directly from the extracted release copy:

.\install.ps1 -SkillsDir C:\Users\you\.agents\skills
.\check.ps1 -SkillsDir C:\Users\you\.agents\skills

Update and uninstall use the same boundary. For updates, download the newer published release zip first, extract it, and then run update from that newer release copy against the same SkillsDir:

.\update.ps1 -SkillsDir C:\Users\you\.agents\skills
.\uninstall.ps1 -SkillsDir C:\Users\you\.agents\skills

The installer writes only Vibe-owned files under /vibe. It does not edit Codex, Claude, Agents, host settings, command wrappers, or global prompt files. Re-running install or update preserves user-added files and refuses unowned path conflicts instead of deleting the directory.

After install, Vibe treats `` as the shared skills directory. If a host or your own workflow needs a different skills directory, pass that path explicitly. The runtime contract still stays SkillsDir-centered.

Extra scan roots are runtime configuration, not installation. Put them in ~/.vibeskills/skill-roots.json for user-wide roots or /.vibeskills/skill-roots.json for project roots.

Repo checkout install is now a developer/internal path. Public installation should start from a published release zip. Old host/profile install docs remain as legacy migration material for existing installs.

Open More Docs Only When Needed

• Need legacy host/profile details for an existing old install? Start with the simple install guide; it points to archived legacy material when needed.
• Need offline setup? Start with the simple install guide, then follow the archived notes only if the default path does not fit.

📦 Upstream references and reused ideas

VibeSkills reuses ideas and tools from existing open-source projects, then adapts the parts that fit this runtime.

VibeSkills does not claim to replace or fully reproduce every upstream project listed below. The goal is narrower: reuse proven ideas where they fit, then keep the user-facing surface smaller and easier to follow.

🙏 Acknowledgements

This project references, adapts, or integrates ideas, workflows, or tooling from projects such as:

superpower · claude-scientific-skills · get-shit-done · OpenSpec · spec-kit · mem0 · scrapling · claude-flow · serena

We try to attribute upstream work carefully. If we missed a source or described a dependency inaccurately, please open an Issue and we will correct it.

Contributor thanks: xiaozhongyaonvli and ruirui2345 for community contributions to this project.

---

🚀 Getting Started

If VibeSkills is already installed, start with one invocation.

⚠️ Invocation note: VibeSkills uses a Skills-format runtime. Invoke it through your host’s Skills entrypoint, not as a standalone CLI program.

• First try a small request such as planning, clarifying, or breaking down a task.
• If you want later turns to stay inside the governed workflow, append $vibe or /vibe to each message.
• If VibeSkills is not installed yet, start with Simple install (recommended).

Note: $vibe or /vibe only enters the governed runtime. It does not by itself prove that host plugins, providers, or online enhancement are fully configured.

Public host status: codex and claude-code are the clearest install-and-use paths today. cursor, windsurf, openclaw, and opencode are available too, but some of those paths are still preview-oriented or host-specific.

---

---

Star History