AI Skills in Practice: Building Your First Skill

You understand the theory. Context files, triggers, prompts, references, output contracts — you know what the pieces are and why they matter. Now you build one.

This post is hands-on. We will take a real, repetitive workflow that most developers perform weekly, and turn it into a skill that produces consistent results every time. No specific tool required — the principles apply whether you use Claude Code, Cursor, Copilot, or any AI assistant that supports custom instructions.

Step 1: Find Your Workflow

The best candidate for your first skill has three properties:

1. You do it repeatedly. At least once a week, ideally more.
2. The steps are knowable. You could explain the process to a junior developer.
3. Quality varies. Sometimes you do it thoroughly, sometimes you rush.

Here are common candidates ranked by how well they fit:

For this walkthrough, we will build a commit message skill. It is something every developer does multiple times a day, quality is notoriously inconsistent, and the steps are well-defined.

Step 2: Document What You Actually Do

Before writing any skill definition, observe yourself performing the workflow. Not what you think you should do — what you actually do.

Here is what a typical developer does when writing a commit message:

1. Look at git diff to see what changed
2. Try to remember why they made the change
3. Type something like “fix bug” or “update styles”
4. Occasionally write a proper message when the change is important

Now here is what a good commit message process looks like:

1. Review staged changes (git diff --staged)
2. Identify the type of change (feature, fix, refactor, docs, test)
3. Summarize what changed in the subject line (imperative mood, under 72 chars)
4. Explain why the change was made in the body (if non-obvious)
5. Reference related issues or tickets
6. Check recent commits to match the repository’s style

The gap between “what I actually do” and “what the process should be” is exactly what the skill fills. You are encoding the thorough version of the workflow so it happens every time, even when you are tired or rushed.

Step 3: Write the Trigger

For a commit message skill, the trigger is straightforward:

trigger: "When the user asks to commit, write a commit message,
         or prepare changes for commit"

Some tools support explicit triggers as slash commands (/commit). If yours does, use that — it is unambiguous and discoverable.

Keep the trigger focused. This skill writes commit messages. It does not stage files, resolve conflicts, or push to remote. Those are separate workflows.

Step 4: Write the Prompt

Start with the steps you documented, then add precision:

## Workflow

1. Run git status to see all modified and untracked files
2. Run git diff to see staged and unstaged changes
3. Run git log (last 5 commits) to match this repo's commit style
4. Analyze the changes and determine:
   - Type: feat, fix, refactor, docs, test, chore, style, perf
   - Scope: which component or area was affected
   - What changed (the "what")
   - Why it changed (the "why" — from context, PR description, or user input)
5. Draft a commit message following Conventional Commits format

## Rules

- Subject line: imperative mood, lowercase, no period, under 72 characters
- Body: explain "why" not "what" (the diff shows the what)
- Do not commit files that contain secrets (.env, credentials, API keys)
- If changes span multiple concerns, suggest splitting into separate commits
- Match the style and conventions of recent commits in the repository
- Use a HEREDOC for the commit message to preserve formatting

Notice what the rules prevent:

• “update stuff” commits (the type and scope force specificity)
• Accidental secret commits (explicit file check)
• Sprawling commits (suggestion to split)
• Style inconsistency (match recent commits)

Step 5: Add References

A commit message skill is relatively self-contained, but references still help:

references:
  - conventional-commits.md  # Format specification and type definitions

If your team has specific commit conventions beyond Conventional Commits — required ticket numbers, specific scope names, emoji prefixes — put them in a reference document rather than bloating the prompt.

For a more complex skill like code review, the references carry more weight. The review skill references your coding standards, security checklist, and performance guidelines. Without those references, the skill reviews against generic best practices instead of your team’s actual standards.

Step 6: Define the Output

## Output

A git commit command ready to execute:

git commit -m "$(cat <<'EOF'
type(scope): subject line under 72 characters

Body explaining why this change was made. Reference issues
if applicable.
EOF
)"

The output contract here is minimal because the output format is well-defined (a commit message). For skills with richer output — like code review or documentation — the output contract needs more structure.

Step 7: Assemble and Test

Here is the complete skill:

name: commit
description: "Create well-structured commit messages by analyzing
              staged changes and matching repository conventions"

trigger: "When the user asks to commit or create a commit message"

prompt: |
  ## Workflow
  1. Run git status to see all modified and untracked files
  2. Run git diff to see staged and unstaged changes
  3. Run git log (last 5 commits) to match this repo's commit style
  4. Analyze changes: type, scope, what changed, why
  5. Draft a commit message in Conventional Commits format

  ## Rules
  - Subject: imperative mood, lowercase, no period, under 72 chars
  - Body: explain "why" not "what"
  - Do not commit files containing secrets
  - Suggest splitting if changes span multiple concerns
  - Match recent commit style in the repository

references:
  - conventional-commits.md

output: |
  A ready-to-execute git commit command with HEREDOC formatting

Now test it. Make a real change to your project and invoke the skill instead of writing the commit message yourself. Evaluate the result against what you would have written manually.

Step 8: Iterate from Real Usage

Your first version will have gaps. That is expected. Here is how to iterate:

Collect failure modes

After using the skill ten times, you will notice patterns:

• “It keeps suggesting chore when I mean refactor” → Clarify type definitions in the reference
• “It writes body text for trivial one-line changes” → Add a rule: “Skip body for single-file, single-concern changes under 10 lines”
• “It does not mention the issue number” → Add a rule: “If the branch name contains an issue number, include it as Refs #NNN”

Add rules from failures

Every failure is a missing rule. But resist the urge to add rules preemptively. Only add rules that address problems you have actually encountered. A skill with thirty rules is harder to maintain and more likely to have contradictions than one with ten precise rules.

Test edge cases

Run the skill against different types of changes:

• A single typo fix (should produce a minimal message)
• A large feature addition (should suggest splitting if it touches many files)
• A dependency update (should mention what was updated and why)
• A revert (should reference the original commit)

Each edge case either confirms the skill handles it or reveals a gap to fill.

A Second Example: PR Description Skill

To reinforce the pattern, here is another common workflow extracted into a skill:

name: pr-description
description: "Write structured PR descriptions with summary,
              changes, test plan, and review notes"

trigger: "When the user asks to create a PR or write a PR description"

prompt: |
  ## Workflow
  1. Run git log to see all commits on this branch vs main
  2. Run git diff main...HEAD to see the full changeset
  3. Check if the branch tracks a remote (need to push?)
  4. Analyze all commits — not just the latest, ALL of them
  5. Draft a PR title (under 70 chars) and description

  ## Rules
  - Title: short, descriptive, no prefix needed
  - Summary: 1-3 bullet points explaining what and why
  - Test plan: bulleted checklist of verification steps
  - Do not include implementation details in the title
  - If there are uncommitted changes, warn before proceeding

output: |
  ## Summary
  <1-3 bullet points>

  ## Test plan
  - [ ] Verification step 1
  - [ ] Verification step 2
  - [ ] ...

Same structure, different workflow. The pattern holds: trigger, prompt with workflow steps and rules, references if needed, output contract.

When Not to Build a Skill

Not everything should be a skill. Avoid building skills for:

• One-off tasks. If you will never do it again, a regular prompt is fine.
• Tasks that require deep judgment. Architecture decisions, hiring evaluations, strategic planning — these need human reasoning, not repeatable workflows.
• Rapidly changing processes. If the workflow changes weekly, the skill maintenance cost exceeds its value. Wait until the process stabilizes.
• Tasks the AI does well without help. If “explain this error” consistently produces good results with zero structure, adding a skill adds overhead without improving quality.

The sweet spot is workflows that are repeatable, teachable, and currently inconsistent. That is where skills deliver the most value.

Your Assignment

Pick one workflow from your daily routine. Write the skill definition using the four-component structure:

1. Trigger — when does it activate?
2. Prompt — what are the steps and rules?
3. References — what documents does it need?
4. Output — what should the result look like?

Use it for a week. Keep a list of every time the output was not quite right. After a week, add rules to address the top three failure modes.

In Part 5, we go beyond single skills: composing multiple skills together, delegation patterns, and automation that runs without you typing anything.