@@ -0,0 +1,93 @@
+# Basic Composition Example
+
+This example shows Weave automatically routing between two **Claude Code skills** — a Design System skill and a Backend API skill — based on the meaning of your query.
+
+## What This Demonstrates
+
+When you have multiple skills loaded, Weave selects the right one for each task without you specifying which to use. A design query activates the Design System skill. A backend query activates the Backend API skill. When a task spans both domains, Weave composes both skills together automatically.
+
+This is the simplest Weave use case: one platform, two skills, zero manual routing.
+
+## Directory Structure
+
+```
+basic-composition/
+├── weave.yaml          ← Weave config: one skill directory, dynamic strategy
+├── skills/
+│   ├── design_system.md  ← Claude Code skill: Design System Engineer
+│   └── backend_api.md    ← Claude Code skill: Backend API Engineer
+└── README.md           ← This file
+```
+
+## How to Run
+
+From the repository root:
+
+```bash
+cd examples/basic-composition
+
+# Option A: interactive query mode (recommended)
+weave run --config weave.yaml
+
+# Then type any query at the prompt:
+# weave> design a button component with Tailwind CSS
+# weave> write a REST endpoint for creating a user
+# weave> add accessibility labels to a form
+```
+
+```bash
+# Option B: one-shot query
+weave load ./skills --platform claude_code
+weave query "design a button component with Tailwind CSS"
+
+# See all loaded skills:
+weave list
+
+# With similarity scores for all skills:
+weave query "write a REST endpoint" --explain
+```
+
+## Expected Output
+
+```
+Loaded 2 skill(s) from ./skills (platform: claude_code)
+Session saved to .weave_session.json
+
+# Design query → Design System skill selected
+$ weave query "design a button component with Tailwind CSS"
+[1] Design System Engineer (claude_code) — score: 0.7214
+    Building and maintaining UI components, design tokens, and accessibility
+    standards for a consistent design system using Tailwind CSS and React.
+
+# Backend query → Backend API skill selected
+$ weave query "write a REST endpoint for creating a user"
+[1] Backend API Engineer (claude_code) — score: 0.6891
+    Designing and implementing RESTful APIs, database schemas, and server-side
+    business logic using FastAPI and PostgreSQL.
+```
+
+## How It Works
+
+1. `weave load ./skills` reads both SKILL.md files and embeds each skill's
+   `trigger_context` and `capabilities` using `all-MiniLM-L6-v2` (local, no API key).
+2. At query time, `weave query` embeds the query text and computes cosine similarity
+   against every loaded skill's embedding.
+3. The highest-scoring skill is returned. If the top two scores fall within
+   `confidence_threshold: 0.1` of each other, both are returned for composition —
+   Weave assumes the task spans both domains.
+4. `WeaveComposer` merges the contexts: higher-confidence skill first,
+   deduplicated, with a `---` separator before the secondary skill's unique content.
+
+## Extending This Example
+
+- Add a third SKILL.md to `skills/` (e.g. a DevOps skill) — Weave picks it up
+  automatically on the next `weave load`.
+- Adjust `confidence_threshold` in `weave.yaml` to control how aggressively
+  Weave composes multiple skills per query.
+- Set `explain: true` in the `output` section to see similarity scores for every
+  loaded skill on every query.
+- See the **[cross-platform example](../cross-platform/)** to compose skills from
+  different AI coding tools (Claude Code + Cursor) together.
+- See **[`../weave.yaml.example`](../weave.yaml.example)** for all available config options.
+- See **[`../../docs/architecture.md`](../../docs/architecture.md)** for a full explanation
+  of the composition pipeline.
@@ -0,0 +1,39 @@
+---
+name: Backend API Engineer
+description: Designing and implementing RESTful APIs, database schemas, and server-side business logic using FastAPI and PostgreSQL with a focus on correctness, validation, and testability.
+capabilities: [api, rest, fastapi, postgresql, database, validation, testing, python]
+version: "1.0"
+author: Weave Example
+---
+
+# Backend API Engineer
+
+This skill governs how API endpoints, data models, and server-side logic are designed and implemented. Every endpoint must be validated, documented, and covered by tests.
+
+## Endpoint Design
+
+- Follow REST conventions strictly: GET for reads, POST for creates, PATCH for partial updates, DELETE for removes.
+- Return consistent JSON envelopes: `{"data": ..., "error": null}` on success, `{"data": null, "error": "..."}` on failure.
+- Use plural resource names in paths: `/users`, `/orders/{order_id}`, not `/user` or `/getOrder`.
+- Never expose internal IDs or database primary keys in URLs. Use UUIDs.
+
+## Request Validation
+
+- Use Pydantic models for all request bodies and query parameters. No raw `dict` inputs.
+- Validate at the boundary — never trust incoming data inside business logic layers.
+- Return HTTP 422 with field-level error details for validation failures. Never 500.
+- Strip and normalize strings on input: trim whitespace, lowercase emails.
+
+## Database
+
+- Use SQLAlchemy ORM with Alembic for migrations. Never write raw DDL by hand.
+- Every table must have: `id` (UUID), `created_at`, `updated_at` columns.
+- Index foreign keys and any column used in a WHERE clause.
+- Never run N+1 queries. Use `joinedload` or `selectinload` for relationships.
+
+## Testing
+
+- Every endpoint must have at least one happy-path test and one error-path test.
+- Use `pytest` with `httpx.AsyncClient` against a test database, not mocks.
+- Seed test data in fixtures, not inside test functions.
+- Tests must be independent and order-agnostic — never share state between tests.
@@ -0,0 +1,38 @@
+---
+name: Design System Engineer
+description: Building and maintaining UI components, design tokens, and accessibility standards for a consistent design system using Tailwind CSS and React.
+capabilities: [design, components, tailwind, accessibility, tokens, react, ui]
+version: "1.0"
+author: Weave Example
+---
+
+# Design System Engineer
+
+This skill governs how UI components, design tokens, and visual standards are implemented and maintained across the product. Every component must be token-driven, accessible, and consistent with the design system.
+
+## Component Structure
+
+- Use functional React components with named exports only. No default exports.
+- Accept a `className` prop on every presentational component for consumer overrides.
+- Keep components under 150 lines. Extract sub-components when a component grows larger.
+- Co-locate the component, its types, and its tests in the same directory.
+
+## Design Tokens
+
+- Never hardcode colours, spacing, or typography values directly in components.
+- Use Tailwind design tokens exclusively: `text-primary`, `bg-surface`, `p-4`.
+- Custom tokens live in `tailwind.config.js` under `theme.extend`. Never duplicate them.
+- When a token does not exist, propose adding it — do not use a raw value as a workaround.
+
+## Accessibility
+
+- Every interactive element must be keyboard-navigable with a visible focus ring.
+- Use semantic HTML: `<button>` not `<div onClick>`, `<nav>` not `<div className="nav">`.
+- All images require `alt` text. Purely decorative images use `alt=""`.
+- Colour contrast must meet WCAG AA minimums: 4.5:1 for normal text, 3:1 for large text.
+
+## Naming Conventions
+
+- Component files: PascalCase (`ButtonGroup.tsx`, `CardHeader.tsx`).
+- CSS class variables: kebab-case (`--color-primary`, `--spacing-base`).
+- Props: camelCase, descriptive (`isDisabled` not `dis`, `onValueChange` not `onChange2`).
@@ -0,0 +1,15 @@
+version: "1"
+
+skills:
+  - path: ./skills
+    platform: claude_code
+
+composition:
+  strategy: dynamic
+  max_active_skills: 2
+  confidence_threshold: 0.1
+  model: all-MiniLM-L6-v2
+
+output:
+  verbose: false
+  explain: false