riffer 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 849df927faaf4614ad3a4833aafa5323731d3c1f4a7a8687db35ee5d341eb334
-  data.tar.gz: 1d992d83487a673fef8714d6f72811eb94fdb5e646e33612eb18ac915257b832
+  metadata.gz: 12ca19d6aeb04239a6938aa523a9e7254a1a5599a9629e6a333fc385a0d94de3
+  data.tar.gz: dec4506d7e4800b9cf12aa817e5df14c65b8822930d50ad75b0c912a6d5099bf
 SHA512:
-  metadata.gz: f1967690dfbe21181d4670117de7563936c05dd7d7303597378584acba35a0543de292fb9e4f72d9ed71789d4b73dc17023ce1d1c0bba27434dea93646dccc4d
-  data.tar.gz: 71b4c1568a2b4f5f420f3546283f5c56bc979b8234734049a8df714363faf132f36bc892dabc3e62702c59c43e74ad7e697fb702c772f2bfdec6f56950c0a1fb
+  metadata.gz: 84b914f6160009c13ba5ac1ed6b659fe45ba13dea14ccb1dd94d529b9de4526c0c7afff84e6bbeac565b81d529e42689c07874da89f6509e4510d59756cad073
+  data.tar.gz: df04dc8a8ee28e70b95073b790d268c7488f0a9cd16131e1acafbfa651a9254d8868d9042607a73a5f4572e5e0a5eaee84b27965034894e4022294344d89be1f

data/.agents/architecture.md

@@ -4,7 +4,7 @@
 
 ### Agent (`lib/riffer/agent.rb`)
 
-Base class for AI agents. Subclass and use DSL methods `model`, `instructions`, and `structured_output` to configure. Orchestrates message flow, LLM calls, tool execution, and structured output parsing via a generate/stream loop.
+Base class for AI agents. Subclass and use DSL methods `model`, `instructions`, `structured_output`, and `skills` to configure. Orchestrates message flow, LLM calls, tool execution, structured output parsing, and skill activation via a generate/stream loop.
 
 ```ruby
 class EchoAgent < Riffer::Agent
@@ -40,6 +40,22 @@ Adapters for LLM APIs. The base class uses a template-method pattern — `genera
 
 Providers are registered in `Riffer::Providers::Repository::REPO` with identifiers (e.g., `openai`, `amazon_bedrock`).
 
