VibeSkills: a routing layer that turns local SKILL.md folders into an orchestrated agent workflow

The problem VibeSkills targets: too many local Skills, no assignment logic

The README's worked example opens with a concrete situation: during publication preparation, the configured folders on one host held more than 100 Skills. That is the problem VibeSkills is built around. A large local Skill library is not useful on its own, because nothing decides which Skill owns which part of a task, what that Skill should hand back, or how anyone confirms the hand-back is complete.

VibeSkills answers those three questions explicitly. It reviews candidate Skills and their SKILL.md files, then states what each selected Skill owns, what it should deliver, and how completion will be checked. In the documented case it chose 7 Skills out of the 100-plus available, arranged them into 5 work groups and 10 work units, and ran 17 checks across data, experiment results, figures, report and slides before final acceptance.

The audience is narrow on purpose. If you run an agent harness that reads local Skill folders, and you have accumulated enough of them that selection is now guesswork, this is the layer you are missing. If you have three Skills and one task type, the routing overhead buys you very little.

How the routing and gating actually work

The process has five named stages, and the order matters because stage I blocks everything after it. First VibeSkills confirms the requirement: goal, constraints, available material, expected delivery. The README states the process stops here until the requirement is approved, which gives the plan and the final check a shared basis. Skipping that step means the acceptance check at stage V has nothing to compare against.

Second, it recommends a level. `L` is for multi-step work of manageable size and splits the task, then works through the parts in order with less time and context overhead. `XL` is for larger work with several relatively independent parts, uses a more detailed breakdown, and can run up to two non-conflicting parts at the same time, with additional coordination and result collection. You confirm the level; the recommendation is not binding.

Third comes Skill organization: VibeSkills reviews your configured folders, selects methods that fit each part, and ties every selected Skill to concrete work, an expected delivery, and a check. Fourth, execution, where the current agent does the work. Code tasks can use TDD when appropriate: show the problem with a failing test, make the change, run the tests again. Completed, failed and blocked states are recorded so a later session can continue.

Fifth is the check. VibeSkills compares the actual result with every planned item, and required work that is incomplete, failed or blocked prevents final acceptance. That is the design decision worth noticing: the gate is per item, not a pass or fail on the whole task. The repository layout backs this up with `protocols/`, `schemas/`, `rules/` and `adapters/` directories, plus a CI workflow named `vco-gates.yml`, so the acceptance logic is expressed as schemas and rules rather than prose.

Installing VibeSkills and running a first real task

The README points to `docs/install/README.en.md` and `docs/quick-start.en.md` rather than to a package registry, and the repository root carries install and uninstall scripts for both shells. The project's own build metadata names the workspace package `vibe-skills-workspace` and requires Python 3.10 or newer, so treat the repository checkout as the distribution.

Start from a clone of the default branch and run the installer for your platform. On a Unix-like host the README's install directory documents `install.sh`; on PowerShell hosts it is `install.ps1`.

git clone https://github.com/foryourhealth111-pixel/Vibe-Skills.git
cd Vibe-Skills
./install.sh

After installing, the README's front page gives one command for checking the local runtime state. Run it and read the report before starting any task, because it is the only documented way to see what the runtime currently believes about your installation.

pwsh ./check.ps1

The quick-start document is where the first task is described. The shape to expect, based on the five stages, is that you state the requirement, confirm the level VibeSkills recommends, let it read your configured Skill folders and propose an assignment, approve the plan, and then wait for the acceptance check. The README does not document a rollback procedure, so if a run goes wrong, `uninstall.sh` or `uninstall.ps1` and a fresh install is the only route the repository files describe. Updates follow the same pattern through `update.sh` and `update.ps1`.

Where VibeSkills gets in the way

The requirement gate is the first real cost. VibeSkills will not proceed until the goal, constraints, available material and expected delivery are approved. For exploratory work, where you genuinely do not know the delivery until you have poked at the problem, that gate is friction rather than safety, and the honest move is to do the exploration outside VibeSkills and bring it in once the shape is clear.

The `XL` level is the second constraint. Up to two non-conflicting parts run at the same time, which means the parallelism is deliberately shallow. A task with eight independent branches will not get eight-way concurrency out of this, and the README says `XL` carries additional coordination and result collection overhead, so the level is not free.

Third, the whole mechanism depends on local Skill folders that contain SKILL.md files. The README describes reading those files to shortlist candidates. If your Skills are stored some other way, or if a Skill has no SKILL.md, the selection stage has nothing to work from. And because acceptance is per planned item, a task whose true completion criterion is fuzzy will produce a check that is either vacuous or wrong; the tool cannot invent a criterion you did not state.

The repository also shows its own moving parts: `_python_source_roots.py`, `vgo_python_source_roots.py`, `vgo_cli/` and `scripts.check.upstream.sh` sit alongside the main tree. That is a sign of a project still rearranging its own scaffolding, and the version in `pyproject.toml` (4.1.0) is ahead of the newest release listed in the README (v4.0.0).

How this differs from a plain Skill library or a fixed pipeline

The closest alternative is not another router; it is the thing most teams already have, which is a folder of Skills plus a human who picks one by hand. The difference is where the decision lives. In the manual setup, selection is implicit and unrecorded, and nothing forces a Skill to declare what it will deliver or how completion will be judged. VibeSkills makes those declarations explicit at stage III and then holds them to account at stage V. You are trading a small amount of upfront ceremony for a written assignment and a per-item gate.

The other alternative is a hand-written pipeline: a fixed sequence of steps wired together for one class of task. That is faster and more predictable when the task never varies. VibeSkills is the opposite trade. It reads the task first, then chooses, which is why it can handle the documented case of 100-plus candidates and 7 selections, but it also means the plan is not knowable in advance. If your work is one repeatable job, a fixed pipeline will beat it on time and context overhead; if your work is varied and your Skill library keeps growing, the fixed pipeline becomes the thing you rewrite every month.

Maintenance, upgrades and the Apache-2.0 licence

The last push to the default branch was on 2026-07-17, and the most recent release, v4.0.0, carries the same date. Two earlier releases, v3.2.0 and v3.1.1, landed on 2026-07-08 and 2026-05-06, so the release cadence over that window was uneven rather than steady. The repository is not archived.

Upgrade cost is the part worth budgeting for. The repository ships `update.sh` and `update.ps1`, which suggests updates are applied in place rather than by reinstalling, but the README does not document what an update preserves or how to get back to the previous version if one misbehaves. The presence of `uninstall.sh` and `uninstall.ps1` gives you a way out, not a way back. If you run this in a shared environment, capture the output of `pwsh ./check.ps1` before and after an update so you have your own record of what changed.

The licence is Apache-2.0, and the repository carries a `NOTICE` file and a `THIRD_PARTY_LICENSES.md`, which is what you would expect from a project that vendors dependencies under `vendor/` and `third_party/`. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, but it also requires that you keep the licence and notice files and state what you changed. If you redistribute a modified copy, those obligations travel with it. That is a description of the licence terms, not advice about your situation.

Editorial conclusion

Adopt VibeSkills if you already keep a folder of SKILL.md files and want an agent harness to pick from them, plan in L or XL, and refuse delivery until each planned item passes a check. Do not adopt it if you want a hosted service or a package you can simply pip install from a registry: the documented path is a repository checkout plus install.sh or install.ps1, and the README does not document rollback. Before committing, verify that your harness supports the protocol files under protocols/ and schemas/, that your Skill folders actually contain SKILL.md files VibeSkills can read, and that the check.ps1 or check.sh output matches the runtime state you expect on your machine.

Frequently asked questions

Official sources

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