Trace Brief — A practical journal about AI agents

AI Agent Identity and Attestation | Trace Brief

2026-08-02T00:00:00Z

An assistant that drafts an answer and an agent that can send the answer are not the same security problem. The latter crosses a boundary: it acts on a service, touches data, and may spend another person's authority. A user login alone cannot explain which software acted, which running copy held the credential, or why that copy was allowed to perform this particular operation.

This guide follows AI agent identity and attestation for programmatic access from 2018 to 2026. The dates do not mark one neat standardization cycle. They trace several pieces that matured separately: workload identity, OAuth delegation, fine-grained authorization, proof-of-possession tokens, and, most recently, agent-specific identity models.

Put those pieces together and you get a stack, not a magic credential. Identity names the agent. Attestation establishes what is running. Authentication proves control of a credential. Authorization limits an action. Delegation records whose authority is involved. Audit preserves enough of that chain to reconstruct the event later.

Separate the agent from the human

An agent acting for a person still needs its own identity. Treating it as the person's session collapses two questions into one:

Who supplied the authority or requested the work?
Which software principal made the call?

Those answers can differ even during one task. A finance employee may start an expense review, an orchestration service may create a short-lived agent instance, and that instance may call a document system and a payment API. If every request looks like the employee, an investigator cannot distinguish the employee's direct actions from decisions made by the agent. Revoking the agent without disabling the employee also becomes difficult.

The opposite shortcut is incomplete too. A unique agent identity with no link to its initiator shows which software acted, but not whose authority it used. This matters when the same agent serves many people or receives work from another agent.

The clean model keeps at least two principals:

the human, service, or upstream agent that supplied the request and authority;
the agent software or runtime instance that attempted the action.

Microsoft's 2026 Entra Agent ID documentation is one concrete implementation of this split. It models an agent identity separately from a human identity and distinguishes autonomous access from delegated access. Its blueprint and instance objects are product-specific, not a universal standard, but the separation is useful beyond that platform.

The split draws another boundary. A prompt, model name, tool list, or downloaded skill can change behavior, but none is an access-control principal by itself. The distinction matters for systems built from reusable instruction packages such as the ones covered in our Agent Zero and SKILL.md guide. Behavior belongs in the evidence around a decision; it is not permission.

The five-part identity stack

A production design can be tested against five records. They may live in different systems, but each answers a different question.

1. A stable software definition

The first record identifies the agent as a configured piece of software. Call it a blueprint, registration, service identity, or agent definition. It points to an owner, approved purpose, allowed deployment context, and lifecycle state.

This identity survives ordinary restarts so administrators can review policy and revoke the agent as a product. Do not share it between unrelated agents merely because they use the same model. A travel assistant and a payroll assistant need different identities even if both call the same inference API.

2. A runtime instance backed by attestation

The second record identifies the running workload. A stable definition says what was registered; attestation supplies evidence about what is executing now and where.

SPIFFE defines a SPIFFE Verifiable Identity Document, or SVID, as a cryptographically verifiable workload identity. SPIRE can issue one after node and workload attestation. Its agent interrogates the local environment, such as the kernel or a Kubernetes kubelet, and compares selectors with registration entries before returning an identity document.

Attestation is stronger than placing a secret in an environment variable. A copied API key can run anywhere. A short-lived workload credential issued after platform checks can be tied to a particular trust domain and renewed without storing a long-lived secret in the agent.

Attestation still does not prove that a model's proposed action is sensible. It answers a narrower question: is this the workload we expected to receive this identity?

3. The subject and delegation chain

When an agent acts for someone else, the request needs both an actor and a subject. OAuth 2.0 Token Exchange, standardized in RFC 8693 in 2020, provides a vocabulary for that relationship. A security token service can receive a subject token and, where needed, an actor token. The resulting token can carry an act claim that records the current actor and, in nested form, earlier actors in a delegation chain.

Delegation and impersonation are not synonyms. With impersonation, the receiving service may see the agent as if it were the subject. With delegation, the service can preserve the fact that the agent is acting on the subject's behalf. Agent systems usually benefit from the latter because the separate actor is important evidence.

Keep chains bounded. If one agent can delegate to a second, which can freely delegate to a third, the original approval becomes less meaningful at every hop. Policy should limit who may receive delegated authority, which audience may accept it, and how long it lasts.

4. An action-specific authorization grant

An identity is not permission. A valid agent may still be forbidden to read a salary file, issue a refund, or message an external address.

OAuth scopes are often too broad for high-consequence actions. RFC 9396, published in 2023, adds an authorization_details structure for richer requests. It can express a type of authorization along with actions, locations, and other resource-specific fields. A payment grant, for example, can name a payee, amount, currency, and permitted action instead of handing the agent a general payments.write scope.

Keep fine-grained grants short-lived and audience-bound. The resource server must validate them rather than trusting the agent's own account of its limits. For risky operations, the policy can also require fresh human approval tied to the exact action details.

5. An audit event that joins the chain

The final record connects the action to the identities and policy decision. A useful event contains more than an agent name and a success flag. It preserves:

the stable agent definition and running instance identifiers;
the subject, actor, and any relevant delegation link;
the requested action, target resource, and authorization decision;
the credential or grant identifier without logging the secret itself;
the policy version, approval reference, time, result, and correlation ID.

The model and instruction versions may also be relevant, especially when a behavioral change explains why an allowed action was selected. Those fields support diagnosis, but they do not replace the principal and grant identifiers.

The broader AI agent ecosystem places this identity stack in the control layer around the model. That location is deliberate. The runtime and policy system must enforce access even if the model is confused, manipulated, or simply wrong.

How the stack evolved from 2018 to 2026

There was no single moment when "agent identity" arrived. The important milestones came from workload security and authorization before agent-specific products adopted them.

2018: SPIRE enters the cloud native ecosystem

SPIRE was accepted into the Cloud Native Computing Foundation in March 2018. Its purpose was workload identity in dynamic infrastructure, not AI agents. An agent runtime remains a workload and does not warrant a weaker identity merely because a model participates in its control loop.

SPIRE moved to incubation in 2020 and graduated in 2022. By then, the pattern of attesting a workload and issuing a short-lived identity was established independently of the recent agent market.

2020: OAuth names delegation actors

RFC 8693 standardized token exchange in January 2020. Subject and actor tokens gave security systems a way to distinguish the party whose authority is represented from the party currently acting. This is one of the closest existing building blocks for an agent working on behalf of a user or another service.

2023: Authorization becomes more specific

Two 2023 RFCs cover different weaknesses in bearer-token access. RFC 9396 lets a client ask for detailed authorization instead of relying only on coarse scopes. RFC 9449, known as DPoP, lets an OAuth client demonstrate possession of a key and binds issued tokens to that key. This reduces the value of a stolen token and helps detect replay.

DPoP is not workload attestation. A DPoP proof shows that the caller controls a private key; it does not establish which binary, container, or orchestration environment holds the key. A design may use DPoP and an attested workload identity together because they answer different questions.

2026: agent-specific identity becomes an explicit standards problem

In February 2026, NIST published an initial concept paper on software and AI agent identity and authorization. The paper asks how existing standards can support agent identification, authentication, authorization, least privilege, delegation, human binding, auditing, nonrepudiation, and data-flow provenance. It discusses OAuth, OpenID Connect, SPIFFE and SPIRE, SCIM, zero trust guidance, and Model Context Protocol authorization.

NIST also launched an AI Agent Standards Initiative covering secure, interoperable agents. The important signal is not that the problem has been solved. It is that agent identity now has a dedicated standards and reference-implementation agenda.

Microsoft Entra Agent ID offers a current product example with agent blueprints, instances, sponsors, permissions, and agent-aware sign-in logs. Other vendors will use different objects. One inference follows from the standards landscape: no single format yet represents the whole chain from software registration through workload attestation, delegation, action authorization, and audit.

A programmatic access flow

Consider an employee who asks an internal agent to send a contract to a supplier. A well-bounded flow could work like this:

