VibeSkills: A Python Orchestration Layer That Routes Local Skills Through a Five-Stage Workflow

What VibeSkills Actually Does

VibeSkills is not a library you import. It is a Skill, written in Python, that sits above other local Skills and decides which ones run and in what order. The README frames it as a general-purpose orchestrator: it reviews the local Skill folders you configure, reads their SKILL.md files, shortlists candidates, and assigns them to parts of a task. The core problem it solves is coordination. If you have dozens of Skills, each with its own tool usage and working steps, you need a way to pick the right ones for a given job and to know when that job is actually done. VibeSkills gives an Agent one process from receiving a task to checking the delivery. That process is fixed: confirm the requirement, recommend a level, organize Skills, execute and record, then check the result. The final check is not optional. Required work that is incomplete, failed, or blocked prevents final acceptance.

The Five-Stage Pipeline and the Approval Gate

The workflow is explicit and sequential. Stage one confirms the requirement: goal, constraints, available material, and expected delivery. The README states the process stops here until the requirement is approved. That is a hard gate. No plan, no execution, no delivery. Stage two recommends a level, L or XL, based on task scope, steps, dependencies, and parallel work opportunities. You then confirm the level. Stage three organizes Skills: VibeSkills reviews local folders, selects methods, and states what each Skill owns, what it should deliver, and how completion will be checked. Stage four executes and records, with completed, failed, and blocked states saved so a later session can continue. Stage five compares the actual result against every planned item. This is a control system, not a suggestion engine. The approval pauses are deliberate. They force a human or a supervising Agent to sign off before context and compute are spent.

L and XL: Two Sizes of Breakdown

The level choice changes how work is split. L is for multi-step work of manageable size. It splits the task and works through the parts in order, with less time and context overhead. XL is for larger work with several relatively independent parts. It uses a more detailed breakdown and can run up to two non-conflicting parts at the same time, with additional coordination and result collection. The difference is not cosmetic. XL introduces parallelism, which means you need result collection and conflict detection. The README says XL can run two non-conflicting parts in parallel, but it does not detail how conflicts are detected. That is a gap. If your task has hidden dependencies between parts, the parallelism could produce inconsistent results. The documentation gives a worked example: a machine learning experiment used the L workflow, selected 7 Skills from over 100, arranged them into 5 groups and 10 work units, and passed 17 checks. That example is a single data point, and it is L, not XL.

How Local Skills Get Selected and Bound to Work

Selection is driven by SKILL.md files. VibeSkills reviews the configured folders, shortlists candidates by reading those files, and then assigns Skills to concrete work, expected delivery, and a check. The README shows a diagram with the task's work kinds on the left, VibeSkills making the assignment in the middle, and local Skill folders on the right. A selected Skill is tied to a specific unit of work. That binding is what makes the final check possible. If a Skill does not define what it delivers or how completion is checked, VibeSkills cannot verify it. The README says local Skills can store tool usage, working steps, decision rules, and checking methods. So the quality of your SKILL.md files directly determines whether VibeSkills can do its job. This is a real constraint: the orchestrator is only as precise as the metadata in your Skills. If your SKILL.md files are vague, the shortlist will be vague, and the final acceptance check will be weak.

Getting It Running: Commands and Configuration

The README points to a docs/install directory and a quick-start guide. The only concrete command shown is pwsh ./check.ps1, which reports the current local runtime state. That is a PowerShell script, so you need PowerShell available. The repository is Python-based, but the entry point for checking state is PowerShell. That is a mixed toolchain. The install documentation is linked as docs/install/README.en.md, and the quick start is docs/quick-start.en.md. The README also links to a CI workflow file at .github/workflows/vco-gates.yml, which suggests there are automated gates in the repository's own CI. The README does not list a pip install command or a setup.py. You are expected to clone the repository and follow the docs. The configuration key is the Skill folders you configure, but the README does not name the exact config key or environment variable. That is a gap you will need to fill by reading the install docs.

TDD and State Recording: The Execution Details

During execution, VibeSkills can use test-driven development when appropriate. The README describes the TDD loop: show the problem with a failing test, make the change, and run the tests again. That is a conditional, not a mandate. It says when appropriate, which leaves room for the orchestrator to skip TDD for non-code tasks like writing a report or creating figures. The state recording is more important. Completed, failed, and blocked states are recorded so a later session can continue. That means VibeSkills is designed for interrupted work. If a session dies mid-task, the next session can pick up from the recorded state. That is a practical feature for long-running workflows. But the README does not specify where the state is stored, whether it is a file, a database, or something else. That matters for multi-host setups. The ML case study mentions configured folders on the same host, so the state is likely local, but that is an inference, not a documented fact.

Limitations and When It Is the Wrong Tool

VibeSkills is wrong for tasks that do not fit a deliverable-based plan. If you have a single-step operation, or a task where the output is exploratory and cannot be checked against a list, the five-stage gate will be overhead. The approval pauses will slow you down. The README says the process stops until the requirement is approved, so you cannot skip that step. Also, the parallelism in XL is limited to two non-conflicting parts. If your task has many independent parts, you will not get full parallel speedup. The documentation does not explain how conflict detection works, so you cannot predict whether two parts will be considered conflicting. Another limitation is the dependency on SKILL.md quality. If your Skills lack checking methods, the final acceptance check will not catch real problems. The 17 checks in the ML case study are impressive, but they were for that specific task. Your task will have different checks, and VibeSkills will only run what your Skills define.

Alternatives and Maintenance Considerations

A direct alternative is a manual orchestration script, where you write a Python or shell script that calls each Skill in sequence and checks exit codes. That gives you full control over order and parallelism, but you lose the automatic shortlisting and the structured state recording. Another alternative is a workflow engine like Prefect or Airflow, which handles task dependencies, retries, and scheduling. Those tools are general-purpose and not tied to SKILL.md metadata, so they require you to define the orchestration logic yourself. The difference is that VibeSkills bakes in the five-stage process and the Skill selection from SKILL.md, while a workflow engine gives you primitives but no domain logic. On maintenance, the project is under Apache-2.0, which allows commercial use and modification. The last push was 2026-07-17, and there are three recent releases, so it is actively maintained. The CI workflow suggests automated gates, but you should check the docs for upgrade notes between versions. The README does not mention a migration guide, so upgrading from v3.x to v4.0.0 may require reading the release notes.

Editorial conclusion

Adopt VibeSkills if you run multi-step tasks inside an Agent environment where you already maintain a folder of local Skills with SKILL.md files and need a repeatable gate before delivery. Do not use it for single-step jobs, for tasks with no clear deliverable list, or for teams that cannot tolerate a required approval pause before execution. Before adopting, verify that your Agent runtime supports running a Python Skill at this orchestration level, confirm that your SKILL.md files carry the check criteria VibeSkills expects, and run pwsh ./check.ps1 to see what the local runtime state reports. The 17-check acceptance gate is concrete, but it only works if your own Skills define completion in a way VibeSkills can compare.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes