skillware
A Python framework for modular, self-contained skill management for machines.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ARPAHLS/skillware with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ARPAHLS/skillware'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/arpahls--skillware)HTML
<a href="/listings/arpahls--skillware"><img src="/api/listings/arpahls--skillware/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires **Python 3.10 or newer** (see `requires-python` in `pyproject.toml`).
1. Installation
You can install Skillware directly from PyPI:
pip install skillware
Or for development, clone the repository and install in editable mode:
git clone https://github.com/arpahls/skillware.git cd skillware pip install -e ".[dev,all]"
For documentation-only work, `pip install -e ".[dev]"` is enough. Skill and framework contributors should use `[dev,all]` to match CI (see [TESTING.md](docs/TESTING.md) and [Install extras](docs/usage/install_extras.md)).
> **Note**: Every skill has a dedicated pip extra (`pip install "skillware[category_skill]"`). The `SkillLoader` validates `manifest.yaml` on load and suggests the matching extra when packages are missing. See [Install extras](docs/usage/install_extras.md).
2. Verify your installation
skillware list skillware paths
You should see a table of bundled registry skills and a paths summary confirming install and discovery. **Bundled skills from `pip install skillware` are always available** — an empty local `skills/` folder does not disable them.
For path tiers, shadowing, config files, and the interactive menu, see [CLI — paths & tiers](docs/usage/cli.md#skillware-paths), [CLI — config](docs/usage/cli.md#skillware-config), and [Finding skills on disk](docs/usage/README.md#finding-skills-on-disk). If `skillware` is not on your PATH, use `python -m skillware list` ([CLI Reference](docs/usage/cli.md#running-the-cli)).
3. Configuration
**Skill paths (optional):** copy [`.skillware.yaml.example`](.skillware.yaml.example) to `.skillware.yaml` in your project root, or use the interactive menu (**`4` / `paths`**) to persist project and external skill roots. Inspect merged settings with `skillware config show`. See [CLI — config](docs/usage/cli.md#skillware-config).
**API keys:** copy the environment template and add your keys.
**Unix / macOS:**
cp .env.example .env
**Windows (PowerShell):**
Copy-Item .env.example .env
Edit `.env` with agent keys (for example Gemini) and any keys your skills need. Agent keys power your LLM client; skill keys are declared per skill in the [Skill library](docs/skills/README.md). Operator files (`skillware addressbook init`, `skillware evm init`) live under `~/.config/skillware/` and survive upgrades. See [API keys for skills](docs/usage/api_keys.md) for `.env` setup, [Address book operator config](docs/usage/addressbook_operator_config.md), and `skillware doctor`.
4. Usage Example (Gemini + Gmail)
pip install "skillware[office_gmail_handler,gemini]"
Set `GOOGLE_API_KEY`, `GMAIL_ADDRESS`, and `GMAIL_APP_PASSWORD` in `.env` ([API keys](docs/usage/api_keys.md)). Then run the interactive loop:
python examples/gemini_gmail_minimal.py
Minimal wiring:
from skillware.core.env import load_env_file
from skillware.core.loader import SkillLoader
import google.genai as genai
from google.genai import types
load_env_file()
bundle = SkillLoader.load_skill("office/gmail_handler")
skill = bundle["class"]()
chat = genai.Client().chats.create(
model="gemini-3.5-flash",
config=types.GenerateContentConfig(
tools=[SkillLoader.to_gemini_tool(bundle)],
system_instruction=bundle["instructions"],
),
)
# Loop: chat.send_message(user) → skill.execute(tool args) → from_function_response**What happens:** `SkillLoader` loads the bundle (manifest, `instructions.md`, Effect class) and adapts it to a Gemini tool → Gemini receives your message plus the skill directive and calls the tool → `skill.execute()` runs structured Gmail actions (resolve recipients from the address book, search/read inbox, preview or send mail) over your dedicated agent mailbox → results (`status`, previews, `agent_hint`) return to Gemini via `from_function_response` so the model can confirm with you before sends and continue the conversation.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 289 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <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-F4ECC8?style=flat-square" alt="License">
- <img src="https://img.shields.io/badge/Python-3.10+-DBD3DC?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=C7E4CA" alt="PyPI Version"></a>
- <a href="https://skillware.site/bench/"><img src="https://img.shields.io/badge/Evals-Bench-D4E4F1?style=flat-square" alt="Evals | Bench"></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=F0D9CC" 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="#comparison">Comparison</a> •
- <a href="#architecture">Architecture</a> •
- <a href="#supported-agent-skill-categories">Skill categories</a> •
- <a href="#quick-start">Quick Start</a> •
- <a href="#documentation">Documentation</a> •
- <a href="#contributing">Contributing</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 a host agent needs to use a capability in 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 [Supported Agent Skill Categories](#supported-agent-skill-categories), the [Skill library](docs/skills/README.md), the [documentation sitemap](docs/sitemap.md), or on our <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">site ↗</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:`).
- ## Comparison
- Most agent frameworks treat capabilities as prompt recipes, markdown checklists, or loose protocol wrappers that ask models to generate code on the fly. Skillware treats capabilities as versioned software modules: self-contained bundles pairing typed contracts, tested Python logic, agent directives, and offline assurance suites. Pre-compiled host execution decouples capability from model hallucination and eliminates the trial-and-error debugging loops inherent in unstructured tool calling.
- Every skill in the registry is curated, tested, and steered by ARPA Hellenic Logical Systems rather than aggregated from thousands of unvetted, arbitrary third-party uploads. At runtime, dumping full tool documentation degrades model reasoning and inflates token costs. Through just-in-time progressive disclosure, `SkillContext` mounts compact one-line taxonomy briefs upfront (~45 tokens per skill) and unlocks full playbooks only when an action is dispatched, excising up to 85% of redundant prompt tokens.
- <div align="center">
- <img src="https://raw.githubusercontent.com/ARPAHLS/skillware-bench/main/docs/figures/fig11_latency_anatomy.png" alt="Latency anatomy across execution stages" width="100%" />
- </div>
- > **Latency anatomy across execution stages:** JIT context excision shrinks prefill latency, compact model routing accelerates decoding, and deterministic host validation eliminates error-retry loops, cutting end-to-end median latency by 55.6% and collapsing time-to-first-token (TTFT).
- Mission-critical enterprise workflows—such as financial transaction screening, regulatory compliance forensics, and sensor telemetry normalization—cannot afford prompt ambiguity, hallucinated edge cases, or non-deterministic event triggers. Security is embedded directly into the framework: isolated credential providers prevent ambient process leakage, AST audits prohibit runtime code synthesis, and hardware execution gates protect physical substrates. Executing pre-verified code paths replaces erratic model behavior with tight, deterministic score distributions essential for CI/CD release gating.
- <div align="center">
- <img src="https://raw.githubusercontent.com/ARPAHLS/skillware-bench/main/docs/figures/fig14_run_to_run_determinism.png" alt="Run-to-run determinism and variance contraction" width="100%" />
- </div>
- > **Run-to-run determinism across 40 seeded replays:** Unassisted script generation scatters across an erratic score distribution (mean 61.0, σ = 4.1). Skillware contracts run-to-run variance by 5.1× (mean 88.2, σ = 0.8), establishing the reproducibility needed for regulated enterprise production.
- To see how Skillware architecturally compares against MCP, Agent Skills, Antigravity, and LangChain, read [COMPARISON.md](COMPARISON.md). For empirical telemetry, stress crucibles, and 23-model benchmark evaluations, visit the [Skillware-Bench repository](https://github.com/ARPAHLS/skillware-bench).
- ## 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, category hubs (docs/skills/<category>/), 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/ # Standard template with required files
- └── tests/ # Clone-repo tests (framework + optional maintainer skill tests)
- ├── test_*.py # Framework tests (loader, CLI, issuer, …)
- └── skills/ # Optional maintainer skill tests (edge cases)
- ```
- ## Supported Agent Skill Categories
- Category hubs live under `docs/skills/<category>/`. Full catalog: [Skill library](docs/skills/README.md). Crawl map: [documentation sitemap](docs/sitemap.md).
- | Category | Skills | Description |
- | :--- | :---: | :--- |
- | [Data Engineering](docs/skills/data_engineering/README.md) | 5 | Datasets, generation, and ETL-style tooling |
- | [Compliance](docs/skills/compliance/README.md) | 3 | Privacy, policy, and regulatory guardrails |
- | [DeFi](docs/skills/defi/README.md) | 3 | On-chain ops, trading, and agent wallet management |
- | [Monitoring](docs/skills/monitoring/README.md) | 3 | Agent loop observability, budget gates, RPC health, and task control |
- | [Office](docs/skills/office/README.md) | 3 | Documents, desktop work, and productivity automation |
- | [Security](docs/skills/security/README.md) | 3 | Defenses for untrusted input reaching logical systems |
- | [Creative](docs/skills/creative/README.md) | 2 | Image processing, media editing, and creative utilities |
- | [Finance](docs/skills/finance/README.md) | 2 | Fintech, blockchain, payments, and financial services |
- | [Optimization](docs/skills/optimization/README.md) | 2 | Middleware, efficiency, and token economics |
- | [Bio](docs/skills/bio/README.md) | 1 | Life sciences, bioinformatics, genomics, and biotechnology |
- | [Dev Tools](docs/skills/dev_tools/README.md) | 1 | Developer workflows, repo tooling, and coding |
- | [Linguistics](docs/skills/linguistics/README.md) | 1 | Language adapters and internet-register lexicons |
- | [Networking](docs/skills/networking/README.md) | 1 | Egress proxy rotation, multi-region inspection, and transport middleware |
- | [Wellness](docs/skills/wellness/README.md) | 1 | Coaching guardrails and mental health support |
- ## Quick Start
- Requires **Python 3.10 or newer** (see `requires-python` in `pyproject.toml`).
- ### 1. Installation
- You can install Skillware directly from PyPI:
- ```bash
- pip install skillware
- ```
- Or for development, clone the repository and install in editable mode:
- ```bash
- git clone https://github.com/arpahls/skillware.git
- cd skillware
- pip install -e ".[dev,all]"
- ```
- For documentation-only work, `pip install -e ".[dev]"` is enough. Skill and framework contributors should use `[dev,all]` to match CI (see [TESTING.md](docs/TESTING.md) and [Install extras](docs/usage/install_extras.md)).
- > **Note**: Every skill has a dedicated pip extra (`pip install "skillware[category_skill]"`). The `SkillLoader` validates `manifest.yaml` on load and suggests the matching extra when packages are missing. See [Install extras](docs/usage/install_extras.md).
- ### 2. Verify your installation
- ```bash
- skillware list
- skillware paths
- ```
- You should see a table of bundled registry skills and a paths summary confirming install and discovery. **Bundled skills from `pip install skillware` are always available** — an empty local `skills/` folder does not disable them.
- For path tiers, shadowing, config files, and the interactive menu, see [CLI — paths & tiers](docs/usage/cli.md#skillware-paths), [CLI — config](docs/usage/cli.md#skillware-config), and [Finding skills on disk](docs/usage/README.md#finding-skills-on-disk). If `skillware` is not on your PATH, use `python -m skillware list` ([CLI Reference](docs/usage/cli.md#running-the-cli)).
- ### 3. Configuration
- **Skill paths (optional):** copy [`.skillware.yaml.example`](.skillware.yaml.example) to `.skillware.yaml` in your project root, or use the interactive menu (**`4` / `paths`**) to persist project and external skill roots. Inspect merged settings with `skillware config show`. See [CLI — config](docs/usage/cli.md#skillware-config).
- **API keys:** copy the environment template and add your keys.
- **Unix / macOS:**
- ```bash
- cp .env.example .env
- ```
- **Windows (PowerShell):**
- ```powershell
- Copy-Item .env.example .env
- ```
- Edit `.env` with agent keys (for example Gemini) and any keys your skills need. Agent keys power your LLM client; skill keys are declared per skill in the [Skill library](docs/skills/README.md). Operator files (`skillware addressbook init`, `skillware evm init`) live under `~/.config/skillware/` and survive upgrades. See [API keys for skills](docs/usage/api_keys.md) for `.env` setup, [Address book operator config](docs/usage/addressbook_operator_config.md), and `skillware doctor`.
- ### 4. Usage Example (Gemini + Gmail)
- ```bash
- pip install "skillware[office_gmail_handler,gemini]"
- ```
- Set `GOOGLE_API_KEY`, `GMAIL_ADDRESS`, and `GMAIL_APP_PASSWORD` in `.env` ([API keys](docs/usage/api_keys.md)). Then run the interactive loop:
- ```bash
- python examples/gemini_gmail_minimal.py
- ```
- Minimal wiring:
- ```python
- from skillware.core.env import load_env_file
- from skillware.core.loader import SkillLoader
- import google.genai as genai
- from google.genai import types
- load_env_file()
- bundle = SkillLoader.load_skill("office/gmail_handler")
- skill = bundle["class"]()
- chat = genai.Client().chats.create(
- model="gemini-3.5-flash",
- config=types.GenerateContentConfig(
- tools=[SkillLoader.to_gemini_tool(bundle)],
- system_instruction=bundle["instructions"],
- ),
- )
- # Loop: chat.send_message(user) → skill.execute(tool args) → from_function_response
- ```
- **What happens:** `SkillLoader` loads the bundle (manifest, `instructions.md`, Effect class) and adapts it to a Gemini tool → Gemini receives your message plus the skill directive and calls the tool → `skill.execute()` runs structured Gmail actions (resolve recipients from the address book, search/read inbox, preview or send mail) over your dedicated agent mailbox → results (`status`, previews, `agent_hint`) return to Gemini via `from_function_response` so the model can confirm with you before sends and continue the conversation.
- More providers and patterns: [usage guides](docs/usage/README.md).
- ## Documentation
- | Topic | Links |
- | :--- | :--- |
- | **Introduction** | [Introduction](docs/introduction.md) · [Vision](docs/vision.md) · [Comparison](COMPARISON.md) |
- | **Usage guides** | [Skill Library](docs/skills/README.md) · [Category hubs](#supported-agent-skill-categories) · [Sitemap](docs/sitemap.md) · [Usage Guide](docs/usage/README.md) · [Skill chaining](docs/usage/skill_chaining.md) · [Gemini](docs/usage/gemini.md) · [Enterprise cloud](docs/usage/enterprise_cloud.md) · [OpenAI-compatible hosts](docs/usage/openai_compatible.md) · [Install extras](docs/usage/install_extras.md) · [Examples](examples/README.md) · [Agent Loops](docs/usage/agent_loops.md) · [API Keys](docs/usage/api_keys.md) · [CLI](docs/usage/cli.md) |
- | **Operator config** | [EVM operator config](docs/usage/evm_operator_config.md) · [Address book operator config](docs/usage/addressbook_operator_config.md) |
- | **Security** | [Skill trust model](docs/security/skill-trust-model.md) · [SECURITY.md](SECURITY.md) |
- | **Contributing** | [Contributing](CONTRIBUTING.md) · [Glossary](docs/glossary.md) · [Agent Native Workflow](docs/contributing/ai_native_workflow.md) · [Testing](docs/TESTING.md) · [Changelog](CHANGELOG.md) |
- ## Contributing
- Skills, docs, tests, and framework fixes are welcome. Start with [Contributing](CONTRIBUTING.md), the [glossary](docs/glossary.md), [Agent Native Workflow](docs/contributing/ai_native_workflow.md), and [Testing](docs/TESTING.md). See the [Agent Code of Conduct](CODE_OF_CONDUCT.md). Open PRs with the [pull request template](.github/PULL_REQUEST_TEMPLATE.md).
- ## Stats
- <a href="https://pepy.tech/projects/skillware"><img src="https://img.shields.io/badge/Stats-PePyTech-F0D9CC?style=flat-square" alt="PePy.tech dashboard"></a>
- <a href="https://pypistats.org/packages/skillware"><img src="https://img.shields.io/badge/Stats-PyPiStats-F0D9CC?style=flat-square" alt="PyPI Stats dashboard"></a>
- PyPI download counts measure **install activity** from public aggregators (including CI and mirrors), not unique users. Use the badge links above for charts and version breakdowns.
- ## Citing
- <a href="https://doi.org/10.48550/arXiv.2611.07652"><img src="https://img.shields.io/badge/Paper-F4ECC8?style=flat-square" alt="Paper"></a>
- <a href="https://doi.org/10.5281/zenodo.21552745"><img src="https://img.shields.io/badge/Software-DBD3DC?style=flat-square" alt="Software"></a>
- <a href="https://doi.org/10.5281/zenodo.23725543"><img src="https://img.shields.io/badge/Bench-D4E4F1?style=flat-square" alt="Bench"></a>
- <br/>
- <a href="https://doi.org/10.48550/arXiv.2611.07652"><img src="https://img.shields.io/badge/DOI%20P-10.48550%2FarXiv.2611.07652-F4ECC8?style=flat-square" alt="DOI 10.48550/arXiv.2611.07652"></a><br/>
- <a href="https://doi.org/10.5281/zenodo.21552745"><img src="https://img.shields.io/badge/DOI%20S-10.5281%2Fzenodo.21552745-DBD3DC?style=flat-square" alt="DOI 10.5281/zenodo.21552745"></a><br/>
- <a href="https://doi.org/10.5281/zenodo.23725543"><img src="https://img.shields.io/badge/DOI%20B-10.5281%2Fzenodo.23725543-D4E4F1?style=flat-square" alt="DOI 10.5281/zenodo.23725543"></a>
- If you use Skillware in research or products, please cite it using [CITATION.cff](https://github.com/ARPAHLS/skillware/blob/main/CITATION.cff) (GitHub Cite this repository) or the Zenodo concept DOI above (DOI S). That DOI is stable across releases. For reproducibility, also record the Skillware version you used (PyPI or Git tag, for example 0.6.1). For citing the paper, use the arxiv DOI above (DOI P).
- ## Contact
- For questions, suggestions, or contributions, please open an issue or reach out to us:
- * **Email**: [skillware-os@arpacorp.net](mailto:skillware-os@arpacorp.net)
- * **Enterprise**: [skills@arpacorp.net](mailto:skills@arpacorp.net) — enterprise skills, chaining, and forward deployed engineering
- * **Security**: [security@arpacorp.net](mailto:security@arpacorp.net) — report bugs, vulnerabilities, or other sensitive issues (see [SECURITY.md](SECURITY.md))
- * **Issues**: [GitHub Issues](https://github.com/arpahls/skillware/issues)
- For skill-specific questions or reaching a skill's maintainer, check issuer and author details on the skill card, in the repo [Skill Library](docs/skills/README.md), or on our website's <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">skills catalog ↗</a>.
- ---
- <div align="center">
- <img src="assets/arpalogo.png" alt="ARPA Logo" width="50px" />
- <br/>
- Built & Maintained by ARPA Hellenic Logical Systems & the Community
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.