From Long Prompts to Operational Manuals—Designing Agent Skills

Executive Summary

There are limits to the practice of putting every rule into a long Prompt each time you want to give an Agent detailed instructions. As the number of tasks grows, the Prompt expands, unrelated rules become mixed together, and important conditions get buried.

An Agent Skill is not merely a “saved long-form Prompt.”

It is a selectable unit of work that combines metadata indicating when to use it, procedures describing how to proceed, and an output contract specifying what to produce. Progressive Disclosure—normally referencing only a compact index and loading the body of only the Skill that matches the request—enables specialization without expanding the context more than necessary.

Using the code-review Skill from Lab 1, this article explains the following topics in order:

• The difference between Static Context and Dynamic Context
• Why SKILL.md is an “operational contract”
• The publicly explainable flow from metadata to Skill execution
• Four types of failure that occur as more Skills are added
• How to choose between one Agent plus Skills and Multi-agent

Where We Are in the Series

This five-part series explores the question: “AI has become extraordinarily intelligent. So, can we actually entrust it with real work?”

1. What Is Agentic Engineering?
2. Antigravity as a Workplace
3. Agent Skills as Operational Manuals (This Article)
4. Process Design with Agents CLI and ADK Graph
5. Evaluation Through Output and Trajectory

Connecting from the Previous Article—Workplace Rules and Work Procedures Are Different

In the previous article, we examined Antigravity as an Agent’s workplace. A Project defines the boundary of an engagement, MCP provides interfaces to external systems, Permissions restrict the scope of operations, and Artifacts support human inspection.

However, even after the workplace is prepared, a new hire still does not know how to conduct a code review.

Shared rules such as “be accurate” and “be safe” leave open questions about which files to examine, what to prioritize, and how to format findings. Each specialized task requires procedures specific to that work.

In other words, if a Project’s shared rules are the employee handbook, a Skill is the manual for a specific task.

A Company That Reads Every Manual Aloud Each Morning

Imagine a company that reads all of the following to a new employee every time it assigns them a task:

• The company’s fundamental policies
• Code review procedures
• Deployment procedures
• Incident response procedures
• Security audit procedures
• Monthly reporting procedures
• Hiring interview procedures

Even when today’s assignment is only a code review, the employee must listen to every manual. This not only takes time but also makes it harder to see what matters for the current task. If procedures conflict with one another, it is also unclear which should take priority.

The same problem occurs when a large volume of instructions is permanently placed in an AI’s Context window.

To address this, we divide information into two categories.

Static Context—What Always Stays on the Desk

This is the small amount of information required for every task.

• The Agent’s role and purpose
• Organization-wide prohibitions
• The Project structure and shared conventions
• A compact index of available Skills

Because this information is always available, it can be applied reliably. However, too much of it consumes the Context.

Dynamic Context—What Is Retrieved from the Bookshelf Only When Needed

This is detailed information read after a specific task has been selected.

• Code review checkpoints
• Pre-deployment checklists
• Incident response triage procedures
• Task-specific templates and helper scripts

Because this information is loaded only when needed, it is easier to add specialized procedures.

This staged disclosure—in which the index remains small and continuously available while the body is read only after selection—is called Progressive Disclosure.

In other words, making Context smarter does not mean providing everything. It means ensuring that the necessary information can be reached at the moment it is needed.

What Does SKILL.md Establish as a Contract?

In Build With Google Day 1 Lab 1, you create a Custom Skill within a Project using the following structure:

my-first-project/
└─ .agents/
   └─ skills/
      └─ code-review/
         └─ SKILL.md

The Lab’s SKILL.md is broadly divided into two layers.

---
name: code-review
description: Reviews code changes for bugs, style issues, and best practices.
             Use when reviewing code files or checking programming quality.
---

〈Code Review Skill〉

## Review Checklist
1. Correctness
2. Edge Cases
3. Performance

## Feedback Protocol
- Identify the line number and what should be changed
- Explain the technical reason for the change

The initial YAML section is the metadata. name is the Skill’s identifier, while description communicates the kinds of requests for which the Skill should be considered.

The body is the execution contract. It defines what to inspect, the order in which to proceed, and what to output.

It is important not to treat description as merely introductory copy.

Weak description
  “A Skill for working with code”
  → The scope is too broad, so it is unclear when to use it

Strong description
  “Use when asked to review code files or assess their quality,
    examining bugs, edge cases, and performance”
  → The applicability conditions and scope of work are clear

In practice, exclusion criteria are also useful. Explicit boundaries such as “Do not use for implementing new features” or “Return review comments only, without modifying files” can reduce conflicts with adjacent Skills.

In other words, SKILL.md is not a note containing knowledge. It is an operational contract that connects selection criteria, execution procedures, and output format.

How Is a Skill Selected and Used?

The following diagram summarizes what can be explained externally.

1. The user requests, “Review this Python code.”
2. The Agent compares the request with the compact metadata of the available Skills.
3. code-review is selected as a candidate.
4. After selection, the body of SKILL.md is read.
5. The Checklist is executed, and the output follows the Feedback Protocol.

The bodies of unselected Skills for deployment or incident response do not need to enter the Context for this request. This is the practical benefit of Progressive Disclosure.

However, this diagram represents the contract model for Agent Skills. It does not claim that a particular product’s proprietary router implements exactly the same algorithm internally.

In other words, what we can design and inspect is “which metadata to expose and what to execute after selection”; there is no need to speculate about invisible internal processing.

The code-review Skill Verified on the VM

On the VM, we verified the following characteristics of the Project-local code-review Skill:

• It has a name and description
• It checks Correctness, Edge Cases, and Performance
• It provides line numbers
• It explains the reason for each issue and how to address it

In addition, the review of the Lab’s demo_bad_code.py produced the following two visible findings:

1. A crash path in which get_user_data(...) may return None, but the code proceeds to u['name'] without checking the return value.
2. A performance bottleneck in which time.sleep(0.1) inside the payment-processing loop forces operations to wait sequentially.

These findings map clearly to the Skill contract.

What we can conclude is that the Skill was registered in the Project and that one example output aligned with the contracted review criteria. From a single successful result, we cannot conclude that it can correctly review every piece of code or that the internal router’s selection accuracy is a particular percentage.

In other words, the value of a Skill lies not in producing an “intelligent-looking answer,” but in connecting the request, review criteria, and output through a traceable contract.

How Do Skills, Shared Rules, and MCP Differ?

Because these three are easily confused, let us return to the new-hire analogy.

A code review Skill can instruct the Agent to “invoke a static analysis Tool.” However, the Skill itself is not the capability to connect to an external system.

Conversely, even when an MCP Tool is available, the Skill or Workflow is responsible for determining when and in what order to use it, as well as which results to verify.

In other words, shared rules define persistent boundaries, Skills provide on-demand procedures, and MCP provides the means to reach external systems.

Is It Better to Add as Many Skills as Possible?

The answer is no. A Skill specializes an individual Agent, but the library as a whole introduces new failure modes.

The Build With Google presentation organized the main Skill evaluation failures into four categories.

1. Trigger Failure

A Skill that should be used is not selected, or an irrelevant Skill is selected.

Example causes: the description is abstract, adjacent Skills use overlapping vocabulary, or exclusion criteria are missing.

2. Execution Failure

The correct Skill is selected, but the Agent skips steps, uses the wrong Tool, or fails to follow the output format.

Example causes: ambiguous procedures, missing success criteria, or undocumented exception handling.

3. Token Budget Failure

The body or reference materials are too large, causing important information to become buried within the Context.

Example causes: materials that only need to be read on demand are written directly into the body, or procedures and background explanations are not separated.

4. Regression

Adding a new Skill creates selection conflicts with existing Skills, breaking requests that previously worked.

Example causes: overlapping scopes, overly similar Skill names or descriptions, or insufficient regression testing across the entire library.

Quality of an individual Skill
  ≠ Quality of the entire Skill library

A correct Skill on its own
  + A similar Skill
  → A new system-level problem: routing conflicts

In other words, creating a Skill is not the end of the work. You must evaluate whether it is selected, whether it executes correctly, whether it puts pressure on the Context, and whether it breaks existing behavior.

Single Agent + Skills
  Best for: Work performed within the same permissions and work boundaries,
            where only the procedures need to change

Multi-agent
  Best for: Work that genuinely needs to run in parallel,
            be evaluated independently, or strictly separate
            permissions and execution environments

Key Takeaways

• A Skill is not a saved long-form Prompt. It is a selectable operational contract connecting metadata, execution procedures, and output format.
• Progressive Disclosure is the design of context placement. The index remains available, while the detailed body is read only after selection.
• A Skill library requires evaluation. Examine Trigger, Execution, Token Budget, and Regression failures.

Next Time

A single task such as code review can be handled through a Skill’s procedures.

But what about a multi-stage process that classifies inquiries, sends only shipping-related questions to a specialist, and politely declines unrelated requests? Such a process must manage the order of execution, the conditions for branching, and the destinations it must not enter.

Next time, we will use Agents CLI and ADK Graph to separate the LLM’s ambiguous judgment from the strict control provided by code.

References

• Build With Google Day 1 — Lab 1
• Agent Skills specification
• Adding Agent Skills support
• Skill authoring best practices
• Evaluating skills