The orchestration service accepts the request under the employee's authenticated session and creates a task record.
It starts an agent instance from an approved software definition. The workload platform attests the process and issues a short-lived workload identity.
A token service checks that this agent may act for this employee in the contract workflow. It exchanges the relevant tokens and preserves agent and subject identities.
The agent proposes send_contract, naming the document, recipient, and expiry. The model's proposal is data, not authority.
The policy service compares those details with the employee's role, the agent's policy, recipient rules, and any approval requirement.
If allowed, it issues a narrow token for the document service. Rich authorization details describe the permitted action and resource. DPoP can bind that token to the instance's key.
The document service validates issuer, audience, expiry, proof of possession, action details, and local policy before sending anything.
Each component writes correlated events. The final record can show who requested the work, which agent instance acted, what grant it used, and what the service returned.

Now change one fact: the prompt contains instructions copied from an untrusted document telling the agent to send every contract in the folder. The model may propose the broader action, but the original grant covers one named document and recipient. The policy service rejects the request.

That is why prompt-injection defenses and identity controls are complementary. Filtering malicious instructions may reduce bad proposals. Precise authorization limits what a successful manipulation can execute.

Implementation choices that hold up

Start with the protected action, not with the identity product. List the resources an agent can read or change, then define the evidence required at each boundary.

Prefer ephemeral credentials over embedded secrets

Long-lived API keys make identity ambiguous and rotation disruptive. Use a platform identity, workload attestation, or secretless exchange to obtain short-lived credentials. Keep the signing key in the platform's protected key store where possible.

Separate definitions from instances

A stable definition helps with ownership, policy, inventory, and revocation. Per-instance identity helps with containment and investigation. The two-level design also supports parallel runs without making all copies indistinguishable.

Make delegation visible to the resource server

Do not flatten the agent into the human unless a legacy integration leaves no alternative. Preserve actor and subject claims, and make the receiving service validate both. For autonomous tasks, state that no human subject is present instead of inventing one.

Reduce authority at every hop

A downstream token should have no more authority than the upstream grant and normally should have less. Restrict audience, resource, action, time, and delegation depth. Never let a model construct trusted claims directly.

Bind sensitive grants to a key

Sender-constrained tokens reduce replay risk. DPoP is one option for OAuth clients; mutual TLS is another in suitable environments. Key binding does not remove the need for short lifetimes, audience checks, or workload attestation.

Design revocation and inventory together

Administrators need to find every agent definition, owner, sponsor, active instance, credential, permission, and downstream dependency. Revocation should cover one instance, the stable agent, a user-to-agent delegation, or a compromised signing key without requiring a system-wide shutdown.

Common failure modes

Shared human credentials erase the actor boundary. The logs may look complete while attributing an agent's actions to a person who never performed them directly.

Static agent API keys prove little about the current workload. They can leak into logs, images, developer machines, or unrelated deployments. Rotation becomes the only response because there is no instance boundary.

Attestation without authorization proves that the expected workload is running, then may grant it far too much access. Authorization without attestation may issue a precise grant to an unknown copy of the software. Both controls are necessary for sensitive programmatic access.

Broad scopes turn a small model error into a large operational event. If an agent needs to refund one order, a token that can refund every order is a policy failure even when the agent behaves correctly in testing.

Incomplete delegation logs make multi-agent chains impossible to reconstruct. Recording only the final agent hides who initiated the task and which intermediary passed the authority onward.

Unbounded delegation lets authority drift. A grant intended for one workflow can reach agents with different owners, instructions, or trust domains. Cap the number of hops and explicitly allow recipients.

Finally, identity metadata can become stale. Owners leave, blueprints change, and dormant agents retain permissions. Lifecycle controls such as inventory review, expiry, sponsor reassignment, and automated deprovisioning matter as much as token issuance.

Deployment checklist

Before an agent receives production access, confirm that the system can answer these questions with records rather than assumptions:

Does the agent have a unique, stable software identity and accountable owner?
Does each running instance receive a short-lived identity after workload or platform verification?
Can a resource server distinguish the agent from the human or service on whose behalf it acts?
Are autonomous and delegated actions represented differently?
Is authorization limited by audience, resource, action, time, and delegation depth?
Are high-impact actions tied to explicit details and, when needed, fresh approval?
Are tokens sender-constrained where replay would be costly?
Can policy reject an action even when the model requests it and the identity is valid?
Do logs join the definition, instance, subject, actor, grant, policy decision, and result?
Can administrators revoke one instance, one delegation, or the whole agent without disabling unrelated users?

If any answer is "no," adding a more capable model will not close the identity gap. Fix the missing boundary first. The standards and product names will keep changing, but the underlying questions are stable: which software is running, whose authority it carries, what exact action it may take, and what evidence remains after it acts.

Trace Brief maintains this guide as standards move from concept papers into specifications and deployments. See the editorial policy for how sources and updates are handled.

AI Agent Ecosystem 2026: A Practical Map | Trace Brief

2026-08-02T00:00:00Z

Put a support bot with one retrieval tool beside a coding assistant that edits a repository and a procurement workflow that runs for hours. People call all three AI agents, even though their permissions, state, and failure modes have little in common.

A vendor chart tends to blur those differences, and it goes stale quickly. This guide maps the responsibilities that remain after product names change: inference, orchestration, tools, memory, evaluation, and control.

What counts as an AI agent?

An AI agent is software in which a model can choose the next step, use one or more tools, inspect the result, and continue until it reaches a stopping condition. Autonomy varies. Some systems request approval before every external action. Others work inside a constrained environment and escalate only when confidence is low or a permission is missing.

This is the difference between an agent and a conventional chat interface. Chat may stop after generating an answer. An agent takes part in a control loop:

It receives a goal and relevant context.
It chooses an action or produces an intermediate result.
The runtime executes the action and records what happened.
The model observes the result and decides whether to continue.
A policy, budget, completion signal, or human ends the run.

The loop may finish after one turn or continue for hours. It can survive a process restart and pass work to specialists. Autonomy is a design choice bounded by permissions, time, cost, and risk.

Evaluate the whole system. A strong model attached to vague tools and unlimited permissions can be less useful than a smaller model inside a well-observed workflow with precise schemas and clear recovery behavior.

The six layers of the agent stack

Six layers account for most of the engineering work. A product may combine several behind one API, but each responsibility still has to live somewhere.

1. Models and inference

The model interprets instructions, produces structured output, selects tools, and synthesizes results. Benchmark quality is only one selection criterion. Teams also care about latency, cost, context length, modality, deployment requirements, and whether tool calls work reliably on their actual tasks.

Keep the model replaceable. Prompts, tool schemas, and evaluation cases should not be so entangled with one provider that an upgrade requires a rewrite. Still, "provider agnostic" is no excuse to ignore real differences. Models vary in how they follow constraints, recover from tool errors, and handle long contexts.

2. Agent runtimes and orchestration

The runtime surrounds the model loop. It assembles context, dispatches tool calls, handles retries, applies limits, streams events, and returns the result. Frameworks differ mainly in how much of that behavior they expose to developers.

A lightweight SDK fits a short workflow whose control flow belongs in ordinary code. Graph-oriented runtimes make more sense when execution branches, pauses for approval, resumes after failure, or persists across processes. In a multi-agent design, a central manager may call specialists as tools or hand control to another agent.

Integration counts are a weak way to choose a framework. Find the hardest state transition in the workflow instead. If a payment approval must survive a restart, durable state matters more than a large prompt-template catalog. A task that finishes in two tool calls probably does not need a complex graph.

3. Tools and environment

Tools are where model decisions become database reads, browser actions, code execution, tickets, or messages. Every tool therefore creates a trust boundary.

A tool should have a narrow scope and leave a useful record. Its name should describe the action, its input schema should reject ambiguous requests, and its output should distinguish success from partial failure. Permissions must reflect the current user. A refund_order tool with validated limits is safer than a generic execute_sql tool, even if both could produce the same database change.

Execution environments also matter. Code-running agents need isolation, resource limits, network policy, and an explicit filesystem boundary. Browser agents need protection against hostile page content and clear confirmation before consequential actions. The runtime should treat tool output as untrusted data, not as new instructions.

4. Context and memory

Context is what the model can see for the current decision. Memory decides what should persist and how it returns later. The terms describe different parts of the system.

Short-term memory may be the conversation and recent tool results. Long-term memory can include user preferences, approved facts, summaries, or domain records stored outside the model context. Retrieval systems select relevant items; compaction keeps a growing run within a usable budget.

Maximizing retention is the wrong goal. The system needs to decide what is safe and useful to recall. Stored model conclusions can be wrong, and personal data may have retention constraints. Record provenance, separate user-provided facts from model-generated summaries, and allow stored information to expire or be corrected.

5. Evaluation and observability

An uptime graph can show that the service responded. It cannot show whether an agent made a sensible sequence of decisions. For that, teams need traces of model turns, tool arguments and results, handoffs, guardrail outcomes, latency, token usage, and human interventions.

Score the outcomes that matter for the task. A customer-service agent might be measured on resolution accuracy, policy compliance, escalation quality, and cost. A coding agent may need tests, static analysis, review acceptance, and a check that it touched only the intended files. One aggregate "quality" number can hide the failure that matters.

Build an evaluation set from real tasks and known incidents. Run it when prompts, tools, models, or orchestration logic change. Production traces should feed new edge cases back into that set after sensitive information has been handled appropriately.

6. Identity, policy, and human control

Give an agent an identity distinct from the model provider and, in most cases, from the person who started the run. That identity determines which resources it can access, which actions require approval, and how the audit log attributes changes.

Apply least privilege at the tool layer and use short-lived credentials when possible. Keep read and write capabilities separate. Irreversible, high-value, or public actions need human confirmation. The approval screen should name the action, target, and parameters. A generic "Allow?" dialog gives the reviewer responsibility without enough information to make a decision.

The NIST AI Risk Management Framework organizes risk work around governing, mapping, measuring, and managing. Agent teams need those activities during design and operation because tools can turn a model error into an external action.

How MCP and A2A connect the stack

Two protocol families cover different connection problems.

Model Context Protocol (MCP) standardizes how an AI application connects to servers that expose tools, resources, and prompts. Its host-client-server architecture keeps the host responsible for orchestration and creates a dedicated client connection for each server. MCP does not decide how an agent reasons; it gives applications a consistent way to discover and invoke capabilities.

A team can expose a database schema as a resource and a constrained query function as a tool without building a custom integration for every agent host. The standard interface does not remove the need for security review. A remotely discovered tool still needs authentication, authorization, input validation, and careful treatment of returned content.

Agent2Agent (A2A) addresses communication between independent agent systems. The specification defines how agents advertise capabilities, exchange messages, manage tasks, and return artifacts. In broad terms, MCP connects an agent application to context and tools, while A2A helps one agent system collaborate with another.

The protocols solve different parts of the connection problem and can be used together. Real deployments still need agreement on identity, authorization, data semantics, error handling, and service-level expectations. A common envelope cannot guarantee that two agents interpret a business concept the same way.

What changes in production

Prototype demos usually show the successful path. Production systems also need an answer for timeouts, partial data, repeated actions, stale approvals, and records that change while the agent is planning.

The runtime needs idempotency keys, time and cost budgets, cancellation, retry policy, checkpoints, and a dead-letter or escalation path. Without those controls, retrying a failed run can repeat a payment, overwrite newer data, or leave work in an ambiguous state.

Prompt wording cannot carry the security model. "Do not reveal secrets" is an instruction, not a permission system. Secrets should be unavailable unless a specific tool requires them, and that tool should enforce the permitted operation. Text found in documents, web pages, emails, or tool output must not silently override system policy. Sensitive trace data also needs redaction and retention controls.

Human oversight works best when it is designed around risk tiers:

Low-risk, reversible reads can run automatically and remain fully logged.
Bounded writes can run automatically when validation passes and rollback is available.
Financial, destructive, legal, or public actions require explicit approval.
Ambiguous or policy-conflicting tasks stop safely and explain what is needed.

