The Ad Hoc AI Coding Agent Skills
Guidebook

AI coding assistants are shaped by the instructions they receive. On-demand skills, always-on instruction files like AGENTS.md and CLAUDE.md, and custom agents are all ways of delivering guidance to an AI assistant. The specific format matters less than what’s inside these files: your organization’s knowledge about how to write good code.

That knowledge (your coding standards, architecture decisions, security practices, domain expertise) becomes a durable asset when you capture it clearly. You can adapt that asset to whatever delivery mechanism works best today and change course when something better comes along.

Building in flexibility is a smart investment because AI coding assistance is changing fast. New models, new tools, and new approaches arrive regularly. Research findings from six months ago may not apply to current models. A delivery mechanism that works well today may be replaced. That is no reason to wait, because the tools are useful now. It is a reason to build with change in mind and to avoid deep dependencies on any single tool’s syntax or conventions.

When you separate the knowledge (what you want to convey) from the delivery mechanism (how you convey it), you can adapt more easily. A well-documented coding standard can become an on-demand skill, a section of an always-on instruction file, or whatever comes next, without starting from scratch.

The process of writing this guidance is valuable in itself. You’ll surface disagreements, clarify ambiguities, and build shared understanding across your team. The final artifact is a byproduct of the real value: organizational clarity.

Don’t start skill development by brainstorming what might be useful. Start by observing what’s actually happening. Where do code reviews repeatedly flag the same issues? Where does AI-generated code consistently miss the mark? What do new team members struggle with?

These patterns point to real opportunities. A skill that addresses a problem you’ve observed multiple times is almost certainly worth the investment. A skill that addresses a hypothetical future problem may never be used.

This is also why your first skills should be your own. It’s tempting to import skills from open source repositories or vendor collections. There are a lot available on the internet, and the number grows daily. They look polished, they’re readily available, and they seem to solve problems you have. But importing without understanding creates risk. The skill may not fit your context, and it may not be safe (see Practice 6). Coding standards, delivery processes, architecture patterns, and security requirements vary widely. You also skip the learning that comes from articulating what you actually want. Write skills based on corrections you repeatedly make, patterns you want to reinforce, and mistakes you want to prevent. This grounds your skills in real needs and builds organizational understanding.

Start small. Pick one or two clear pain points and develop skills to address them. Validate that they help before expanding. Premature abstraction, which means trying to solve problems you don’t have yet, leads to skills that are complex, hard to maintain, and often unused.

Skill development doesn’t happen unless you make space for it. Consider adding a recurring skill development session to your agile cycle: perhaps 30 to 60 minutes per sprint where the team reviews recent pain points and drafts or refines skills. Some teams combine this with retrospectives; others keep it separate. The key is regularity. Small, consistent investments compound over time, and tying the work to observed problems keeps it grounded in real value.

Effective skills encode more than coding standards. They capture domain knowledge, policy requirements, accessibility standards, and organizational context. Much of this knowledge lives with people who aren’t software developers.

Policy experts understand compliance requirements that must be reflected in code. Subject matter experts know domain terminology and business rules. End users understand the problems the software is meant to solve. Documentation specialists know how to communicate clearly. Security staff understand the threats your systems face and the controls your authorization depends on.

Build cross-functional teams for skill development. Create ways for non-engineers to contribute their expertise, even if they can’t write the skill files themselves. Review skills with diverse stakeholders to catch gaps that a purely technical team would miss.

A skill that tries to cover everything becomes hard to maintain and hard to test. When it’s updated, you can’t be sure what else might break. When it doesn’t work, you can’t isolate why.

Build focused skills that do one thing well. A skill for error handling. A skill for logging conventions. A skill for API design patterns. These can be combined as needed for different projects or contexts.

This modularity also makes it easier to retire or replace individual skills. When your logging approach changes, you update one skill, not every skill that happens to mention logging.

Once you’ve codified your own practices, look at what’s portable. Not all knowledge is organization-specific, particularly in a government context. Some types of skills are highly portable across agencies and even across governments.

Portable across agencies

• Technical platform knowledge. How to work with specific languages, frameworks, or legacy systems.
• Compliance and accessibility patterns. Section 508, security frameworks, plain language requirements. These are common across government.
• Specification and documentation standards. How to structure outputs, write clearly, and organize information.
• Public benefit program patterns. Eligibility determination, review and approval flows, and appeals processes. Federal rules define much of this logic, making it shareable even when state-specific variations exist.

Less shareable

• Organization-specific coding conventions.
• Business rules and domain logic unique to your agency.
• Skills tied to your specific architecture or integrations.

When importing external skills, evaluate them critically, for security as well as fit (see Practice 6). Understand why they’re written the way they are. Adapt them to your context rather than using them as-is.

And when you develop skills that encode portable technical knowledge, consider contributing them back. The instruction sets you create today can help other agencies tomorrow.

