<img src="./logo.png" width="124" alt="VibeSkills logo">

<picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-tagline-en-dark.svg"> <img src="./docs/assets/readme-tagline-en-light.svg" width="560" alt="VibeSkills is a general-purpose Skill that automatically routes local Skills and intelligently orchestrates harness workflows."> </picture>

<br>

<a href="https://github.com/foryourhealth111-pixel/Vibe-Skills/releases/latest"> <strong>Latest release · v4.1.0</strong> </a>

<br>

<a href="./docs/install/README.en.md"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/install-cta-en-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="./docs/assets/install-cta-en-light.svg"> <img src="./docs/assets/install-cta-en-light.svg" width="210" height="38" alt="Install VibeSkills"> </picture> </a>

<br>

<a href="./docs/quick-start.en.md">Quick start</a> ·

</div>

<a id="skillsbench-performance"></a> <h2 align="center">Measured on SkillsBench</h2>

<p align="center"> <strong>Mean verifier reward: +21.12 pp</strong><br> <strong>Total tokens: -29.6%</strong> · <strong>Tool calls: -33.1%</strong> </p>

SkillsBench is a benchmark designed to evaluate whether AI agents can effectively use Skills to complete professional tasks across diverse domains. Its purpose is to measure how much a model’s ability to solve complex real-world tasks improves when it is equipped with specialized Skills.

To evaluate performance in production-like environments where a large number of Skills are installed simultaneously, we adapted SkillsBench into a more realistic large-scale multi-Skill setting. In the original SkillsBench setup, each task is provided only with the specialized Skill associated with that task. In our modified setting, every task is evaluated in a global environment containing all 195 specialized Skills, while all other experimental conditions remain unchanged. This setting is intended to assess whether an agent can autonomously discover, select, and orchestrate the relevant Skills from a large installed Skill pool, and organize them into an effective workflow for completing complex tasks.