+Each provider declares a preferred skill adapter via `self.skills_adapter` (Markdown for most, XML for Anthropic).
+
+### Skills (`lib/riffer/skills/`)
+
+Support for the [Agent Skills spec](https://agentskills.io/). Skills are packaged as directories containing `SKILL.md` files with YAML frontmatter. The framework discovers skills through a pluggable backend, injects metadata into the system prompt, and provides a tool (`skill_activate`) for the LLM to load full skill instructions on demand.
+
+- `Config` - DSL configuration object (`backend`, `adapter`, `activate`)
+- `Backend` - base class interface (`list_skills`, `read_skill`)
+- `FilesystemBackend` - built-in filesystem scanner
+- `Frontmatter` - parsed YAML frontmatter value object with `.parse(raw)` class method
+- `Context` - coordinates discovery, activation, caching, and prompt rendering for a generation cycle
+- `Adapter` - base class for skill adapters (`render_catalog`, `activate_tool`)
+- `MarkdownAdapter` - default Markdown skill adapter
+- `XmlAdapter` - XML skill adapter for Anthropic/Claude
+- `ActivateTool` - default tool the LLM calls to activate a skill
+
 ### Messages (`lib/riffer/messages/`)
 
 Typed message objects that extend `Riffer::Messages::Base`:
@@ -65,6 +81,10 @@ Structured events for streaming responses:
 - `WebSearchDone` - web search completion with query and sources
 - `Interrupt` - callback interrupted the agent loop
 
+### Per-Call State Reset
+
+Each call to `generate` or `stream` resets `context`, tools, tool runtime, model, skills state, and the interrupted flag via `prepare_run`. Only the message history and cumulative `token_usage` persist across calls. This means `context:` must be passed on every call.
+
 ### Stopping the Loop Early
 
 Two mechanisms can stop the agent loop before the LLM finishes naturally:
@@ -75,7 +95,15 @@ Two mechanisms can stop the agent loop before the LLM finishes naturally:
 
 ### Resuming After an Interrupt
 
-`agent.resume` or `agent.resume_stream` continues an interrupted loop. Both accept `messages:` for cross-process resume from persisted data.
+Two resume paths:
+
+- **In-memory** — call `generate` or `stream` again with a string on the same agent instance. The message history is preserved and the new user message is appended.
+- **Cross-process** — pass persisted messages as an array to a new agent instance. Array input uses messages as-is (no system message prepend). Passing an array to an agent that already has messages raises `Riffer::ArgumentError`.
+
+```ruby
+agent.generate('Continue')              # in-memory resume
+MyAgent.new.stream(persisted_messages)  # cross-process resume
+```
 
 On resume, `execute_pending_tool_calls` detects tool calls from the last assistant message that lack corresponding tool result messages and executes them before entering the LLM loop. This handles the case where an interrupt fired mid-way through tool execution.
 
@@ -105,6 +133,17 @@ lib/
     params.rb            # Parameter collection with DSL and validation
     structured_output.rb # Structured output schema wrapper
     stream_events.rb     # Stream events namespace/module
+    skills.rb            # Skills namespace/module
+    skills/
+      config.rb          # DSL configuration object
+      adapter.rb         # Adapter base class (render_catalog, activate_tool)
+      markdown_adapter.rb # Default Markdown skill adapter
+      xml_adapter.rb     # XML skill adapter for Anthropic/Claude
+      backend.rb         # Backend base class (interface)
+      filesystem_backend.rb # Built-in filesystem backend
+      frontmatter.rb     # Parsed YAML frontmatter value object with .parse
+      context.rb         # Skills context for a generation cycle
+      activate_tool.rb   # Default skill_activate tool
     structured_output/
       result.rb          # Parse/validation result object
     helpers/

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.17.0"
+  ".": "0.18.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0](https://github.com/janeapp/riffer/compare/riffer/v0.17.0...riffer/v0.18.0) (2026-03-13)
+
+
+### Features
+
+* add support for agent skills ([#151](https://github.com/janeapp/riffer/issues/151)) ([8847d54](https://github.com/janeapp/riffer/commit/8847d54dede875f207d0e0b28bb64039d3c2e69f))
+* Unify generate/stream API with multi-turn support, remove resume methods ([#165](https://github.com/janeapp/riffer/issues/165)) ([58826df](https://github.com/janeapp/riffer/commit/58826df27806bb10afe1c7ad94322cc643d049f9))
+
 ## [0.17.0](https://github.com/janeapp/riffer/compare/riffer/v0.16.1...riffer/v0.17.0) (2026-03-06)
 
 

data/docs/03_AGENTS.md

@@ -282,27 +282,46 @@ See [Guardrails](09_GUARDRAILS.md) for detailed documentation.
 
 ### generate
 
-Generates a response synchronously. Returns a `Riffer::Agent::Response` object:
+Generates a response synchronously. Returns a `Riffer::Agent::Response` object.
+
+The behavior depends on what you pass and the agent's current state:
+
+| Input      | Agent state                    | Behavior                                                                                                                                                              |
+| ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **String** | No prior messages              | **New conversation.** Builds system messages (instructions + skills), adds user message, calls the LLM.                                                               |
+| **String** | Has messages from a prior call | **Continue conversation.** Appends the user message to the existing history and re-enters the LLM loop. Pending tool calls from a prior interrupt are executed first. |
+| **Array**  | No prior messages              | **Restore from persisted data.** Uses the array as-is (no system messages added). Pending tool calls are executed. This is for cross-process resume.                  |
+| **Array**  | Has messages from a prior call | **Raises `Riffer::ArgumentError`.** Use a string to continue, or a new agent instance to start from a persisted array.                                                |
+
+**State reset per call:** Each call to `generate` or `stream` resets `context`, tools, tool runtime, model, skills state, and the interrupted flag. This means `context:` must be passed on every call — it is not carried over from a previous call. The only state that persists across calls is the message history and cumulative `token_usage`.
 
 ```ruby
-# Class method (recommended for simple calls)
+agent.generate('Hello', context: {user_id: 123})
+agent.generate('Follow up')  # context is nil here — pass it again if needed
+agent.generate('More', context: {user_id: 123})  # context is restored
+```
+
+```ruby
+# New conversation (class method — recommended for simple calls)
 response = MyAgent.generate('Hello')
 puts response.content       # Access the response text
 puts response.blocked?      # Check if guardrail blocked (always false without guardrails)
 puts response.interrupted?  # Check if a callback interrupted the loop
 
-# Instance method (when you need message history or callbacks)
+# New conversation (instance method — when you need message history or callbacks)
 agent = MyAgent.new
 agent.on_message { |msg| log(msg) }
 response = agent.generate('Hello')
 agent.messages  # Access message history
 
-# With message objects/hashes
-response = MyAgent.generate([
-  {role: 'user', content: 'Hello'},
-  {role: 'assistant', content: 'Hi there!'},
-  {role: 'user', content: 'How are you?'}
-])
+# Multi-turn conversation
+agent = MyAgent.new
+agent.generate('Hello')
+agent.generate('Tell me more')   # continues with full history
+
+# Restore from persisted messages (cross-process resume)
+agent = MyAgent.new
+response = agent.generate(persisted_messages, context: {user_id: 123})
 
 # With context
 response = MyAgent.generate('Look up my orders', context: {user_id: 123})
@@ -322,10 +341,10 @@ response = MyAgent.generate([
 
 ### stream
 
-Streams a response as an Enumerator:
+Streams a response as an Enumerator. Follows the same input rules as `generate` — a string starts a new conversation or continues an existing one, an array restores from persisted data.
 
 ```ruby
-# Class method (recommended for simple calls)
+# New conversation (class method — recommended for simple calls)
 MyAgent.stream('Tell me a story').each do |event|
   case event
   when Riffer::StreamEvents::TextDelta
@@ -337,12 +356,17 @@ MyAgent.stream('Tell me a story').each do |event|
   end
 end
 
-# Instance method (when you need message history or callbacks)
+# New conversation (instance method — when you need message history or callbacks)
 agent = MyAgent.new
 agent.on_message { |msg| persist_message(msg) }
 agent.stream('Tell me a story').each { |event| handle(event) }
 agent.messages  # Access message history
 
+# Multi-turn conversation
+agent = MyAgent.new
+agent.stream('Hello').each { |event| handle(event) }
+agent.stream('Tell me more').each { |event| handle(event) }
+
 # With files
 MyAgent.stream('What is in this image?', files: [{data: base64_data, media_type: 'image/jpeg'}]).each do |event|
   print event.content if event.is_a?(Riffer::StreamEvents::TextDelta)
@@ -428,7 +452,9 @@ end
 
 #### Resuming an Interrupted Loop
 
-Use `resume` (or `resume_stream`) to continue after an interrupt. On resume, the agent automatically detects and executes any pending tool calls (tool calls from the last assistant message that lack a corresponding tool result) before re-entering the LLM loop.
+There are two ways to resume after an interrupt, depending on whether the agent is still in memory or you're restoring from persisted data.
+
+**In-memory resume** — call `generate` (or `stream`) again with a string. The agent keeps its message history, so a new string appends a user message and continues the loop. Pending tool calls from the interrupt are automatically executed first.
 
 ```ruby
 agent = MyAgent.new
@@ -438,53 +464,43 @@ response = agent.generate('Do something risky')
 
 if response.interrupted?
   approve_action(agent.messages)
-  response = agent.resume   # executes pending tools, then calls the LLM
+  response = agent.generate('Approved, go ahead')  # executes pending tools, then calls the LLM
 end
 ```
 
-For cross-process resume (e.g., after a process restart or async approval), pass persisted messages via the `messages:` keyword. Accepts both message objects and hashes:
+You can also resume without adding a new user message by passing a continuation like `'Continue'` — the LLM will pick up from the existing context.
+
+**Cross-process resume** — when the agent is gone (process restart, async approval, etc.), create a new agent and pass the persisted messages as an array. Array input uses messages as-is (no system messages added) and executes any pending tool calls.
 
 ```ruby
-# Persist messages during generation (e.g., via on_message callback)
+# During generation, persist messages via on_message callback
 # Later, in a new process:
 agent = MyAgent.new
-response = agent.resume(messages: persisted_messages, context: {user_id: 123})
+response = agent.generate(persisted_messages, context: {user_id: 123})
 
 # Or resume in streaming mode:
-agent.resume_stream(messages: persisted_messages).each do |event|
+agent = MyAgent.new
+agent.stream(persisted_messages).each do |event|
   # handle stream events
 end
 ```
 
-When called without `messages:`, resumes from in-memory state. When called with `messages:`, reconstructs state from persisted data. No prior interruption is required in either case.
-
-### resume
-
-Continues an agent loop synchronously. Returns a `Riffer::Agent::Response` object:
-
-```ruby
-# In-memory resume after an interrupt
-response = agent.resume
+**Important:** You cannot pass an array to an agent that already has messages. This raises `Riffer::ArgumentError` because it would silently discard the existing history. Use a string to continue, or create a new agent instance for cross-process resume.
 
-# Cross-process resume from persisted messages
-response = agent.resume(messages: persisted_messages, context: {user_id: 123})
-```
+#### Building System Messages for Persistence
 
-### resume_stream
+Use `generate_instruction_message` and `generate_skills_message` to generate system messages independently. This is useful for database persistence workflows where you need to store and later reconstruct message histories.
 
-Continues an agent loop as a streaming Enumerator. Accepts the same arguments as `resume`:
+Both methods return a `Riffer::Messages::System` or `nil` (when unconfigured). They accept an optional `context:` keyword, just like `generate`.
 
 ```ruby
-# In-memory resume
-agent.resume_stream.each do |event|
-  # handle stream events
-end
-
-# Cross-process resume
 agent = MyAgent.new
-agent.resume_stream(messages: persisted_messages).each do |event|
-  # handle stream events
-end
+sys = agent.generate_instruction_message(context: ctx)     # => Riffer::Messages::System or nil
+skills = agent.generate_skills_message(context: ctx)        # => Riffer::Messages::System or nil
+
+# Store in DB, then later resume in a new process:
+messages = [sys, skills, user_msg].compact
+MyAgent.new.generate(messages, context: ctx)
 ```
 
 ### interrupt!
@@ -516,18 +532,18 @@ Returns `nil` if the provider doesn't report usage, or a `Riffer::TokenUsage` ob
 
 ## Response Attributes
 
-`Riffer::Agent::Response` is returned by `generate` and `resume`:
+`Riffer::Agent::Response` is returned by `generate`:
 
-| Attribute          | Type                        | Description                                        |
-| ------------------ | --------------------------- | -------------------------------------------------- |
-| `content`          | `String`                    | The response text                                  |
+| Attribute           | Type                        | Description                                        |
+| ------------------- | --------------------------- | -------------------------------------------------- |
+| `content`           | `String`                    | The response text                                  |
 | `structured_output` | `Hash` / `nil`              | Parsed and validated structured output (see below) |
-| `blocked?`         | `Boolean`                   | `true` if a guardrail tripwire fired               |
-| `tripwire`         | `Tripwire` / `nil`          | The guardrail tripwire that blocked the request    |
-| `modified?`        | `Boolean`                   | `true` if a guardrail modified the content         |
-| `modifications`    | `Array`                     | List of guardrail modifications applied            |
-| `interrupted?`     | `Boolean`                   | `true` if the loop was interrupted                 |
-| `interrupt_reason` | `String` / `Symbol` / `nil` | The reason passed to `throw :riffer_interrupt`     |
+| `blocked?`          | `Boolean`                   | `true` if a guardrail tripwire fired               |
+| `tripwire`          | `Tripwire` / `nil`          | The guardrail tripwire that blocked the request    |
+| `modified?`         | `Boolean`                   | `true` if a guardrail modified the content         |
+| `modifications`     | `Array`                     | List of guardrail modifications applied            |
+| `interrupted?`      | `Boolean`                   | `true` if the loop was interrupted                 |
+| `interrupt_reason`  | `String` / `Symbol` / `nil` | The reason passed to `throw :riffer_interrupt`     |
 
 ### response.structured_output
 
@@ -629,7 +645,7 @@ Callbacks registered with `on_message` can call `agent.interrupt!` (or `throw :r
 - **When to use:** Flow control that depends on runtime decisions — human-in-the-loop approval, budget tracking, conditional pausing.
 - **Response:** `response.interrupted?` returns `true`, `response.interrupt_reason` contains the optional reason.
 - **Streaming:** Yields an `Interrupt` event with a `reason` attribute.
-- **Resumable:** Yes. Call `resume` or `resume_stream` to continue. Pending tool calls are automatically executed before the LLM loop resumes.
+- **Resumable:** Yes. Call `generate('Continue')` or `stream('Continue')` on the same agent instance to resume. For cross-process resume, pass persisted messages as an array to a new agent. Pending tool calls are automatically executed before the LLM loop resumes.
 
 ```ruby
 agent = MyAgent.new
@@ -640,7 +656,7 @@ end
 response = agent.generate('Do something risky')
 response.interrupted?      # => true
 response.interrupt_reason  # => "approval needed"
-response = agent.resume    # continues where it left off
+response = agent.generate('Approved, continue')  # continues where it left off
 ```
 
 ### Max Steps Limit
@@ -650,7 +666,7 @@ The `max_steps` class method caps the number of LLM call steps in the tool-use l
 - **When to use:** Safety net to prevent runaway tool-use loops — useful when agents have access to many tools or operate autonomously.
 - **Response:** `response.interrupted?` returns `true`, `response.interrupt_reason` is `:max_steps`.
 - **Streaming:** Yields an `Interrupt` event with `reason: :max_steps`.
-- **Resumable:** Yes. Call `resume` or `resume_stream` to continue. Pending tool calls are automatically executed before the LLM loop resumes.
+- **Resumable:** Yes. Call `generate('Continue')` or `stream('Continue')` on the same agent instance to resume. For cross-process resume, pass persisted messages as an array to a new agent. Pending tool calls are automatically executed before the LLM loop resumes.
 
 ```ruby
 class MyAgent < Riffer::Agent
@@ -669,11 +685,11 @@ If a guardrail, provider call, or other internal code raises an exception, it pr
 
 ### Comparison
 
-|               | Guardrail Tripwire                   | Callback Interrupt               | Max Steps Limit                  |
-| ------------- | ------------------------------------ | -------------------------------- | -------------------------------- |
-| Defined       | At class level (`guardrail :before`) | At instance level (`on_message`) | At class level (`max_steps 8`)   |
-| Fires         | Automatically on every request       | When callback logic decides      | When step count reaches limit    |
-| Resumable     | No                                   | Yes (`resume` / `resume_stream`) | Yes (`resume` / `resume_stream`) |
-| Response flag | `blocked?`                           | `interrupted?`                   | `interrupted?`                   |
-| Stream event  | `GuardrailTripwire`                  | `Interrupt`                      | `Interrupt`                      |
-| Purpose       | Policy enforcement                   | Flow control                     | Runaway loop prevention          |
+|               | Guardrail Tripwire                   | Callback Interrupt                   | Max Steps Limit                      |
+| ------------- | ------------------------------------ | ------------------------------------ | ------------------------------------ |
+| Defined       | At class level (`guardrail :before`) | At instance level (`on_message`)     | At class level (`max_steps 8`)       |
+| Fires         | Automatically on every request       | When callback logic decides          | When step count reaches limit        |
+| Resumable     | No                                   | Yes (call `generate`/`stream` again) | Yes (call `generate`/`stream` again) |
+| Response flag | `blocked?`                           | `interrupted?`                       | `interrupted?`                       |
+| Stream event  | `GuardrailTripwire`                  | `Interrupt`                          | `Interrupt`                          |
+| Purpose       | Policy enforcement                   | Flow control                         | Runaway loop prevention              |

data/docs/04_TOOLS.md

@@ -380,9 +380,9 @@ By default, tool calls are executed sequentially in the current thread using `Ri
 
 ### Built-in Runtimes
 
-| Runtime | Description |
-|---------|-------------|
-| `Riffer::ToolRuntime::Inline` | Executes tool calls sequentially (default) |
+| Runtime                         | Description                                    |
+| ------------------------------- | ---------------------------------------------- |
+| `Riffer::ToolRuntime::Inline`   | Executes tool calls sequentially (default)     |
 | `Riffer::ToolRuntime::Threaded` | Executes tool calls concurrently using threads |
 
 ### Per-Agent Configuration

data/docs/06_STREAM_EVENTS.md

@@ -218,7 +218,7 @@ agent.stream("Hello").each do |event|
 end
 ```
 
-After an interrupt, use `resume_stream` to continue the loop. See [Agents - Interrupting the Agent Loop](03_AGENTS.md#interrupting-the-agent-loop) for details.
+After an interrupt, call `stream` again with a string to continue the loop. See [Agents — Resuming an Interrupted Loop](03_AGENTS.md#resuming-an-interrupted-loop) for details.
 
 ### TokenUsageDone
 

data/docs/07_CONFIGURATION.md

@@ -84,11 +84,11 @@ Riffer.configure do |config|
 end
 ```
 
-| Value | Description |
-|-------|-------------|
+| Value                          | Description                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------- |
 | `Riffer::ToolRuntime` subclass | Instantiated automatically (e.g., `Riffer::ToolRuntime::Inline`, `Riffer::ToolRuntime::Threaded`) |
-| `Riffer::ToolRuntime` instance | Custom runtime with specific options |
-| `Proc` | Dynamic resolution |
+| `Riffer::ToolRuntime` instance | Custom runtime with specific options                                                              |
+| `Proc`                         | Dynamic resolution                                                                                |
 
 Per-agent configuration overrides this global default. See [Tools — Tool Runtime](04_TOOLS.md#tool-runtime-experimental) for details.
 
@@ -145,10 +145,10 @@ end
 
 Options are passed through to the [Bedrock Converse API](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html#converse-instance_method).
 
-| Option                               | Description                                                       |
-| ------------------------------------ | ----------------------------------------------------------------- |
-| `inference_config`                   | Hash with `max_tokens`, `temperature`, `top_p`, `stop_sequences`  |
-| `additional_model_request_fields`    | Hash for model-specific params (e.g., `top_k` for Claude)        |
+| Option                            | Description                                                      |
+| --------------------------------- | ---------------------------------------------------------------- |
+| `inference_config`                | Hash with `max_tokens`, `temperature`, `top_p`, `stop_sequences` |
+| `additional_model_request_fields` | Hash for model-specific params (e.g., `top_k` for Claude)        |
 
 ```ruby
 class MyAgent < Riffer::Agent

data/docs/10_SKILLS.md

@@ -0,0 +1,166 @@
+# Skills
+
+Skills are packaged AI agent capabilities per the [Agent Skills spec](https://agentskills.io/). Each skill is a directory containing a `SKILL.md` file with YAML frontmatter and Markdown instructions. The framework discovers skills through a pluggable backend, injects a compact catalog into the system prompt (~50 tokens/skill), and provides a tool for the LLM to activate skills on demand.
+
+## Creating a Skill
+
+Create a directory with a `SKILL.md` file:
+
+```
+.skills/
+  code-review/
+    SKILL.md
+  data-analysis/
+    SKILL.md
+```
+
+Each `SKILL.md` has YAML frontmatter and a Markdown body:
+
+```markdown
+---
+name: code-review
+description: Reviews code for quality, style, and potential issues.
+---
+
+You are a code review assistant.
+
+Review the code for:
+
+- Style issues
+- Potential bugs
+- Performance problems
+```
+
+**Required frontmatter fields:**
+
+- `name` — lowercase alphanumeric with hyphens, 1-64 chars (must match directory name)
+- `description` — 1-1024 chars, helps the LLM decide when to activate
+
+Additional frontmatter keys are passed through as metadata.
+
+## Configuring an Agent
+
+Use the `skills` block DSL to configure skills:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model "openai/gpt-4o"
+  instructions "You are a helpful assistant."
+  skills do
+    backend Riffer::Skills::FilesystemBackend.new(".skills")
+  end
+end
+```
+
+Multiple directories can be scanned (first-path-wins for duplicates):
+
+```ruby
+skills do
+  backend Riffer::Skills::FilesystemBackend.new(".skills", "~/.riffer/skills")
+end
+```
+
+### Dynamic Backend via Proc
+
+```ruby
+skills do
+  backend ->(context) { tenant_backend(context[:tenant_id]) }
+end
+```
+
+### Custom Adapter
+
+The adapter controls how the skill catalog is rendered in the system prompt and which tool the LLM calls to activate a skill. The adapter is auto-selected by provider (Markdown for most, XML for Anthropic). Override with:
+
+```ruby
+skills do
+  backend Riffer::Skills::FilesystemBackend.new(".skills")
+  adapter Riffer::Skills::XmlAdapter
+end
+```
+
+### Activated Skills
+
+Load skill instructions into the system prompt at startup (no tool call needed):
+
+```ruby
+skills do
+  backend Riffer::Skills::FilesystemBackend.new(".skills")
+  activate ["code-review"]
+end
+```
+
+Accepts a Proc for dynamic resolution:
+
+```ruby
+skills do
+  backend Riffer::Skills::FilesystemBackend.new(".skills")
+  activate ->(context) { context[:active_skills] || [] }
+end
+```
+
+## How It Works
+
+1. **Discovery** — At the start of `generate`/`stream`, the backend's `list_skills` returns frontmatter for all available skills.
+2. **Catalog injection** — The adapter formats the catalog and appends it to the system prompt.
+3. **Activation** — When the LLM matches a task to a skill, it calls the `skill_activate` tool with the skill name. The tool returns the full SKILL.md body.
+4. **Execution** — The LLM follows the skill's instructions to complete the task.
+
+## Custom Backends
+
+Implement `Riffer::Skills::Backend` for non-filesystem storage:
+
+```ruby
+class DatabaseBackend < Riffer::Skills::Backend
+  def list_skills
+    # Return Array[Riffer::Skills::Frontmatter]
+  end
+
+  def read_skill(name)
+    # Return String (skill body)
+    # Raise Riffer::ArgumentError if not found
+  end
+end
+```
+
+## Custom Adapters
+
+Subclass `Riffer::Skills::Adapter` to customize how the skill catalog is rendered and which tool the LLM uses to activate skills:
+
+```ruby
+class CustomAdapter < Riffer::Skills::Adapter
+  def render_catalog(skills)
+    # Return String (skill catalog for the system prompt)
+    # Use `activate_tool.name` to reference the activation tool
+  end
+
+  def activate_tool
+    # Return a Riffer::Tool subclass
+    # Defaults to Riffer::Skills::ActivateTool
+    Riffer::Skills::ActivateTool
+  end
+end
+```
+
+The built-in adapters are `Riffer::Skills::MarkdownAdapter` (default) and `Riffer::Skills::XmlAdapter` (used by Anthropic).
+
+## Accessing Skills in Tools
+
+The skills context (`Riffer::Skills::Context`) is available via `context[:skills]` during execution:
+
+```ruby
+class SkillSearchTool < Riffer::Tool
+  identifier "skill_search"
+  description "Searches available skills."
+
+  params do
+    required :query, String
+  end
+
+  def call(context:, query:)
+    skills_context = context[:skills]  # Riffer::Skills::Context
+    matches = skills_context.skills.values.select { |s| s.description.include?(query) }
+    json(matches.map { |s| {name: s.name, description: s.description} })
+  end
+end
+```