How to Build Custom AI Agent Skills: A Step-by-Step Guide

AI coding agents follow instructions. The quality of those instructions determines whether you get mediocre output or production-ready results. This tutorial walks you through building a custom skill from scratch — from identifying the need to publishing it for your team.

Prerequisites

Before starting, make sure you have:

• SkillReg CLI installed
• A SkillReg account (free tier works)
• An AI coding agent (Claude Code, Codex, or Cursor)

Step 1: Identify the Right Task

Not every task needs a skill. Skills are most valuable when:

• Repetitive — You or your team does it more than once a week
• Multi-step — It involves more than a single command
• Error-prone — Manual execution sometimes goes wrong
• Requires consistency — Different people should get the same result

Good candidates for skills:

• PR review workflows
• Deployment pipelines
• Database migration checks
• Test generation patterns
• Code style enforcement
• API endpoint scaffolding

Bad candidates:

• One-off scripts
• Simple single-command tasks
• Tasks that change every time

Step 2: Document the Manual Process

Before writing a skill, write down exactly how you do the task manually. Be specific. For this tutorial, we'll build a PR review skill that checks for common issues.

Here's the manual process:

1. Read all changed files in the PR
2. Check for console.log statements left in production code
3. Check for hardcoded secrets or API keys
4. Verify that new functions have TypeScript types
5. Check that imports are organized
6. Look for potential SQL injection or XSS vulnerabilities
7. Verify test coverage for new code paths
8. Write a summary with findings

Step 3: Create the SKILL.md File

Create a new file in your project:

mkdir -p .claude/skills
touch .claude/skills/SKILL.md

Start with the frontmatter:

---
name: pr-review-security
version: 1.0.0
description: Review pull requests for security issues, code quality, and best practices
agents:
  - claude-code
  - codex
  - cursor
tags:
  - review
  - security
  - code-quality
author: "@your-org"
---

Choosing the Right Name

Skill names should be:

• Lowercase with hyphens — pr-review-security, not PRReviewSecurity
• Descriptive — The name should tell you what it does
• Scoped — Prefix with your org if publishing to a registry

Step 4: Write the Instructions

Now translate your manual process into structured instructions:

## Overview
Review the current pull request for security vulnerabilities, code quality issues,
and adherence to team standards. Produce a detailed report with severity ratings.

## Prerequisites
- Access to the git diff of the current branch vs main
- Ability to read all files in the repository

## Steps

### 1. Gather Context
- Run `git diff main...HEAD --name-only` to list all changed files
- Read each changed file completely
- Identify the type of change (new feature, bug fix, refactor)

### 2. Security Checks
For each changed file, check for:
- Hardcoded secrets (API keys, tokens, passwords, connection strings)
- SQL queries built with string concatenation (SQL injection risk)
- User input rendered without sanitization (XSS risk)
- Dangerous function calls (eval, exec, unsafe innerHTML usage)
- Insecure HTTP calls (http:// instead of https://)
- Missing authentication checks on API routes

### 3. Code Quality Checks
- Console.log or debug statements left in production code
- Functions missing TypeScript type annotations
- Unused imports or variables
- Magic numbers without named constants
- Functions longer than 50 lines
- Duplicated code blocks (>10 lines)

### 4. Test Coverage
- Check if new functions have corresponding test files
- Verify that edge cases are tested
- Check that error paths are covered

### 5. Generate Report
Format the findings as a markdown report:

**Critical** — Must fix before merge (security issues)
**Warning** — Should fix (code quality)
**Info** — Nice to have (style, optimization)

Include:
- File path and line number for each finding
- Description of the issue
- Suggested fix
- Severity rating

Step 5: Define Guardrails

Guardrails are the most important part of a production skill. They prevent the agent from doing things it shouldn't:

## Guardrails
- NEVER modify any code — this is a read-only review
- NEVER approve or merge the PR automatically
- NEVER access files outside the repository
- NEVER run any commands that modify the filesystem
- ALWAYS report findings even if they seem minor
- ALWAYS include line numbers in findings
- If unsure about a finding, mark it as "Needs Human Review"

Step 6: Add Environment Configuration

If your skill needs environment variables:

env:
  GITHUB_TOKEN:
    description: "GitHub API token for fetching PR metadata"
    required: false
  REVIEW_STRICTNESS:
    description: "Review strictness level (strict, moderate, lenient)"
    default: "moderate"

Step 7: Test Locally

Before publishing, test the skill locally:

1. Place the SKILL.md in .claude/skills/ in your project
2. Open a PR or create some changes on a branch
3. Ask Claude Code: "Run the pr-review-security skill on the current branch"
4. Review the output — is it what you expected?

Common Issues During Testing

Too verbose — The agent produces a 500-line report for 3 changed files. Solution: Add "Be concise. Only report actual issues, not things that are fine." to the instructions.

Misses obvious issues — The agent skips hardcoded API keys. Solution: Add specific examples of what to look for: "Check for patterns like const API_KEY = 'sk-...' or Authorization: Bearer with hardcoded values."

False positives — The agent flags test fixtures as hardcoded secrets. Solution: Add "Ignore files in __tests__/fixtures/ and __mocks__/ directories."

Step 8: Publish to SkillReg

Once the skill works reliably, publish it for your team:

# Login to SkillReg
skillreg login

# Publish under your org scope
skillreg push @your-org/pr-review-security

Your team can now install it:

skillreg pull @your-org/pr-review-security

Step 9: Iterate Based on Feedback

Skills improve over time. Track common issues:

• False positives — Tighten the criteria or add exceptions
• Missed issues — Add more specific checks
• Performance — If the skill is slow, narrow the file scope

Bump the version appropriately:

# Update the version in SKILL.md frontmatter, then:
skillreg push @your-org/pr-review-security

Complete Example

Here's the final, production-ready SKILL.md:

---
name: pr-review-security
version: 1.2.0
description: Review pull requests for security issues, code quality, and best practices
agents:
  - claude-code
  - codex
  - cursor
tags:
  - review
  - security
  - code-quality
author: "@your-org"
env:
  REVIEW_STRICTNESS:
    description: "Review strictness level"
    default: "moderate"
---

## Overview
Review the current PR for security vulnerabilities and code quality issues.
Produce a concise report grouped by severity.

## Steps
1. List changed files with `git diff main...HEAD --name-only`
2. Read each changed file
3. For each file, check:
   - Hardcoded secrets (API keys, tokens, passwords)
   - SQL injection (string concatenation in queries)
   - XSS (unsanitized user input in HTML)
   - Missing type annotations
   - Console.log in production code
   - Unused imports
4. Check for corresponding test files
5. Generate a report grouped by Critical / Warning / Info

## Guardrails
- NEVER modify code — read-only review
- NEVER approve or merge automatically
- ALWAYS include file paths and line numbers
- Ignore test fixtures and mock files

Skill Design Patterns

The Checklist Pattern

Best for review and audit skills. Define a clear list of things to check, and the agent works through them systematically.

The Pipeline Pattern

Best for multi-stage workflows. Each step produces output that feeds into the next: build, test, deploy, verify.

The Template Pattern

Best for code generation skills. Define the structure you want, and the agent fills in the details based on context.

The Guard Pattern

Best for safety-critical workflows. The skill's primary job is to check preconditions and stop execution if anything is wrong.

Ready to build your first skill? Install the SkillReg CLI and follow the SKILL.md reference for the complete format specification.