First Custom Agent Skill
Building a custom Agent Skill for Claude Code that automates PR description generation from git diff output — packaged as a reusable SKILL.md with YAML frontmatter.
Goal
Understand the Agent Skills format by building a practical skill from scratch: auto-generating structured pull request descriptions from staged changes.
Context
Agent Skills are directories containing a SKILL.md file with YAML frontmatter that give agents additional capabilities. Skills are supported across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform. This experiment builds a skill called pr-describe that reads git diff output and produces a standardized PR description following conventional commits.
Prompt used
Given the output of `git diff --staged`, generate a structured pull request description with: a one-line title following conventional commits format, a Summary section (3 bullet points max), a Test Plan (numbered checklist), and a Breaking Changes section (or 'None'). Be concise and technical.
Implementation notes
The SKILL.md file uses required YAML frontmatter (name, description) plus optional fields for tools and examples. The skill directory at .claude/skills/pr-describe/ contains SKILL.md, a helper script get-diff.sh that stages and pipes git diff, and a sample output for Claude to reference. Claude Code automatically loads the skill when the working directory contains a git repo and the skill name is invoked.
Result
The skill reliably generates PR descriptions matching the conventional commits specification. After 10 test runs on different repositories, the title format was correct 9/10 times. The summary quality varied based on diff verbosity — very large diffs (500+ lines) produced less precise summaries.
What worked
- YAML frontmatter is minimal and the skill loaded without issues
- Claude correctly invoked the get-diff.sh helper without being told to
- Output format was consistent across runs
- Skill is portable — copying the directory to a new project just works
What failed
- Very large diffs (500+ lines) overwhelm the skill — summary quality degrades
- No built-in truncation logic; needs a MAX_DIFF_LINES guard in the helper script
- The skill does not yet handle merge commits differently from feature commits
Next iteration
Add a diff-chunking mechanism to the helper script. Publish the skill to a public GitHub repo following the anthropics/skills marketplace format.