Curious Human
Lessons from building skill templates for Claude Code and GitHub Copilot
Writing effective instructions for AI coding agents is its own design discipline. After building and iterating on several skill templates for Claude Code and GitHub Copilot I've landed on a set of patterns that meaningfully change how agents behave. Not tweaks. Structural differences in output quality, reliability, and workflow coherence.
Here's what I've learned along the way.
A skill is a markdown file with YAML frontmatter that defines a reusable workflow an agent can execute. You can view the spec here. They can be very simple but also can create more defined patterns of interaction such that they become a prompt and more like a runbook: structured instructions that guide an agent through a multi-step process with clear inputs, outputs, and decision points.
---
name: architect
description: Creates technical implementation plans for GitHub Issues...
allowed-tools: Read, Glob, Grep, Write, Bash, EnterPlanMode, mcp__github__*
---
# Technical Architecture Workflow
Create a technical implementation plan for a GitHub Issue.The allowed-tools field scopes what the agent can do. The description determines when the skill gets invoked. The body defines how the work gets done. Each of these surfaces has its own design considerations.
Early versions of my skill descriptions used imperative phrasing: "Create a technical implementation plan." This works, but it underperforms for discoverability. When an agent searches for available skills based on a user's natural language request, third-person present-tense descriptions match better.
Before:
Create a technical implementation plan for a GitHub Issue.After:
Creates technical implementation plans for GitHub Issues by exploring the
codebase, designing phased approaches, and opening draft PRs. Use when the
user wants to plan, architect, or design the implementation for a spec'd issue.The "Use when..." suffix is the key addition. It encodes the trigger conditions — the natural language phrases a user might say that should activate this skill. "I want to plan this issue." "Let's architect the solution." "Can you design the implementation?" All of these now match. This is especially important when writing skills for GitHub Copilot, because their UX in local development doesn't support slash activation ("/myskill") the way Claude Code does.
This is keyword engineering. You're writing for a retrieval system, not a human reader.
A high impact pattern I have found is adding progress checklists to complex skills. Several of my skills have workflows longer than six steps. Without explicit tracking, agents lose their place. They skip steps. They repeat work. They hallucinate completion.
A progress checklist looks like this:
## Progress Tracking
Copy this checklist to track your progress:
- [ ] Step 1: Select issue
- [ ] Step 2: Validate specification
- [ ] Step 3: Claim issue
- [ ] Step 4: Create branch, placeholder plan, and draft PR
- [ ] Step 5: Explore the codebase
- [ ] Step 6: Enter plan mode and design implementation
- [ ] Step 7: Update plan file with actual content
- [ ] Step 8: Present plan for approval
- [ ] Step 9: FinalizeIt's not complex. It's a markdown checklist at the top of the file. But it gives the agent a concrete state-tracking mechanism across conversation turns. Without it, you're relying on the agent's working memory to recall where it is in a nine-step proces, and that fails more often than you'd expect.
Two of my skills include explicit feedback loop instructions:
**Feedback loop:** If any verification step fails, attempt to fix the
issue and re-run verification before proceeding. Only checkpoint when
all gates pass.Without this, agents treat verification as a read-only observation. Tests fail? Note it in the output and move on. Linter complains? Log the warning. The feedback loop instruction converts passive observation into active correction: fail, fix, re-verify, proceed.
This is the difference between an agent that reports test failures and one that fixes them.
Early skill files were long. This has two problems: it burns tokens on every invocation, and it makes the skill file harder to read and maintain.
The fix is resource files — separate markdown documents that live alongside the skill:
skills/architect/
├── SKILL.md
└── resources/
├── plan-template.md
└── session-template.mdThe skill references them:
### Step 1: Create the plan
- See [resources/plan-template.md](resources/plan-template.md)
for the full plan formatThe agent reads the resource file only when it reaches that step, not at skill load time. This is lazy loading for agent instructions.
Every skill that touches git or GitHub includes explicit approval gates:
**Ask the user for permission before committing:**
- "Ready to commit these changes? [Yes / No / Show diff]"This isn't about safety theater. It's about maintaining user agency in agentic workflows. An agent that pushes code without asking is an agent that gets its permissions revoked. An agent that pauses at the right moments builds trust — and trust is what lets you give it more autonomy over time. Figuring out the right balance here between productive and annoying constant asking is not alway easy, more art than science, but refining these workflows makes a big difference in having maintainable harnesses for development.
If you're building complex skills for AI coding agents, start with the workflow. Get the steps right. Get the order right. Add gates where things can go wrong. Add checklists where things are complex. Then write the instructions.