feat: skills — additive instruction+tool bundles, clock + calc examples

Phase 6: skill.New constructor satisfying the agent.Skill contract;
instruction-only skills; ordered additive composition; skill/clock
(injectable-clock time tools) and skill/calc (recursive-descent arithmetic
evaluator) as ready-made examples with full test suites incl. an
agent-loop round trip. ADR-0013; README skills section + matrix synced.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -237,9 +237,32 @@ the model can react to; unknown tools likewise; duplicate tool names across
 toolboxes fail loudly. On `agent.ErrMaxSteps` (and on model errors) the
 partial result with the full transcript is still returned.
 
-## Skills *(pending — Phase 6)*
+## Skills
 
-Skills = reusable instruction+tool bundles attachable to any agent.
+Skills are reusable instruction+tool bundles attachable to **any** agent,
+at construction or on demand. Instructions extend the system prompt;
+tools extend the toolset — additively, in attachment order.
+
+```go
+import (
+    "gitea.stevedudenhoeffer.com/steve/majordomo/skill"
+    "gitea.stevedudenhoeffer.com/steve/majordomo/skill/calc"
+    "gitea.stevedudenhoeffer.com/steve/majordomo/skill/clock"
+)
+
+research := skill.New("research",
+    skill.WithInstructions("Cite a source for every claim."),
+    skill.WithTools(searchTool, fetchTool),
+)
+
+a := agent.New(m, "You are helpful.", agent.WithSkill(research))
+a.AddSkill(clock.New()) // ready-made: time awareness
+a.AddSkill(calc.New())  // ready-made: exact arithmetic
+```
+
+Anything implementing the three-method `agent.Skill` interface (Name /
+Instructions / Tools) is a skill — `skill.New` is just the convenient way
+to build one.
 
 ## Feature/provider support matrix
 
@@ -263,7 +286,7 @@ Notes: Ollama has no native tool_choice — `"none"` drops the tools;
 Cross-cutting: Parse grammar ✅ · aliases/tiers ✅ · failover chains ✅ ·
 health tracking/backoff ✅ · LLM_* env DSNs ✅ · media pipeline ✅
 (per-target normalization in chains) · agent loop ✅ · `Generate[T]` +
-schema derivation ✅ · skills pending.
+schema derivation ✅ · skills ✅ (with clock + calc examples).
 
 ## Development
 

docs/adr/0013-skill-model.md

