<div align="center">

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

# ⚡ Skillsmith: The Agentic OS
### The $100M 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 Evolution (XSkill)
Your project instructions should learn from your wins. Use `skillsmith evolve` to capture structural engineering patterns from your Git history or raw source code. Skillsmith translates developer experience into repeatable, benchmarked agent skills automatically.

### 🌲 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
```

### 2. Initialize (Sovereign Ghost-Sync)
```bash
# Sync 889+ expert skill packs natively (No Node/NPX required!)
skillsmith init --bundle python-pro
# or guided setup with structural profiling
skillsmith init --guided
```

### 3. Search & Install (Global Ecosystem) 🌍
Explore 889+ expert skills archived in our sovereign ghost-content branch.
```bash
# Search for skills (v1.0.8+)
skillsmith search --categories
skillsmith search "authentication" --limit 5

# Install directly from the sovereign index
skillsmith add --remote awesome next-js-expert
```

### 4. Evolve & Evaluate (Phase 2.2) 🌌🧪
Skillsmith isn't static. It autonomously captures patterns from your Git history and **scores** your entire skill library (including Ghost Skills) against industry standards.

```bash
# Capture new patterns from recent Git history
skillsmith evolve capture --limit 50

# Benchmark and score your expert library
skillsmith evolve evaluate
```
This generates a **Skill Leaderboard** and detailed compatibility report in `.agent/evals/`.

### 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. |

---

## 🤖 Power Commands for Top-Tier Performance

Skillsmith injects a specialized command surface into your AI tools:

- `/swarm` — Decompose massive goals into parallelized agent graphs with integrated Thinking Tree artifacts in `.agent/TREE.md`.
- `/team-exec` — Execute missions with structured roles (O-R-I-R) and stateful `MISSION.md` updates.
- `/evolve` — Capture structural engineering patterns from experience.
- `/tree` — Strategic recursive reasoning for deep goal resolution; now supports `--output` for sharing strategic paths.
- `/ready` — High-speed pre-release sanity check (Git, Profile, Index).

---

## 📈 Roadmap: The Path to v2.0

- [x] **v0.7**: Content Gravity & 33+ Workflows
- [x] **v0.9**: Autonomous Evolution (XSkill Phase 1)
- [x] **v1.0**: **Competitive Evolution (Swarms & Thinking Trees)**
- [ ] **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>
