Next Level AI Coding Agents - Skills Files

This post is part 2 in a series of posts about taking your AI coding agents to the next level.

In part 1 of this series, Instructions Files, we learned about how to set up instructions files for AI coding agents and how those files help keep your agents working in a manner consistent with your coding standards. Part 2 of the series shows you how to teach your agents how to do specific things - knowledge for repeatable tasks. This is the domain of skills files.

Instruction files are the “here are our coding and work standards” details. They are the generic, high level overview instructions. Skills files are the “here is how to perform specific tasks, step by step” details that give our AI coding agents greater knowledge.

With instructions files, agents still fumble over complex and multi-step tasks, even when they know the general conventions. Skills files fill in that gap. They solve the problem of how to do something, not just what to do.

Skills Files Overview

A skills file is a markdown file that provides to an agent a reusable, step-by-step process for implementing a specific task. You can think of it like a runbook. It’s something written once, and referenced repeatedly. Whenever an agent needs to implement a task of a specific type, it will reference that related skills file for the pattern to follow. It differs from instructions files in that it is only referenced and included in the context as needed, where instructions files are included in the context every single time.

Contrast/Compare Skills and Instructions

Standards & Conventions

Originally developed for Claude, skills remain the most mature in that ecosystem. However, skills are the one place in AI coding agents where a coherent standard has formed. And the majority of AI coding agents on the market now support skills in the same manner.

• Skills live in a folder named skills. Where that folder goes can vary depending on the agent you’re using.
• Each skill lives in a sub-folder under the skills parent folder that is named for that particular skill.
• Inside each skill folder is a file named SKILL.md, which provides the instructions for that skill.
• Agents are generally decent at finding and using those skills that are relevant, but it is also best practice to provide guidance in the instructions files on when to use each skill.
• Most agents support the ability to have both global and project specific skills folders.

An example skills folder:

.claude/
└── skills/
    ├── scaffold-module/
    │   └── SKILL.md
    ├── add-endpoint/
    │   └── SKILL.md
    └── write-domain-event/
        └── SKILL.md

A skills folder may also include sub-folders, which contain other markdown files that a skill can reference for further, more detailed instructions.

If you’re not using Claude, consult the documentation of your preferred coding agent for anything that might vary in their implementation.

What Makes a Good Skills File

There is a general pattern that has become the accepted standard for skills files.

• Clear trigger - Describe when the agent should use this particular skill.
• Prerequisites - Detail out the context required and exactly what inputs are needed for this skill to be implemented.
• Step-by-step procedure - Describe in detailed, numbered, unambiguous steps how to implement this functionality. Include code examples if the skill is language specific and it’s relevant.
• Verification instructions - Detail out how the agent will verify that it did the job correctly and the process was followed.
• Example output - Show the agent what success looks like.
• Keep it focused - Keep it to one skill per file. Keep the scope narrow and precise.

Real-World Examples

Here are a couple of excellent real-world examples of SKILL.md files to show you how to create skills.

A simple add-endpoint/SKILL.md file:

---
name: add-endpoint
description: "Use when adding a new HTTP endpoint to the application. 
  Applies to any new API route using FastEndpoints."
---

# Add a FastEndpoints Endpoint

## Trigger
Use this skill any time a new API endpoint is needed.

## Prerequisites
- The use case handler for this endpoint already exists in the Application layer
- You know the HTTP verb, route, and request/response shape

## Steps

1. Create three files in `src/{Module}/Endpoints/`:
   - `{Action}{Resource}Request.cs`
   - `{Action}{Resource}Response.cs`
   - `{Action}{Resource}Endpoint.cs`

2. Define the request record:
```csharp
public record CreateOrderRequest(
    Guid CustomerId,
    List<OrderLineItem> Items);
```

3. Define the response record:
```csharp
public record CreateOrderResponse(Guid OrderId, string Status);
```

4. Implement the endpoint:
```csharp
public class CreateOrderEndpoint(IMediator mediator)
    : Endpoint<CreateOrderRequest, CreateOrderResponse>
{
    public override void Configure()
    {
        Post("/orders");
        AllowAnonymous(); // or use appropriate auth policy
    }

    public override async Task HandleAsync(
        CreateOrderRequest req, CancellationToken ct)
    {
        var command = new CreateOrderCommand(req.CustomerId, req.Items);
        var result = await mediator.Send(command, ct);

        result.Switch(
            success => Response = new CreateOrderResponse(
                success.OrderId, "Created"),
            notFound => HttpContext.Response.StatusCode = 404,
            invalid => HttpContext.Response.StatusCode = 400);
    }
}
```

5. Map `Result` outcomes to HTTP status codes:
   - `Result.Success` → 200/201
   - `Result.NotFound` → 404
   - `Result.Invalid` → 400
   - `Result.Unauthorized` → 401

6. Add a unit test in `tests/{Module}/Endpoints/`:
   - Test each `Result` outcome maps to the correct status code
   - Use `NSubstitute` to mock `IMediator`

