# Capability Authorization Gate

> |

- **Type:** Skill
- **Install:** `agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-capability-authorization-gate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AnthonyAlcaraz](https://agentstack.voostack.com/s/anthonyalcaraz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills/tree/main/skills/knowledge-representation/capability-authorization-gate
- **Website:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

## Install

```sh
agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-capability-authorization-gate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Capability Authorization Gate

## Overview

Self-aware agents must understand their own capabilities and limitations. The
Capability Model Pattern (Ch3, Example 3-5) makes operational parameters
explicit, queryable structure: each capability declares what it `requires`, an
`authorization-level`, and an optional quantitative `limit`. During planning the
agent determines whether it has the access, authorization, and headroom to
fulfill a request **before attempting it** — and routes/escalates when it does
not.

The chapter's worked example: a `Customer-Support-Agent` can
`Answer-Product-Question` (Public, needs only Product-Knowledge) but
`Process-Refund` requires Supervisor authorization, Financial-System-Access, and
caps at 500 USD. A 600-USD refund must be recognized as exceeding authority and
routed appropriately — "creating more reliable, trustworthy automation with
appropriate human oversight" — instead of attempting a prohibited action.

The gate returns three decisions:

- **allow** — capability declared, granted auth level >= required, all required
  resources present, amount (if any) within limit.
- **escalate** — the agent itself cannot, but a higher authority could:
  authorization too low, a required grant missing, or the amount over the limit.
  This is the "route appropriately" path.
- **deny** — the capability is undeclared. The agent has no such ability at all.

The DevOps manifestation (anchored in fictional AWS account `123456789012`):
capabilities like `read_metrics` (Public), `query_logs` (User),
`restart_instance` (Supervisor + `ec2:write`), and `scale_autoscaling_group`
(Supervisor, limit 10 instances) become the queryable authority model that gates
tool orchestration in Ch6. A User-level latency investigator can read metrics
and logs but escalates a restart or an over-limit scale.

## When to Use

- An agent must decide "can I do this?" before invoking a tool or taking an action
- Modeling agent operational boundaries (authority, required grants, limits)
- Building the queryable authority layer that gates tool orchestration (Ch6)
- Implementing graceful escalation/routing instead of attempting prohibited actions

Phrases: "capability model", "can the agent do X", "authorization level",
"operational limit", "escalate", "refund limit", "agent authority",
"queryable authority", "tool authorization gate".

## When NOT to Use

- **Human RBAC/IAM enforcement.** This is the agent's planning-time self-check,
  not your platform's identity policy. Real credential checks still happen at the
  API boundary.
- **Validating the capability NODE shape.** Use `schema-pattern-selector`
  (`capability_model` validation) to confirm a capability declaration is
  well-formed; this skill consumes well-formed declarations and decides.
- **As the only security control.** The gate prevents the agent from ATTEMPTING
  an over-authority action; it does not replace server-side authorization. Defense
  in depth: gate at planning AND enforce at the boundary.

## Process

| Step | Input | Action | Output | Verification |
|------|-------|--------|--------|--------------|
| 1 | agent spec JSON (id, granted_level, granted_resources, capabilities[]) | `lib.agent_from_spec(spec)` | `Agent` with `Capability` map | unknown auth level raises at construction |
| 2 | agent + capability type + optional amount | `lib.authorize(agent, cap, amount)` | `{decision, capability, reasons, required_level, granted_level}` | allow only if level met, resources present, within limit |
| 3 | over-limit amount | `lib.authorize(agent, "Process-Refund", 600)` | `decision == "escalate"`, reason cites limit | $600 vs $500 limit escalates, never allows |
| 4 | undeclared capability | `lib.authorize(agent, "X")` | `decision == "deny"` | deny is distinct from escalate |
| 5 | agent + capability + amount | `lib.can_do(agent, cap, amount)` | bool | True only when decision is allow |

## Rationalizations