@@ -0,0 +1,37 @@
+# ADR-0013: Skill model — additive instruction+tool bundles
+
+**Status:** Accepted — 2026-06-10
+
+## Context
+
+mort's "skills" are reusable capabilities (a prompt fragment plus tools)
+attached to different agents at runtime. majordomo needs the same shape
+without mort specifics: attachable to any agent, on demand, composing
+additively and predictably.
+
+## Decision
+
+- The **contract** is the three-method `agent.Skill` interface (Name /
+  Instructions / Tools). It lives in package agent — the consumer of the
+  contract — so skill→agent and agent→skill never both happen (no import
+  cycle, and third parties can satisfy it without importing package skill).
+- Package **skill** is the standard constructor: `skill.New(name,
+  WithInstructions(...), WithTools(...)/WithToolbox(...))`. Instruction-only
+  skills (nil toolbox) are legal — agent treats Tools()==nil as "no tools".
+- **Composition is additive and ordered:** instructions append to the
+  agent's system prompt in attachment order, separated by blank lines;
+  skill tools join the merged toolset with the same loud duplicate-name
+  policy as toolboxes (ADR-0012). No hooks, no resources, no lifecycle —
+  none of mort's skills need them, and out-of-scope discipline says don't
+  build for hypotheticals (they'd be an additive interface upgrade later).
+- Two ready-made example skills ship as subpackages and double as the
+  pattern reference: `skill/clock` (time awareness; injectable clock) and
+  `skill/calc` (exact arithmetic via a hand-rolled recursive-descent
+  evaluator — no eval, no dependencies).
+
+## Consequences
+
+- A skill instance is reusable across agents simultaneously (it is
+  read-only after construction).
+- mort's skill registry maps onto plain values: build `*skill.Skill`s,
+  attach per agent at invocation time.

docs/adr/README.md

@@ -16,3 +16,4 @@ One decision per file, append-only; supersede rather than rewrite.
 | [0010](0010-tools-structured-output-mapping.md) | Tools and structured output — canonical shape, native mappings | Accepted |
 | [0011](0011-google-provider.md) | Google provider on the official Gen AI SDK | Accepted |
 | [0012](0012-agent-loop.md) | Agent run loop | Accepted |
+| [0013](0013-skill-model.md) | Skill model — additive instruction+tool bundles | Accepted |

progress.md

@@ -1,5 +1,20 @@
 # progress
 
+## 2026-06-10 — Phase 6: skills
+
+**Landed:** `skill/` (ADR-0013): the agent.Skill contract satisfied by a
+buildable skill.New(name, WithInstructions/WithTools/WithToolbox);
+instruction-only skills legal; same-instance reuse across agents; additive
+ordered composition proven (prompt appending + toolset merge + loud
+duplicate policy). Example skills: `skill/clock` (time_now/time_convert,
+injectable clock) and `skill/calc` (calculate over a hand-rolled
+recursive-descent evaluator: + - * / % ^, parens, unary minus, scientific
+notation; division-by-zero and non-finite results rejected). Tests cover
+the evaluator table, tool execution through ExecuteTool, and a full
+agent-loop run answering from the calculate result.
+
+**Next:** Phase 7 — examples/, mort migration map, README finalization.
+
 ## 2026-06-10 — Phase 5: agent loop, Generate[T], schema derivation
 
 **Landed:** `agent/` (ADR-0012): New(model, system, opts) with toolboxes,

skill/calc/calc.go

@@ -0,0 +1,220 @@
+// Package calc is an example skill giving any agent exact arithmetic: a
+// calculate tool evaluating +, -, *, /, %, ^, parentheses, and unary minus
+// over floats — because models guess at arithmetic and tools don't.
+package calc
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/skill"
+)
+
+// New builds the calc skill.
+func New() *skill.Skill {
+	tool := llm.Tool{
+		Name:        "calculate",
+		Description: "Evaluate an arithmetic expression exactly. Supports + - * / % ^ (power), parentheses, and unary minus. Use for ANY arithmetic instead of computing in your head.",
+		Parameters: json.RawMessage(`{
+			"type": "object",
+			"properties": {
+				"expression": {"type": "string", "description": "e.g. (2 + 3) * 4 / 1.5"}
+			},
+			"required": ["expression"]
+		}`),
+		Handler: func(_ context.Context, args json.RawMessage) (any, error) {
+			var p struct {
+				Expression string `json:"expression"`
+			}
+			if err := json.Unmarshal(args, &p); err != nil {
+				return nil, fmt.Errorf("bad arguments: %w", err)
+			}
+			v, err := Eval(p.Expression)
+			if err != nil {
+				return nil, err
+			}
+			return map[string]any{"expression": p.Expression, "result": v}, nil
+		},
+	}
+	return skill.New("calc",
+		skill.WithInstructions("You have a calculate tool. Use it for any arithmetic instead of estimating."),
+		skill.WithTools(tool),
+	)
+}
+
+// Eval evaluates an arithmetic expression with a small recursive-descent
+// parser (no dependencies, no reflection, no eval).
+//
+// Grammar:
+//
+//	expr   := term (("+"|"-") term)*
+//	term   := unary (("*"|"/"|"%") unary)*
+//	unary  := "-" unary | power
+//	power  := atom ("^" unary)?          # right-associative
+//	atom   := number | "(" expr ")"
+func Eval(input string) (float64, error) {
+	p := &parser{src: input}
+	v, err := p.expr()
+	if err != nil {
+		return 0, err
+	}
+	p.skipSpace()
+	if p.pos < len(p.src) {
+		return 0, fmt.Errorf("unexpected %q at position %d", p.src[p.pos], p.pos)
+	}
+	if math.IsInf(v, 0) || math.IsNaN(v) {
+		return 0, fmt.Errorf("result of %q is not a finite number", input)
+	}
+	return v, nil
+}
+
+type parser struct {
+	src string
+	pos int
+}
+
+func (p *parser) skipSpace() {
+	for p.pos < len(p.src) && (p.src[p.pos] == ' ' || p.src[p.pos] == '\t') {
+		p.pos++
+	}
+}
+
+func (p *parser) peek() byte {
+	p.skipSpace()
+	if p.pos >= len(p.src) {
+		return 0
+	}
+	return p.src[p.pos]
+}
+
+func (p *parser) expr() (float64, error) {
+	v, err := p.term()
+	if err != nil {
+		return 0, err
+	}
+	for {
+		switch p.peek() {
+		case '+':
+			p.pos++
+			r, err := p.term()
+			if err != nil {
+				return 0, err
+			}
+			v += r
+		case '-':
+			p.pos++
+			r, err := p.term()
+			if err != nil {
+				return 0, err
+			}
+			v -= r
+		default:
+			return v, nil
+		}
+	}
+}
+
+func (p *parser) term() (float64, error) {
+	v, err := p.unary()
+	if err != nil {
+		return 0, err
+	}
+	for {
+		switch p.peek() {
+		case '*':
+			p.pos++
+			r, err := p.unary()
+			if err != nil {
+				return 0, err
+			}
+			v *= r
+		case '/':
+			p.pos++
+			r, err := p.unary()
+			if err != nil {
+				return 0, err
+			}
+			if r == 0 {
+				return 0, fmt.Errorf("division by zero")
+			}
+			v /= r
+		case '%':
+			p.pos++
+			r, err := p.unary()
+			if err != nil {
+				return 0, err
+			}
+			if r == 0 {
+				return 0, fmt.Errorf("modulo by zero")
+			}
+			v = math.Mod(v, r)
+		default:
+			return v, nil
+		}
+	}
+}
+
+func (p *parser) unary() (float64, error) {
+	if p.peek() == '-' {
+		p.pos++
+		v, err := p.unary()
+		if err != nil {
+			return 0, err
+		}
+		return -v, nil
+	}
+	return p.power()
+}
+
+func (p *parser) power() (float64, error) {
+	base, err := p.atom()
+	if err != nil {
+		return 0, err
+	}
+	if p.peek() == '^' {
+		p.pos++
+		exp, err := p.unary() // right-associative: 2^3^2 = 2^(3^2)
+		if err != nil {
+			return 0, err
+		}
+		return math.Pow(base, exp), nil
+	}
+	return base, nil
+}
+
+func (p *parser) atom() (float64, error) {
+	switch c := p.peek(); {
+	case c == '(':
+		p.pos++
+		v, err := p.expr()
+		if err != nil {
+			return 0, err
+		}
+		if p.peek() != ')' {
+			return 0, fmt.Errorf("missing closing parenthesis at position %d", p.pos)
+		}
+		p.pos++
+		return v, nil
+	case c >= '0' && c <= '9' || c == '.':
+		start := p.pos
+		for p.pos < len(p.src) && (p.src[p.pos] >= '0' && p.src[p.pos] <= '9' || p.src[p.pos] == '.' ||
+			p.src[p.pos] == 'e' || p.src[p.pos] == 'E' ||
+			((p.src[p.pos] == '+' || p.src[p.pos] == '-') && p.pos > start && (p.src[p.pos-1] == 'e' || p.src[p.pos-1] == 'E'))) {
+			p.pos++
+		}
+		v, err := strconv.ParseFloat(strings.TrimSpace(p.src[start:p.pos]), 64)
+		if err != nil {
+			return 0, fmt.Errorf("bad number %q at position %d", p.src[start:p.pos], start)
+		}
+		return v, nil
+	case c == 0:
+		return 0, fmt.Errorf("unexpected end of expression")
+	default:
+		return 0, fmt.Errorf("unexpected %q at position %d", c, p.pos)
+	}
+}

