The Problem

AI coding agents produce inconsistent output because they lack the operational knowledge senior engineers apply automatically: when to write a test, how to structure a review, what "done" means. This repo encodes those workflows as machine-readable skill definitions so agents follow the same quality gates across the entire development lifecycle, from spec through ship.

What This Does

The repository contains 24 skills under skills/, each a SKILL.md file defining a workflow (e.g., test-driven-development, code-review-and-quality, security-and-hardening). Eight slash commands in commands/ map to lifecycle phases—/spec, /plan, /build, /test, /review, /webperf, /code-simplify, /ship—and each command activates the relevant skills automatically. A hooks/ directory provides shell scripts for session-start and cache-management behavior.

The evals/ directory is the quality layer: 42 test files and 18 evaluation cases with JSON fixtures that verify skills actually work. The scripts/ directory contains the validation tooling (validate-skills.js, run-evals.js) that lints skill definitions and runs the evaluation suite.

How It Is Wired

Execution starts in scripts/run-evals.js, which imports scripts/lib/skill-lint.js and scripts/validate-skills.js. The import graph is shallow—12 internal modules, only 2 import edges, no circular dependencies—so the tooling is straightforward to extend. skill-lint.js carries the widest blast radius: 1 module imports it, and it validates every skill definition, so a change there affects all skills.

The hooks/ scripts (sdd-cache-pre.sh, sdd-cache-post.sh, simplify-ignore.sh) run as shell hooks, not through the JavaScript pipeline. They handle filesystem state—caching and ignore-pattern management—and are the only components touching the system outside the repo. The evals/fixtures/ directory contains standalone test fixtures (Express servers, HTML pages, Node apps) that evaluation cases exercise.

The commands/*.toml files are the agent-facing entry points; each defines a slash command that maps to skill files. The .claude/, .gemini/, and .opencode/ directories contain agent-specific command definitions, letting the same skills work across Claude Code, Gemini CLI, and OpenCode.

How To Use It

Setup: Install via the skills CLI (per README):

npx skills add addyosmani/agent-skills            # install all 24 skills
npx skills add addyosmani/agent-skills --skill test-driven-development

For Claude Code native integration:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

Configuration: No environment variables required. Skills are Markdown files; the references/ directory holds shared checklists that skills reference by path.

Running it: Invoke a slash command in your agent, e.g., /spec to start the specification workflow. The validation tooling runs via scripts/run-evals.js and scripts/validate-skills.js.

Real-World Use

A team using Claude Code adopts this repo to enforce consistent engineering practice. When a developer types /build, the agent loads skills/incremental-implementation/SKILL.md, which mandates one atomic task at a time, test-driven, with a commit per task. The /review command loads skills/code-review-and-quality/SKILL.md, which applies a five-axis review (correctness, security, performance, maintainability, testing) before merge. The evals/ suite runs in CI to verify each skill's instructions still produce correct behavior on the fixture projects.

Code Health & Issues

Static analysis (not opinion) found 6 issues across 2 kinds:

  • High - Duplicated code blocks: 24 repeated 6-line blocks across 12 files, including skills/idea-refine/scripts/idea-refine.sh and hooks/sdd-cache-pre.sh. Extract shared helpers.
  • Medium - High branching density (5 instances): scripts/run-evals.js has 192 branch points over 478 lines. Decompose decision-heavy logic.

Repository hygiene: tests present (42 files), CI configured (GitHub Actions), no lockfile, no committed secrets, license present.

SDLC observations from the file structure:

  • High - CI never runs the test suite: 16 test files exist, but no workflow invokes them. A green check that never executed an assertion is misleading.
  • Medium - GITHUB_TOKEN permissions undeclared: test-plugin-install.yml inherits repository defaults; add permissions: contents: read.
  • Medium - Checkout persists credentials: test-plugin-install.yml doesn't set persist-credentials: false, leaving the token in .git/config for later steps.
  • Low - No job timeouts: test-plugin-install.yml jobs run to the six-hour platform default.

The Bottom Line

A well-structured skills library with real validation tooling and an evaluation suite—more engineering rigor than most agent-prompt repos. The CI gaps are fixable in an afternoon. Teams standardizing agent behavior across Claude Code, Gemini, and OpenCode will get the most value; the duplicated shell logic and un-executed tests are the main debt to clear.