A hands-on tutorial series for building agent skills — reusable instructions that teach AI coding agents how to do specific tasks well.
Learn Agent Skills teaches you how to build agent skills from scratch. Skills are reusable instructions that teach AI coding agents (GitHub Copilot, Claude Code, Cursor, and others) how to perform specific tasks well. Follow the tutorials in order and build a fully working README Wizard skill by the end.
Clone the repo and start with Tutorial 1:
git clone https://github.com/debs-obrien/learn-agent-skills.git
cd learn-agent-skillsOpen it in VS Code (or your preferred editor with an AI agent) and follow the tutorials in order.
Use this repository as the guide and reference implementation, but do the hands-on exercises in a separate practice project.
- Clone this repo and keep it open for the tutorial instructions.
- Create a second folder or repo for the exercises, for example
readme-wizard-lab. - Build your own skill in that practice project.
- Compare your work against the finished reference skill in
.agents/skills/readme-wizard/only when you need to check your structure or debug a step.
Each step gives you a prompt to copy — paste it into your AI agent (GitHub Copilot, Claude Code, Cursor, etc.) and let the agent do the work. That's the whole point: you're learning to work with your agent.
Claude Code users: Use
.claude/skills/instead of.agents/skills/for your skill folders.
Important: Don't build the README Wizard directly inside this repo. This repo already contains a finished version for reference.
| # | Tutorial | What you'll learn |
|---|---|---|
| 1 | Build Your First Skill | What skills are, how they work, and build a simple one |
| 2 | Anatomy of a Skill | The folder structure, how skills get loaded, and progressive disclosure |
| 3 | Build the README Wizard — Phase 1 | Set up a practice project, create the skill folder, write a basic SKILL.md, and test it |
| 4 | Build the README Wizard — Phase 2 | Add detail: badges, best practices, templates, and diagrams |
| 5 | Build the README Wizard — Phase 3 | Refactor into the skill folder structure with references, assets, and scripts |
| 6 | Build the README Wizard — Phase 4 | Add validation, evals, and test end-to-end |
| 7 | Share Your Skill | Push to GitHub and install with the skills CLI |
learn-agent-skills/
├── .agents/
│ └── skills/
│ ├── good-morning/ # Example skill from Tutorial 1
│ │ └── SKILL.md
│ └── readme-wizard/ # README Wizard skill (Tutorials 3-6)
│ ├── SKILL.md
│ ├── scripts/
│ │ └── scan_project.sh
│ ├── references/
│ │ └── readme-best-practices.md
│ ├── assets/
│ │ ├── badges.json
│ │ ├── readme-template.md
│ │ └── diagrams.md
│ └── evals/
│ └── evals.json
├── assets/ # Images used in the tutorials
├── .gitignore
├── 01_build-first-agent-skill.md # Tutorial 1: What skills are
├── 02_skill-deep-dive.md # Tutorial 2: Anatomy of a skill
├── 03_build-readme-wizard-skill-part_1.md # Tutorial 3: Phase 1 — Get it working
├── 04_build-readme-wizard-skill-part_2.md # Tutorial 4: Phase 2 — Add detail
├── 05_build-readme-wizard-skill-part_3.md # Tutorial 5: Phase 3 — Refactor
├── 06_build-readme-wizard-skill-part_4.md # Tutorial 6: Phase 4 — Validate
├── 07_share-your-skill.md # Tutorial 7: Share it
├── CLAUDE.md
├── LICENSE
└── README.md
- An AI coding agent: GitHub Copilot, Claude Code, Cursor, or any skills-compatible agent
- A practice project: create a fresh folder or repo where you'll build the skill during the tutorials
- A project to test against: your practice project, your own repo, or any public repo you can clone
Once you've built the README Wizard (or if you just want to try it), you can use it on any project.
Install the finished skill:
npx skills add debs-obrien/readme-wizardThen open any project and copy this prompt:
Improve the README for this project using the readme-wizard skill.
That's it. The agent will scan the project, read the best practices, pick the right badges, and generate a polished README.
Works with remote repos too. Clone any GitHub repo and run it:
git clone https://github.com/OWNER/REPO.git
cd REPOImprove the README for this project using the readme-wizard skill.
Or be more specific:
Improve the README for this project. Run the scan script first to detect the project metadata, then follow the readme-wizard skill instructions. Make sure to include badges, a quick start section, and a project structure tree.
Contributions are welcome. Open an issue or submit a pull request.
MIT License — see LICENSE for details.