learn-agent-skills
CLAUDE.md46 starsChanged 8 months agoMITView on GitHub
A hands-on tutorial series for building agent skills — reusable instruction sets that teach AI coding agents (GitHub Copilot, Claude Code, Cursor, etc.) how to perform specific tasks. Learners follow 7 sequential tutorials to build a "README Wizard" skill that generates polished README files for any project. This is a documentation-only repository — no application code, no build system, no test framework. Content is Markdown tutorials and Bash scripts. Scan a project for metadata (outputs JSON): Test cases live in…
In this repository2 other files it gives its agents.
- good-morningSkill
- readme-wizardSkill
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Claude Code users: use .claude/skills/ instead of .agents/skills/ — this distinction is noted throughout the tutorials.
- Very specific: line 25
Commit messages: use conventional-style prefixes (e.g., refactor:, fix:).
- Very specific: line 36
Test cases live in .agents/skills/readme-wizard/evals/evals.json — 4 scenarios with human-readable assertions.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
What This Repository Is
A hands-on tutorial series for building agent skills — reusable instruction sets that teach AI coding agents (GitHub Copilot, Claude Code, Cursor, etc.) how to perform specific tasks. Learners follow 7 sequential tutorials to build a "README Wizard" skill that generates polished README files for any project.
This is a documentation-only repository — no application code, no build system, no test framework. Content is Markdown tutorials and Bash scripts.
Repository Structure
- Tutorials (
01_*.mdthrough07_*.md): Sequential lessons meant to be followed in order. Each contains prompts for learners to paste into their AI agent. .agents/skills/: Contains finished reference implementations of skills built in the tutorials (Copilot/cross-agent path)..agents/skills/readme-wizard/: The main skill built across Tutorials 3-6, with sub-folders forscripts/,references/,assets/, andevals/.assets/: Images used within the tutorial Markdown files.readme-wizard-workspace/: Gitignored directory for skill optimization/eval artifacts.
Key Conventions
- Skill folder structure follows the Agent Skills open standard:
SKILL.md(instructions + YAML frontmatter),scripts/(deterministic shell work),references/(domain knowledge),assets/(data/templates),evals/(test cases). - SKILL.md frontmatter: YAML between
---markers withnameanddescriptionfields. The folder name must match thename:field exactly. - Claude Code users use
.claude/skills/instead of.agents/skills/— this distinction is noted throughout the tutorials. - Shell scripts (
scan_project.sh) must be executable (chmod +x). - Commit messages use conventional-style prefixes (e.g.,
refactor:,fix:).
Running the Scripts
Scan a project for metadata (outputs JSON):
bash .agents/skills/readme-wizard/scripts/scan_project.sh <project-directory>Evals
Test cases live in .agents/skills/readme-wizard/evals/evals.json — 4 scenarios with human-readable assertions. There is no automated test runner; evals are validated manually or by an AI agent checking assertions against generated output.
Tutorial Format
Each tutorial follows a consistent structure: success check at top, prerequisites checklist, step-by-step instructions with "Copy this prompt" code blocks, troubleshooting section, and "Next Steps" link to the next tutorial.
Skills CLI
Skills can be installed with npx skills add <owner>/<skill-name> and discovered at skills.sh.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