## Verification
- [ ] `dotnet build` passes with no warnings
- [ ] `dotnet test` passes
- [ ] Route follows existing conventions in the module
- [ ] All `Result` outcomes are handled — no unhandled cases

A more detailed scaffold-module/SKILL.md file that references other files in a sub-folder.

---
name: scaffold-module
description: "Use when creating a new bounded context or feature module 
  from scratch. Applies to any new top-level domain module."
---

# Scaffold a New Module

## Trigger
Use this skill when asked to create a new module, bounded context,
or major feature area.

## Prerequisites
- The module name is confirmed (e.g., `Payments`, `Inventory`)
- The aggregate root for this module is identified
- You understand whether this module needs its own database schema

## Folder Structure

Create the following structure under `src/{Module}/`:
src/{Module}/
Domain/
{Aggregate}.cs
{Aggregate}Id.cs
Events/
Application/
Create{Aggregate}/
Create{Aggregate}Command.cs
Create{Aggregate}Handler.cs
Create{Aggregate}Validator.cs
Infrastructure/
{Module}DbContext.cs
{Aggregate}Configuration.cs
{Aggregate}Repository.cs
Endpoints/
(add endpoints using the add-fastendpoints-endpoint skill)
{Module}Module.cs

## Steps

1. **Create the aggregate root** — see [Domain Patterns](domain-patterns.md)
   for value object, domain event, and guard clause conventions.

2. **Create the module registration class:**
```csharp
public static class {Module}Module
{
    public static IServiceCollection Add{Module}Module(
        this IServiceCollection services, IConfiguration config)
    {
        services.AddDbContext<{Module}DbContext>(opts =>
            opts.UseNpgsql(config.GetConnectionString("{Module}")));

        services.AddScoped<I{Aggregate}Repository, {Aggregate}Repository>();

        return services;
    }
}
```

3. **Register in `Program.cs`:**
```csharp
builder.Services.Add{Module}Module(builder.Configuration);
```

4. **Create the EF Core DbContext:**
```csharp
public class {Module}DbContext(DbContextOptions<{Module}DbContext> options)
    : DbContext(options)
{
    public DbSet<{Aggregate}> {Aggregate}s => Set<{Aggregate}>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("{module}");
        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof({Module}DbContext).Assembly);
    }
}
```

5. **Create the initial handler** using the Application layer conventions
   in [Application Patterns](application-patterns.md).

6. **Add a migration:**
```bash
dotnet ef migrations add Init_{Module} \
  --project src/{Module} \
  --startup-project src/Api
```

7. **Add the first endpoint** using the `add-fastendpoints-endpoint` skill.

8. **Add integration tests** in `tests/Integration/{Module}/`
   using `WebApplicationFactory`.

## Verification
- [ ] `dotnet build` passes with no warnings
- [ ] `dotnet test` passes
- [ ] Module is registered in `Program.cs`
- [ ] No direct references from this module to other module internals
- [ ] Migration script generated and reviewed

Wiring Skills to your Agent

As I mentioned before, agents in general do an ok job with finding and using skills automatically. That said, it’s a much better idea to specify in the instructions files when to use skills so that the agent has clear, defined guidelines on the workflow.

The typical approach is to add a section in your instructions file(s) that specifies in what situations to use each skill. For example, you might add the following in an instructions file:

## Skills
Before scaffolding a new module read `.claude/skills/scaffold-module/SKILL.md`.
Before adding a new endpoint, read `.claude/skills/add-endpoint/SKILL.md`.

Skills are only useful if an agent knows when and where to find them. As we have learned, the more specific context you provide an agent, the better the output it creates.

Building Your Skills Library

A mistake a lot of people make is to spend days, or weeks, trying to create a library of skills that includes everything they might ever need. There are a massive number of skills out there that people have already created, with more being added every day.

Implementing skills into your workflow takes time. You need to research and review existing skills, or write one yourself from scratch. And you need to update the instructions files to guide the AI on when to use each skill. That’s an investment of your resources and time.

Instead, start small. Pick two or three of your biggest AI agent coding pain points and find or write skills for those. For example, in my experience, many agents seem to struggle with properly implementing EntityFramework or Blazor. You have your own pain points. Pick a couple of them to start with. Then as you work, each time you catch an agent making the same mistake repeatedly, add a skill for that issue. Keep growing from there.

Remember that, as with instructions files, they are living documents that require regular maintenance and review. It’s not a matter of adding and forgetting. Languages evolve and grow, and your skills files must be updated to evolve and grow with them.

Conclusion

Skills files are the natural next step progression after instructions files. They take your AI coding agent from “knows your rules” to “knows your playbook”. Working hand in hand, instructions and skills files give your agent the knowhow to go from low level generalist to senior level specialist.

Sometimes, though, there are more complex and involved needs that skills won’t be able to handle. In our next post we’ll look at MCP servers and other custom tools that can give your AI coding agents new capabilities entirely.

Resources

• Part 1: Instructions Files
• Anthropic Skills Overview
• OpenAI Skills Overview
• Gitbook: skill.md explained: How to structure your product for AI agents
• Agent Skills
• GitHub Copilot Agent Skills
• Using Agent Skills in VS Code