A Practical Guide to Agent Skills for AI Coding Agents: Use Them, Build Them, Contribute

If you work with AI coding agents, you may have a folder of prompts somewhere. A code review checklist. A release-notes format. The exact way your team writes migrations. You paste them in at the start of a session, the agent does the thing, and then that knowledge evaporates when the context window resets. Next session, you paste again.

Agent skills fix that. A skill packages a workflow once, as files the agent loads on demand, and reuses it across every conversation, whether your team works in Claude Code, Cursos, GitHub Copilot or Codex. For an engineering team, that means your conventions, reviews and audits run the same way every time, no matter who opens the session. 

This guide covers what skills are, how they compare to MCP, how to use them, and how to build your own. At the end, we share the open-source skills we just released at Eagerworks, which you can install today or contribute to.

What are agent skills?

A skill is a folder with a SKILL.md file at its root, plus optional supporting directories:

<pre><code class="language-plaintext">my-skill/
├── SKILL.md        # Required: metadata + instructions
├── scripts/        # Optional: executable code the agent can run
├── references/     # Optional: extra docs loaded on demand
└── assets/         # Optional: templates, logos, data files
</code></pre>

The SKILL.md file starts with YAML frontmatter that declares two required fields, name and description, followed by markdown instructions. That is the whole contract.

The mechanism that makes skills useful is progressive disclosure. The agent does not load every skill into context at startup. It preloads only the name and description of each installed skill, which is a few tokens. When a task matches a description, the agent reads the full SKILL.md into context. If that file references files in references/ or assets/, the agent pulls those only when the task actually needs them. Code in scripts/ can run without entering the context window at all.

This is the difference between a skill and a long pasted prompt. A pasted prompt sits in context the entire session, consuming tokens and competing for the model's attention whether the task needs it or not. A skill keeps its detail on disk until the moment it applies.

Skills also went from an Anthropic feature to an open standard, now specified at agentskills.io and adopted across a growing set of agent products. You build a skill once and run it on any skills-compatible agent.

Agent Skills vs. MCP, prompts, and AGENTS.md

Engineers ask this immediately, so here is the short version.

Skills vs. prompts. 

A prompt is text you supply each time. A skill is procedural knowledge that loads automatically when relevant and stays out of context when it is not. If you paste the same instructions across sessions, that is a skill waiting to be built.

Skills vs. MCP. 

MCP (Model Context Protocol) gives an agent access to external tools and data: a database, an issue tracker, an internal API. Skills are the knowledge layer. They guide the agent through multi-step workflows, including how and when to call those MCP tools. The two compose. If you already run an MCP server, a skill captures the workflow on top of it so the agent applies your process consistently.

Skills vs. AGENTS.md. 

A AGENTS.md file is always-on context, loaded for every task in a project. Skills load on demand. Put genuinely global context in AGENTS.md. Put task-specific procedures in skills, so they activate only when that task comes up and do not tax every other interaction.

How to use agent skills in Claude Code, Cursor and Copilot

Because skills are an open format, the same skill folder runs in any skills-compatible agent without modification: Claude Code, Cursor, GitHub Copilot, Codex, Amp, and a growing list of others. You do not write one version per tool. A skill your team writes for Claude Code works in Cursor as-is.

Install with the skills.sh CLI. 

The simplest path is the open-source skills.sh CLI. It detects the coding agents you have installed and puts the skill where each of them looks for it:

<pre><code class="language-bash"># install a skill from any public repository
npx skills add &lt;owner&gt;/&lt;repo&gt; --skill &lt;skill-name&gt;

# target specific agents
npx skills add &lt;owner&gt;/&lt;repo&gt; --skill &lt;skill-name&gt; -a claude-code -a cursor
</code></pre>

Skills install into your project by default, so they can be committed and shared with your team. Add -g to make them available in every project.

Or vendor the folder yourself. 

A skill is just files, so you can copy it into your repository. Agents with native skills support pick it up from their skills directory. For agents that work from a rules or instructions file (AGENTS.md, Cursor rules, Copilot instructions), add a short pointer telling the agent to read the skill's SKILL.md when the task is relevant. Either way, every agent reads the same files, so there is nothing to keep in sync between tools.

How your agents picks the right skill

Invocation is implicit. You do not call a skill by name, you describe the task, and the agent matches it against the installed descriptions. In practice it looks like this:

"Review the changes on this branch before I open the PR"

The agent recognizes the match, loads the skill, and follows its instructions. The quality of that matching depends almost entirely on how you write the description, which brings us to building your own.

How to build your own skill