It’s easy to think of a skill as documentation. After all, it’s just a document. But an agent acts on what a skill says. Skills can bundle scripts for the agent to run, point to external tools and URLs, and direct the agent to read files, execute commands, or call services. The agent typically does this with the developer’s own permissions, on a machine that holds source code and credentials. In practice, a skill behaves less like a document and more like a software dependency.

Public skill marketplaces have already shown some potential consequences. In early 2026, a security audit of one popular skill registry found 341 malicious skills among the 2,857 it examined, many designed to steal credentials. Researchers have also found that marketplace scanning badges offer less assurance than they appear to, and that attackers can hijack skills hosted in abandoned GitHub repositories. Estimates of how widespread the problem is vary considerably by method. Rather than assuming all public skills are malicious, organizations should treat every individual skill as unverified until reviewed.

Plain-text skills aren’t automatically safe either. Malicious instructions don’t require code. A few sentences buried in a long skill can tell an agent to send environment variables to an outside server, weaken a validation check, or quietly add a dependency. This is a form of prompt injection, and it can be hard to spot in a quick review.

Watch what goes in, too

Always-on instruction files are sent to the model with every request, and on-demand skills are sent whenever the agent loads them, often to a vendor-hosted service. Skills also live in repositories that may be shared widely or published under an open-source policy. Keep secrets, credentials, internal hostnames, personally identifiable information, controlled unclassified information (CUI), and detailed security architecture out of them. Confirm that your AI tools are authorized for the data that your skills and code contain, within your system’s authorization boundary and any FedRAMP or equivalent requirements that apply.

Base review on capability

Not every skill needs the same scrutiny. A practical approach is to tier review by what a skill can do.

1. 1

   Guidance only

   Plain-text instructions with no bundled scripts and no external references. Register freely, and let peer review happen through use.

2. 2

   Extend what the agent can do

   Bundled scripts, external URLs, new tool access, or instructions to install software. Requires security review before broad use.

3. 3

   Organization-wide or security-sensitive

   Skills that encode security, compliance, or organization-wide standards require formal review (see Practice 7).

Imported skills get the same tiered review as internal ones, plus a provenance check: where did this come from, and who can change it upstream? Pin imported skills to a specific reviewed version and keep a copy in your own registry rather than pulling them live from a public marketplace each time.

Back instructions with enforcement

Because agents follow instructions probabilistically, security can’t depend on an agent obeying a skill. Run agents with the least access they need to credentials, networks, and production systems. Rely on automated checks in your pipeline (secrets detection, dependency and license scanning, static analysis) to enforce what must hold no matter what the agent generates. Apply those same checks to the instruction files themselves, and flag any change that adds a script or an external reference.

Finally, fold skills into your existing governance rather than building something parallel. Skills belong in your software supply chain practices and your AI policies. For federal agencies, OMB Memorandum M-25-21 already calls for generative AI acceptable-use policies and AI governance boards. Those are natural homes for guidance on skills and instruction files. State and local agencies can apply the same thinking through their own AI and security policies.

Skills are trivially easy to create. Anyone can write one in a few minutes or download one from the internet. If your governance process requires formal submissions, committee approvals, and lengthy documentation, people are likely to work around it. They’ll keep useful skills in personal directories and never share them.

You’ll end up with the worst of both worlds: overhead from maintaining a governance structure that doesn’t actually govern, plus all the risks of ungoverned activity happening in shadow repositories and personal directories.

Design your governance processes so that doing things the official way is genuinely easier than the alternative. Make registration self-service. Make sharing frictionless. Make discovery intuitive. When the sanctioned path is the path of least resistance, adoption follows naturally.

Govern through transparency, not gatekeeping

Rely on visibility and feedback rather than approval gates. Let anyone register a skill in a central registry with minimal friction. Show what others are using. Surface skills that have high adoption or positive feedback. Let peer review happen through use and discussion, not committees.

Reserve formal review for skills with broad scope or high risk: organization-wide standards, security-sensitive guidance, compliance-related requirements. Skills that bundle scripts, reference external resources, or give agents new access warrant security review before broad use (see Practice 6). For guidance-only, team-level experimentation, transparency is usually sufficient.

Recent research shows why testing matters.

What Vercel found in early 2026

Software company Vercel compared two ways of giving AI agents access to framework documentation: on-demand skills, where the agent decides when to invoke them, and an always-on instruction file, where the documentation is always available. They expected on-demand skills to work better.

What studies of AGENTS.md files found

What you put into an instruction file can significantly change what an AI coding tool produces, in both directions. One study found that focused instruction files cut completion time, while another study found that unnecessary instructions lowered task success and raised cost.

The key takeaway from research to date is that assumptions can be wrong, and testing is the only way to determine what works in your context. Establish baselines.

Measure outcomes, not activity

It’s easy to count skills created, track invocations, and report adoption numbers. These metrics feel concrete and look good in reports. But they don’t tell you whether skills are improving outcomes.

What matters is whether code quality is improving, developers are more productive, fewer issues make it to production, and the AI’s output requires less rework. These are harder to measure but far more meaningful.

