Deep Dive: How addyosmani/agent-skills Turns Engineering Discipline into Skills

Companion to the hands-on tutorial: Install and use addyosmani/agent-skills on Cui.Guru. The tutorial shows how to use it. This post explains why it is built this way.

addyosmani/agent-skills (about 116.8k stars per the GitHub API on 2026-11-13, MIT licensed) describes itself as “Production-grade engineering skills for AI coding agents”. The README’s pitch: skills “encode the workflows, quality gates, and best practices that senior engineers use”, packaged so agents follow them “consistently across every phase of development”.

The workflow in motion

Architecture

The repo has a few top-level directories: skills/ (25 skills), commands/ (9 TOML slash commands), agents/ (4 personas), hooks/, references/ (shared checklists) and evals/. AGENTS.md names three composable layers: skills are the “how”, personas the “who”, slash commands the “when”.

The core design idea

Skills are workflows, not advice. The meta-skill using-agent-skills says it plainly: “Skills are workflows, not suggestions. Follow the steps in order. Don’t skip verification steps.” CONTRIBUTING.md recommends an anatomy for each skill: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification. The two unusual sections are the ones aimed at the agent’s own excuses. From skills/test-driven-development/SKILL.md:

| Rationalization | Reality |
|---|---|
| "I'll write tests after the code works" | You won't. And tests written after the fact test implementation, not behavior. |
| "This is too simple to test" | Simple code gets complicated. The test documents the expected behavior. |

The lifecycle skills end with a Verification checklist, and the meta-skill (using-agent-skills) states the project-wide rule: “A task is not complete until verification passes. ‘Seems right’ is never sufficient.”

Commands are thin entry points

A command is a short TOML file with a description and a prompt. commands/build.toml begins:

description = "Implement tasks incrementally — build, test, verify, commit. Add \"auto\" to run the whole plan in one approved pass."

prompt = """
Invoke the incremental-implementation skill alongside test-driven-development.

The default mode implements one task (failing test, minimal code, full suite, build, commit) and stops. /build auto requires an existing spec, one approval of the plan, then runs every task with the same loop, one commit per task. It stops for failing tests, ambiguous specs or irreversible steps. The prompt notes that autonomous mode “is not faster per task”: it only removes the human stepping between tasks.

Personas fan out, but never nest

AGENTS.md sets the rule: “the user (or a slash command) is the orchestrator. Personas do not invoke other personas.” The only multi-persona pattern it endorses is parallel fan-out with a merge step, used by /ship (commands/ship.toml): code-reviewer, security-auditor and test-engineer run concurrently, with all three subagent calls “in a single assistant turn”, and their reports merge into a go/no-go decision with a rollback plan. The code-reviewer persona reviews across five axes: correctness, readability, architecture, security, performance.

Skills are tested too

evals/README.md describes three tiers. Tier 1 is structural validation in CI (frontmatter, required sections, reference links, command parity). Tier 2 is a deterministic routing check: a stemmed TF-IDF over skill descriptions, so positive prompts must rank their skill and no two descriptions should collide; the README calls it “a lexical approximation of routing”. Tier 3 is behavioral, run on demand through headless claude and graded against expectations[]. CONTRIBUTING.md requires every new skill to ship an evals/cases/<skill-name>.json.

Hooks are optional

hooks/session-start.sh can inject the meta-skill into a new session, emitting the standard SessionStart JSON envelope via jq. Its own header says the plugin does not wire it, because hosts such as Claude Code and Codex CLI already route skills from descriptions and a second router would duplicate the native one.

Takeaways

• A skill is a process with exit criteria; the Verification checklist is what makes it more than a prompt.
• Writing down the agent’s likely rationalizations, with rebuttals, is a cheap guardrail.
• Keep orchestration flat: commands orchestrate, personas report, skills hold the steps.
• Treat skill descriptions as an API surface and test their routing in CI.
• Per the README, a single-skill npx install does not copy the repo-level references/ folder, so install the whole repo if skills link to shared checklists.

Want a skills-driven engineering workflow set up for your team? Talk to Cui.Guru.