foryourhealth111-pixel/Vibe-Skills

Coordinate local Skills for composite agent work

VibeSkills is a workflow runtime for AI agents. It takes one request, splits it into bounded parts, and lets the right local Skills handle planning, implementation, testing, docs, research, or review inside the same run.

Core function	Best at	Works with
Organize multiple local Skills in one task	Composite work such as code changes plus tests plus docs plus review, or research plus writing plus delivery	Codex, Claude Code, Windsurf, Cursor, OpenCode, OpenClaw, and other Skills-compatible hosts

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.

Runtime notes for advanced readers

Installed local skills are the only specialist reference surface in the public runtime story. Host-declared extra local roots extend that same local surface without a new central catalog. This is not a claim that the final architecture is complete.

A skill counts as actually used only when execution evidence supports it, and work_binding records what was actually bound in the run.

For this runtime boundary, Python owns final truth artifacts, canonical validation, task semantics, work_binding, specialist decision truth, and structured runtime result data. PowerShell still performs stage orchestration, environment setup, script bridging, host receipts, shell-native checks, and leaf execution. Do not add new task semantics to PowerShell; existing PowerShell stage scripts are transitional orchestration surfaces. A future full-Python runtime is optional, not required for this version.

         

🧠 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["vibe<br/>Runtime Entry"]
    freeze["Freeze<br/>Requirement"]
    plan["Build<br/>Work Model"]
    route["Bind Skills<br/>Late"]
    skills["Declared local Skills only<br/>real SKILL.md required"]
    future["Local skill folders can grow<br/>while the public entry stays the same"]
    verify["Verify<br/>Tests + Evidence"]
    memory["Remember<br/>Workspace 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 <repo-root> --skills-dir <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: