Vibe-Skills

1. Project Overview

Vibe-Skills (VibeSkills) is a general-purpose orchestration Skill that automatically discovers, routes, and coordinates a large library of local "Skills" so that AI coding agents can plan, execute, and verify complex multi-step tasks without a developer having to manually pick the right tool for every sub-task.

2. Background & Positioning

As "agent skill" ecosystems (Claude Code Skills, Codex-style harnesses, and similar agent frameworks) have grown, developers often end up with dozens or hundreds of individual Skills installed locally — covering everything from data science to security review to documentation writing. Remembering which Skill to invoke, in what order, and how to confirm the result actually matches what was asked for becomes its own management problem.

Vibe-Skills was created to solve that meta-problem. Instead of being one more specialized Skill, it acts as a router and orchestrator sitting above the rest of the library: it confirms requirements with the user first, estimates how large the task is, shortlists the Skills relevant to each work module, tracks execution state across a session, and produces an acceptance report comparing what was planned against what was actually delivered.

This differs from typical Skill collections (which are simply a folder of independent, single-purpose Skills) in that Vibe-Skills adds a workflow layer: task planning, skill discovery without loading the whole library into context, progress persistence across sessions, and a formal verification step before a task is considered done. It ships with a bundled library of 250+ community Skills as well, making it usable as both an orchestrator and a ready-to-use Skill pack.

3. Feature Categories

• 🧭 Orchestration Core — the engine responsible for requirement confirmation, complexity assessment (--l / --xl), Skill assignment, and execution tracking. Examples: core/skill-contracts, agents/ planning templates, protocols/ communication specs, adapters/ for different host applications. Purpose: turn a natural-language request into a coordinated, auditable plan.
• 🔬 Scientific & Data Skills — the largest bundled category, covering bioinformatics, statistics, and ML research. Examples: biopython, astropy, rdkit, scanpy, pymc-bayesian-modeling, scikit-learn, pytorch-lightning. Purpose: give agents domain-specific expertise for scientific computing and data analysis tasks.
• 🛡️ Security & Quality Skills — reviewer and hardening tools. Examples: security-reviewer, security-best-practices, security-threat-model, security-ownership-map, code-reviewer. Purpose: catch vulnerabilities and enforce code-quality gates during agent-driven development.
• 📝 Documentation & Writing Skills — content and technical writing helpers. Examples: docs-write, docs-review, writing-plans, scientific-writing, markdown-mermaid-writing. Purpose: produce and maintain consistent, high-quality written artifacts.
• ⚙️ DevOps & Deployment Skills — integration and deployment helpers. Examples: netlify-deploy, vercel-deploy, skypilot-multi-cloud-orchestration, mcp-integration, gh-fix-ci. Purpose: automate shipping and infrastructure tasks directly from the agent workflow.
• 📊 Visualization & Reporting Skills — chart and report generation. Examples: creating-data-visualizations, matplotlib, plotly, scientific-slides, report-generator. Purpose: turn raw analysis into presentable outputs.

4. Key Highlights

• Requirement confirmation before work starts — the orchestrator clarifies scope and constraints with the user up front, reducing wasted work from misunderstood tasks.
• Context-efficient Skill discovery — it scans SKILL.md files in configured folders and shortlists only the relevant candidates, instead of loading an entire 250+ Skill library into the model's context window.
• Session continuity — a session_root folder persists inputs, progress, and decisions, so multi-step tasks can be resumed rather than restarted.
• Formal delivery verification — a delivery-acceptance-report compares the approved work plan (module-work-plan.json) against actual execution (module-execution.json), flagging passed, failed, or blocked items.
• Complexity-aware workflow levels — --l and --xl flags let users signal task scope so the orchestrator adjusts planning depth accordingly.
• 250+ bundled Skills out of the box — spanning science, security, DevOps, documentation, and more, usable directly or through the orchestrator.

5. Use Cases by Role

