9  Skills: Portable Procedures Without Hidden Authority

Part III · Skills and the compositional research toolchain

Implementation baseline: business-tech-presentation 1.1.0 · reviewed reference snapshot 45a903c

A skill can explain how to do work without gaining permission to do it. The Northstar presentation workflow makes that separation concrete: reviewed guidance shapes the deck, while a separately authorized tool—and only that tool—may construct a PowerPoint artifact.

9.1 Procedure is not authority

A skill is a reviewed, non-executable procedure. It can describe an evidence method, narrative sequence, quality checklist, or accessibility practice. A tool is executable capability with a schema, policy gate, limits, progress, and result contract. Confusing the two turns instructional text into an implicit plugin system.

The implemented boundary is deliberately asymmetric:

Concern Skill Tool
Primary role Explain a reviewed procedure Perform a bounded operation
Representation Integrity-checked text and declared resources Compiled server-owned implementation
Selection Static skills[] entry in agent.yaml Separate static tools[] entry
Effect Adds context May consume compute, network, or create an artifact
Authority None Only the authority granted by current policy
Model control May request a declared resource May propose typed arguments only

Loading text does not register a function. It cannot choose a provider, read credentials, open a path, install a package, enable network access, execute a bundled script, increase a quota, or alter agent.yaml. A procedure can say “inspect evidence before writing,” but it cannot make an inspection tool exist.

Treat skills as integrity-bound documentation and tools as separately authorized effects. Progressive disclosure changes what the model can read, not what the system permits it to do.

9.2 Static admission before progressive disclosure

The live configuration names reviewed IDs, not directories:

skills:
  - name: business-tech-presentation

tools:
  - name: presentation_builder

The static skill catalog maps business-tech-presentation to one reviewed package identity and profile. There is no search path, dynamic import, package resolver, URL, arbitrary prompt, or caller-supplied directory. Unknown and duplicate names fail startup. The current dependency rule also fails startup unless business-tech-presentation and presentation_builder are selected together. That pairing expresses a reviewed operational profile; it does not collapse their authority.

The server initially gives the coordinator only a short routing description. When presentation work becomes relevant, the coordinator can call load_skill. The successful result admits the bound SKILL.md, or one declared textual reference or asset, into context. This is progressive disclosure: detailed procedure is paid for in context only when needed.

The Pi client renders a successful operation as a business-tech-presentation · skill · completed card. Without that event, a transcript does not establish that the skill was loaded. The card is operational evidence of the load, not proof that every instruction was followed.

9.3 Integrity-bound package and declared resources

The skill package has a manifest that records its identity, profile version, and every payload file’s role, byte count, and SHA-256 digest. Startup rejects:

  • missing or undeclared payload files;
  • changed byte counts or digests;
  • duplicate, hidden, absolute, or unsafe paths;
  • symbolic links;
  • unsupported front matter or profile versions;
  • oversized content; and
  • identity or version mismatch.

Declared resources include the core procedure plus bounded narrative, visual, evidence, accessibility, outline, and theme material. Declaration has two purposes. It makes the review set finite, and it prevents a later filesystem addition from silently becoming model context.

Script files illustrate an important distinction. A manifest can integrity-check a script as package material without granting it execution authority. load_skill does not return scripts, and the live skill loader does not run them. Integrity answers “are these the reviewed bytes?” It does not answer “may these bytes execute?”

SHA-256 binding also has limits. It detects a change relative to the reviewed manifest under the collision-resistance assumption; it does not establish that the procedure is correct, safe for every task, or authored by a trusted party. Review, package admission, and execution authorization remain separate gates.

9.4 The Northstar presentation workflow

The research turn distinguishes five evidence classes: attached declarations, workbook measurements, generated image observations, deterministic calculations, and retrieved public guidance. The follow-up—“make a short pptx deck about those findings”—must preserve those distinctions rather than flatten them into a confident marketing narrative.

The skill guides the coordinator through a bounded sequence:

  1. state the governing message and intended decision;
  2. build an evidence ledger before slide construction;
  3. draft answer-first titles that form a coherent sequence;
  4. choose a visual form suited to each claim;
  5. preserve units, missingness, uncertainty, and source labels;
  6. use semantic construction rather than drawing instructions;
  7. inspect warnings and the rendered artifact; and
  8. describe completion honestly.

This workflow is portable because its important concepts are not PptxGenJS calls or PowerPoint coordinates. They are procedure-level obligations. The executable mapping from those concepts to a .pptx remains server-owned.

