Skip to content

spec: capability skills end at the result; library exposes the skill - #35

Merged
David Koleczek (DavidKoleczek) merged 1 commit into
mainfrom
spec/capability-skill-and-library-surface
Oct 16, 2026
Merged

David Koleczek (DavidKoleczek) merged 1 commit into
mainfrom
spec/capability-skill-and-library-surface

Conversation

@DavidKoleczek

Copy link
Copy Markdown
Collaborator

Changes

spec/invocation.md, under "Self-description":

  • A capability's skill carries when to use it, whether it is deterministic or model-backed, every argument and what it is for, a worked invocation, and the result. It no longer lists the failures.
  • "The library exposes the skill and each piece it is built from" becomes "The library exposes the skill."

Rationale

  • Failure behavior is specified under "Failure": a failure is loud, exits non-zero, and names its remedy. Restating error codes in every capability skill duplicates that and lengthens the help text an agent reads before each call.
  • The skill directory, repository, and resources are rendered into the skill text. Exposing each as its own library function adds public surface that callers do not need.

A capability's skill carries when to use it, whether it is deterministic or
model-backed, every argument, a worked invocation, and the result. Failure
behavior stays specified under "Failure": a failure is loud and names its
remedy, so the skill does not restate it.

The library exposes the skill itself. The skill directory, repository, and
resources are rendered into the skill text, so they need no separate public
accessors.

Generated with Amplifier

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant