Metadata-Version: 2.4
Name: skills-tree
Version: 1.0.3
Summary: Architect — taxonomy-driven skill recommendation engine for AI agent builders
License: MIT License
        
        Copyright (c) 2026 Ossama Hashim (https://github.com/SamoTech)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/SamoTech/skills-tree
Project-URL: Documentation, https://github.com/SamoTech/skills-tree#readme
Project-URL: Repository, https://github.com/SamoTech/skills-tree
Project-URL: Bug Tracker, https://github.com/SamoTech/skills-tree/issues
Keywords: ai,agents,skills,recommendation,llm,taxonomy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: networkx>=3.0
Requires-Dist: markdown>=3.5
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Provides-Extra: server
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "server"
Dynamic: license-file

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/SamoTech/skills-tree/main/docs/assets/logo-dark.svg">
  <img src="https://raw.githubusercontent.com/SamoTech/skills-tree/main/docs/assets/logo-light.svg" alt="Skills Tree" width="200" height="52">
</picture>

# Skills Tree

![Banner](docs/assets/banner.svg)

<!-- HIGHLIGHTS_START -->
## 📆 This Week's Highlights — June 15, 2026

### 🔥 Most Active Skills
- **Readme** — 1 PR
- **Xquik Api** — 1 PR

<!-- HIGHLIGHTS_END -->


### The AI Agent Skill OS — Build Smarter Agents, Faster

> **360 skills across 17 categories. Versioned, benchmarked, and openly evolving.**  
> **Stop rediscovering. Start building on what the community has already proven.**
>
> **50 skills are battle-tested today.** **308 are stubs** waiting for a real example, real I/O, and real failure modes — see [`meta/QUALITY-REPORT.md`](meta/QUALITY-REPORT.md) for the full list. PRs that turn a stub into a production-ready entry are the highest-impact contribution you can make.

[![Stars](https://img.shields.io/github/stars/SamoTech/skills-tree?style=for-the-badge&color=22c55e&logo=github)](https://github.com/SamoTech/skills-tree/stargazers)
[![Forks](https://img.shields.io/github/forks/SamoTech/skills-tree?style=for-the-badge&color=3b82f6&logo=github)](https://github.com/SamoTech/skills-tree/network)
[![Watchers](https://img.shields.io/github/watchers/SamoTech/skills-tree?style=for-the-badge&color=a855f7&logo=github)](https://github.com/SamoTech/skills-tree/watchers)
[![Views](https://visitor-badge.laobi.icu/badge?page_id=SamoTech.skills-tree&style=for-the-badge&color=0e75b6&label=Views)](https://github.com/SamoTech/skills-tree)
[![Issues](https://img.shields.io/github/issues/SamoTech/skills-tree?style=for-the-badge&color=ef4444&logo=github)](https://github.com/SamoTech/skills-tree/issues)
[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen?style=for-the-badge)](CONTRIBUTING.md)
[![Contributors](https://img.shields.io/github/contributors/SamoTech/skills-tree?style=for-the-badge&color=f59e0b&logo=github)](https://github.com/SamoTech/skills-tree/graphs/contributors)
[![Last Commit](https://img.shields.io/github/last-commit/SamoTech/skills-tree?style=for-the-badge&color=06b6d4&logo=github)](https://github.com/SamoTech/skills-tree/commits/main)
[![Repo Size](https://img.shields.io/github/repo-size/SamoTech/skills-tree?style=for-the-badge&color=8b5cf6&logo=github)](https://github.com/SamoTech/skills-tree)
[![CI](https://img.shields.io/github/actions/workflow/status/SamoTech/skills-tree/validate-skills.yml?branch=main&style=for-the-badge&label=CI&logo=github-actions&logoColor=white)](https://github.com/SamoTech/skills-tree/actions/workflows/validate-skills.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)
[![Skills](https://img.shields.io/badge/Skills-360%2B-8b5cf6?style=for-the-badge)](skills/)
[![Version](https://img.shields.io/badge/Version-2.0-orange?style=for-the-badge)](meta/CHANGELOG.md)
[![GitHub Pages](https://img.shields.io/badge/Docs-Live-22c55e?style=for-the-badge&logo=github)](https://samotech.github.io/skills-tree)

**[🌐 Browse Live UI](https://samotech.github.io/skills-tree) · [🗺️ Systems](systems/) · [🏗️ Blueprints](blueprints/) · [📊 Benchmarks](benchmarks/) · [🔬 Labs](labs/) · [🤝 Contribute](CONTRIBUTING.md) · [🗺 Roadmap](meta/ROADMAP.md)**

[🐦 **Share Skills Tree on X / Twitter →**](https://twitter.com/intent/tweet?text=Skills%20Tree%20%E2%80%94%20the%20shared%20operating%20system%20for%20AI%20agent%20capabilities.%20Working%20code,%20real%20benchmarks,%20failure%20modes,%20and%20evolution%20history.&url=https%3A%2F%2Fgithub.com%2FSamoTech%2Fskills-tree&hashtags=AI,Agents,LLM,OpenSource)

🌐 **Read in your language:**
🇬🇧 English
· [🇸🇦 العربية](i18n/README.ar.md)
· [🇨🇳 中文](i18n/README.zh.md)
· [🇪🇸 Español](i18n/README.es.md)
· [🇩🇪 Deutsch](i18n/README.de.md)
· [🇫🇷 Français](i18n/README.fr.md)
· [🇮🇳 हिन्दी](i18n/README.hi.md)
· [🇯🇵 日本語](i18n/README.ja.md)
· [🇰🇷 한국어](i18n/README.ko.md)
· [🇧🇷 Português](i18n/README.pt.md)
· [🇷🇺 Русский](i18n/README.ru.md)

</div>

---

## The Problem

Every AI agent builder rediscovers the same skills from scratch.

Someone learns RAG the hard way. Someone else figures out memory injection at 2am. A third person spends a week benchmarking ReAct vs LATS — and never shares the results. A fourth discovers the same failure modes you already hit last month.

**That collective knowledge is disappearing into Slack threads, private repos, and Twitter bookmarks.**

Skills Tree fixes that.

---

## What This Is

**Skills Tree is the shared operating system for AI agent capabilities.**

A living, versioned, community-powered index of everything an agent can do — at its best, documented with working code, real benchmarks, failure modes, and evolution history.

We don't pretend every entry is finished. **Battle-tested skills (badged 🟢 verified) are production-ready and copy-paste safe.** Yellow / unscanned skills are the community's TODO list — open files, real problem space, and the clearest signal of where contributions are most useful.

It's not a list. It's infrastructure being built in public.

---

## 🚀 Start Here — Battle-Tested Skills

If you're new, **read these first**. Each one ships with runnable code, typed I/O, failure modes, and a model-comparison table.

### Agent reasoning loops
- [**ReAct**](skills/09-agentic-patterns/react.md) — Thought → Action → Observation, the foundation of tool-using agents
- [**Chain of Thought**](skills/09-agentic-patterns/cot.md) — explicit step-by-step reasoning + self-consistency
- [**Tree of Thought**](skills/09-agentic-patterns/tot.md) — branched reasoning with scoring + beam search
- [**Reflection / Reflexion**](skills/09-agentic-patterns/reflection.md) — critique → revise loop on top of any output
- [**Self-Consistency**](skills/02-reasoning/self-consistency.md) — sample N chains, majority-vote
- [**Planning**](skills/02-reasoning/planning.md) — typed, DAG-validated plans your executor can run
- [**Task Decomposition**](skills/02-reasoning/task-decomposition.md) — break a goal into atomic, runnable subtasks

### Retrieval & memory
- [**RAG**](skills/03-memory/rag.md) — chunk → embed → retrieve → cite, end-to-end with confidence + threshold
- [**Vector Store Retrieval**](skills/03-memory/vector-store-retrieval.md) — typed top-k cosine search with metadata filtering
- [**Embedding Generation**](skills/12-data/embedding-generation.md) — batched, content-hash-cached, Matryoshka-truncatable
- [**Memory Injection**](skills/03-memory/memory-injection.md) — top-K user memories per turn
- [**Short-Term Memory**](skills/03-memory/short-term-memory.md) — token-budgeted rolling window (the foundation for everything else)

### Calling LLMs in production
- [**Function / Tool Calling**](skills/07-tool-use/function-calling.md) — the primitive that turns an LLM into an agent
- [**OpenAI API**](skills/07-tool-use/openai-api.md) — chat, structured outputs, tools, embeddings, streaming, retry
- [**Anthropic API**](skills/07-tool-use/anthropic-api.md) — Claude with tool loop, prompt caching, streaming

### Working with text
- [**Translation**](skills/06-communication/translation.md) — placeholder-safe MT with glossary + tone
- [**Paraphrasing**](skills/06-communication/paraphrasing.md) — simplify / formalize / diversify
- [**OCR**](skills/01-perception/ocr.md) — VLM + classical OCR with confidence-based human-review routing

### Code
- [**Code Generation**](skills/05-code/code-generation.md) — spec → AST-validated source with self-repair on failure
- [**Bug Fixing**](skills/05-code/bug-fixing.md) — agentic loop: read → patch → test → repeat until green
- [**Code Review**](skills/05-code/code-review.md) — automated critique with severity tiers

### Web
- [**Web Search**](skills/11-web/web-search.md) — Tavily/Serper/Brave with recency + host allowlist + TTL cache
- [**Web Scraping**](skills/11-web/web-scraping.md) — trafilatura + BS4 fallback, metadata, redirect-safe

### Security
- [**Input Sanitization**](skills/14-security/input-sanitization.md) — 4-layer defense: structural + boundary + content + isolation

### Action execution
- [**File Write**](skills/04-action-execution/file-write.md) — atomic, crash-safe file writes for agents
- [**HTTP Request**](skills/04-action-execution/http-request.md) — production HTTP with idempotency, retry-on-idempotent-only, header redaction
- [**Dependency Auditor**](skills/17-infrastructure/dependency-auditor.md) — vulnerability + license + freshness audit

> **The full battle-tested set is auto-listed in [`meta/QUALITY-REPORT.md`](meta/QUALITY-REPORT.md). The same report names every stub that needs upgrading — those are the highest-impact PRs you can submit.**

---

## What's Inside

```
skills-tree/
│
├── skills/          → 360 atomic skill files (50 battle-tested, 308 stubs awaiting upgrade)
│                     run `python3 tools/check_skill_quality.py` for the live count
├── systems/         → Multi-skill workflows (research agent, code reviewer...)
├── blueprints/      → Copy-paste production architectures
├── benchmarks/      → Head-to-head, reproducible skill comparisons
├── labs/            → Experimental & bleeding-edge capabilities
│
├── docs/            → Interactive web UI (GitHub Pages)
├── i18n/            → Localized READMEs (Arabic, Chinese, Spanish, German, French, Hindi, Japanese, Korean, Portuguese, Russian)
├── meta/            → Schema, glossary, frameworks, roadmap, changelog
└── requirements.txt → Pinned Python deps for CI workflows
```

---

## 🗂️ The 17 Skill Categories

| # | Category | Skills | What It Covers |
|---|---|---|---|
| 01 | 👁️ **Perception** | 36 | Text, images, PDFs, code, sensors, databases, screens |
| 02 | 🧠 **Reasoning** | 39 | Planning, deduction, abduction, causal chains, commonsense |
| 03 | 🗄️ **Memory** | 19 | Working, episodic, semantic, vector, injection, forgetting |
| 04 | ⚡ **Action Execution** | 21 | File I/O, HTTP, email, shell, database writes |
| 05 | 💻 **Code** | 28 | Write, run, debug, review, refactor, test, deploy |
| 06 | 💬 **Communication** | 15 | Summarize, translate, draft, argue, adapt tone |
| 07 | 🔧 **Tool Use** | 32 | APIs — GitHub, Slack, Stripe, OpenAI, MCP, A2A |
| 08 | 🎭 **Multimodal** | 14 | Images, audio, video, VQA, 3D, charts |
| 09 | 🤖 **Agentic Patterns** | 23 | ReAct, CoT, ToT, MCTS, LATS, RAG, Debate |
| 10 | 🖥️ **Computer Use** | 20 | Click, type, scroll, OCR, terminal, VM, a11y tree |
| 11 | 🌐 **Web** | 17 | Search, scrape, crawl, login, fill forms, parse RSS |
| 12 | 📊 **Data** | 18 | ETL, SQL, embeddings, time series, anomaly detection |
| 13 | 🎨 **Creative** | 14 | Copywriting, image prompts, SVG, music, scripts |
| 14 | 🔒 **Security** | 13 | Sandboxing, secret scanning, audit logs, rollback |
| 15 | 🎼 **Orchestration** | 22 | Multi-agent, state machines, retry, consensus |
| 16 | 🏺 **Domain-Specific** | 28 | Medical, legal, finance, DevOps, education, science |
| 17 | 🛠️ **Infrastructure** | 1 | Dependency auditing & supply-chain tooling (early) |

> Counts above reflect skill files on disk and are auto-synced by `tools/update_readme_counts.py` (run nightly via [`update-skill-count.yml`](.github/workflows/update-skill-count.yml)). If you spot a drift, open an issue.

---

## A Skill in 60 Seconds

Every skill file is self-contained and production-ready:

````markdown
# Memory Injection
Category: memory | Level: intermediate | Stability: stable | Version: v2

## Description
Dynamically inject relevant past memories into an agent's system prompt
before each turn — giving the model user context without filling the window.

## Example
```python
client.messages.create(
    system=f"{base_system}\n\n## Memory\n{top_k_memories}",
    messages=[{"role": "user", "content": user_message}]
)
```

## Benchmarks  → benchmarks/memory/injection-strategies.md
## Related     → working-memory.md · rag.md · vector-store-retrieval.md
## Changelog   → v1 (2025-03) · v2 (2026-04, added retrieval scoring)
````

Every skill includes:
- ✅ What it does and why it matters
- ✅ Typed inputs/outputs
- ✅ Runnable Python code (`claude-opus-4-5` / `gpt-4o`)
- ✅ Frameworks table (LangChain, LangGraph, CrewAI, mem0...)
- ✅ Failure modes and edge cases
- ✅ Related skills cross-links
- ✅ Version history

---

## Skill Versioning — How Evolution Works

Skills are not static files. They evolve as the community learns:

```
v1 — Initial entry: description + minimal example
v2 — Enriched: better example + failure modes + related skills
v3 — Battle-tested: benchmarks + model comparison + production notes
```

**To upgrade a skill:**
1. Bump the version in frontmatter
2. Add a changelog entry explaining what improved
3. Open a PR titled `improve: skill-name — v1 → v2`

The best versions surface naturally — through PR merge frequency and inclusion in Systems + Blueprints.

---

## 🗺️ Systems — Multi-Skill Workflows

See how skills combine into real, working agent pipelines:

| System | Skills Used | Use Case |
|---|---|---|
| [Research Agent](systems/research-agent.md) | Web search + RAG + Summarize + Cite | Deep research automation |
| [Coding Agent](systems/coding-agent.md) | Code reading + Write + Debug + Test | End-to-end code generation |
| [Code Reviewer](systems/code-reviewer.md) | Code reading + Reasoning + Comment gen | Automated PR reviews |
| [Data Pipeline Agent](systems/data-pipeline-agent.md) | DB reading + ETL + Anomaly detection | Automated data ops |
| [Customer Support Bot](systems/customer-support-bot.md) | Memory injection + Intent + Response gen | Personalized support |
| [Computer Use Agent](systems/computer-use-agent.md) | Screen reading + OCR + Click + Type | Full GUI automation |
| [Data Analyst](systems/data-analyst.md) | SQL + Charts + Summarize + Insight gen | Automated data analysis |
| [Voice Agent](systems/voice-agent.md) | Audio transcription + NLU + TTS | Real-time voice interaction |

---

## 🏗️ Blueprints — Production Architectures

Copy-paste architectures for the most common agent patterns:

| Blueprint | Description |
|---|---|
| [RAG Stack](blueprints/rag-stack.md) | Embed → store → retrieve → generate, fully wired |
| [Multi-Agent Workflow](blueprints/multi-agent-workflow.md) | Sequential orchestration with handoffs |
| [Multi-Agent Mesh](blueprints/multi-agent-mesh.md) | N specialists + orchestrator, parallel execution |
| [Computer Use Browser](blueprints/computer-use-browser.md) | Browser automation via Playwright + vision |
| [Human-in-the-Loop](blueprints/human-in-the-loop.md) | Approval gates, escalation, audit trails |
| [Self-Healing Agent](blueprints/self-healing-agent.md) | Error detection, retry logic, rollback |
| [Memory-First Agent](blueprints/memory-first-agent.md) | Profile + episodic + vector memory combined |

---

## 📊 Benchmarks — Real Numbers, Reproducible

We test so you don't have to:

| Benchmark | Winner | Margin | Link |
|---|---|---|---|
| ReAct vs LATS (HotpotQA) | LATS | +8.3% accuracy | [→](benchmarks/reasoning/react-vs-lats.md) |
| RAG retrieval strategies | HyDE | +12% recall | [→](benchmarks/memory/rag-retrieval-strategies.md) |
| Memory injection methods | Top-K semantic | Best cost/quality ratio | [→](benchmarks/memory/injection-strategies.md) |
| Function calling comparison | Claude 3.7 | +6% on tool accuracy | [→](benchmarks/tool-use/function-calling-comparison.md) |

> Every benchmark includes methodology, dataset, and reproducible test scripts.

---

## 🏆 This Week's Highlights

> Auto-updated weekly · [Full leaderboard →](meta/LEADERBOARD.md)

**🔥 Most Active Skills**
- `skills/09-agentic-patterns/react.md` — 12 community improvements this month
- `skills/03-memory/memory-injection.md` — v2 with retrieval scoring
- `skills/02-reasoning/causal.md` — new benchmark comparison added

**⚡ Battle-Tested** *(used in 10+ public projects)*
`ReAct` · `Chain of Thought` · `RAG Pipeline` · `Memory Injection` · `Tool Use`

**🔬 Hot in Labs**
- `labs/reasoning/tree-of-agents.md` — multi-agent tree search
- `labs/memory/episodic-compression.md` — lossy-but-useful memory compression
- `labs/tool-use/adaptive-tool-selection.md` — dynamic tool filtering for large registries

---

## 🤝 How to Contribute

Four types of contributions — all valued:

| Type | What It Is | PR Title Format |
|---|---|---|
| **New Skill** | A capability not yet indexed | `feat: add [skill] to [category]` |
| **Skill Upgrade** | Bump v1→v2 with better content | `improve: [skill] — v1→v2` |
| **Benchmark** | Head-to-head with real numbers | `benchmark: [skill-a] vs [skill-b]` |
| **System / Blueprint** | Multi-skill workflow or architecture | `system: add [name]` |

```bash
git clone https://github.com/SamoTech/skills-tree.git
cp meta/skill-template.md skills/05-code/my-new-skill.md
# Fill in every section → open a PR
```

### Quality Rules

- ❌ No generic prompts or vague descriptions
- ❌ No skills without a working code example
- ✅ Must solve a real, specific problem
- ✅ Must be structured and reusable
- ✅ Must include inputs, outputs, and at least one runnable example

Full guide: **[CONTRIBUTING.md](CONTRIBUTING.md)**

---

## Quick Start

```bash
# Clone
git clone https://github.com/SamoTech/skills-tree.git

# Find a skill by keyword
grep -r "memory injection" skills/ --include="*.md" -l

# Read a full system end-to-end
cat systems/research-agent.md

# See benchmark results
cat benchmarks/tool-use/function-calling-comparison.md
```

Or **[browse the live UI →](https://samotech.github.io/skills-tree)**

---

## Who This Is For

```
🏗️  Agent Builders       → Production skill patterns, ready to use today
🔬  AI Researchers        → Benchmarks, taxonomy, and full capability coverage
📐  System Architects     → Blueprints for multi-agent production systems
🎓  Learners              → Structured path from basic skills → advanced systems
🤝  Contributors          → A community that improves everything together
```

---

## 🗺️ Roadmap

See the full plan: **[meta/ROADMAP.md](meta/ROADMAP.md)**

**Near-term (v2.x):**
- Skill dependency graph — visual map of how skills relate
- Skill Paths — curated learning tracks (e.g., "Build a Research Agent in 5 skills")
- JSON/YAML export of all skill metadata for programmatic use
- Community skill ratings and upvotes
- Auto-leaderboard: Top Skills This Week, Most Improved, Battle-Tested

**Medium-term (v3.0):**
- CLI: `skills-tree search "memory injection"` → returns ranked results
- LangChain Hub / MCP registry integration
- ✅ ~~Localization: Arabic, Chinese, Spanish READMEs~~ — **shipped in v2.1**
- Automated changelog generation on PR merge

**Long-term vision:**
- Skills Tree becomes the canonical reference for AI agent capabilities
- Every major agent framework links here as the skill index
- 1000+ skills, all battle-tested, all benchmarked

---

## Vision

> AI agents are becoming teammates, not tools.
>
> Skills Tree is the shared foundation they run on — a living OS of capabilities
> that the community builds, tests, and evolves together.
>
> Every skill added here saves every agent builder who comes after you.
> Every benchmark run here prevents someone else from wasting a week.
> Every system documented here becomes a launchpad for the next builder.
>
> This is not a repo. It's infrastructure for the AI-native era.

---

<div align="center">

**[⭐ Star this repo](https://github.com/SamoTech/skills-tree) · [🌐 Browse Skills](https://samotech.github.io/skills-tree) · [🤝 Contribute](CONTRIBUTING.md) · [🗺 Roadmap](meta/ROADMAP.md) · [💖 Sponsor](https://github.com/sponsors/SamoTech)**

*The AI Agent Skill OS — built by the community, for the community.*

</div>