vibeskills v4.1.0 was benchmarked on SkillsBench (https://www.skillsbench.ai/) using DeepSeekV4Flash-VE and OpenHands as the baseline evaluation setup. Compared with the baseline without vibeskills, vibeskills increased the average task score by 21.12%, while reducing token consumption by 29.6% and tool calls by 33.1%.

<p align="center"> <a href="https://github.com/foryourhealth111-pixel/vibeskills-benchmark/tree/main/studies/full-skills-comparison"> <img src="./docs/assets/skillsbench-task-outcomes.png" width="900" alt="SkillsBench paired task outcomes: Lean Vibe increased mean reward from 50.3% to 71.4%, increased the full-score rate from 47.6% to 69.5%, scored higher on 23 tasks, tied on 55, and scored lower on 4"> </a> </p>

<p align="center">_{Task quality: 39 to 57 full-score tasks; Lean Vibe scored higher on 23 tasks, Native on 4, with 55 ties.}</p>

<p align="center"> <a href="https://github.com/foryourhealth111-pixel/vibeskills-benchmark/tree/main/studies/full-skills-comparison"> <img src="./docs/assets/skillsbench-resource-use.png" width="900" alt="SkillsBench resource comparison: total token use fell from 491.1 million for Native to 345.8 million for Lean Vibe, while tool calls fell by 33.1%"> </a> </p>

<p align="center">_{Resource use: 491.122M to 345.756M total tokens, with tool calls reduced from 9,954 to 6,664.}</p>

Analysis of the logs from the original benchmark shows that VibeSkills achieves better task performance not by invoking more Skills.

Instead, it first clarifies the task objective and delivery requirements, then decomposes a complex task into several verifiable subtasks. It subsequently selects only a small number of truly relevant capabilities from a large pool of candidate Skills and executes them in an order determined by their dependencies. This helps reduce misunderstandings of the task, omitted steps, and incorrect Skill selection, thereby improving overall task performance.

In terms of token cost and tool usage, this workflow also eliminates a substantial amount of ineffective trial and error. Native agents are more likely to repeatedly invoke tools in unproductive directions, reread the same context, and redo previous work. In contrast, VibeSkills converges more quickly on the critical steps through clearer planning and pre-delivery checks. As a result, it not only improves task quality, but also significantly reduces tool-call loops and the token overhead caused by repeated context processing.

<p align="center"> <a href="https://github.com/foryourhealth111-pixel/vibeskills-benchmark/blob/main/studies/full-skills-comparison/README.md">Study, public data, and reproduction</a> · </p>

<p align="center"> <picture> <source media="(prefers-color-scheme: dark) and (max-width: 600px)" srcset="./docs/assets/readme-preface-v2-en-mobile-dark.svg"> <source media="(prefers-color-scheme: light) and (max-width: 600px)" srcset="./docs/assets/readme-preface-v2-en-mobile-light.svg"> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-preface-v2-en-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="./docs/assets/readme-preface-v2-en-light.svg"> <img src="./docs/assets/readme-preface-v2-en-light.svg" width="900" alt="Skills are excellent local assets of reusable experience. After downloading and installing many Skills, it is easy to sometimes forget which Skills have already been installed and not know which Skills to invoke. Further, when a complex task involves the combined organization and invocation of multiple Skills from different domains, planning becomes complicated for people: they must explain to the AI in detail which Skills each module should use, while the AI may forget these designs during execution. Many current harness frameworks do not actively plan how to make good use of local Skill resources, and may even fall into an either-or scheduling conflict between the harness framework and domain Skill resources. The core of this project is to follow harness frameworks similar to Superpower and GSD. Based on modular decomposition by the planning state machine, it uses different Skills to assist different modules, fully schedules existing local resources, reduces users' planning and cognitive burden, and gives users an end-to-end delivery experience. It is committed to becoming a handy steward for the Skill resources around you. When a complex task appears, it can help users slowly sort out which modules are needed and which good experiences can be reused, then deliver an excellent result."> </picture> </p>

<a id="vibeskills-ml-practice-case"></a> <h2 align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-01-en-dark.svg"> <img src="./docs/assets/readme-chapter-01-en-light.svg" width="720" alt="VibeSkills Practice Case: Completing a Machine-Learning Experiment"> </picture> </h2>

Task Use public data to complete a reproducible classification experiment and deliver a data audit, statistical review, 4 result figures, a scientific report, and a 7-slide group-meeting deck.

The diagram shows what happened after the requirement and plan were approved: how the task was executed, what it produced, and how the result was checked.

The task used the L workflow and proceeded in order. During publication preparation, the configured folders on the same host contained more than 100 Skills. VibeSkills reviewed the candidates and their SKILL.md files, selected 7 for this task, and arranged the work into 5 groups and 10 work units. Those units covered environment setup, data audit, modeling, statistical review, figures, the report, and the slide deck.

After the work finished, VibeSkills ran 17 checks across the data, experiment results, figures, report, and slides. The task passed final acceptance after the required files, cross-deliverable consistency, and core reproduction all passed.

<p align="center"><strong>7 Skills selected · 5 work groups · 10 / 10 work units completed · 17 / 17 checks passed</strong></p>

<p align="center"> <a href="./docs/cases/ml-experiment/README.md#case-execution">View case execution</a> · <a href="./docs/cases/ml-experiment/README.md#final-delivery">View final delivery</a> </p>

<a id="how-vibeskills-carries-a-task-through-to-delivery"></a> <h2 align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-02-en-dark.svg"> <img src="./docs/assets/readme-chapter-02-en-light.svg" width="720" alt="How VibeSkills Carries a Task Through to Delivery"> </picture> </h2>

VibeSkills gives an Agent one process from receiving a task to checking the delivery.

Each stage answers a concrete question: what needs to be done, how the work should proceed, which Skills should take part, what actually happened, and whether the result is ready to deliver.

<p align="center"> <img src="./docs/assets/vibeskills-harness-overview-en.svg" width="860" alt="VibeSkills confirms the requirement, chooses L or XL, organizes Skills, records the work, and checks the result; code work can enter a TDD loop"> </p>

1. Confirms the requirement. Before work begins, it confirms the goal, constraints, available material, and expected delivery. The process stops here until the requirement is approved, giving the plan and final check a clear basis.
2. Recommends a level. VibeSkills recommends L or XL from the task's scope, steps, dependencies, and opportunities for parallel work. You then confirm the level. Manageable work proceeds in order; larger work is split more finely.
3. Organizes Skills. VibeSkills reviews the local Skill folders, selects the methods that fit each part, and states what each Skill owns, what it should deliver, and how completion will be checked.
4. Executes and records. After plan approval, the current Agent completes the work. Code tasks can use test-driven development (TDD) when appropriate: show the problem with a failing test, make the change, and run the tests again. Completed, failed, and blocked states are recorded so a later session can continue.
5. Checks the result. VibeSkills compares the actual result with every planned item. Required work that is incomplete, failed, or blocked prevents final acceptance.

<details> <summary><strong>When to use L or XL</strong></summary>

</details>

<a id="how-local-skills-take-part"></a> <h2 align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-03-en-dark.svg"> <img src="./docs/assets/readme-chapter-03-en-light.svg" width="720" alt="How Local Skills Take Part"> </picture> </h2>

Local Skills can store tool usage, working steps, decision rules, and checking methods.

VibeSkills reviews the local Skill folders you configure, then shortlists the Skills that fit the work required by each part of the task.

<p align="center"> <img src="./docs/assets/vibeskills-skill-orchestration-en.png" width="860" alt="VibeSkills sits between task modules and local Skills, coordinating the work and selecting only the Skills each part needs"> </p>

The left side shows the different kinds of work in the task, VibeSkills makes the assignment in the middle, and the local Skill folders are on the right. A selected Skill is tied to concrete work, expected delivery, and a check. The current Agent then follows the shared plan.

VibeSkills does something straightforward: it first makes the whole task clear, then assigns the right Skills to the relevant parts. It coordinates the work and checks the combined result at the end. The task uses the Skills it needs; the rest of the local library stays available without entering the plan.

You can keep adding your own Skills, team Skills, and third-party Skills. VibeSkills does not call every installed Skill automatically; it selects the Skills that fit the current task. The size of the library defines the available choices, not a list that every task must use.

<details> <summary><strong>Will a large Skill library use a lot of tokens?</strong></summary>

VibeSkills checks the Skill folders you configure, but finding files locally and placing their full contents in the model context are different operations.

Discovery and index generation happen locally. VibeSkills first extracts compact information such as each Skill's name, description, intended use, and boundaries, then uses that information to shortlist candidates for each part of the task.

Only retained candidates are then read as complete SKILL.md files. Execution uses only the Skills written into the plan. Token usage therefore depends mainly on how many candidates the task retains, how long those documents are, and how complex the task is. It is not the same as reading the full local Skill library into the model context.

This overhead is not zero. More candidates, longer Skill documents, or a more finely divided task will use more context. The current design bounds that cost with a local index, candidate shortlisting, and on-demand reading.

</details>

<details> <summary><strong>Local folders and selection records</strong></summary>

Alongside the shared Skills directory, more local folders can be listed in ~/.vibeskills/skill-roots.json or <workspace>/.vibeskills/skill-roots.json.

A Skill needs a readable SKILL.md, a name that does not conflict with another Skill, and a clear fit for the current work before it can be selected. Adding a local folder makes those Skills available to later tasks without waiting for the VibeSkills repository to include them.

During planning, agent_skill_organization stores which Skills are intended for each part of the task. During execution, module_assignments stores the actual assignment. Finding a Skill means it can be considered; it does not mean the Skill has already taken part in the work.

</details>

<a id="how-a-task-can-continue-and-be-reviewed"></a> <h2 align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-04-en-dark.svg"> <img src="./docs/assets/readme-chapter-04-en-light.svg" width="720" alt="How a Task Can Continue and Be Reviewed"> </picture> </h2>

A public example lets readers follow the requirement, plan, actual result, and final check.

VibeSkills keeps the approved requirement, plan, execution progress, and final check in the same task record. A later session can continue from the saved progress, and a review can compare the original plan with the actual result. Installation state is recorded separately so it is not confused with task completion.

<details> <summary><strong>View the record files</strong></summary>

Maintainers can use the pre-release checks. Start with the checks in that list and run wider audits only when there is a reason.

</details>

A successful installation does not mean the task ran, and a task record does not mean the final result passed its checks.

<a id="use-vibeskills"></a> <h2 align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-05-en-dark.svg"> <img src="./docs/assets/readme-chapter-05-en-light.svg" width="720" alt="Use VibeSkills"> </picture> </h2>

1. Invoke. In any AI application that supports local Skills, invoke VibeSkills through the application's Skills entry, using $vibe, /vibe, or the syntax it provides.
2. Discover. VibeSkills scans the Skills installation directory and any additional local Skill folders you configure to find the Skills currently available.
3. Organize. It selects suitable Skills for the task, assigns them to the relevant work, and coordinates the result. You do not need to remember which Skill should be used when.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-wave-divider-dark.svg"> <img src="./docs/assets/readme-wave-divider-light.svg" width="240" alt=""> </picture> </p>

<a id="more-documentation"></a> <h2 align="center">More Documentation</h2>

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-wave-divider-dark.svg"> <img src="./docs/assets/readme-wave-divider-light.svg" width="240" alt=""> </picture> </p>

<a id="community-and-credits"></a> <h2 align="center">Community and Credits</h2>

Questions, corrections, and well-scoped contributions are welcome through GitHub Issues and pull requests.

VibeSkills discussions and community practice can also continue on LINUX DO. It is a place to exchange technical questions, AI practice, and experience. Thank you to the LINUX DO community for supporting this project.

The VibeSkills 3.1.0 community practice cases collect several examples that were shared with the community.

Community contributors include xiaozhongyaonvli and ruirui2345.

Third-party software attribution and license information are listed in NOTICE and third-party licenses.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-wave-divider-dark.svg"> <img src="./docs/assets/readme-wave-divider-light.svg" width="240" alt=""> </picture> </p>