My AI agent writes code fast. Documentation? Not so much.

It’s not that it can’t write docs — it will happily produce pages of text. The problem is consistency. One session it structures everything around the Diátaxis framework with tutorials, how-tos, references, and explanations neatly separated. The next session, it dumps everything into one long blob. I spend ten minutes explaining the writing standards, close the session, open a new one, and it’s back to square one.

I’ve tried stuffing rules into the system prompt. I’ve tried keeping a .md file in the repo for it to read. Both work, sort of. But then every project needs its own copy, and they drift out of sync within a week.

Last week, GitHub CLI v2.90.0 shipped a new command group that addresses exactly this: gh skill.

What Are Agent Skills?

Agent Skills are standardized instruction packages that tell an AI agent how to handle specific tasks.

Think of it this way: when you onboard at a new company, you get a checklist — where the code style guide lives, how to open a PR, what the deploy process looks like. You don’t wander around asking everyone. An Agent Skill is that checklist for your AI, except it’s versioned, portable, and works across different agents.

The spec is open and defined at agentskills.io. gh skill is GitHub CLI’s official implementation — search, preview, install, and publish, all from the command line.

Supported agents: GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, and Antigravity.

Hands-On: Installing a Skill

Search

Let’s see what’s out there. The github/awesome-copilot repo has 200+ skills in its skills/ directory:

1

gh skill search documentation

This returns a list of matching skills with names, descriptions, and source repos. Suppose we spot documentation-writer — a technical writing skill built on the Diátaxis framework. Exactly what I need.

Preview

Before installing, take a look at what you’re getting:

1

gh skill preview github/awesome-copilot documentation-writer

This shows the SKILL.md contents: the YAML frontmatter (metadata like name, description, compatibility) and the Markdown body (the actual instructions). You can decide whether it’s a good fit without touching your project.

Install

Looks good. Install it:

1

gh skill install github/awesome-copilot documentation-writer

This creates (or updates) the skill files in your project. The core is a SKILL.md with YAML frontmatter that records the source:

1
2
3
4
5
6
7
8

---
name: documentation-writer
description: "Technical documentation writer following the Diátaxis framework..."
source:
  repo: github/awesome-copilot
  ref: main
  tree-sha: a1b2c3d4e5f6...
---

The Markdown body below that contains the actual instructions — when to trigger, how to structure docs, what tone to use.

A complete skill directory looks like this:

1
2
3
4
5

documentation-writer/
├── SKILL.md          # Required: YAML frontmatter + Markdown instructions
├── scripts/          # Optional: executable scripts
├── references/       # Optional: reference docs
└── assets/           # Optional: templates, resources

SKILL.md is the only required file. Everything else is optional.

Installing for a Different Agent

The default target is GitHub Copilot. For Claude Code:

1

gh skill install github/awesome-copilot documentation-writer --agent claude-code --scope user

--agent sets the target agent. --scope user makes it a user-level skill, not limited to the current project.

Pinning Versions

For production, you probably don’t want skills updating under your feet. Pin to a specific version:

1

gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

With pinning, upstream changes won’t affect you. When you’re ready to update, explicitly run:

1

gh skill update --all

Writing Your Own Skill

Now let’s build one from scratch. Say I want a commit-message-writer skill that enforces Conventional Commits across the team — with scopes, 72-character body wrapping, the works.

Create the Directory

1

mkdir -p commit-message-writer

Write SKILL.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

cat > commit-message-writer/SKILL.md << 'EOF'
---
name: commit-message-writer
description: "Generates commit messages following Conventional Commits specification. Triggered when the user asks to commit, or when suggesting a commit after code changes."
license: MIT
compatibility:
  - github-copilot
  - claude-code
  - cursor
---

## Commit Message Format

When generating a commit message, follow this exact structure:

():