Ai agent spec authoring
Skill leduykhuong-daniel/OSS-docs-as-code-kit/skills/ai-agent-spec-authoring
Use when designing an AI agent feature and you need a single architecture document that declares persona + tools + memory + autonomy + cost budget + guardrails. Produces an "Agent Spec" (the HOW) as a companion to a PRD (the WHAT/WHY). Trigger phrases: agent spec, persona spec, tool fabric design, agent architecture, AI-native PRD companion, cost budget for agent.From its SKILL.md
npx -y skills add leduykhuong-daniel/OSS-docs-as-code-kit --skill ai-agent-spec-authoringAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as CC-BY-4.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
5.4 KB, as published. Nobody here has run it
AI Agent Spec Authoring
A docs-as-code technique for specifying AI agent features. The Agent Spec is a single living document that turns a product idea into a concrete, reviewable agent architecture — versioned and diffable like any other doc-as-code artifact.
Purpose
Create an Agent Spec artifact — one document declaring persona + tool fabric + memory tiers + autonomy boundaries + cost budget + guardrail policy.
Spec vs PRD: A PRD answers WHAT/WHY (problem, capability, success criteria). The Agent Spec answers HOW (concrete persona, tools, memory, guardrails). The PRD comes first; the Spec instantiates the PRD's persona section into a full architecture.
When to use
- You are building an AI agent / assistant feature and need an architecture contract.
- You have a PRD and need the companion "HOW" document.
- Reviewers need a diffable, version-controlled spec instead of a whiteboard sketch.
Pre-flight
- Read the PRD first — confirm it declares evaluation criteria (rubric + dataset + threshold).
- Pick an output path under version control, e.g.
docs/architecture/v{n}/agent-spec.md. - Decide the project type (fully agentic vs AI-augmented) — it changes autonomy defaults.
Workflow — 6 mandatory sections
1. Agent Topology (diagram)
Show actor + tools + external systems + human-in-the-loop (HITL) gates, then count them.
## 1. Agent Topology
```mermaid
graph TB
User[End User] -->|chat| Agent[Domain Co-Pilot]
Agent -->|RAG| KB[Knowledge Base]
Agent -->|tool: query_data| Backend[Domain Backend]
Agent -.->|HITL gate| User
Agent -->|trace| Observability[Tracing platform]
```
**Counts**: 1 agent | 3 tools | 3 memory tiers | 2 external systems
2. Memory Tier Design
A table: Tier / Storage / Size budget / Eviction.
| Tier | Storage | Size | Eviction |
|---|---|---|---|
| Working | In-context | 50K tokens | LRU |
| Episodic | Local DB | 10K conversations | TTL 90d |
| Semantic | Vector store | (corpus) | none |
3. Tool Fabric Registry
A YAML block — each tool declares: id, wiring, permission_scope, autonomy_tier (L0 manual → L4 autonomous), audit_trail, fail_safe_behavior.
tools:
- id: query_data
wiring: native
permission_scope: ["data/**"]
autonomy_tier: L4 # autonomous, audit-only
audit_trail: required
fail_safe_behavior: "Return empty + flag, do not throw"
4. Guardrail Layer
A table: Layer / Implementation / Fail-safe behavior. Map each layer to a known LLM risk (e.g. the OWASP LLM Top 10) so coverage is explicit.
5. Observability Plan
Declare: trace fields, latency SLO (p50/p95/p99), cost aggregation, eval-score monitoring, persona-consistency check cadence.
6. Cost Ceiling
token_ceiling_per_request: 50000 # hard limit → abort
latency_budget_ms: 30000 # 30s p95 SLO
monthly_spend_cap_usd: 200
model_routing_strategy:
classification: "small/cheap model"
reasoning: "mid model"
complex_synthesis: "large model"
abort_conditions:
- "tokens_in > token_ceiling_per_request"
- "monthly_spend > 1.2 * monthly_spend_cap_usd"
escalation:
- threshold: "monthly_spend > 0.8 * cap"
action: "Notify owner"
Self-validation — 5 AI-native principles
- P1 Agent-as-actor: §1 Topology delineates agent vs human vs tool.
- P2 Persona before tool: tools in §3 are chosen to fit the persona, not the reverse.
- P3 Eval before launch: rubric + dataset + threshold referenced from the PRD.
- P4 Cost as first-class: §6 explicit (token + latency + monthly + routing).
- P5 HITL by design: each tool has an autonomy tier; high-risk actions gate to a human.
Worked example
A "Customer Support Co-Pilot" agent spec:
- §1 1 agent, 4 tools (
search_kb,lookup_order,draft_reply,escalate_human), 3 memory tiers. - §3
draft_reply= autonomy L1 (human approves before send);escalate_human= L4. - §6 routing: cheap model for intent classification, mid model for reply drafting.
- §4 guardrail: output filter blocks PII echo; input filter rejects prompt-injection patterns.
The result is one reviewable file a teammate can diff, comment on, and approve in a pull request — the essence of docs-as-code applied to agent design.
Gotchas
- Don't mix Spec with PRD — Spec is HOW (lives in
docs/architecture/), PRD is WHAT/WHY. - Cost budget MUST have explicit abort conditions — silent over-budget is a production incident.
- Persona invariants ≠ system prompt — invariants are a contract ("always cite sources") that survives prompt rewrites; the system prompt is just one implementation.
- Autonomy tier must match persona — an L4-autonomous tool with a "conservative on uncertainty" persona is a contradiction; the spec review should catch it.
- Leave memory headroom — tool definitions + RAG context can consume 30% of the working tier.
- Default write-action tools to L1+ — autonomous write access is excessive agency.