th-b30a6a: send_message grows an optional skill — the engine resolves it, not the client

[brentrager]

Problem

Every client resolved a skill itself and prepended the skill's markdown body to the message text. Two costs:

1. Prose on the wire. The protocol carried a recipe where it should carry an intent.
2. The skill body got persisted into conversation history, so it was replayed as context on every subsequent turn of that session — growing the context window with instructions that only applied to one turn.

Solution

send_message takes an optional skill name. The server resolves it and composes the body into that turn's system prompt.

{ "action": "send_message", "requestId": "…", "sessionId": "…", "message": "review my diff", "skill": "code-review" }

The persisted user message stays exactly what the user typed.

The resolver seam

Piece	What it is
skills::SkillResolver	The host seam — one async fn resolve(&self, name) -> Option<String>. Installed via AppState::with_skill_resolver or LocalServerBuilder::skill_resolver. Big Smooth plugs its own discovery in here.
skills::DirSkillResolver	The working default: <root>/<name>/SKILL.md over the :-separated roots in SMOOTH_SKILLS_DIR, first match wins, YAML frontmatter stripped (it's discovery metadata, not instructions).

SMOOTH_SKILLS_DIR unset ⇒ no resolver is installed, so a multi-tenant deploy never serves host skills by accident.

Fail-closed, unlike images

An unresolvable skill returns error { code: "SKILL_NOT_FOUND" } and the turn does not run. Answering without the requested recipe is indistinguishable to the caller from answering with it, so degrading silently is worse than erroring.

Names are [A-Za-z0-9_-]{1,128} — path traversal is unrepresentable rather than filtered, since the name is joined onto a filesystem root.

Backward compatibility

Absent skill is byte-for-byte the previous behavior. TurnRequest::skill_section defaults to None, which appends no system-prompt section.

Tests

rust/smooth-operator-server/tests/skill_field.rs drives the real handler::handle_frame against in-memory storage and MockLlmClient — fully offline, and it is the contract the polyglot servers will mirror:

• skill body lands in the system prompt, frontmatter stripped, and the persisted user message is untouched
• unknown skill ⇒ SKILL_NOT_FOUND, mock.call_count() == 0 (the turn never ran)
• a traversal name (../greet) resolves nothing
• no resolver installed ⇒ every skill is unknown
• absent skill ⇒ ordinary turn, no ## Skill: in the prompt
• whitespace-only skill ⇒ treated as absent

Plus unit tests in skills.rs for name validation, frontmatter stripping (including a --- markdown rule mid-body and unterminated frontmatter), root precedence, and path-list parsing.

Local gates (this repo's rust/** PR CI is compile-gate only, so these are the real gate):

• cargo test -p smooai-smooth-operator-server --lib --tests → 276 passed, 33 suites
• cargo clippy -p smooai-smooth-operator-server --all-targets → 0 errors (10 warnings, all pre-existing on main)
• cargo fmt --all clean

Docs + spec

• spec/actions/send-message.schema.json — the field, its pattern, and the fail-closed contract
• docs/Reference/Protocol Reference.md — new "Skills on send_message" section

Deferred: polyglot parity

The TS / Python / Go / .NET servers ignore skill (it degrades to an ordinary turn) — the same staging images[] is in today, where Rust is the reference implementation and the ports follow separately. Worth a follow-up pearl once the seam shape has settled here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YSE8xAs9aWN5VhrnnSyLKq

[changeset-bot]

🦋 Changeset detected

Latest commit: b0970d4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@smooai/smooth-operator	Minor
@smooai/smooth-operator-web-chat-example	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR