agentsclimarketplace

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

Install
npx -y skills add leduykhuong-daniel/OSS-docs-as-code-kit --skill ai-agent-spec-authoring

Assembled 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.

TierStorageSizeEviction
WorkingIn-context50K tokensLRU
EpisodicLocal DB10K conversationsTTL 90d
SemanticVector 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.

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.