<div align="center">

<img src="skillsmith_hero_banner_1774380976071.png" width="100%" alt="Skillsmith Hero Banner">

# ⚡ Skillsmith: The Agentic OS
### The Infrastructure Layer for AI-Assisted Engineering

[![PyPI version](https://img.shields.io/pypi/v/skillsmith.svg?color=blue&style=flat-square)](https://pypi.org/project/skillsmith/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Stars](https://img.shields.io/github/stars/ApexIQ/skillsmith?style=social)](https://github.com/ApexIQ/skillsmith)
[![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289da?style=flat-square&logo=discord)](https://discord.gg/skillsmith)

**Standardize instructions. Evolve skills. Orchestrate swarms.**

[Overview](#-the-vision) • [Competitive Moat](#-the-competitive-moat) • [Quick Start](#-high-velocity-setup) • [Pillars](#-architectural-pillars) • [Command Reference](docs/COMMANDS.md)

</div>

---

## 🚀 The Vision

**Skillsmith** isn't just a linter or a template generator. It is the **Intelligence Backbone** for professional engineering teams in the era of Agentic AI. 

While LLMs are powerful, they are context-poor and structurally drift. **Skillsmith** solves this by turning static codebase rules into dynamic, **Self-Evolving Skills-as-Code**. It bridges the gap between raw AI inference and production-grade software delivery.

---

## 🛡️ The Competitive Moat

Skillsmith v1.0 introduces features that place it at the absolute frontier of AI engineering:

### 🌍 Ecosystem Discovery (CLI Hub)
Stop hunting for prompts. Use `skillsmith search` to query the sovereign **Ghost-Content** index of **889+ skills** directly from your terminal. See global categories, filter by tech stack, and install them instantly.

### 🐝 Multi-Agent Swarm Orchestration
Stop running in single-agent loops. Skillsmith can decompose massive goals into **Parallelized Task Graphs** (`skillsmith swarm plan`), assigning specialized roles (**Orchestrator, Researcher, Implementer, Reviewer**) to coordinate complex missions across multiple agent threads via `skillsmith team-exec`.

### 🧬 Autonomous Self-Healing (v1.1.0+)
Skillsmith now autonomously detects performance regressions. If a benchmark score falls below threshold, the **Self-Correction Loop** automatically generates repair packets and applies logic patches to your `SKILL.md` library.

### 🔌 MCP Native Support (Zero Context Bloat)
Expose your entire skill library to any AI tool (Claude Desktop, Cursor, Gemini) via the **Skillsmith MCP Server**.
```bash
# Start the MCP server (stdio for local agents)
skillsmith serve
```

---
### 🌲 Recursive Thinking Trees
When a strategy fails, Skillsmith doesn't just retry. It uses recursive **AND/OR Thinking Trees** (`skillsmith tree`) to resolve goals, exploring multiple implementation paths and strategy fallbacks before a single line of bad code is written.

---

## 🏁 High-Velocity Setup

### 1. Install
```bash
pip install "skillsmith[mcp]"
```

### 2. Initialize (Sovereign Ghost-Sync)
```bash
# Sync 889+ expert skill packs natively
skillsmith init --bundle python-pro
```

### 3. Evolve & Self-Heal (v1.1.0) 🌌🧪
Skillsmith now monitors its own accuracy.
```bash
# Run benchmark and auto-repair degraded skills
skillsmith eval --auto-evolve

# Manually trigger a fix for a specific skill
skillsmith evolve --mode fix --name python-expert
```

### 4. Serve your Library (MCP) 🔌
Expose your skills to external agents with on-demand retrieval.
```bash
skillsmith serve --transport http --port 3333
```

### 4. Align & Certify
```bash
# Keeps your Claude commands, Cursor rules, and IDE instructions 100% in sync.
skillsmith align
skillsmith doctor
```

### 4. Deploy a Swarm
```bash
# Decompose a complex mission into a parallel multi-agent plan.
skillsmith swarm plan "Refactor the entire auth module for OAuth2 parity"
```

---

## 🏗️ Architectural Pillars

| Pillar | Focus | Capability |
|:---|:---|:---|
| **Pillar 1: Structural Integrity** | **Zero Drift** | Unified instructions across **Claude, Cursor, Windsurf, Zencoder, Copilot**. |
| **Pillar 2: Autonomous Evolution** | **Self-Improvement** | Skills that auto-learn from history and code structures (**XSkill/EvoSkill**). |
| **Pillar 3: Team Intelligence** | **Swarm Logic** | Role-based execution with structured handoffs and verification loops. |

---

## 🌍 Codebase Knowledge (CK) Bridge
Skillsmith now integrates **Architectural Intelligence** through the CK Bridge. By running `skillsmith understand sync --deep`, the system builds a high-fidelity **Knowledge Graph** of your repository, enabling subagents to detect architectural hotspots and hotspots before they plan a mission.

---

## 🍱 Onboarding & Documentation
For new users and teams, we have introduced a comprehensive learning path:

1.  **[Bit-by-Bit Guide](docs/BIT_BY_BIT_GUIDE.md)**: A level-up journey from basic induction to autonomous evolution.
2.  **[The Mission Cookbook](docs/COOKBOOK.md)**: 50+ real-world recipes (Goal/Tools/Recipe/Signal) for building complex software.
3.  **[Command Registry](docs/BIT_BY_BIT_GUIDE.md#appendix-the-complete-command-registry)**: Full 77+ command map (CLI + Slash).

---

## 🤖 Power Commands for Top-Tier Performance

- `skillsmith start` — Bootstrap a new repo to readiness in one command.
- `skillsmith commands` — Unified God-View of all 77+ terminal and chat commands.
- `skillsmith cookbook` — Instant preview of mission recipes.
- `skillsmith understand` — Sync architectural intelligence (CK).

---

## 📈 Roadmap: The Path to v2.0

- [x] **v0.9**: Autonomous Evolution (XSkill Phase 1)
- [x] **v1.0**: Competitive Evolution (Swarms & Thinking Trees)
- [x] **v1.1**: **Self-Healing Skills & MCP Integration**
- [ ] **v2.0**: **The Collective** — Decentralized skill sharing & autonomous agent economies.

---

## 📄 License
MIT © ApexIQ

<div align="center">
Built by the Google Deepmind team for those who engineer at the speed of thought.
</div>


