If you're new to agent skills, start with my beginner guide first: What Are Agent Skills? Beginners Guide That post covers what skills are, how they get loaded, and how to build a tiny one from scratch. This post picks up where that one stops. Instead of another tiny example, I want to show you what a practical skill looks like when it solves a real problem. We are going to take the idea of a skill and use it to turn rough project READMEs into polished docs that are consistent, accurate, and reusable across repos. I picked README generation because the output is easy to judge, it comes up again and again, and once you get it right for one project you want the same quality bar everywhere. The problem with one-off README prompts You can absolutely ask an agent to improve your README and get something decent back. Sometimes it will even be very good. But if you do that across multiple projects, the cracks show up quickly: badge styles are inconsistent section order changes from repo to repo install commands drift away from the actual package manager social links get guessed simple projects end up with bloated READMEs the agent repeats the same repo-scanning work every time That is exactly the kind of problem skills are good at solving. Not because they magically make the model smarter, but because they turn a vague prompt into a reusable workflow. The first version was just one file I did not start with a big architecture. The first version of readme-wizard was just a single SKILL.md with instructions telling the agent to: detect the project name, description, license, git remote, package manager, and CI setup add a better structure to the README use shields.io badges include a Quick Start section with real commands show a project structure tree add contributor avatars, documentation links, and optional social badges That first version worked. And that matters. One of the easiest mistakes to make with agent workflows is over-engineering too early. A single file is often enough to prove whether the workflow is useful before you invest more time into it. Here is the important part: start with the smallest thing that can produce a useful result on a real project. What broke in practice Once I started testing the skill on real repos, the limitations showed up quickly. The main issue was not that the agent could not write a README. It could. The issue was consistency. The single-file version was asking the SKILL.md to do too many jobs at once: writing guidance badge formats project-type adaptation rules README structure templates Mermaid diagram templates instructions for how to detect project metadata That creates a few problems. First, the file gets bloated fast. By the time I had all those rules and templates inline, it was over 150 lines and hard to maintain. Second, the agent had to figure out how to inspect the repo on every single run. There was no scanning script yet — just instructions saying "detect the package manager, find the license, parse the git remote." The agent would improvise that detection work each time. Sometimes it got it right. Sometimes it missed a CI workflow file, guessed at the wrong package manager, or invented social links that did not exist. Third, all of that detection reasoning burned tokens and produced inconsistent results. The kind of work that should be boring and repeatable was instead fuzzy and error-prone. The turning point: treat the skill like a workflow, not a prompt That was the point where the skill stopped being just a better prompt and started becoming a real workflow. The structure ended up looking like this: .agents/skills/readme-wizard/ ├── SKILL.md ├── scripts/ │ └── scan_project.sh ├── references/ │ └── readme-best-practices.md ├── assets/ │ ├── badges.json │ ├── diagrams.md │ └── readme-template.md └── evals/ └── evals.json Every part has a different job. And that is the point. SKILL.md became the orchestrator Instead of being one giant wall of instructions, SKILL.md became the thin coordinator. Its job is to define the workflow: run the scan script read the README best-practices guide build from the template pull badge formats from the badge catalog validate against the eval assertions only load diagram templates if the project actually needs them That is a much better use of the main skill file. It keeps the top-level instructions focused on sequence and judgment instead of burying everything in one place. Here is what the workflow section of the final SKILL.md looks like: ## Workflow ### 1. Scan the project Run `scripts/scan_project.sh ` to collect structured JSON metadata. ### 2. Read the best practices guide Read `references/readme-best-practices.md` before writing. ### 3. Build the README Use `assets/readme-template.md` as the base structure. Replace PLACEHOLDER markers with actual project data from t