skill/calc/calc_test.go

@@ -0,0 +1,78 @@
+package calc
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/agent"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+)
+
+func TestEval(t *testing.T) {
+	tests := []struct {
+		expr string
+		want float64
+	}{
+		{"1+2", 3},
+		{"2 * 3 + 4", 10},
+		{"2 + 3 * 4", 14},
+		{"(2 + 3) * 4", 20},
+		{"10 / 4", 2.5},
+		{"-3 + 5", 2},
+		{"--3", 3},
+		{"2^10", 1024},
+		{"2^3^2", 512}, // right-associative
+		{"-2^2", -4},   // unary binds looser than power
+		{"7 % 3", 1},
+		{"1.5e2 + 1", 151},
+		{" ( 1 + 1 ) * ( 2 + 2 ) ", 8},
+	}
+	for _, tt := range tests {
+		got, err := Eval(tt.expr)
+		if err != nil {
+			t.Errorf("Eval(%q): %v", tt.expr, err)
+			continue
+		}
+		if got != tt.want {
+			t.Errorf("Eval(%q) = %v, want %v", tt.expr, got, tt.want)
+		}
+	}
+}
+
+func TestEvalErrors(t *testing.T) {
+	for _, expr := range []string{"", "1/0", "5 % 0", "2 +", "(1+2", "1 + abc", "1 2", "2^99999"} {
+		if _, err := Eval(expr); err == nil {
+			t.Errorf("Eval(%q) should error", expr)
+		}
+	}
+}
+
+// TestSkillInAgentLoop: an agent actually invokes calculate and answers
+// from its result.
+func TestSkillInAgentLoop(t *testing.T) {
+	fp := fake.New("fp")
+	fp.Enqueue("m",
+		fake.ReplyWith(llm.Response{
+			ToolCalls:    []llm.ToolCall{{ID: "c1", Name: "calculate", Arguments: json.RawMessage(`{"expression":"(2+3)*4"}`)}},
+			FinishReason: llm.FinishToolCalls,
+		}),
+		fake.Reply("the answer is 20"),
+	)
+	m, _ := fp.Model("m")
+
+	a := agent.New(m, "Math helper.", agent.WithSkill(New()))
+	res, err := a.Run(context.Background(), "what is (2+3)*4?")
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if res.Output != "the answer is 20" {
+		t.Errorf("output = %q", res.Output)
+	}
+	result := res.Steps[0].Results[0]
+	if result.IsError || !strings.Contains(result.Content, `"result":20`) {
+		t.Errorf("tool result = %+v", result)
+	}
+}

