17 AI Agent Action Catalogue Spec

AI Agent Action Catalogue Spec Skill

Use When

• defining the schema-bound tools an AI agent may invoke, including side effects, reversibility, approvals, audit fields, quotas, and kill switches; use agent PRD for user outcomes.
• Use this procedure when the required source artefacts are available and AI agent action catalogue is the next lifecycle deliverable.

Do Not Use When

• Use ai-agent-feature-prd-spec when that neighbouring route owns the decision or deliverable.
• Do not invent missing project evidence, standards clauses, thresholds, or stakeholder decisions.

Required Inputs

Workflow

1. Inspect the required inputs and log the exact sources, versions, and unresolved assumptions.
2. Apply this skill's existing domain workflow and decision rules to produce AI agent action catalogue.
3. Stop when a required source, accountable decision owner, or deterministic test oracle is absent.
4. Recover by preserving valid work, marking the blocked scope, and returning the narrowest qualified artefact plus the next evidence needed.

Outputs

Evidence Produced

Capability and permission boundaries

Read and search are required. Editing is allowed only when the request authorises creation or repair of the named requirements artefact. Publishing, production mutation, destructive action, spending, and certification require explicit authority.

Degraded mode

Fallback: if a required file, reviewer, standard source, network check, renderer, or execution capability is unavailable, return the narrowest useful qualified result and mark the affected check not assessed; never convert an unassessed check into a pass.

Decision Rules

Quality Standards

• Preserve stable identifiers and bidirectional traceability from project evidence to AI agent action catalogue and its acceptance checks.
• Apply ISO/IEEE measures only with a named metric, method, threshold, evidence source, and responsible reviewer; run the anti-slop gate before release.

Anti-Patterns

• Producing AI agent action catalogue from assumed context. Fix: cite the project source or mark the scope blocked.
• Accepting a material requirement without a deterministic oracle. Fix: add a measurable result, boundary, and verification method.
• Crossing into ai-agent-feature-prd-spec without routing the decision. Fix: hand off the named input and preserve trace links.
• Treating an unavailable check as passed. Fix: mark it not assessed and state the release consequence.
• Claiming standards, statutory, or stakeholder approval without evidence. Fix: cite the source and reviewer or qualify the claim.

References

• Skill authoring and release standard
• Skill guidance
• Executable generation logic
• Agent Reversibility Classification Rubric
• Ai Agent Action Catalogue Template

Overview

The action catalogue is the single source of truth for what tools an agent may call. The planner may only emit tool calls whose names appear in the catalogue. The dispatcher refuses any tool call not in the catalogue. The catalogue is the contract that makes agent behaviour analysable, auditable, and operable.

Core Instructions

Step 1: Inventory candidate tools

Walk the agent FRs from ai-agent-feature-prd-spec and gather every tool the planner could call to satisfy a step. Include reads, writes, external API calls, and internal RPCs.

Step 2: Apply the reversibility classification rubric

For each tool, classify as one of:

See references/agent-reversibility-classification-rubric.md for the full rubric and edge-case treatment.

Step 3: Declare schema and side-effect class

Each tool entry:

name: email.draft.create
description: Create a draft reply in the inbox owner's drafts folder; does not send.
input_schema:
  type: object
  required: [thread_id, body]
  properties:
    thread_id: { type: string }
    body:     { type: string, maxLength: 8000 }
output_schema:
  type: object
  properties:
    draft_id: { type: string }
side_effect_class: write-internal
reversibility_class: compensable
compensating_tool: email.draft.delete

Side-effect classes: read, write-internal, write-external (to a system outside our trust boundary), billing, network-egress.

Step 4: Declare per-tier availability

Each tool entry states which pricing tier may include it for which autonomy level:

tier_availability:
  free:       [L0]
  pro:        [L0, L1, L2]
  enterprise: [L0, L1, L2, L3]

Tools with side_effect_class != read shall not be available on Free tier.

Step 5: Declare audit fields

For every tool call the dispatcher shall log:

• tenant_id, user_id, agent_run_id, plan_id, step_index.
• tool_name, input_args_redacted, output_summary_redacted, latency_ms, cost_usd.
• outcome (success / refused / error / timeout / kill-switch-aborted).
• irreversibility_class snapshot at call time.
• human_approval_event_id if applicable.

Step 6: Declare rate-limit class

Each tool maps to a rate-limit class enforced at the dispatcher:

Step 7: Declare kill-switch behaviour

Each tool entry states:

• Whether the global agent kill-switch refuses this tool (yes for all writes; no for cheap reads).
• Whether the per-tenant kill-switch refuses this tool.
• The user-visible message returned on kill-switch refusal.

Step 8: Write the spec

Action_Catalogue_Spec.md sections: 1) Catalogue summary table, 2) Reversibility rubric, 3) Per-tool entries (or pointer to action-catalogue/<tool>.yaml), 4) Tier availability matrix, 5) Audit field schema, 6) Rate-limit class table, 7) Kill-switch behaviour, 8) Change-control protocol (PR + ADR + red-team smoke before merge), 9) Traceability to agent FRs.

Standards

• OWASP LLM Top 10 (agentic addendum)
• Anthropic tool-use guide (schema discipline)
• NIST AI RMF MEASURE-2 (tool misuse)
• ISO/IEC 42001 Clause 8 (operation)

Compliance metadata fields (additions)

When the SaaS is in scope of SOC 2, ISO 27001, or HIPAA, each tool entry shall carry the following additional metadata fields:

phi_touch:               # none | limited | clinical
cardholder_touch:        # none | reads | writes  (for PCI-DSS scoping)
protected_class_decision: # none | applies (for EU AI Act high-risk + EEOC + Colorado + NYC AEDT)
evidence_class:          # access | approval | integrity | monitoring | change | privacy
retention_minimum:       # ISO 8601 duration; floor per HIPAA / DPA where applicable

These fields drive:

• HIPAA classification per 22-ai-agent-hipaa-control-pack (HIPAA_PHI_Touch_Classification.md).
• SOC 2 / ISO sampling stratification per 25-ai-agent-evidence-pack-spec.
• EU AI Act high-risk treatment per 15-ai-act-and-regulatory-compliance-doc.

A change to any of these fields requires an ADR per the agent ADR catalogue.

Resources

• logic.prompt, README.md, references/ai-agent-action-catalogue-template.md, references/agent-reversibility-classification-rubric.md.