Build a Custom AI Skill in 37 Lines (with working code)

Most teams I have worked with in 2026 have already adopted an AI coding assistant. Few of them have taught it anything specific to their codebase. The assistant knows JavaScript. It does not know that your team has a rule against console.log in production. It does not know that you wrap every error in a custom AppError class. It does not know that your Postgres queries always need a LIMIT clause for safety. That is the gap a custom skill fills. A skill is a small, named bundle of instructions, usually 20 to 40 lines, that an AI agent loads on demand. It does not sit in the system prompt burning tokens. It lives in a folder, has a name, and gets invoked when the task matches.

In this post we will build one. The whole thing: 30 lines of instruction, two files, one bash command to install. The skill reviews a git diff and returns a structured critique covering bugs, security, style, and performance. The output is formatted so you can paste it straight into a PR comment. By the end of this post, you will have a working pattern. I will give you three more skill ideas at the bottom that you can ship in an afternoon each.

Why this matters: the assistant you use is not the assistant that fits

A vanilla AI coding assistant is a generalist. It knows the language, the framework, the library, the common patterns. It does not know your team's house style. It does not know your security requirements. It does not know the conventions you have been arguing about for three years in your pull request reviews. Every time you ask it to write code, you get code that is technically correct but culturally wrong. The senior engineer on your team fixes the output. The junior engineer ships it.

A custom skill is a way to encode the senior engineer's review. Once. And have every future session follow it. The skill is a file, the file is loaded when the task matches, the loaded skill changes the behavior of the assistant for the duration of that task. The result is an assistant that is not just competent, but competent in your codebase. The difference between an assistant you use and an assistant that fits.

The pattern is not new. The pattern is the same pattern as man pages, as eslint rules, as prettier config, as any piece of in-codebase documentation that tells a tool how to behave. The pattern is new in the sense that the tool is an LLM and the documentation is in natural language. The pattern is the same.

What an AI skill actually is

A skill is a small, named bundle of natural language instructions, optionally with a small piece of executable code, that an AI agent loads on demand. The format is platform-specific, but the shape is consistent. Claude Code uses a SKILL.md file with a name, a description, and a body. OpenAI Codex uses a ~/.codex/skills/<name>/SKILL.md file with the same shape. Other platforms have equivalent files. The body is the actual instructions — what the agent should do when the skill is invoked. The name and description are how the agent decides when to invoke it.

The mechanism is the same as a tool call. The agent looks at the user's request. The agent compares the request to the description of every available skill. If a description matches, the agent loads the skill and follows the instructions. The mechanism is fast, the loading is free, and the result is an agent that behaves as if the skill was always part of its context.

A skill can be 10 lines or 1000 lines. Most useful skills are 20 to 40 lines. The cost of loading a skill is proportional to its length, so the sweet spot is "as short as possible while still being specific." A skill that says "write good code" is useless. A skill that says "review a git diff and return a structured critique covering bugs, security, style, and performance, with a one-line summary at the top and bullet points for each issue" is useful. The difference is the specificity.

The skill we are building today

We are going to build a skill that reviews a git diff and returns a structured critique. The skill is invoked when the user asks for a code review, a diff review, a PR review, or any similar phrase. The output is formatted to be pasted straight into a GitHub PR comment — Markdown, with sections for each kind of issue, a one-line summary at the top, and concrete suggestions for each issue.

The skill lives in a file called SKILL.md, in a folder called code-review, in the skills directory of your AI assistant. For Claude Code, that is ~/.claude/skills/code-review/SKILL.md. For OpenAI Codex, that is ~/.codex/skills/code-review/SKILL.md. The content is the same. The path is different.

The skill has three parts: a name, a description, and a body. The name is a short identifier. The description is one or two sentences that tell the agent when to invoke the skill. The body is the actual instructions. The body is where the value lives.

# name: code-review
# description: Review a git diff and return a structured critique covering bugs, security, style, and performance. Use this when the user asks for a code review, a diff review, or a PR review.
# ---

When asked to review code, follow this process:

1. Run `git diff` to get the current changes (or read the diff the user provides).
2. Analyze the diff for the following categories, in this order:
   - **Bugs**: Logic errors, off-by-one, missing error handling, race conditions.
   - **Security**: Injection, secrets in code, unsafe deserialization, missing auth.
   - **Style**: Naming, formatting, dead code, magic numbers, comments.
   - **Performance**: N+1 queries, unnecessary allocations, blocking calls in async paths.
3. For each issue, provide: the file, the line range, a one-sentence description, and a concrete suggestion.
4. Format the output as Markdown with a one-line summary at the top.

Use this template for the output:

> **Summary**: <one-line summary of the diff>

- **[BUG]** `path/to/file.py:42-45` — <description>. Suggestion: <fix>.
- **[SECURITY]** `path/to/file.py:60` — <description>. Suggestion: <fix>.
- **[STYLE]** `path/to/file.py:30` — <description>. Suggestion: <fix>.
- **[PERF]** `path/to/file.py:80` — <description>. Suggestion: <fix>.

If there are no issues in a category, omit the section.