9.5 Separate presentation_builder authorization

presentation_builder is selected and authorized as a tool under Chapter 8’s policy loop. The skill cannot summon it when the tool is absent. Conversely, direct tool selection does not turn the skill package into executable code.

The model-facing contract accepts a semantic deck: filename, deck title, purpose, bounded slides, evidence labels, optional speaker notes, and supported semantic content. The initial profile includes title, statement, bullets, comparison, metrics, bounded charts, bounded flows, and admitted-image slides. The model cannot submit:

  • JavaScript, TypeScript, Python, HTML, shell, or macros;
  • host paths, package names, credentials, endpoints, or remote assets;
  • template files, private masters, component IDs, or recipe IDs;
  • slide coordinates, arbitrary styles, or unrestricted geometry;
  • OLE objects, embedded packages, or external relationships.

Image slides refer only to admitted invocation-local source IDs and require alt text plus an evidence label. Source notes accept bounded labels and optional credential-free HTTPS URLs. The schema is correction-friendly, but runtime parsing is authoritative: provider schema acceptance cannot bypass the implementation’s narrower checks.

9.6 Semantic input, server-owned composition

A semantic slide says what the content means. The server decides how that meaning is composed:

semantic slide
      ↓ validate and normalize
reviewed composition recipe
      ↓ select 2–5 reviewed components
bounded slide regions
      ↓ render and inspect
one PowerPoint slide

The independently authored gallery contains 312 mappings. Region-aware components receive an existing slide, a fixed region, validated content, and a reviewed variant. They do not create slides themselves. Startup validation rejects unknown component identities, incompatible regions, duplicate occupancy, geometric overlap, and unreviewed template references.

This design keeps model variability above the rendering boundary. A model can choose a comparison or process meaning, but it cannot ask the worker to place an arbitrary object outside the slide, invoke a hidden template, or reach an unreviewed component by name. Server-owned recipes can select reviewed timeline, cycle, network, handoff, six-stage, and linear-flow forms while retaining the same semantic request contract.

The trade-off is deliberate limitation. A bounded vocabulary cannot reproduce every bespoke visual expression. Portability here means controlled composition with known failure modes, not unrestricted design automation.

9.7 Missing values and numeric normalization

Presentation data frequently arrives with missing observations. The implementation distinguishes two uses of null:

  • conventional null in an optional field normalizes to omission; and
  • explicit null inside a chart series means a missing observation.

A missing chart observation renders as a gap or N/A, never as zero. Zero is a measurement; null is absence. Conflating them changes the claim shown by the deck.

Finite numeric strings such as "0.2" or "1e-1" can normalize to numbers before strict validation. Non-finite, malformed, or out-of-range values still reject. Bar charts use a visible zero baseline and support signed values. Line charts show scale, markers, and values. Automatically derived callouts describe neutral first-to-last change or observed range rather than guessing whether higher or lower is desirable.

These transformations improve correction behavior without weakening the boundary. Normalization is explicit and bounded; it is not permission to reinterpret arbitrary prose as data.

9.8 Artifact construction and validation

A killable Bun worker runs the pinned presentation library and emits a candidate OOXML package. Cancellation or deadline expiry terminates the worker because the underlying ZIP generation has no trusted cooperative cancellation contract.

Before admission, the server checks the typed deck limits and inspects the produced package. Validation rejects, among other conditions:

  • unexpected slide count;
  • macros or active/embedded packages;
  • external relationships;
  • negative geometry;
  • visible text below 9 pt; and
  • output above the configured byte ceiling.

Quality analysis separately warns about generic or repeated titles, claim-bearing slides without evidence labels, missing decision/risk framing, repeated layouts, generic chart units, and dense bullets. A warning is not structural acceptance, and structural acceptance is not visual approval.

Completed bytes enter a process-local opaque artifact store. The result contains a random artifact ID, sanitized filename, PowerPoint MIME type, exact byte count, SHA-256 digest, slide count, profile, and expiry. There is no artifact-listing endpoint. IDs expire, and a restart discards the store.

9.9 Verified handoff and safe replacement

The Pi extension observes the completed server-tool event, immediately fetches the short-lived artifact from the loopback /v1 endpoint, refuses redirects, and verifies both exact byte count and SHA-256 before saving. A matching digest without the expected length would not satisfy the handoff; both fields bind the retrieved payload to the completion metadata.