The smallest useful skill is a single SKILL.md file. Here is a complete one that standardizes pull request descriptions:

<pre><code class="language-markdown">---
name: pr-description
description: >-
  Write a pull request description from a git diff or a list of
  changes. Use when the user asks for a PR description, PR summary,
  or wants to open a pull request.
---

# PR Description

Produce a pull request description with these sections:

## Summary
One or two sentences on what changed and why.

## Changes
A bullet list of the concrete changes, grouped by area.

## Testing
How the change was verified. State the commands run.

## Notes
Breaking changes, follow-ups, or risks. Omit if none.

Keep it factual. Do not invent testing that was not described.
</code></pre>

That file alone is installable and works. A few principles separate a skill that triggers reliably from one that sits unused.

Best practices for skills that actually get used

• The description decides everything. The agent only ever sees name and description until a task matches. A vague description like "helps with PRs" rarely fires. State both what the skill does and when to use it, including the phrases a user would actually type. The example above lists "PR description," "PR summary," and "open a pull request" on purpose.
• Start from real gaps. Run your agent on representative tasks and watch where it struggles or needs the same correction twice. Build skills to close those specific gaps, not hypothetical ones.
• Keep the body lean, push detail outward. When SKILL.md grows unwieldy, move detail into references/ and link to it. The agent loads those files only when the task needs them, which keeps your common path cheap. If two parts of a skill are rarely used together, separate them.
• Use scripts for deterministic steps. Anything that must be exact and repeatable belongs in scripts/ as code. Code runs the same way every time and executes without consuming context. The agent decides when to run it.
• Match freedom to the task. For processes that must be followed exactly, such as data pipelines, compliance checks, or migration steps, write tight, low-freedom instructions. For creative output where variety is good, leave room.
• Test like you test code. Define input queries, expected behavior, and output format, then run them. Test across the models you plan to use, since different models read instructions differently.

To scaffold the folder structure and a starter SKILL.md, use Anthropic's open-source skill-creator skill, which walks you through it interactively and, like any skill, runs in any compatible agent.

Agent skills security: how to vet a skill before you install it

Skills can include code that the agent executes, which is what makes them powerful and also what makes them a risk. A malicious skill can direct an agent to run commands or call tools in ways that do not match its stated purpose, leading to data exfiltration or unauthorized access.

The rule is simple: install skills only from sources you trust, meaning ones you wrote or obtained from a known publisher. Before running a skill from anywhere else, audit every file in it, the SKILL.md, the scripts, and the referenced resources, and look for network calls or file access that do not fit the skill's job. An open, version-controlled repository is the auditable path here, which is exactly what we built.

Our open-source skills

We collected the skills our team relies on and open-sourced them. They cover the work we do most: committing and opening pull requests, reviewing code, documenting decisions, designing APIs, deploying, and auditing the codebases we build and inherit for client projects. Every skill is a plain folder you can read end to end before you run it, and each one follows the progressive-disclosure pattern described above: a lean SKILL.md hub, detail in references/, and copyable templates in assets/. Each skill also ships a CHANGELOG.md and a semver version, so you can see what changed before you pull an update.

Open-source agent skills you can install today

Git workflow and AI code review

• commit. Turns everything pending in the working tree into a series of coherent Conventional Commits, one per logical change, instead of one commit for everything. It infers the type and scope vocabulary from your repo's own history, never stages secrets or build output, and stops at the commit: no push, no amend, no rebase.
• create-pr. Opens or updates a pull request. It resolves the base branch from evidence instead of assuming main, writes a description with a fixed structure, derives the verification checklist from the tooling it actually finds in the repo, and splits the test plan into automated results and tickable manual test scenarios for the reviewer. It attaches screenshots through the GitHub CLI when the change is visible, and leaves an explicit placeholder rather than inventing a URL or a test step.
• pr-review. Runs an AI code review on a diff (a branch, a PR, or staged changes) against five lenses: correctness, security and data integrity, repo conventions, test coverage, and documentation. Findings carry a conservative severity ladder, and when the target is a GitHub PR it posts the review as inline comments. It is read-only unless you explicitly ask it to fix what it found.

Documentation

• decision-record. Writes an architecture decision record as a dated markdown file under docs/decision-records/, with a one-sentence title and four fixed sections: Context, Decision, Consequences, Related. It never invents the rationale behind a decision. If it does not know the why, it asks.

API design

• rest-api-design. Designs and reviews REST APIs: resource modeling, methods and status codes, RFC 9457 error shapes, pagination, versioning, auth, rate limiting, and OpenAPI 3.1. It surveys the existing API first, so new endpoints match the conventions already in the codebase.

