Billing, support, and growth teams want to add tools to the same product agent. Billing wants invoice reminders. Support wants refunds. Growth wants campaigns. A shared tool registry alone will not align those teams’ permissions, review screens, or operational responsibilities.
A capability is a product job with an owner and a contract. A tool is one callable operation. A skill teaches the agent how to combine operations for a job. Those three units should relate without becoming interchangeable.
Give each capability a domain and an owner
Use names that describe product work: billing.reminders, support.refunds, or marketing.campaigns. The domain gives a team a place to own rules and failures. Avoid building the entire taxonomy around vendors such as CRM or email; the same email service can support several different jobs.
A capability record can describe the operation’s meaning even when a framework changes.
| Field | Reminder capability example |
|---|---|
| Owner | Billing team; finance operations owns the business result |
| Inputs and objects | Workspace, invoice IDs, approved contact roles |
| Tools | List eligible invoices, read disputes, prepare messages, send reviewed messages |
| Authority | Named billing connection plus delegated finance review |
| Consequence | External email and a CRM note |
| Review | Exact recipients and message text, with a locked selection |
| Recovery | Stop unsent work; sent email cannot be recalled |
| Result | Per-invoice send status and provider receipt |
| Limits | Defined batch size, spend budget, and repeat-contact policy |
| Rollout | Workspace eligibility, version, pause control |
| Tests | Disputes, changed contact, paid invoice, duplicate event, revoked connection |
The platform should reject a registration missing execution policy or a real owner. A polished tool description is not a complete capability contract.
Put procedures in skills and permissions in services
A reminder skill can explain the order of work: read the invoice, exclude disputes, choose the approved billing contact, prepare a draft, and request review. The skill can also include examples of ambiguous requests and cases that require clarification.
The Agent Skills specification describes a directory with SKILL.md, metadata and instructions, plus optional scripts, references, and assets. The format also supports progressive loading. The experimental allowed-tools field depends on host support; metadata alone does not establish an application security boundary.
A product does not need to adopt the file format to make procedures explicit. A versioned instruction bundle with examples can serve the same product purpose. Use a portable format when multiple compatible hosts need the procedure.
The distinction matters during a change. Updating a skill to mention refunds must not grant a refund permission. A skill may request a tool; the server decides whether the acting identity may use the tool.
Version the whole job, not only the prompt
Record the model configuration, tool schema versions, skill version, and operation policy version on each run. Keep the original versions available when investigating a result.
Pin pending proposals to the versioned operation and exact inputs that produced the review. A rollout should not reinterpret yesterday’s approved proposal under today’s broader skill. Expire the proposal or prepare a new version when the relevant contract changes.
Change reviews should explain behavior: a new contact source, a different dispute exclusion, or a wider sending scope. “Prompt improvement” hides a product change if the new wording causes the agent to contact additional customers.
Make one platform serve every entry point
The useful shared platform includes:
- Context resolution and retrieval under the acting identity.
- Tool registration with schemas, ownership, and capability metadata.
- Proposal storage and a common review-card contract.
- Authorization and current rollout checks in the operation service.
- Durable jobs, cancellation, retries, and per-object receipts.
- Trace IDs connected to jobs, evaluations, and product analytics.
- Notification delivery and a durable inbox for pending decisions.
The agent can appear in a drawer, a native editor, a mobile view, or an external host. Shared platform contracts keep the operation consistent while each surface presents the detail the person needs.
An integrated experience can make a proposal easier to inspect. A drawer can work well for explaining or initiating work. Neither surface replaces execution checks. Surface design compares those choices.
Use feature flags for rollout, not authority
A workspace flag can make reminder drafting available to a pilot group. An authorization policy can decide which invoice and connection the acting account may use. Both checks belong in the execution path.
Define pause behavior by capability: stop new proposals, cancel active preparation, or block further writes. A remote provider may already have accepted an email. The receipt must preserve completed effects even after the capability is disabled.
Keep read-only diagnosis available when possible. Turning off a sending capability should not require disabling invoice explanations and the history needed to investigate the incident.
Give contributing teams a release contract
Each team should ship the capability schema, saved evaluation cases, review UI fields, operation implementation, telemetry, recovery description, and an on-call owner together. The platform team owns the common runtime and contracts; the domain team owns the meaning and correctness of the business operation.
Cross-domain requests need explicit limits. “Collect this overdue balance” should not silently combine billing reminders, support refunds, and marketing campaigns. A plan crossing capabilities should disclose the separate consequences and collect the appropriate decisions.
Start with one domain end to end. Generalize the common contracts after a second domain exposes actual differences. A platform built before any complete job often standardizes imagined requirements.
Review platform quality through completed work
A weekly review should connect capability versions to verified results, authorization failures, declined proposals, duplicate attempts, unknown outcomes, and late corrections. Tracing explains vendor options for inspecting the run. The BizOps scorecard separates product outcomes from infrastructure activity.
The platform’s goal is to let another team ship a useful job without inventing new permission, review, and history conventions. Tool count is an inventory measure; tool count does not establish that people can complete more work.