Include qualitative feedback. Ask developers whether skills are helping. Watch for signs of frustration or workarounds. Be willing to report honestly about what isn’t working. That’s how you improve.

Skills are tied to context that changes. Dependencies get updated. Coding standards evolve. Architecture patterns shift. A skill that was accurate a year ago may now encode outdated practices.

Every skill needs an owner: someone responsible for keeping it current. Owners should review skills periodically and update them when circumstances change. Automated checks can help flag skills that haven’t been reviewed or evaluated recently.

When a skill is no longer useful, retire it gracefully. Remove it from active use, but don’t delete it silently. Communicate what changed and what replaces it. Make the transition smooth for people who were relying on it.

Progress requires honest assessment. Use this self-assessment to understand your current state and chart a path forward. Understanding where you are helps you prioritize what to do next. An organization just starting out needs different things than one with established practices.

Read through the five levels below and find the highest level where every description fits your organization today. If you’re between two levels, choose the lower one. The descriptions you don’t yet meet show you where to focus. Each level also points to the practices that matter most at that stage.

Level 1: Organic or unorganized

• Individuals experiment with AI coding assistants.
• There are no shared skills.
• There’s no visibility into what others are doing.

Next step: Survey what already exists informally.

Focus practices: 1 – Capture knowledge, 2 – Start with real problems

Level 2: Team adoption

• Teams develop and share skills informally.
• There’s some local consistency, but no cross-team coordination.
• Shadow skills are the norm.

Next step: Create a minimal registry; surface what exists.

Focus practices: 4 – Keep skills focused, 6 – Treat skills as part of your software supply chain, 7 – Make the right way the easy way

Level 3: Organizational awareness

• Leadership recognizes skill development as a practice area.
• There are initial efforts to inventory and share.
• There are emerging standards, but adoption is voluntary.

Next step: Establish lightweight governance; begin measuring.

Focus practices: 3 – Include diverse perspectives, 7 – Make the right way the easy way, 8 – Test and measure

Level 4: Governed and measured

• A lightweight governance model is in place.
• A registry exists with good adoption.
• Metrics are established and tracked.
• The official path is genuinely easier than unofficial alternatives.

Next step: Focus on continuous improvement; share across teams.

Focus practices: 8 – Test and measure, 9 – Maintain what you create, 5 – Share what’s shareable

Level 5: Strategic capability

• Skill development is integrated with workforce development.
• Continuous improvement is based on measured outcomes.
• Captured knowledge encodes institutional expertise.
• Delivery mechanisms adapt as the field evolves.
• There is cross-agency sharing and collaboration.

Next step: Contribute to the broader community; mentor other agencies.

Focus practices: 5 – Share what’s shareable, 1 – Capture knowledge

First 30 days

• Identify a sponsor and small working group.
• Survey current state: what skills exist informally, and which were imported from outside sources?
• Select a low-risk pilot area.
• Establish a minimal registry (can be a shared document to start).
• Define initial baseline metrics.

30 to 90 days

• Develop 2-3 skills through a documented process.
• Test your lightweight review model.
• Experiment with delivery mechanisms.
• Gather feedback on friction points.
• Measure against your baseline.

6 months

• Expand to additional teams.
• Refine governance based on what you’ve learned.
• Invest in discoverability and tooling integration.
• Establish ongoing measurement practices.
• Document what’s working and what isn’t.

Ongoing

• Regular review cycles for effectiveness.
• Deprecation of underperforming skills.
• Cross-team sharing and collaboration.
• Periodic governance assessment: is the right way still the easy way?
• Adapt delivery mechanisms as the field evolves.

This guidebook opened with an analogy to infrastructure as code for framing how to manage and govern agent skill and instruction files. The maturation of cloud computing was accelerated by tools like IaC, and organizations that adopted them reaped (and continue to reap) the benefits.

The analogy helps explain some of the main benefits agent instruction files bring to software teams. Like infrastructure as code, agent instruction files can be managed in a version control system like Git. They can also coexist, and often do, in the same repository as the code they help generate. And like IaC for cloud infrastructure, agent instruction files address the problem of system knowledge living in one team member’s head or scattered across wikis, Google Docs, Git issues, and Slack messages. Besides improving the output of AI coding agents, they are a way to centrally capture team standards, conventions, and practices so they’re visible and auditable.

Infrastructure as code files (like Terraform) and agent instruction files (like SKILL.md) do differ in one important way.

Infrastructure as code codifies an outcome. Agent skills and instruction files codify intent.

That difference is worth keeping in mind. A framework for managing and governing agent instruction files should also include what are called executable invariants: the hooks, checks, and tests that run at commit time or in the CI pipeline and enforce the properties that must hold no matter what an AI coding agent generates. Examples include:

• Linting and formatting
• Test coverage thresholds
• Dependency and license scanning
• Secrets detection
• Accessibility checks on anything public-facing

A full discussion of executable invariants is outside the scope of this guidebook, but they are an important complement to the practices described here.