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>

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())
+	}
+}