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.

Quick Start

Clone the repo and start with Tutorial 1:

git clone https://github.com/debs-obrien/learn-agent-skills.git
cd learn-agent-skills

Open it in VS Code (or your preferred editor with an AI agent) and follow the tutorials in order.

Recommended Workflow

Use this repository as the guide and reference implementation, but do the hands-on exercises in a separate practice project.

1. Clone this repo and keep it open for the tutorial instructions.
2. Create a second folder or repo for the exercises, for example readme-wizard-lab.
3. Build your own skill in that practice project.
4. 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.

How to Follow This Tutorial

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.

undefinedClaude Code users: Use .claude/skills/ instead of .agents/skills/ for your skill folders.

undefinedImportant: Don’t build the README Wizard directly inside this repo. This repo already contains a finished version for reference.

Tutorials

#	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

Project Structure

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

Prerequisites

• undefinedAn AI coding agent: GitHub Copilot, Claude Code, Cursor, or any skills-compatible agent
• undefinedA practice project: create a fresh folder or repo where you’ll build the skill during the tutorials
• undefinedA project to test against: your practice project, your own repo, or any public repo you can clone

Use the skill on any project

Once you’ve built the README Wizard (or if you just want to try it), you can use it on any project.

undefinedInstall the finished skill:undefined

npx skills add debs-obrien/readme-wizard

undefinedThen open any project and copy this prompt:undefined

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.

undefinedWorks with remote repos too. Clone any GitHub repo and run it:

git clone https://github.com/OWNER/REPO.git
cd REPO

Improve the README for this project using the readme-wizard skill.

undefinedOr be more specific:undefined

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.

Contributing

Contributions are welcome. Open an issue or submit a pull request.

License

MIT License — see LICENSE for details.

---