Manage Context through Agent Skills

Introduction

Context management is crucial when using Agentic AI to solve problems, and Anthropic’s Agent Skills🔗 context management model has recently become a mainstream industry standard. It is supported in tools such as Claude Code🔗, Codex🔗, and Opencode🔗. By studying how to integrate it into existing workflows, we can improve development efficiency.

Existing Problems

A project accumulates many project-related documents. In my case, I have recorded a series of documents for a specific project. In practice, they may not necessarily be related to software development; they could also be knowledge, rules, or examples from different domains:

project
├── xxx.md
├── HowToFetchData.md
├── HowToFormValidation.md
├── HowToOrganizeComponent.md
└── HowToTesting.md

For example, if you want to write tests, you can bring in the relevant domain document and hand it to Agentic AI:

Terminal window
Based on @HowToTesting.md, finish the tests in @Foobar.test.ts

This can be described as the most straightforward and flexible way to manage context, but this workflow still feels fragmented and requires assigning context through commands every time:

  • Missing context: You may forget to provide key documents, causing the AI to generate code that does not comply with the project’s conventions.
  • Repetitive work: Each conversation requires specifying and assigning context again.
  • No specific standards: The format is arbitrary.

Automatically Managing Context with Agent Skills

If you want the Agent to more intelligently determine and retrieve relevant context on its own, you can achieve this through Skills. The key mechanism is “progressive disclosure”: each time the Agent runs, it only loads Skills context when needed:

  • Discovery: The Agent only loads the name and description metadata of each available skill to determine whether it is relevant to the current task
  • Activation: When the task matches the skill description, the Agent reads the full SKILL.md instructions and applies them to the context
  • Execution: Load referenced files or execute bundled code as needed
Terminal window
my-skill/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: dynamically referenceable documents
└── assets/ # Optional: static assets

Example Using Scripts

For example, my project has a step for generating OpenAPI🔗 scripts wrapped in a swagger.sh shell script, which is usually run after development is complete to generate API documentation. You can expose a specific skill by writing a skill and its related documentation.

Terminal window
swagger/
├── SKILL.md
└── scripts/
└── doc-gen.sh
SKILL.md
---
name: swagger
description: Comprehensive Swagger documentation management for Go projects using swaggo/swag
---
## What I do
This skill includes the `scripts/doc-gen.sh` script and provides instructions for managing Swagger API documentation in Go projects:
...

Example Using references and assets

To better explain the use of references/ and assets/, here is a more complete skill example that includes the references and assets directories:

complete-skill/
├── SKILL.md
├── scripts/
│ └── process-data.sh
├── references/
│ ├── API_REFERENCE.md
│ └── error-codes.md
└── assets/
├── templates/
│ └── config-template.json
└── diagrams/
└── workflow.png

In SKILL.md, you can reference these files like this:

SKILL.md
---
name: complete-skill
description: A complete skill for processing data and generating reports, including reference documentation and static assets
---
## Feature Overview
This skill is used to process data and generate reports.
## Detailed References
See the [API Reference](references/API_REFERENCE.md) for complete API documentation.
If you encounter an error, check the [Error Code Table](references/error-codes.md).
## Usage Example
Use the [configuration template](assets/templates/config-template.json) as a starting point.
For the workflow diagram, see the [workflow diagram](assets/diagrams/workflow.png).

This way, the Agent can dynamically load these additional resources when needed without consuming too much context during the initial load.

Metadata Specification

Metadata = data used to describe data, stored in the frontmatter at the beginning of a Markdown file. Different specifications have their own extended metadata, so you can refer to the documentation of the tool you are using.

  • name
    • Up to 64 characters
    • Must contain only lowercase letters, numbers, and hyphens
    • Must not contain XML tags
    • Must not contain reserved words: “anthropic”, “claude”
  • description
    • Must not be empty
    • Up to 1024 characters
    • Must not contain XML tags

MCP vs Agent Skills

They can complement each other
  1. Use prompts to direct the Agent
  2. Use Skills to plan domain-specific knowledge context and teach the agent specific workflows
  3. Use MCP to reliably and consistently integrate all external capabilities

Does Using Agent Skills Mean Unlimited Context?

A large number of Skills will still increase the chance of incorrect references by an AI Agent

Using Agent Skills does not mean a truly unlimited context window. Instead, it effectively manages model context through progressive disclosure and external execution mechanisms.

Further Reading