Understanding Agent Skills

Example helloworld-blog skill showing SKILL.md

Introduction

Skills are reusable instruction sets that teach an AI agent how to perform specific tasks.

This is how you make sure AI is developing code that follows your company’s current standards, patterns and processes.

For example:

Follow naming conventions
Code review to your standards
Commit messages in a preferred format
Use your existing code patterns
Follow your release process

They sit alongside your codebase and are applied when the agent recognises a relevant scenario.

Example Helloworld Skill

Let’s look at an example skill, this would sit in a file called SKILL.md:

---
name: helloworld-blog
description: Minimal demo skill for the Hugo blog. Generates or updates a single blog post with correct frontmatter and structure. Use when the user asks for a helloworld example, a demo post, or to verify skill setup for this blog.
---

# Helloworld Blog Skill

Use this skill when working on the Hugo blog in `rhuaridh-blog/` and the user wants a minimal, correct example (e.g. helloworld post or skill verification).

## Instructions

1. **Location** — Blog posts live under `rhuaridh-blog/content/blog/`. Use lowercase, hyphenated filenames (e.g. `my-post-title.md`).
2. **Frontmatter** — Every post must include:
   - `title`, `description`, `summary` (strings)
   - `date` (ISO 8601, e.g. `2026-03-05T09:00:00+01:00`)
   - `draft: false`
   - `categories: [AI]` (or other)
   - `tags: [relevant, tags]`
   - Optional: `header_image`, `header_image_alt`
3. **Body** — Start with an optional `

` if there is a header image, then `## Introduction`, then sections as needed. Use UK English.
4. **Scope** — When asked for a “helloworld” example, create or update one post that demonstrates this structure without changing the rest of the blog.

## Example

For “create a helloworld post”, create a short post with one section (e.g. Introduction) that confirms the blog setup and this skill are working.

How skills add value

Consistency - Everyone gets the same behaviour: same review checklist, same commit format, same security checks. Stop the AI guessing how your development team operate.
Faster onboarding - New joiners and AI can see “how we do X here” instead of digging through docs or asking repeatedly.
Reuse and scale - One skill can be used across many repos. Update the skill once and every agent benefits.
Controlled delegation - You decide what the agent is allowed to do and how. Skills act as guardrails and reduce the risk of the agent going off-script.
Progressive disclosure - Skills keep the main prompt lean. Detailed instructions are loaded only when the task demands it.

Together, these make AI agents more predictable, safer, and easier to roll out across teams.

Best practices for creating a skill

Be specific in the description - The agent uses the skill’s short description to decide when to apply it. Describe the task and the situation clearly so it’s invoked at the right time.
Scope one skill per job - One skill per workflow (e.g. “PR review”, “commit messages”, “run tests”) keeps skills maintainable and makes it obvious when each should run.
Write clear, step-by-step instructions - Similar to Runbooks and Playbooks, the body of the skill should tell the agent exactly what to do, in order.
Stand on the shoulders of giants - Look at how Claude and others have created their skills, and take inspiration for your own.

Summary

Skills turn prompting into repeatable, standardised behaviour. They add value by improving consistency, speeding up onboarding, scaling best practice, and keeping agent behaviour under control.

Here are some more resources to get started on creating your own: