As we all integrate coding agents into our workflows, it's important to figure out how to get the most value out of them for ourselves, our teams, and our projects. The general consensus is that providing proper context is the single most important thing we can do to get good results. Prompts like "Improve performance, make no mistakes" will rarely yield the desired outcome on their own.
So how do you "teach" coding agents the specifics of your projects and tools? How do you add your own preferences to the common processes?
In the last couple of months, two open specifications have emerged to help with this: AGENTS.md and Agent Skills.
Standardizing project context with AGENTS.md
The idea behind AGENTS.md is simple: let's standardize project context. You can think of project context like a README for coding agents, containing basic orientation guide information such as:
- How to install a project
- What tools to use
- Where the tests are and how to run them
- Where to find documentation for specific topics (like architecture)
Once you start working on your project with a coding agent, it will inspect the code base and suggest creating a context file. This is beneficial because, from that point on, the agent can find the right information much faster, automatically enhancing your prompts with useful context.
Managing agent-specific configurations
That's a massive win for the AI-assisted development experience. There is one catch, though: every agent prefers its own specific file location (for example, CLAUDE.md or GEMINI.md). If you want to keep your options open for your team (which you absolutely should), you don't want to duplicate all these files. That's where AGENTS.md shines, offering "a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." The good news is most major agents are compatible with this specification and will happily read the AGENTS.md file if they find it.
The main exception is Claude Code, but the workaround is simple. Because Claude Code supports links, all you need to do is create a CLAUDE.md file with the following line:
@AGENTS.mdYou can then add any Claude-specific instructions right below it.
Best practices for your AGENTS.md file
While providing good context is essential, you shouldn't overdo it. Too much context can actually degrade an AI model's performance.
Keep it concise
The AGENTS.md content is sent with every prompt, so every unnecessary line dilutes the signal for the lines that matter. Aim for fewer than 150 lines; for smaller repos, 30 to 50 lines is plenty. A good litmus test for every line: "Would removing this cause the agent to make a mistake it wouldn't otherwise make?" If not, delete it.
Review auto-generated context
Most agents offer an init command that generates a starting context file. It's a useful starting point, but don't ship it as-is. Review it, remove anything the agent can already figure out on its own (such as standard directory structures), and add the things only you know: the silent invariants, the non-obvious conventions, the gotchas that have bitten your team before. Research from ETH Zurich found auto-generated context files can hurt agent performance when they're full of generic information the model already knows.
Use it as an index
Think of it more as a directory for finding information rather than a place to dump everything. For example, instead of pasting your entire architecture description there, create a docs/ARCHITECTURE.md file and include a simple pointer:
* Detailed architecture and diagrams are located at [docs/ARCHITECTURE.md]An orientation table is even better because this is optimized for agents, not humans:
| Topic | Document |
|-------|----------|
| Setup & CLI usage | `README.md` |
| System design & diagrams | `ARCHITECTURE.md`, `ARCHITECTURE-DETAILED.md` |
| Interface contracts | `specs/README.md` |This keeps the base AGENTS.md file lightweight while giving the model enough context to fetch additional files when needed.
What else belongs here? Generally, you'll want to document small invariants (things that fail silently) and core decision-making guardrails. For example: "Catch specific exceptions, not generic ones. Broad catches mask real bugs."
Because different models have different coding habits, this file should be dynamic. If you notice an agent making the same mistake repeatedly, document the fix here. As your project grows, you can offload these rules into a separate file and reference them in your orientation table.
While AGENTS.md handles the "always-on" context sent with every prompt, it isn't ideal for highly specific, situational knowledge. That's where Agent Skills come in.
What are Agent Skills?
So far, we've been organizing additional context in an ad hoc way using separate docs, tables, and links. It works, but it lacks structure. Agent Skills is another open specification designed to formalize how we create and share these task-specific instructions.
It's simple: a skill is a folder containing a SKILL.md file. The file uses YAML front matter to provide metadata for the agent. Let's look at a basic example:
---
name: pre-commit-check
description: Run project checks before committing. Use when the user asks to commit changes or prepare a commit.
---
## Steps
1. Run linting: `npm run lint:fix`
2. Run the test suite: `npm test`
3. If either step fails, show the errors and stop — do not commit
4. Stage the changes and create the commit following conventional commits formatDefining and structuring tasks
In this example, we've defined a specific task for the agent to execute before making a commit. This highlights how you should approach skills: don't try to teach the agent generic tasks (like how to write code or make a git commit in general), but rather give it the specific context and guardrails unique to your project and team workflow. Also notice the language: Run linting, not Use the Bash tool to run `npm run lint:fix` . There's a lot of nuance in how you write skill content to keep it portable and effective, which I'll cover in detail in a future post.
The skill format requires a name and a description in the YAML front matter. The agent uses the description to decide whether a skill is relevant to a user's prompt. This technique is called progressive disclosure. The agent initially only loads the skill names and descriptions into its context, reading the full file only when needed. This keeps the prompt size under control while making vast amounts of information available on demand.
Triggering a skill
Skills can be triggered in two ways: automatically based on the intent of your prompt (for example, saying "Let's commit this code") or explicitly using a slash command such as /pre-commit-check. (Again, there is plenty of nuance to this; I'll cover that in a follow-up article, including engineering best practices to test your skill triggers.)
You might recognize this as the "commands" or "rules" feature used by various proprietary agents before skills were standardized. Today, the industry is converging around the open skills standard, allowing them to be called explicitly or implicitly.
A skill folder can also contain supporting resources such as scripts or documentation:
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directoriesTrue to progressive disclosure, these extra resources are only read by the agent if the main instructions explicitly reference them.
To make skills discoverable, you need to store them where agents can find them. While the specification hasn't fully standardized this yet, the emerging convention is to use a .agents/skills/ directory. Most modern agents can discover skills there automatically. For the few that can't, you can easily set up a symlink to their expected path. Saving your skills in .agents/skills/ gives you the highest amount of flexibility moving forward.
While local skills bring plenty of value to a single repository, their greatest benefit comes from sharing them across teams, projects, or the open source community.
Sharing and distributing skills
The most logical starting point for sharing skills is moving them out of your local repository and into a dedicated project. Other developers can then clone the repository and symlink it, or pull it in as a Git submodule. Both approaches are straightforward (especially with an AI agent helping you set it up), and Git handles the versioning perfectly. This works beautifully for small teams.
However, a pure Git approach requires manual setup and constant pulling, and it scales poorly as your collection grows. If a repository gets too large, you're forced to either symlink everything or split your skills across multiple repos for different audiences.
Bundling skills with plug-ins and marketplaces
To solve this, some agents are introducing plug-ins and marketplaces.
A plug-in bundles related skills together into a named group—think categories like "dev workflow," "onboarding," or "ops"—with a metadata file describing the bundle.
A marketplace takes it one step further: it's a Git repository that catalogs multiple plug-ins, so users can discover and install them with a single command instead of manually cloning and symlinking.
This area isn't standardized yet. The AgentSkills.io spec covers the skill format itself, but packaging and distribution are still evolving—every agent handles it differently. That said, the concepts are converging. Let's look at one concrete implementation in Claude Code.
A Claude Code plug-in is a folder containing a metadata file and a collection of skills:
dev/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── pre-commit-check/
└── SKILL.mdThe plugin.json file describes the plug-in with typical metadata such as name, version, and author.
{
"name": "dev",
"description": "Developer workflow skills — pre-commit checks, code review, testing",
"version": "1.0.0",
"author": {
"name": "Dejan"
}
}If you have multiple plug-ins, you can organize them into a marketplace. To turn a Git repository into a marketplace, add a marketplace.json file to the root directory to catalog the available plug-ins:
{
"name": "skill-workshop",
"owner": {
"name": "Dejan"
},
"plugins": [
{
"name": "dev",
"source": "./plugins/dev",
"description": "Developer workflow skills — pre-commit checks, code review, testing"
}
]
}There's no need for complex hosting infrastructure or package registries—only a structured Git repository. Users can register the marketplace URL once and install the plug-ins they need:
/plugin marketplace add https://github.com/dejanb/skill-workshop.git
/plugin install dev@skill-workshopOnce installed, the skills are ready to use directly:
/dev:pre-commit-checkOther agents offer similar mechanisms. Cursor supports plug-in directories with their own metadata format. The Gemini command-line interface (CLI) uses extension configuration files. The details differ, but the pattern is the same: group skills, add metadata, and point users to a Git repository.
Unified tooling and future standards
The lack of standardization doesn't mean there are no efforts to provide unified tooling. One standout open source project is Lola, which takes a package manager approach to managing AI context. Instead of manually juggling agent-specific configurations, a single lola install command automatically distributes and versions your skills across all supported assistants. To see exactly how this functions in a real environment, you can walk through the complete end-to-end demonstration workflow on Red Hat Developer.
Until tooling such as Lola becomes the universal standard, the best local strategy today is to keep your core skills in .agents/skills/—that's where most agents look by default—and add the agent-specific packaging on top as needed. The skill content stays the same; only the wrapping changes.
While a pure Git approach is universal, investing a little extra effort into setting up plug-ins and marketplaces provides significant value if you plan to distribute skills across a large organization—especially when onboarding less technical users.
So far, we have explored the concept of agent context and how skills fit into this broader framework. We also discussed their primary use cases and how to scale them for large organizations and the wider public. In our next installment, we'll focus on the specific content of these skills, the tools we use to build them, and how to maintain them effectively over the long run.