Risk tiers keep people focused on consequential decisions. If every read requires the same confirmation as a payment, reviewers will learn to approve prompts without reading them.

How to choose an agent stack

Pick one workflow before evaluating platforms. Write down its input, desired outcome, available evidence, permitted actions, and accountable owner. Implement the simplest deterministic version that can do the job, then add model-driven decisions where fixed rules cannot handle the variation.

Use the following questions to evaluate architecture and vendors:

Can we see and constrain every external action?
Can a run pause, resume, and recover without repeating side effects?
Can the final result point to the tool outputs or sources behind it?
Can we replay representative tasks after a system change?
Does the agent act with scoped credentials and an auditable identity?
Which interfaces are standard, and which behaviors are proprietary?
What do complete tasks cost, including retries, and how long do they take?
What happens when confidence is low, a tool fails, or the budget runs out?

Run a small evaluation before committing to a framework. Include ordinary cases, malformed inputs, unavailable tools, permission failures, conflicting instructions, and tasks that should be refused. Inspect the complete traces rather than grading only the final prose.

Model upgrades arrive faster than most teams can rework permissions, traces, or recovery logic. Those components deserve more attention than model branding. If a model makes a poor choice, the tools should limit what it can change. Checkpoints should stop a retry from repeating the action, and the trace should give a reviewer enough evidence to reconstruct the run.

For more implementation-focused coverage as the archive grows, browse all Trace Brief field guides and review the standards we use for technical claims.

Agent Zero AI SKILL.md Features Guide | Trace Brief

2026-08-02T00:00:00Z

An Agent Zero skill can be only one Markdown file. That small file still changes what the agent knows how to do, when it should use the procedure, and which supporting resources it can reach. Those are the Agent Zero AI SKILL.md features worth understanding before you install or write one.

Agent Zero can surface a skill when a task matches its description. It can then load the detailed instructions on demand. A user can also pin a skill so its procedure remains active in the current chat. This gives a skill two jobs: it must be discoverable from a short description, and it must be precise enough to guide the work after activation.

A vague skill may never load. A sprawling skill may load too much text and bury its own important rules. A well-designed skill keeps the routing metadata short, puts the working procedure in SKILL.md, and moves bulky material into files that the agent reads only when needed.

What a SKILL.md skill is

A skill is a directory with a required SKILL.md file. The file begins with YAML frontmatter and continues with Markdown instructions. The open Agent Skills specification requires two frontmatter fields: name and description.

The name is a machine-readable identifier. It must use lowercase letters, numbers, and hyphens, stay within 64 characters, and match the parent directory. The description explains both what the skill does and when an agent should use it. That second part is not decoration. It supplies the routing clues that help an agent select the right skill for a request.

Agent Zero's own documentation draws a practical boundary between three extension types:

Extension	Best use	How it reaches the agent
Skill	A repeatable procedure or specialized method	Description and tag matching, then on-demand loading
Tool	An action the agent can execute	Function or code exposed to the agent
Knowledge	Facts and reference material	Retrieval when the information is relevant

Use a skill for "how to do this work." Use a tool for "perform this action." Use knowledge for "retrieve facts about this subject." A skill may call a tool or point to knowledge, but it should not pretend that instructions alone create a capability the runtime does not have.

This fits the broader AI agent stack: a skill shapes the procedure inside the agent loop, while tools, permissions, memory, and runtime controls still determine what can happen outside the prompt.

The Agent Zero skill features that matter

Selective loading does most of the work. Agent Zero documents skills as focused instructions that it can load when a task needs them. The open standard calls the pattern progressive disclosure. A runtime can keep only the name and description available for discovery, load the full SKILL.md after activation, and read scripts or reference files later.

On-demand discovery

Users can ask for the outcome in ordinary language instead of naming every skill. Agent Zero searches for a suitable procedure from the available metadata. A description such as "Reviews Python database migrations for locking, rollback, and data-loss risk" gives the router much more useful evidence than "Helps with databases."

Manual activation and pinning

The Web UI also exposes a Skills selector from the plus button in the chat input. A user can add a skill manually, remove it, or pin it for a conversation. According to the current Agent Zero skills guide, active skills are added to the Protocol part of the prompt and remain visible to the agent on each turn.

Pinning is useful when a whole conversation must follow one procedure, such as a review rubric or a document format. It is a poor default for a skill that might become relevant once. Every pinned procedure competes for prompt space and attention, so the official guide recommends keeping the active list short.

Bundled resources

A skill can carry more than instructions. The standard defines conventional folders for executable scripts/, supporting references/, and static assets/. This makes a skill a small, versionable work package rather than a prompt fragment copied between chats.

The split also makes maintenance cleaner. A validator can live in scripts/, a long policy manual in references/, and a document template in assets/. The main file tells the agent when each resource is necessary. It does not paste all of them into the context at once.

Portability with limits

The Agent Skills format is open and is used by more than one agent product. Agent Zero's contributor guide lists compatibility with Agent Zero, Claude Code, Cursor, OpenAI Codex CLI, GitHub Copilot, and Goose. Portability is still a claim to test, not an automatic guarantee. Runtimes expose different tools, approval systems, paths, and interpretations of optional metadata.

For a portable core, follow the official specification: use a matching folder and name, write a specific description, keep the procedure in Markdown, and link to optional resources with relative paths. Add runtime-specific fields only when the target runtime needs them.

How to create a portable Agent Zero skill

Agent Zero documents both a helper CLI and a manual path. Its contributor guide uses python -m helpers.skills_cli create my-skill-name to scaffold a skill and python -m helpers.skills_cli validate my-skill-name to check it. For manual creation, it places custom skills under usr/skills/.

A small portable skill can use this layout:

release-note-review/
├── SKILL.md
├── references/
│   └── house-style.md
└── scripts/
    └── check_release.py

The corresponding SKILL.md can stay compact:

---
name: release-note-review
description: Review software release notes for missing upgrade steps, unclear compatibility claims, and unsupported security statements. Use before publishing a release or changelog.
license: MIT
metadata:
  version: "1.0"
---

# Release note review

1. Read the proposed release notes and identify the affected version.
2. Verify compatibility and security claims against linked issues or commits.
3. List missing upgrade, rollback, and configuration steps.
4. Apply the wording rules in `references/house-style.md`.
5. Run `scripts/check_release.py` on the final file.
6. Report every unresolved warning. Do not describe the review as passed while warnings remain.

This example uses the fields defined by the open specification. The instructions name the input, evidence, sequence, supporting files, validation step, and stopping condition. They do not depend on a hidden shared understanding between the author and the agent.

Watch the frontmatter dialect

Agent Zero's contributor documentation shows extra fields such as version, author, tags, triggers, and allowed_tools. The open Agent Skills specification defines license, compatibility, metadata, and an experimental allowed-tools field in addition to the two required fields.

The underscore in Agent Zero's documented allowed_tools and the hyphen in the open spec's allowed-tools are a real compatibility detail. Do not assume that one spelling grants or restricts tools identically across clients. If a field controls permissions, verify it against the installed Agent Zero version and the destination runtime. Put author or version data under metadata when you want to remain close to the portable standard.

That recommendation is an inference from the two current documents, not a promise that every client handles metadata in the same way. Validation can confirm the file format. Only a runtime test can confirm behavior.

How to load, pin, and remove skills

Agent Zero normally handles discovery from the request. Give it a concrete task that matches the description and inspect whether the skill appears in the run. If automatic recall is unreliable, improve the description before adding a long trigger list. The official contributor guide treats the description as central to semantic matching.

For manual control in the Web UI:

Open the relevant chat.
Select the plus button in the chat input.
Open Skills and search for the skill.
Add it to the current conversation.
Remove it when the special procedure no longer applies.

Pin a skill when several turns must follow the same contract. A long editorial review, a migration checklist, or a repeated data-cleaning recipe fits that pattern. An occasional image conversion does not need to occupy every turn.