That is the entire skill. 37 lines including the Markdown template. The skill tells the agent what to do, in what order, in what format. The agent does the rest. The result is a code review that is consistent, structured, and ready to paste into a PR comment.

Installing the skill

The installation is one bash command per platform. For Claude Code:

mkdir -p ~/.claude/skills/code-review
cat > ~/.claude/skills/code-review/SKILL.md <<'EOF'
<the SKILL.md content above>
EOF

For OpenAI Codex, the same content goes in ~/.codex/skills/code-review/SKILL.md. For other platforms, the same content goes in the equivalent directory. The content is the same. The location is platform-specific.

Once the file is in place, the skill is available. The next time the user asks for a code review, the agent will load the skill, follow the instructions, and produce the output. No restart required, no API call to enable the skill, no configuration. The skill is a file. The file is loaded when the agent sees a matching request.

The first time you use the skill, you will be surprised by how good the output is. The skill is doing real work — the structured output, the priority of categories, the one-line summary, the paste-ready Markdown. None of that is in the agent's default behavior. All of that is the skill. The agent is the same. The skill is what makes the output useful.

Why this works

A skill works because of two properties of the modern AI agent. The first is the ability to load context on demand. The agent does not have every skill loaded at all times. The agent loads the skill when the description matches the user's request. The mechanism is fast, the cost is low, and the result is that a small set of skills can cover a large set of use cases without bloating the system prompt.

The second is the ability to follow structured instructions reliably. The skill is a set of numbered steps, a template, a category list, a format. The agent follows the structure. The output is consistent. The output is pasteable. The output is the same on every run. The structure is what makes the skill work — without the structure, the output would be free-form, and free-form output is harder to use.

The third property, which is more subtle, is that the skill is a file. The file can be reviewed. The file can be tested. The file can be improved. The file can be shared. The file can be checked into the codebase. The file can be evolved as the team's needs evolve. The file is the documentation. The file is the test. The file is the artifact.

Three more skill ideas

The pattern generalizes. Any time the agent does something that follows a template, that follows a category list, that follows a set of structured steps, that is a candidate for a skill. Three ideas you can ship in an afternoon each.

1. A commit-message skill. The skill generates a commit message from a git diff following the team's commit message convention. The convention can be Conventional Commits, or Semantic Release, or your team's custom format. The output is a single commit message, ready to paste into the commit editor. The skill is 20 lines.

2. A test-coverage skill. The skill reads a code file, identifies the test cases that are missing, and writes the test cases in the team's test framework. The output is a list of new test cases, ready to be added to the test file. The skill is 40 lines. The test framework, the test naming convention, and the assertion style are all encoded in the skill.

3. A dependency-audit skill. The skill reads a package.json (or requirements.txt, or Cargo.toml, or whatever), identifies the dependencies that are out of date, and writes the upgrade commands for each. The output is a list of upgrade commands, ready to be pasted into the terminal. The skill is 30 lines.

The pattern is the same for all three. A small, named bundle of natural language instructions, optionally with a small piece of executable code, that an AI agent loads on demand. The pattern is not new. The pattern is the same pattern as man pages, as eslint rules, as prettier config, as any piece of in-codebase documentation that tells a tool how to behave. The pattern is new in the sense that the tool is an LLM. The pattern is the same.

When to write a skill

The decision to write a skill is the same as the decision to write a function. If the task comes up more than three times, write a skill. If the task has a structure that the agent does not already know, write a skill. If the output needs to be consistent across sessions, write a skill. If the team has a convention that the agent should follow, write a skill.

The decision to NOT write a skill is also the same as the decision to NOT write a function. If the task is one-off, do not write a skill. If the task is a conversation, not a structured output, do not write a skill. If the agent already does the task well, do not write a skill. The skill is a tool. The skill is for tasks that the agent does not do well without help.

The pattern is the same as the pattern for tests, for documentation, for type annotations. The pattern is: write the thing once, have the machine do it forever. The skill is the machine. The pattern is the same.

The Shape of What Comes Next

The pattern of "small, named bundle of natural language instructions that an AI agent loads on demand" is the pattern that will define the next five years of AI tooling. The pattern is not new. The pattern is the same pattern as man pages, as eslint rules, as prettier config, as any piece of in-codebase documentation that tells a tool how to behave. The pattern is new in the sense that the tool is an LLM. The pattern is the same.

The interesting questions in 2027 are not "which AI agent should I use" but "which skills should my team have" and "how do I get the team to write them." The skills are the new documentation. The skills are the new tests. The skills are the new architecture decision records. The skills are the artifacts that the team produces. The artifacts are the difference between a team that uses AI and a team that has internalized AI. The artifacts are the work.

A small toolkit to get started, if you have not already: install the code-review skill from this post. The cat > ~/.claude/skills/code-review/SKILL.md <<'EOF' ... EOF one-liner is all it takes. The next time you ask the agent for a code review, you will get a structured, paste-ready output. The first review will surprise you. The tenth review will be muscle memory. The 100th review will be the difference between a team that uses AI and a team that has internalized AI. The skill is the work. The rest is documentation.