Repo-Local Capability Binding

A portable skill names an abstract operation; a repo-local, agent-read markdown document binds that operation to whatever tooling this repo actually uses. The skill says "publish to the issue tracker." It does not say gh issue create. What the phrase means here is answered by docs/agents/issue-tracker.md in the repo, whose headings are literally the skill's verbs:

## When a skill says "publish to the issue tracker" → Create a new file under .scratch/<feature-slug>/ (creating the directory if needed). ## When a skill says "fetch the relevant ticket" → Read the file at the referenced path…

That document is a dispatch table written in prose, and it is the whole mechanism. It is why the answer to "how do I make your skills work with Jira / Linear / Beads?" is "it already does" — the skills were never coupled to a backend, so supporting one is a matter of writing down the binding, not branching the skill. The source's setup skill generates the binding interactively (pick GitHub / local markdown / other; "describe the workflow and I'll record it as prose") and links it from CLAUDE.md alongside the triage-label and domain-doc bindings, so every skill in the repo resolves its verbs the same way.

The durable idea is an old one arriving in a new substrate: an interface, with the implementation injected per-deployment — except both the interface and the binding are natural-language markdown read by a model, which is what makes the binding cheap enough to be worth writing for a one-person repo. It buys the same thing dependency injection buys: the skill library becomes shareable across repos whose infrastructure has nothing in common, which is the precondition for Skill Artifact Transfer at all. The vault has a prior instance of the same move at artifact scale — /to-tickets emitting one medium-agnostic artifact that reads either as a local tickets.md or as native tracker issues with blocking edges (Agent Task Graph).

The honest cost: the binding is prose, so nothing checks it. A stale or wrong binding doc fails at agent-interpretation time, in whatever way the model improvises, rather than at a type boundary.

Claims

• Couple a skill to an abstract operation, not to a tool; bind the operation to concrete tooling in a repo-local document the agent reads. principle — durable: it is the interface/implementation separation, and it is what makes a skill portable across repos at all. A skill that hard-codes gh issue create is a skill that only works where GitHub is; the indirection is the difference between a library and a local script.
• Write the binding document as a dispatch table keyed by the skill's own phrases — heading per verb, resolution underneath. best practice — context: natural-language skills read by a model, where the "call site" is a phrase rather than a symbol; keying on the exact phrase is what makes the lookup reliable. Contingent on the skills using stable, distinctive phrasing — the coupling is by string, and nothing enforces it.
• Generate the binding with a setup skill rather than asking the user to author it, and link it from the agent's always-loaded entry point. best practice — context: a distributed skill library facing users who will not read authoring docs; the source's setup interviews for tracker, triage labels, and domain-doc shape, then writes them and adds CLAUDE.md links. The cost is a bespoke bootstrap skill to maintain per library.
• "It already works with your tracker" is the payoff of the indirection, not a feature that was built — the recurring question ("how do I make this work with Jira?") is answered by writing the binding, not by adding a Jira integration. observation — a good diagnostic for whether the indirection is real: if new backends need code, it wasn't.
• A prose binding is unchecked: it fails at interpretation time, not at a type boundary. principle — durable, and the standing cost of natural-language interfaces. The flexibility that lets one document bind GitHub, local markdown, or "describe the workflow and I'll record it as prose" is exactly the absence of a checkable contract.
• The source's setup writes docs/agents/{issue-tracker,triage-labels,domain}.md plus CLAUDE.md links, and defaults the repo to a single bounded context ("multi-context is if you have a big monorepo… for 99% of people, a single context is going to be fine"). observation — the concrete layout as shown on screen; the 99% is the source's estimate, recorded as claimed.

Related

• Skill Artifact Transfer — the thing this enables: a skill set is portable only if its environment-specific couplings live outside it. Binding is the mechanism transfer needs.
• Agent Task Graph — the same indirection one level down, at artifact scale: /to-tickets emits one medium-agnostic ticket set that reads as local markdown or as native tracker issues with blocking edges.
• Context Routing — CLAUDE.md linking out to the binding docs is routing: point at where the answer lives rather than inlining it, so the binding costs nothing until a skill needs it.
• Agent-Computer Interface (ACI) — the binding doc is the interface surface the agent programs against; this page is about keeping that surface abstract and injecting the concrete end.
• CLI Tools over MCP Servers — the contrasting resolution of the same coupling question: reach the tool through a CLI the agent already knows, rather than declaring an abstract verb and binding it.
• Minimal Skill Surface — the binding doc is reference material pushed out of SKILL.md and behind a pointer; the skill stays small and portable for the same reason.
• Public Skill Adoption — why portability is load-bearing: a repo cloned by many is a repo whose infrastructure assumptions must be someone else's to declare.
• Golden Templates — the sibling for code: a verified concrete artifact adapted per repo, where this is an abstract verb resolved per repo.
• Distillate: The whole flow, end-to-end: the smart zone is the unit of work

Linked from

• Abstract-to-Concrete Grounding
• Agent Task Graph
• The whole flow, end-to-end: the smart zone is the unit of work
• Minimal Skill Surface