ai-agent-tooling-and-hitl

name	ai-agent-tooling-and-hitl
description	Use when designing agent tool catalogs, tool schemas, action gating, human approval, and human-in-the-loop control for agentic AI systems.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

AI Agent Tooling And HITL

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use When

• Design tool catalogs, tool contracts, action scopes, and approval gates for agents.
• Decide when an agent action requires human review, confirmation, or escalation.
• Integrate agent tools with audit logs, reversibility, tenant policy, and runtime budgets.

Do Not Use When

• The work is not AI-specific or agentic-AI-specific.
• A narrower retained AI parent skill fits the request better.

Required Inputs

• Product, tenant, user, data, risk, and operational context relevant to the AI workflow.
• Target artifact: design, implementation plan, audit, test strategy, UX flow, commercial policy, or runbook.
• Constraints from security, privacy, reliability, billing, support, and compliance stakeholders when relevant.

Workflow

1. Read this SKILL.md first.
2. Load references/routing.md to select the absorbed child reference that matches the task.
3. Load only the selected child reference files needed for the current request.
4. Produce execution-oriented output with assumptions, risks, evidence, and next actions where relevant.

Quality Standards

• Keep routing explicit: name which reference files were used when the work depends on absorbed material.
• Preserve tenant isolation, auditability, cost controls, safety gates, and operational evidence when they matter.
• Prefer concrete contracts, checklists, tables, schemas, runbooks, and decision records over broad summaries.

Anti-Patterns

• Loading every absorbed reference by default.
• Treating AI-specific billing, compliance, safety, or UX concerns as generic SaaS work without checking AI failure modes.
• Hiding retired skill names; old slugs must remain discoverable through references/routing.md.

Outputs

• A concrete deliverable matched to the request: architecture, implementation plan, audit, policy, runbook, UX flow, test strategy, or operating model.
• The selected consolidated reference files and any assumptions, risks, evidence requirements, or follow-up actions that affect execution.

References

• references/routing.md maps retired child skill slugs to their consolidated reference folders.

Consolidated Child References

• Load references/routing.md to map retired AI child skill slugs to their reference modules.

Inputs

Artefact	Required?	Purpose
Tool schemas and side-effect classification	yes	Define callable actions
Identity, tenant, approval, and budget policy	yes	Enforce authority
Reversal and audit requirements	yes	Bound consequences

Capability contract

Default to read-only tool design. Tool invocation, approval simulation, and side-effect testing require isolated fixtures and explicit execution authority.

Degraded mode

Fallback without executable tools: validate schemas, permission scopes, approval policy, and reversal design statically; mark runtime enforcement unverified.

Decision rules

Action class	Gate	Failure avoided
Read-only, low sensitivity	Policy-scoped automatic call	Approval fatigue
Reversible mutation	Confirm policy and log result	Silent unwanted change
Irreversible, financial, external, or privileged	Just-in-time human approval	Unauthorised impact

Domain anti-patterns

• Giving one tool broad multi-action scope. Fix: expose narrow, typed actions.
• Trusting prompt text for authorisation. Fix: enforce identity and policy outside the model.
• Asking approval after execution. Fix: gate before side effects.
• Omitting idempotency and reversal. Fix: define both for every mutation.
• Logging arguments without protecting secrets. Fix: redact and classify audit fields.