skill/clock/clock.go

@@ -0,0 +1,102 @@
+// Package clock is an example skill giving any agent reliable time
+// awareness: a current-time tool (models cannot know "now") and a timezone
+// conversion tool, with an injectable clock for tests.
+package clock
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/skill"
+)
+
+// Option configures the skill.
+type Option func(*config)
+
+type config struct {
+	now func() time.Time
+}
+
+// WithClock injects the time source (tests).
+func WithClock(now func() time.Time) Option {
+	return func(c *config) { c.now = now }
+}
+
+// New builds the clock skill.
+func New(opts ...Option) *skill.Skill {
+	cfg := config{now: time.Now}
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	nowTool := llm.Tool{
+		Name:        "time_now",
+		Description: "Get the current date and time. Use whenever the user's request depends on today's date or the current time.",
+		Parameters: json.RawMessage(`{
+			"type": "object",
+			"properties": {
+				"timezone": {"type": "string", "description": "IANA timezone like America/New_York; defaults to UTC"}
+			}
+		}`),
+		Handler: func(_ context.Context, args json.RawMessage) (any, error) {
+			var p struct {
+				Timezone string `json:"timezone"`
+			}
+			if err := json.Unmarshal(args, &p); err != nil {
+				return nil, fmt.Errorf("bad arguments: %w", err)
+			}
+			loc := time.UTC
+			if p.Timezone != "" {
+				var err error
+				if loc, err = time.LoadLocation(p.Timezone); err != nil {
+					return nil, fmt.Errorf("unknown timezone %q", p.Timezone)
+				}
+			}
+			t := cfg.now().In(loc)
+			return map[string]string{
+				"rfc3339": t.Format(time.RFC3339),
+				"weekday": t.Weekday().String(),
+				"human":   t.Format("Monday, January 2, 2006 at 15:04 MST"),
+			}, nil
+		},
+	}
+
+	convertTool := llm.Tool{
+		Name:        "time_convert",
+		Description: "Convert an RFC3339 timestamp to another timezone.",
+		Parameters: json.RawMessage(`{
+			"type": "object",
+			"properties": {
+				"time": {"type": "string", "description": "RFC3339 timestamp"},
+				"timezone": {"type": "string", "description": "target IANA timezone"}
+			},
+			"required": ["time", "timezone"]
+		}`),
+		Handler: func(_ context.Context, args json.RawMessage) (any, error) {
+			var p struct {
+				Time     string `json:"time"`
+				Timezone string `json:"timezone"`
+			}
+			if err := json.Unmarshal(args, &p); err != nil {
+				return nil, fmt.Errorf("bad arguments: %w", err)
+			}
+			t, err := time.Parse(time.RFC3339, p.Time)
+			if err != nil {
+				return nil, fmt.Errorf("unparseable time %q: %w", p.Time, err)
+			}
+			loc, err := time.LoadLocation(p.Timezone)
+			if err != nil {
+				return nil, fmt.Errorf("unknown timezone %q", p.Timezone)
+			}
+			return map[string]string{"rfc3339": t.In(loc).Format(time.RFC3339)}, nil
+		},
+	}
+
+	return skill.New("clock",
+		skill.WithInstructions("You have time tools. Never guess the current date or time — call time_now. Use time_convert for timezone math."),
+		skill.WithTools(nowTool, convertTool),
+	)
+}

