skillware

<div align="center">
  <img src="assets/skillware_logo.png" alt="Skillware Logo" width="400px" />

  A Python framework for modular, self-contained skill management for machines.
</div>

<br/>

<div align="center">
  <img src="https://img.shields.io/badge/License-MIT-efcefa?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/Python-3.10+-bae6fd?style=flat-square" alt="Python Version">
  <a href="https://pypi.org/project/skillware/"><img src="https://img.shields.io/pypi/v/skillware?style=flat-square&color=bbf7d0" alt="PyPI Version"></a>
  <a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/pepy/dt/skillware?style=flat-square&label=DLs%20%E2%86%93&color=ffdac1" alt="Total PyPI downloads"></a>
</div>

<br/>

<div align="center">
  <a href="#mission">Mission</a> •
  <a href="#how-it-works">How it works</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#documentation">Documentation</a> •
  <a href="#contributing">Contributing</a> •
  <a href="#comparison">Comparison</a> •
  <a href="#stats">Stats</a> •
  <a href="#citing">Citing</a> •
  <a href="CHANGELOG.md">Changelog</a> •
  <a href="#contact">Contact</a>
</div>

---

**Skillware** is an open-source framework and registry for modular, actionable Agent capabilities. It installs know-how for AI agents, or modular **Skills** (code, contract, and host guidance) decoupling capability from intelligence. In short, don't prompt your agents, equip them.

> "I know Kung Fu." - Neo

## Mission

Every new agent stack tends to reinvent tool schemas, system prompts, and safety rules. **Skillware** packages each capability as a self-contained bundle and adapts it to **Gemini**, **Claude**, **OpenAI**, **Ollama**, and other OpenAI-compatible hosts. For the full story and roadmap, see **[Vision](docs/vision.md)**.

A **Skill** in this framework provides everything an Agent needs to master a domain:

1. **Contract**: Constitution, safety boundaries, and typed I/O baked into the bundle.
2. **Effect**: Executable Python so agents run real work, not guess it.
3. **Directive**: System instructions and cognitive maps so any host uses the capability as intended.
4. **Assurance**: Offline tests that Effect honors Contract before a skill joins the registry.
5. **Interface**: Standardized tool schemas for any LLM or agent runtime.

Optional **Corpus** and **Reference** assets extend bundles when needed. Every bundled registry skill also ships **Presentation** (`card.json`) for catalog and UI metadata. Full reference: [Introduction — Skill anatomy](docs/introduction.md#skill-anatomy).

### Skill library

Browse capabilities by category in the [Skill library](docs/skills/README.md) or on our <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">site&nbsp;↗</a>.

## How it works

```mermaid
flowchart LR
    Registry[Registry] -->|Load| Loader[Loader]
    Loader -->|Adapt| AnyHost["Any Host"]
```

Install the registry once. Skillware loads a bundle, adapts it to your host's tool format, and your app runs the agent loop (Gemini, Claude, Ollama, custom scripts, …). See the [Introduction](docs/introduction.md) for loader details, [Agent loops](docs/usage/agent_loops.md) for the execution pattern, and [Skill chaining](docs/usage/skill_chaining.md) for multi-skill sessions (`SkillContext`, named `chains:`).

## Architecture

This repository is organized into a core framework, a registry of skills, and
documentation. Runnable provider scripts are indexed in
[examples/README.md](examples/README.md).

```text
Skillware/
├── docs/                       # Introduction, testing, skill catalog, usage guides (docs/usage/)
├── examples/                   # Provider reference scripts — usage demos, not pytest (see examples/README.md)
├── skills/                     # Skill Registry
│   └── category/               # Domain boundaries (e.g., finance)
│       └── skill_name/         # The Skill bundle
│           ├── manifest.yaml   # Contract: schema, constitution, issuer
│           ├── skill.py        # Effect: deterministic execution
│           ├── instructions.md # Directive: host guidance
│           ├── card.json       # Presentation: catalog / UI metadata
│           └── test_skill.py   # Assurance (required for registry skills)
├── skillware/                  # Core Framework Package
│   ├── cli.py                  # Command-line interface
│   ├── context.py              # SkillContext — multi-skill registry host context
│   ├── chains.py               # Named skill chain runner (run_chain, validate_chain)
│   └── core/
│       ├── base_skill.py       # Abstract Base Class for skills
│       ├── chains_config.py    # chains: YAML parsing
│       ├── env.py              # Environment Management
│       └── loader.py           # Universal Skill Loader and Model Adapter
├── templates/                  # Boilerplate templates for new skills
│   └── python_skill/         

... (truncated)