Skills, Agent Profiles, and Projects solve different problems in Agent Zero. A skill adds a procedure. A profile changes the broader behavior of the chat. A project supplies a workspace with its files, memory, secrets, and instructions. If a skill contains customer-specific secrets or large project context, the boundary is probably wrong. Keep secrets in the project's secret system and let the skill describe how authorized tools should request them.

Design a skill for reliable recall and execution

A skill needs a narrow job and an observable result. "Improve code" is not a useful boundary. "Review a database migration and report locking, rollback, and data-loss risks" is narrow enough to route, test, and maintain.

Write the description for the request a user will actually make. Include the artifact, the operation, and the situations that should activate the procedure. Synonyms help when they correspond to real wording, but a pile of loosely related keywords makes accidental activation more likely.

The body should answer six questions:

What input must the agent locate or request?
Which sources or files are authoritative?
What actions should happen, and in what order?
What must the agent never assume or change?
How does it verify the result?
What should it report when work cannot continue?

Keep stable rules in the main file. Move detailed tables, product documentation, and templates into focused references. The specification recommends keeping the complete SKILL.md under 500 lines and below roughly 5,000 tokens of instructions. Those are design recommendations rather than hard runtime limits, but they point at the right failure mode: once a skill becomes a handbook, the agent may struggle to locate the instruction that matters for the current step.

References should stay shallow. The standard recommends relative links from the skill root and warns against deep chains. A main instruction that links to a reference that links to another reference forces the agent to navigate a miniature website before it can work.

Scripts need contracts too. Document their inputs, dependencies, exit behavior, and expected output. A script that silently changes files or prints an ambiguous success message weakens the skill even if the prose is excellent.

Review third-party skills as code and policy

A downloaded skill can influence the agent's decisions and may bundle executable scripts. Treat it as both code and policy. Reading only the description is not enough.

Before activating a third-party skill:

Read the complete SKILL.md and every file it tells the agent to execute.
Check scripts for network calls, destructive filesystem operations, credential access, and installation commands.
Confirm that referenced paths stay inside the intended project or skill directory.
Review dependencies and pin them when reproducibility matters.
Compare requested tools with the narrowest actions the procedure needs.
Test with disposable data before using production credentials or repositories.

The open specification labels allowed-tools experimental and notes that support varies by implementation. This means frontmatter alone is not a dependable sandbox boundary. The runtime's permission controls, container isolation, project scoping, and human approvals remain the controls that matter.

Also inspect the instructions for policy conflicts. A skill that says to ignore repository guidance, conceal errors, publish without validation, or request broad credentials is unsafe even when its scripts are harmless. The package can change behavior through prose before it runs any code.

Agent Zero runs in Docker and offers project isolation, but isolation is not permission to stop reviewing inputs. Mounted host folders, connector access, browser sessions, API tokens, and installed tools can extend the reachable surface. Grant each skill only the environment needed for its job.

Test and maintain the skill

Start with structural validation. Agent Zero documents its helper command:

python -m helpers.skills_cli validate release-note-review

The open standard also provides a reference validator through skills-ref. A clean validation result proves that the package follows the checked format. It does not prove that the routing description works or that the instructions produce a correct result.

Test three behaviors separately.

Recall tests

Write requests that should activate the skill, near-miss requests that should not, and ambiguous requests where the agent should ask for context. Test the language your users employ, not only the exact nouns in the description.

Execution tests

Use representative inputs with known findings. Include a normal case, missing files, malformed data, a failing script, and a task that would require an unavailable permission. Check the work trace as well as the final answer. A polished report can hide a skipped validation step.

Maintenance tests

Run the same cases after changing the skill, Agent Zero version, model, tools, or project configuration. Version the skill with its surrounding repository when possible. Record which behavior changed and why. Keep old compatibility claims out of the description once they are no longer tested.

In practice, a useful Agent Zero skill is smaller than its first draft. Its description routes one recognizable job, its instructions define evidence and verification, and its resources stay available without flooding the prompt. Its tests should not depend on the agent grading its own confidence.

Trace Brief checks technical claims against primary material and records its method in the editorial policy. Browse all AI agent field guides for related architecture and implementation coverage.