design-agent-contract
Design, scaffold, or refactor a production agent's contract and package. Use when defining a declarative agent specification, dependencies, typed input and output, prompts, execution classes, governan
SKILL.mdskills/design-agent-contract/SKILL.md
GitHubDesign an Agent Contract
Create an explicit, typed agent package whose contract can be reviewed before implementation details.
Workflow
- Inspect repository instructions, dependency pins, existing agent packages, and test conventions.
- Write the behavioral contract before the prompt:
- purpose, owner, users, and non-goals;
- input, dependency, and output types;
- execution class and risk assessment;
- allowed skills and tools;
- latency, quality, and cost objectives;
- escalation and fallback behavior.
- Select an execution class:
ephemeralfor bounded work without externally visible side effects;durablefor retries, timers, recovery, or externally visible side effects;human_governedfor consequential operations requiring approval.
- Use
assess-agent-riskto select a governance tier from low, medium, high, or critical based on scenario-level inherent risk and mandatory floors. Keep residual risk and launch decision separate. - Create a consistent package layout. Keep orchestration, tools, runtime skills, prompts, types, policy, and tests separate.
- If the project provides scaffolding tooling, use it, then inspect and customize every generated placeholder.
- Implement a construction function (factory) that receives configuration and dependencies explicitly. Keep module loading free of network calls and mutable runtime work.
- Use schema-validated types for dependencies, structured output, tool inputs, and externally persisted payloads.
- Validate the specification with the project's own validation tooling or CI, then add contract tests for construction, output validation, capability allowlists, and failure behavior.
- Record unresolved decisions rather than silently inventing product policy.
Required Output
Produce or update:
- a declarative agent specification or equivalent manifest;
- a typed agent factory;
- dependency and output types;
- explicit skill and tool allowlists;
- tests and an eval entry point;
- a risk assessment covering execution class, governance tier, residual risk, controls, evidence, and decision.
Read the design standard before changing architecture. Use the examples when drafting a specification or package.
Guardrails
- Do not hide business policy in system prompts.
- Do not give an agent every registered tool by default.
- Do not use untyped dictionaries at durable or external boundaries.
- Do not couple the agent object to durable workflow code.
- Do not declare readiness without eval, observability, and operational owners.
Completion Check
Confirm that another engineer can answer, from repository artifacts alone: what the agent does, what it may call, what it returns, how it executes, how it fails, and how it is evaluated.