docs(skills): teach the LLM call-surface rule + naming conventions

[gwitwer]

Summary

Companion to a server-side companion change — this is the FULL version of the LLM call-surface rule + naming conventions, landing in the canonical sapiom-agent-authoring skill (packages/agent-core/skills/sapiom-agent-authoring/SKILL.md) rather than the Sapiom-repo monorepo pointer. This is the highest-reach teaching surface of the whole effort: it ships into every scaffolded agent project via .claude/skills/, and into the Claude Code plugin.

What landed

New "## Calling LLMs from Steps" section:

• Table: ctx.sapiom.llm.run (one-shot) vs ctx.sapiom.models.run (platform-driven multi-turn loop, models.coding.run for sandboxed coding — never for a one-shot, it overthinks) vs ctx.sapiom.agents.run (dispatch a deployed agent by slug).
• Explicit warning against sending single-shot intent through a multi-turn surface, with a worked "wrong vs right" example: WRONG = models.run + "reply with ONLY JSON" + JSON.parse; RIGHT = llm.run with a forced tool call for the fixed shape, and an explicit type-filtered content read (never assume content[0] — a thinking block can precede it). Notes the incoming output/structuredOf/textOf convenience (feat(tools): served class/lane disclosure, structured output, label ergonomics (SAP-2764) #682, still open) that will automate this once it ships, without depending on it now.
• The label rule: never pick a model; omit model (recommended) or pin "smart"; raw provider ids never honored; results disclose servedClass/lane.
• A debugging pointer (dashboard run detail → step row id → Run Inspector) and the public guide link.

New "## Naming Conventions" section — a table settling agent / run / task / session / dispatch, plus "label" as the author-facing term for a model: value, and the rule that new capabilities must not add a sixth meaning to an already-overloaded word.

Synced across all four copies skill-sync.test.ts guards: the canonical source, both scaffold templates (default, coding-pause), and the Claude Code plugin copy (plugins/sapiom/skills/). Verified with checksums (all four MD5-identical) and the test itself.

packages/tools/src/models/index.ts stale-comment fix: the "Default agent … agent.run / agent.launch" header named a namespace that's actually exported as models — fixed, along with two more instances of the same problem I found in the same file while I was in there: the top-of-file module docstring's OWN self-description ( `agent` capability + a code example calling agent.coding.run, when the real export is models.coding.run — arguably the more prominent occurrence, since it's the file's own introduction) and the Ambient-bound agent.coding namespace comment right above the block that flagged the issue. #682 (open) also touches this file but a different, non-overlapping region (the ModelRunSpec/CodingRunSpec type + JSDoc changes) — no hunk collision either way merges first.

Important finding — an existing terminology guard caught real mistakes in my first draft

scaffold.test.ts's "copies the %s template with exact Agent terminology" test bans certain internal service naming (case-insensitive) from anything shipped into a scaffold. My first draft tripped it twice:

1. The Naming Conventions "agent" row explained the internal-vs-external naming split by directly quoting the internal module's own docstring, which uses different internal vocabulary for the same concept. Reworded to convey the same fact (internal source comments use different, non-public vocabulary) without repeating the banned terms.
2. The debugging pointer cited a literal internal REST endpoint path — real (it's what packages/agent-core/src/client.ts/run.ts actually call), but that internal service naming must never reach scaffolded, customer-facing content. Dropped the literal path; the pointer now just says to use the Run Inspector.

This same constraint may affect four other, already-open PRs in this teaching stack that used the identical debugging-pointer text verbatim, none of which have this specific guard test, so nothing failed there, but the underlying "don't leak internal service naming to customers" policy this test enforces may still apply:

• docs(mcp): teach the LLM call-surface rule in the authoring instructions #679 (MCP instructions fallback)
• docs(harness): teach the LLM call-surface rule in the system prompt #680 (harness system prompt)
• two companion server-side PRs (backend MCP instructions + migration; server-side skills pointer)

Not touched here — flagging for your call rather than unilaterally reopening four already-reviewed PRs.

Testing

cd packages/agent-core
npx jest skill-sync                    # 7 passed
npx jest src/__tests__/scaffold.test.ts # 19 passed (including the terminology guard)
npx jest                                # full package: 18 suites, 171 passed

cd packages/tools
npx jest src/models                     # 25 passed
npx jest                                # full package: 29 suites, 564 passed
npx eslint src/models/index.ts && npx tsc --noEmit   # both clean

Needed a repo-root pnpm build first in this fresh worktree (agent-core/tools/mcp/harness all transitively depend on several unbuilt sibling packages).

Added a changeset (@sapiom/agent-core + @sapiom/tools, both patch) matching this repo's existing convention for skill-content-only changes (e.g. #163, #503).

Related

Refs: internal tracker
#679, #680 (the rest of the teaching stack in this repo)
#682 (open, touches the same file in a non-overlapping region)
Companion server-side PRs (internal, not linked here)

Checklist

• Full rule + warning box + worked example + naming conventions (the complete version)
• Synced across all 4 copies skill-sync.test.ts guards (checksum + test verified)
• models/index.ts stale-comment fix folded in, no overlap with feat(tools): served class/lane disclosure, structured output, label ergonomics (SAP-2764) #682
• Terminology-guard test respected — flagged the same risk for 4 earlier PRs rather than silently reopening them

🤖 Generated with Claude Code

https://claude.ai/code/session_01CDogyqvDnhy5iKgVpeZtWc

[gwitwer]

Consolidated into #685 — content unchanged plus the terminology scrub (already applied here; carried through the merge). Closing this in favor of that.