Deployment

• kamal. Zero-downtime deployments with Kamal, for both 2.x and 1.9.x: first-time setup, deploys and rollbacks, kamal-proxy with Let's Encrypt SSL, secrets, accessories, multi-arch builders, troubleshooting, and the v1 to v2 upgrade. It detects which version you are on before it gives advice.

Codebase audits and compliance

• loop-engineering-audit. Audits whether a repository is ready to be developed by autonomous agent loops: agent-facing docs, reproducible setup, fast deterministic checks, test coverage, CI gates, guardrails, and whether several agent sessions can work in parallel without colliding. It produces a graded report and an ordered work plan, plus advisory recommendations for which agent loops the project could run, each rated by blast radius.
• repo-handoff. Prepares the handoff of a codebase inherited from another team. It grades ten dimensions, from architecture and setup to credentials and operations, and turns every gap into a prioritized list of questions for the previous team, plus an access and ownership transfer checklist.
• audit-hipaa. Audits a codebase and its infrastructure config against the HIPAA Security Rule. It locates PHI in data models, logs, error trackers, analytics, and outbound LLM calls, checks the technical safeguards, and routes the obligations code cannot prove, such as BAAs, to a human.
• mobile-store-review. Audits an Expo, React Native, or native app against Apple's App Review Guidelines and Google Play's policies before you submit: permissions, privacy manifests, account deletion, in-app purchases, SDK floors, and EAS build config.

Coming soon: new agent skills in open pull requests

These are in open pull requests on the repository right now. Follow along, try them from their branches, or leave a review.

• architecture-design. Interviews you about a new system (goals, scale, constraints, quality attributes) and writes a v1 architecture document with diagrams, a decision log with the alternatives considered, and an evolution path. It defaults to the simplest architecture that meets the drivers and pushes back on complexity without a reason.
• design-qa-test-cases. Designs a traceable QA test plan for a feature by reading the project's own code: boundary values from validations, a permission matrix from policies, state transitions from enums. It cross-references existing tests so a case already covered is marked as covered instead of re-listed. It designs cases and never writes test code.
• ui-ux-audit. Audits a product's interface across eight dimensions, including navigation, visual consistency, responsiveness, WCAG 2.2 AA accessibility, forms, and system states. Every finding comes with a concrete recommendation.
• audit-seo. Audits a site's technical SEO from a live URL, the source code, or both, and traces a live finding back to the line that causes it. It never fabricates search volume, rankings, or traffic.
• audit-gdpr. The GDPR counterpart to audit-hipaa: lawful basis and consent, data subject rights (including the soft-delete-is-not-erasure trap), personal data in logs and third-party calls, and processor and transfer obligations.
• audit-soc2. Assesses SOC 2 readiness through a structured intake interview, then produces a gap matrix against the Trust Services criteria, a phased roadmap, and policy templates, without assuming you have bought a compliance platform.
• audit-open-source-repo. Audits whether an outside contributor can discover the project, set it up without the team's secrets, find scoped work, and get a PR merged. Its core check is whether your contribution guidelines run as a command (a linter, a hook, a CI job) and not just as prose.

How to install the Eagerworks skills

Every skill works in any skills-compatible agent. Use the skills.sh CLI, which supports Claude Code, Cursor, GitHub Copilot, Codex, Amp, and dozens of other agents:

<pre><code class="language-bash"># install a single skill
npx skills add eagerworks/skills --skill pr-review

# pick interactively, or install everything
npx skills add eagerworks/skills
npx skills add eagerworks/skills --all
</code></pre>

Or vendor the repository and point your agent at the skill you want. The repository README has copy-paste setup for Claude Code, Cursor, GitHub Copilot, and AGENTS.md-based agents like Codex and Amp:

<pre><code class="language-bash">git clone https://github.com/eagerworks/skills
</code></pre>

How to contribute your own agent skill

The repository is open to contributions. If you have a workflow your team repeats, package it as a skill and open a pull request. A good contribution includes a clear SKILL.md with a description that states when the skill applies, a minimal working example, and any scripts or references kept self-contained in the skill folder. Check the repository's contributing guide for conventions and the review flow.

Get started with agent skills in your AI coding agent

Agent skills turn the prompts you keep re-pasting into capabilities your agent loads on its own. Build one in minutes, run it everywhere, and share it with your team through version control.

Browse the repository, star it if it is useful, and try the skill closest to your work first. If you build something worth reusing, send a pull request. We review them.

github.com/eagerworks/skills