skill/clock/clock_test.go

@@ -0,0 +1,75 @@
+package clock
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+func fixed() time.Time {
+	return time.Date(2026, 6, 10, 15, 30, 0, 0, time.UTC)
+}
+
+func callTool(t *testing.T, name, args string) llm.ToolResult {
+	t.Helper()
+	sk := New(WithClock(fixed))
+	tool, ok := sk.Tools().Get(name)
+	if !ok {
+		t.Fatalf("tool %q missing", name)
+	}
+	return llm.ExecuteTool(context.Background(), tool, llm.ToolCall{
+		ID: "c1", Name: name, Arguments: json.RawMessage(args),
+	})
+}
+
+func TestTimeNowUTC(t *testing.T) {
+	res := callTool(t, "time_now", `{}`)
+	if res.IsError {
+		t.Fatalf("result = %+v", res)
+	}
+	var out map[string]string
+	if err := json.Unmarshal([]byte(res.Content), &out); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if out["rfc3339"] != "2026-06-10T15:30:00Z" || out["weekday"] != "Wednesday" {
+		t.Errorf("out = %v", out)
+	}
+}
+
+func TestTimeNowZoned(t *testing.T) {
+	res := callTool(t, "time_now", `{"timezone":"America/New_York"}`)
+	if res.IsError {
+		t.Fatalf("result = %+v", res)
+	}
+	if !strings.Contains(res.Content, "2026-06-10T11:30:00-04:00") {
+		t.Errorf("content = %s", res.Content)
+	}
+}
+
+func TestTimeNowBadZone(t *testing.T) {
+	res := callTool(t, "time_now", `{"timezone":"Mars/Olympus"}`)
+	if !res.IsError {
+		t.Errorf("result = %+v, want error", res)
+	}
+}
+
+func TestTimeConvert(t *testing.T) {
+	res := callTool(t, "time_convert", `{"time":"2026-06-10T15:30:00Z","timezone":"Europe/Berlin"}`)
+	if res.IsError {
+		t.Fatalf("result = %+v", res)
+	}
+	if !strings.Contains(res.Content, "2026-06-10T17:30:00+02:00") {
+		t.Errorf("content = %s", res.Content)
+	}
+}
+
+func TestInstructionsMentionTools(t *testing.T) {
+	sk := New()
+	if !strings.Contains(sk.Instructions(), "time_now") {
+		t.Errorf("instructions = %q", sk.Instructions())
+	}
+}

skill/skill.go

@@ -0,0 +1,66 @@
+// Package skill provides reusable capability bundles for agents: a named
+// set of instructions (appended to the agent's system prompt) plus optional
+// tools (joined into the agent's toolset). Skills attach to ANY agent, at
+// construction (agent.WithSkill) or on demand (Agent.AddSkill), and compose
+// additively in attachment order.
+//
+// The contract a skill satisfies is the agent.Skill interface; this package
+// is the standard way to build one without writing a type:
+//
+//	research := skill.New("research",
+//	    skill.WithInstructions("Cite sources for every claim."),
+//	    skill.WithTools(searchTool, fetchTool),
+//	)
+//	a.AddSkill(research)
+//
+// Two ready-made example skills ship as subpackages: clock (time awareness)
+// and calc (exact arithmetic).
+package skill
+
+import "gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+
+// Skill is a buildable instruction+tool bundle. The zero value is unusable;
+// construct with New.
+type Skill struct {
+	name         string
+	instructions string
+	toolbox      *llm.Toolbox
+}
+
+// Option configures a Skill under construction.
+type Option func(*Skill)
+
+// WithInstructions sets the text appended to the agent's system prompt.
+func WithInstructions(s string) Option {
+	return func(sk *Skill) { sk.instructions = s }
+}
+
+// WithToolbox attaches the skill's tools as an existing toolbox.
+func WithToolbox(b *llm.Toolbox) Option {
+	return func(sk *Skill) { sk.toolbox = b }
+}
+
+// WithTools attaches loose tools (wrapped in a toolbox named after the
+// skill).
+func WithTools(tools ...llm.Tool) Option {
+	return func(sk *Skill) { sk.toolbox = llm.NewToolbox(sk.name, tools...) }
+}
+
+// New builds a skill.
+func New(name string, opts ...Option) *Skill {
+	sk := &Skill{name: name}
+	for _, opt := range opts {
+		opt(sk)
+	}
+	return sk
+}
+
+// Name identifies the skill (used in duplicate-tool diagnostics).
+func (s *Skill) Name() string { return s.name }
+
+// Instructions returns the system-prompt extension; may be empty.
+func (s *Skill) Instructions() string { return s.instructions }
+
+// Tools returns the skill's toolbox; may be nil for instruction-only
+// skills.
+func (s *Skill) Tools() *llm.Toolbox { return s.toolbox }