| Agent rationalization | Documented rebuttal |
|------------------------|--------------------|
| "I'll just try the refund and let it fail downstream if it's too big." | Attempting a prohibited action is the failure mode the pattern exists to prevent. The chapter: recognize $600 exceeds the $500 limit and route it — do not attempt. Trying-and-failing leaks intent, may partially execute, and erodes the trustworthy-automation guarantee. |
| "Escalate and deny are the same — both mean 'no'." | They are different and the difference is actionable. Deny = the agent has no such capability at all (dead end). Escalate = a higher authority CAN do it (route to a supervisor / human). Collapsing them loses the routing decision the pattern enables. |
| "The agent is Supervisor now, so any refund amount is fine." | Authorization level and quantitative limit are independent checks. Even a Supervisor escalates a $600 refund if the capability's limit is $500. Raising the actor's level does not raise the capability's limit. |
| "Required resources are implicit — skip the grants check." | The chapter ties capabilities to concrete requirements (Financial-System-Access; in DevOps, `ec2:write`). A capability the agent is authorized for but lacks the resource grant for must still escalate. Skipping the grant check produces a confident "allow" the downstream API will reject. |
| "This duplicates IAM, just rely on AWS IAM." | This is the planning-time self-check that lets the agent decide BEFORE making the call (and route gracefully). IAM enforces at the boundary. They compose — defense in depth — they do not substitute. |

## Red Flags

- **Gate returns `allow` for an action the downstream API then rejects.** The
  agent's granted_resources/level are out of sync with reality — refresh the
  capability model from the actual authority source.
- **Everything escalates.** The agent's granted_level/resources are
  under-provisioned, or the capability declarations over-require. Re-check the
  spec; constant escalation defeats automation.
- **A capability has a limit but callers never pass an amount.** The gate warns;
  an unchecked limit is a silent over-authority risk. Always pass the amount for
  limited capabilities.
- **`deny` for a capability the agent clearly should have.** The capability is
  missing from the declaration — add it, do not work around the gate.

## Non-Negotiable Verification

1. **Run the benchmark battery.** `python cli.py benchmark` must report 10/10:
   - Public capability with resources -> allow
   - $600 refund over $500 limit -> escalate (reason cites the limit)
   - undeclared capability -> deny (distinct from escalate)
   - Supervisor + resources allows $400 but still escalates $600
   - DevOps: User escalates restart_instance and over-limit scale, allows read_metrics
   - unknown authorization level raises at construction
2. **Run the scenarios.** `python cli.py scenario support-refund` and
   `python cli.py scenario devops-latency` print allow/escalate/deny across the
   chapter's cases (DevOps anchored in AWS account 123456789012).
3. **Verify CLI help.** `python cli.py --help` exits 0 and prints this SKILL.md
   description (so any harness can discover the skill from --help).

## Security Posture

- **Prompt injection.** The agent spec JSON is untrusted configuration: an
  adversarial spec that inflates granted_level, pads granted_resources, or
  raises a capability limit turns the gate into a rubber stamp. The gate never
  executes spec content - load specs only from the real authority source, not
  from agent- or user-supplied text.
- **Data exfiltration.** No network calls, no file writes. Capability
  declarations may reveal internal authority topology; decisions go to stdout
  and the caller owns downstream piping.
- **Privilege escalation.** The gate is itself an anti-escalation control, but
  it is planning-time and advisory: an "allow" grants no credential, and a
  bypassed gate must still hit server-side IAM at the API boundary. Defense in
  depth - never let this replace boundary enforcement.

## Source Attribution

Distilled from *Agentic GraphRAG* (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch3 — Knowledge
Representation, section "Capability Model Pattern" (Example 3-5: the
Customer-Support-Agent with a $500 refund limit that escalates a $600 request).
The DevOps capability-as-queryable-authority manifestation is from "Applying
schema patterns to infrastructure", feeding the tool-orchestration authority
model in Ch6.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** [AnthonyAlcaraz/agentic-graph-rag-skills](https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills)
- **License:** MIT
- **Homepage:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-anthonyalcaraz-agentic-graph-rag-skills-capability-authorization-gate
- Seller: https://agentstack.voostack.com/s/anthonyalcaraz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.