A Practical Guide to Building Agent Skills for Large Language Models

One of the simplest and most flexible ideas in large language model tooling is the notion of “Skills”. The term refers to a file format that supplies the model with concise, task‑specific information. It originates from an Anthropic specification used in products such as Claude Code and is now supported by most mainstream LLMs. The core idea is to describe and template a named task in a compact way, relying on the model’s ability to load only the necessary information when needed – a principle called progressive disclosure.

Each skill is a small collection of files placed in a directory that the model can locate. For example, Copilot looks for skills under ~/.copilot/skills and Claude under ~/.claude/skills. Project‑specific skills can also be stored in a hidden .claude/skills folder at the repository root.

To illustrate, we create a new skill called prepare‑pr that performs simple checks before a pull request is submitted. The required file is SKILL.md, which must contain a YAML header with at least name and description. The name must match the folder name and use lowercase hyphenated naming.

---
name: prepare‑pr
description: When the user says “Prepare PR”, prepare a Git pull request
---

The body of SKILL.md defines the task and the conditional responses:

# Prepare PR
When the user says “Prepare PR”, use the prepare‑pr skill.
Check whether all changed files are committed and pushed.
Do not check for unstaged files.
If all changes are committed, display a thumbs‑up emoji.
If there are uncommitted changes, display a thumbs‑down emoji.

Testing the skill in Claude Code shows that the skill appears in the tool list and returns the expected emoji based on the repository state.

As an alternative, we can write a Bash script to perform the git check and reference it from the skill. The script scripts/check_git_modified_uncommitted_files.sh contains:

git diff-index --quiet HEAD if [ $? -ne 0 ]; then exit 1 else exit 0 fi

The updated SKILL.md invokes this script and adjusts the response based on the script’s exit code:

---
name: prepare‑pr
description: When the user says “Prepare PR”, prepare a Git pull request
---
# Prepare PR
When the user says “Prepare PR”, use the prepare‑pr skill.
Run [script](scripts/check_git_modified_uncommitted_files.sh) to detect uncommitted changes.
If the script returns 0, show a thumbs‑up and “All changes are committed”.
If the script returns 1, show a thumbs‑down and “Uncommitted changes exist”.

While wrapping a simple Bash check in a skill adds a token overhead, it demonstrates how skills can encapsulate arbitrary logic.

We then extend the skill with a second stage that checks for untracked files that other committed files depend on. A new markdown template assets/untracked_file_dependency.md defines the report format, and the extended SKILL.md adds the additional steps and uses the template to list any dependencies.

---
name: prepare‑pr
description: When the user says “Prepare PR”, prepare a Git pull request
---
# Prepare PR
When the user says “Prepare PR”, use the prepare‑pr skill.
## Stage 1: Check for uncommitted changes
Run [script](scripts/check_git_modified_uncommitted_files.sh).
... (responses as before)
## Stage 2: Check for untracked file dependencies
List all untracked files, search committed files for includes or references, and report any matches using the template at assets/untracked_file_dependency.md.
... (responses based on findings)

The skill can be further expanded with checks such as linting, type checking, or style compliance, allowing teams to enforce standards before a pull request is opened.

In summary, a skill is essentially a set of text files and optional scripts organized in a folder hierarchy. The model loads the skill metadata when needed, avoiding context overload. Skills can be shared via the skills.sh standard or downloaded from the community, providing a lightweight way to extend LLM capabilities.