Skip to main content

Skills: Agent Extension

In previous sessions, you learned that an artificial intelligence model's context window is a finite and costly resource. If we attempt to pack all instructions, style guides, library documentation, and automation scripts into a single AGENTS.md or CLAUDE.md file, we cause Context Bloat, which spikes latency and triggers the Lost in the Middle phenomenon (attention degradation).

To solve this engineering challenge, modern terminal tools (agy, opencode, Claude Code) introduce the concept of Skills: packages of procedural knowledge and specialized tooling loaded on-demand by the agent only when the current task requires it.

1. What is a Skill?​

A Skill is a self-contained capability module that extends an AI agent's operational intelligence. Unlike global, permanent repository rules:

  • Does not saturate initial memory: Remains dormant on local disk and is only injected into the context window when explicitly invoked by the user or when the agent determines that the task matches the skill description.
  • Provides procedural memory: Contains step-by-step workflows ("how to do X"), debugging heuristics, and domain-specific best practices (for example, Flutter with Material Design 3).
  • Includes executable tools: Can bundle terminal scripts (Python, Bash, Dart) and code templates allowing the agent to run automated diagnostics and validations.

Skill Anatomy and Surgical In-Memory Loading

2. Anatomy of a Skill​

Physically, a skill is a structured directory located within the agent configuration folders (at the project level in .agents/skills/<skill-name>/ or at the user level in ~/.gemini/antigravity-cli/skills/).

Its anatomy consists of the following required and optional elements:

.agents/skills/flutter-helper/
├── SKILL.md            # [REQUIRED] Manifest, YAML metadata, and instructions
├── scripts/            # [OPTIONAL] Executable automation scripts
│   ├── check_lints.py
│   └── audit_dispose.sh
└── references/         # [OPTIONAL] Templates, design tokens, and schemas
    ├── m3_colors.json
    └── state_blueprint.dart

The SKILL.md File and its YAML Frontmatter​

The SKILL.md file is the required entry point. It begins with a YAML metadata block enclosed by three hyphens (---):

.agents/skills/flutter-helper/SKILL.md
---
name: flutter-helper
description: "Specialist in frontend development with Flutter, Material 3, State lifecycle, and memory leak prevention."
---

# Flutter Helper Skill

This skill guides the construction, auditing, and refactoring of Flutter user interfaces.

## Implementation Rules
1. Strictly separate Screen (host Scaffold) from Page (internal canvas).
2. Any resource holding listeners (TextEditingController) must be released in dispose().
3. Use const constructors on all immutable widgets.
  • name: Unique kebab-case identifier used to invoke the skill from the command line (e.g., /skill flutter-helper).
  • description: Concise summary explaining when and why it should be activated. Agents use this description to automatically select the appropriate skill via semantic similarity when the user issues a request.

3. Installing and Invoking Skills​

Skills can be installed at two scope levels depending on the team's needs:

1. Project Level (Shared with the Team)​

Stored inside the repository under .agents/skills/<skill-name>/ and tracked in version control with Git. This ensures that any team member or agent cloning the repository has access to the exact same operational capabilities.

2. Global Level (Developer Environment)​

Stored in the CLI user directory (e.g., on Windows C:\Users\<User>\.gemini\config\skills\ or on Linux/macOS ~/.config/agy/skills/). They are available across any project opened in your terminal.

Console Invocation​

In the agentic CLI, you can load and interact with a skill in two ways:

# Direct loading of the skill into the active session
> /skill flutter-helper

[System] Skill 'flutter-helper' loaded into active context.
Tokens added: 920 tokens (0.7% of context limit).

> "Generate a view to register a new contact with phone validation"

4. Installing the Flutter Skill for the Course​

For this course, we will use a specialized Flutter skill providing:

  1. Automated verification of the Screen vs. Page rule (avoiding nested Scaffold widgets).
  2. Detection of orphan controllers that omit the call to dispose().
  3. Validation of official Google Material Design 3 components.

To check available skills in your console environment, run:

Terminal
agy skill list

Or within the interactive agent session:

> /skills

5. Auditing Generated Code and the Living Contract​

When the agent generates or modifies code assisted by the skill, your responsibility as the Human-in-the-Lead is to audit the result before integrating it into the project.

Human-in-the-Lead Audit and Decision Loop

What to fix by hand vs. what to fix in the contract?​

One of the most common pitfalls when working with AI agents is falling into two unproductive extremes: manually fixing everything repeatedly, or overcrowding the AGENTS.md file with tiny, irrelevant rules.

SituationDiagnosisCorrect ActionJustification
Isolated or Cosmetic FlawA margin of 16.0 instead of 20.0, or button text requiring a specific wording tweak.Fix by hand directly in the .dart file.It is not worth consuming tokens or cluttering the global contract for a rule applicable only to one specific view.
Systemic Architectural ViolationThe agent nested a Scaffold inside a Page, used a StatefulWidget for static data, or used deprecated Flutter 1 components (FlatButton).Update the contract (AGENTS.md or .agents/memory/).If you do not update the contract, the agent will make the exact same mistake on the next screen you ask it to build.
The Living Contract Principle

Whenever the agent makes a recurring architectural mistake, do not just fix the code: add the negative or positive rule in .agents/memory/. By doing so, you compound the learning for the entire semester and across your entire team via Git.

Self-Assessment Quiz​

Cargando cuestionario...