• General developers: Use $vibe / /vibe to turn a loose feature request into a scoped plan, have the right bundled Skills (code review, docs, testing) applied automatically, and get a verification report at the end.
• DevOps/SRE: Leverage deployment-oriented Skills (netlify-deploy, vercel-deploy, skypilot-multi-cloud-orchestration) coordinated by the orchestrator for multi-step release or infrastructure tasks.
• Security engineers: Route review tasks through security-reviewer, security-threat-model, and security-ownership-map, with the orchestrator tracking which checks passed or were blocked.
• Data/research scientists: Access a large catalog of scientific-computing Skills (biopython, astropy, pymc, scikit-learn, and dozens more) without needing to individually memorize each tool's invocation.
• Project managers: Use the planning and acceptance-report artifacts (module-work-plan.json, delivery-acceptance-report.md) as a lightweight audit trail of what was requested versus what was delivered.

6. Getting Started

Find what you need — browse the bundled catalog under bundled/skills/ or consult docs/quick-start.en.md for an overview of available capabilities.

Install / integrate — download the published release archive (not a raw repo checkout), then install into your Skills directory:

# Windows
./update.ps1 -SkillsDir <skills-dir>

# macOS / Linux
./update.sh --skills-dir <skills-dir>

Invoke it from your AI application's Skill entry point:

$vibe

or

/vibe

Contribute — read CONTRIBUTING.md, check the zone table at references/contributor-zone-decision-table.md and the proof matrix at references/change-proof-matrix.md, then open a pull request following the documented evidence requirements for your change type.

7. Project Structure

Vibe-Skills/
├── core/            # orchestration engine and skill-contracts
├── agents/          # planning templates
├── adapters/        # integration interfaces for host applications
├── protocols/        # communication specs between components
├── commands/        # CLI entry points
├── bundled/skills/  # 250+ ready-to-use community Skills
├── docs/            # architecture, governance, install & quick-start guides
├── tests/           # validation suite
├── update.sh / update.ps1   # install/update scripts
└── check.sh / check.ps1     # installation verification

Key files: SKILL.md (the orchestrator's own Skill definition), CONTRIBUTING.md (contribution rules), and docs/quick-start.en.md (getting-started guide).

8. Related Ecosystem

Vibe-Skills is designed to run inside AI coding harnesses that support a local "Skills" concept, such as Claude Code and similar agent frameworks. Many bundled Skills wrap or complement well-known open-source libraries in their respective domains — for example scikit-learn, pytorch-lightning, matplotlib, and biopython in the scientific-computing space, and mcp-integration for connecting to Model Context Protocol servers.

9. License

Licensed under Apache License 2.0.

• ✅ Commercial use, modification, distribution, and private use are permitted.
• ✅ You may sublicense modified versions as part of your own project, provided attribution is preserved.
• ❌ No warranty is provided, and the authors are not liable for damages arising from use.
• ℹ️ Third-party components are separately attributed in NOTICE and THIRD_PARTY_LICENSES.md — review those files if you redistribute the bundled Skill library.

10. FAQ

Q: Do I install this by cloning the repository?
A: No — the documentation specifies installing from a published release archive, not a raw repository checkout. See docs/quick-start.en.md.

Q: How do I invoke Vibe-Skills once installed?
A: Through your AI application's Skill entry point, typically $vibe or /vibe, e.g. "Clarify this requirement and turn it into a plan $vibe".

Q: What do the --l and --xl flags mean?
A: They tell the orchestrator the expected scope of the task — --l for manageable work and --xl for larger, more complex projects — so it plans accordingly.

Q: How do I confirm my installation is intact after an update?
A: Run check.sh (or check.ps1 on Windows) to verify installer-managed files are present and unchanged.

Q: Can I use the bundled Skills without the orchestrator?
A: Yes — each Skill under bundled/skills/ is a self-contained folder with its own SKILL.md and can be used independently.

11. Quick Links

• Repository: https://github.com/foryourhealth111-pixel/Vibe-Skills
• Quick Start Guide: docs/quick-start.en.md
• Contributing Guide: CONTRIBUTING.md
• Community: GitHub Issues and Pull Requests on the repository

12. Summary

Vibe-Skills addresses a real pain point in growing agent-Skill ecosystems: knowing which of many installed tools to use, in what order, and whether the result actually met the requirement. Combined with a 250+ Skill bundled library spanning science, security, DevOps, and documentation, it is valuable both as an orchestration layer for teams running large Skill libraries and as a ready-made toolkit for individual developers who want broad capabilities without manual tool selection.