The local file is created with mode 0600. The sanitized default filename does not authorize replacement. If the target already exists, Pi requires confirmation rather than silently overwriting it. Explicit /presentation-artifact <id> and --save <id> operations retain the same verification boundary; preview also requires confirmation and does not expose deck bytes to the model or progress channel.

The opaque ID is short-lived local capability data, not durable source identity. It cannot be used as an attachment on a later invocation, and it should not be published. A saved file becomes ordinary user-owned local state and is outside the server lease.

9.10 What visual review does—and does not—prove

OOXML inspection can prove structural properties of the generated package. It cannot prove that a title wraps well, a chart communicates clearly, color choices work in every display environment, or a presentation application renders every object identically.

Representative acceptance used the exact installed Microsoft PowerPoint for Mac version, PDF export, and rendered-page inspection. The Northstar artifact also received a separate exact-artifact review. Those observations apply to the reviewed bytes, application versions, fonts, and host conditions. They do not establish compatibility with LibreOffice, Keynote, Google Slides, Windows PowerPoint, arbitrary fonts, future versions, or every semantic deck the model may propose.

The published Northstar recording shows skill load, tool completion, and digest-verified save. Its metadata explicitly says the generated deck was not visually inspected during that recorded session. The separately reviewed deck can support a later artifact-specific statement; the recording itself cannot be retroactively promoted into visual-quality evidence.

9.11 Failure modes

Skill-as-plugin. A package directory is scanned and bundled scripts execute. Keep the catalog static and make loading read-only.

Manifest-as-permission. Integrity-checked code is assumed safe to run. Separate byte identity from executable authority.

Semantic escape hatch. A “style” or “template” field accepts arbitrary model content. Keep model input semantic and map it through reviewed server recipes.

Missingness laundering. null becomes zero and changes a chart’s conclusion. Preserve gaps explicitly.

Artifact race. Metadata describes one payload while the client saves another. Verify exact length and digest after retrieval and before replacement.

Screenshot certification. One attractive rendering is generalized to every suite and input. Scope visual evidence to exact artifacts and versions.

9.12 How we test portability

Deterministic tests cover static catalog selection, dependency failure, manifest tampering, undeclared files, unsafe paths and symlinks, progressive resource loading, schema normalization, finite numeric strings, missing chart values, quotas, cancellation, OOXML relationships and package content, leases, digest/byte verification, and replacement behavior. Gallery tests cover all 312 mappings structurally.

Those tests establish bounded mechanics, not universal design quality. Paid model behavior, visual judgment, office-suite compatibility, and human comprehension remain separate evidence classes.

9.13 Pattern summary

Problem: Reusable procedures are often packaged with hidden code or treated as if model context grants authority.

Pattern: Select skills from a static catalog, bind every declared resource to a manifest, disclose them progressively, and require separately selected tools for every executable effect.

Result: A procedure can be portable and compositional without becoming a plugin loader or policy bypass.

Cost: Package review, manifest maintenance, a constrained semantic vocabulary, artifact inspection, and exact-artifact visual review remain necessary.

9.14 Exercises

  1. Add a second non-executable skill whose procedure uses an existing tool. Identify every startup and loading check required without adding a directory scanner.
  2. Construct a chart with [4, null, 0, 7]. Explain the visual and semantic difference among the middle values.
  3. Design an artifact replacement flow for an automated client. State what evidence could replace interactive confirmation without allowing silent overwrite.
  4. Classify each presentation check as schema, policy, package, handoff, or visual evidence. Explain why no single class subsumes the others.

9.15 Chapter contract

  • Scope: reviewed non-executable skills, progressive disclosure, integrity binding, semantic presentation construction, and artifact handoff.
  • Canonical claims: a skill supplies procedure but grants no authority; presentation construction remains a separately authorized tool effect.
  • Migration inputs: former skill-boundary prose, the implemented presentation package, artifact extension, quality audit, and Northstar presentation review.
  • Evidence gates: manifest and catalog tests, builder/package tests, exact byte/digest handoff, and artifact-specific visual review.
  • Demonstration slots: the Northstar skill-load/build/save sequence demonstrates the boundary but not universal visual quality.
  • Source-claim ledger: version, digest, renderer/application version, review status, and limitations accompany presentation evidence.
  • Exclusions: MCP and A2A transport/delegation belong exclusively to Chapter 18; generic tool authorization belongs to Chapter 8.