weave-compose

Platform-aware skill composition layer for AI coding tools.

"Everyone's building skills. Weave makes them work together."

How It Works

Weave ingests skills from AI coding tools (Claude Code, Cursor, Codex, Windsurf) and normalises them into a universal schema — a single Skill object with a name, platform, capabilities, and semantic embedding. At query time it embeds your task description and selects the best skill(s) by cosine similarity against every loaded skill, with no manual routing required. When a task spans multiple skills, Weave composes their contexts into a single merged string ready for injection into any AI coding tool.

Demo

Record your own: brew install vhs && vhs demo.tape

Installation

pip install weave-compose

Requires Python 3.11+. All embeddings run locally — no API key, no cloud dependency.

Quickstart

# 1. Create a minimal SKILL.md file
mkdir my-skills
cat > my-skills/SKILL.md << 'EOF'
---
description: React component design with Tailwind CSS and accessibility best practices.
capabilities: [react, tailwind, components, accessibility]
---
Always use semantic HTML. Never hardcode colours — use Tailwind tokens only.
EOF

# 2. Load and query
weave load ./my-skills
# Loaded 1 skill(s) from ./my-skills (platform: claude_code)
# Session saved to .weave_session.json

weave query "design a button component"
# [1] my-skills (claude_code) — score: 0.61
#     React component design with Tailwind CSS and accessibility best practices.

# 3. Explore further
weave list    # see all loaded skills
weave status  # session info and embedding model in use

CLI Reference

Session state is stored in .weave_session.json in your current working directory. Run weave load once; all subsequent query, list, and status calls restore the session automatically — no re-embedding required.

How Weave Selects Skills

Weave uses all-MiniLM-L6-v2 (runs on CPU, ~80 MB, cached after first use) to embed both your query and each skill's context. It returns the top match by default. If the confidence gap between the first and second result is less than 0.1, both skills are returned for composition — Weave assumes the task spans both domains.

Use --explain to see the full score table:

weave query "design a REST API" --explain

Use --top N to request at least N results:

weave query "build a feature" --top 2

Contributing

Contributions are welcome at every layer — new platform adapters, composition strategies, CLI improvements, and documentation.

• Contributor guide: docs/contributing.md
• Writing a new adapter: docs/adapters.md
• Architecture overview: docs/architecture.md

All code must pass pytest, ruff check ., and mypy --strict . before merging.

License

MIT — see LICENSE.