agentleFS
debs-obriendebs-obrien/learn-agent-skills/CLAUDE.md

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…

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
  1. Very specific:

    Claude Code users: use .claude/skills/ instead of .agents/skills/ — this distinction is noted throughout the tutorials.

    line 23
  2. Very specific:

    Commit messages: use conventional-style prefixes (e.g., refactor:, fix:).

    line 25
  3. Very specific:

    Test cases live in .agents/skills/readme-wizard/evals/evals.json — 4 scenarios with human-readable assertions.

    line 36

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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_*.md through 07_*.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 for scripts/, references/, assets/, and evals/.
  • 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 with name and description fields. The folder name must match the name: 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.