skill/skill_test.go

@@ -0,0 +1,97 @@
+package skill_test
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/agent"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/skill"
+)
+
+// The skill package must satisfy the agent contract.
+var _ agent.Skill = (*skill.Skill)(nil)
+
+func TestSkillConstruction(t *testing.T) {
+	tool := llm.Tool{Name: "t1"}
+	sk := skill.New("research",
+		skill.WithInstructions("Cite sources."),
+		skill.WithTools(tool),
+	)
+	if sk.Name() != "research" || sk.Instructions() != "Cite sources." {
+		t.Errorf("skill = %q / %q", sk.Name(), sk.Instructions())
+	}
+	if sk.Tools() == nil || len(sk.Tools().Tools()) != 1 {
+		t.Errorf("tools = %+v", sk.Tools())
+	}
+	if sk.Tools().Name() != "research" {
+		t.Errorf("toolbox name = %q, want skill name", sk.Tools().Name())
+	}
+}
+
+func TestInstructionOnlySkill(t *testing.T) {
+	sk := skill.New("tone", skill.WithInstructions("Be kind."))
+	if sk.Tools() != nil {
+		t.Error("instruction-only skill must have nil toolbox")
+	}
+}
+
+// TestSkillsAttachToAnyAgent: the same skill instance layers onto multiple
+// agents, on demand, extending prompt and toolset additively.
+func TestSkillsAttachToAnyAgent(t *testing.T) {
+	echo := llm.Tool{
+		Name: "echo",
+		Handler: func(_ context.Context, args json.RawMessage) (any, error) {
+			return string(args), nil
+		},
+	}
+	sk := skill.New("echoer",
+		skill.WithInstructions("Echo when asked."),
+		skill.WithTools(echo),
+	)
+
+	for _, base := range []string{"Agent one.", "Agent two."} {
+		fp := fake.New("fp")
+		fp.Enqueue("m", fake.Reply("done"))
+		m, _ := fp.Model("m")
+
+		a := agent.New(m, base)
+		a.AddSkill(sk)
+		if _, err := a.Run(context.Background(), "hi"); err != nil {
+			t.Fatalf("Run: %v", err)
+		}
+
+		req := fp.Calls()[0].Request
+		if !strings.HasPrefix(req.System, base) || !strings.Contains(req.System, "Echo when asked.") {
+			t.Errorf("system = %q", req.System)
+		}
+		if len(req.Tools) != 1 || req.Tools[0].Name != "echo" {
+			t.Errorf("tools = %+v", req.Tools)
+		}
+	}
+}
+
+// TestMultipleSkillsCompose: instructions append in order; toolsets merge.
+func TestMultipleSkillsCompose(t *testing.T) {
+	fp := fake.New("fp")
+	fp.Enqueue("m", fake.Reply("ok"))
+	m, _ := fp.Model("m")
+
+	a := agent.New(m, "Base.",
+		agent.WithSkill(skill.New("one", skill.WithInstructions("First."), skill.WithTools(llm.Tool{Name: "t1"}))),
+		agent.WithSkill(skill.New("two", skill.WithInstructions("Second."), skill.WithTools(llm.Tool{Name: "t2"}))),
+	)
+	if _, err := a.Run(context.Background(), "go"); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	req := fp.Calls()[0].Request
+	if req.System != "Base.\n\nFirst.\n\nSecond." {
+		t.Errorf("system = %q", req.System)
+	}
+	if len(req.Tools) != 2 {
+		t.Errorf("tools = %+v", req.Tools)
+	}
+}