agent-skills-framework

# Agent Skills Framework > Skill by [ara.so](https://ara.so) — AI Agent Skills collection. A comprehensive framework of 23 production-grade engineering skills that guide AI coding agents through the complete software development lifecycle. Skills encode workflows, quality gates, and best practices that senior engineers use, packaged for consistent agent execution. ## What It Does Agent Skills provides: - **7 slash commands** mapping to development phases (`/spec`, `/plan`, `/build`, `/test`, `/review`, `/code-simplify`, `/ship`) - **23 structured workflows** covering everything from idea refinement to production deployment - **Auto-activation** based on context (API design triggers `api-and-interface-design`, UI work triggers `frontend-ui-engineering`) - **Quality gates** with verification steps, anti-rationalization tables, and "STOP" conditions - **Agent personas** for specialized reviews (code-reviewer, test-engineer, security-auditor) - **Reference checklists** for testing, security, performance, and accessibility ## Installation ### Claude Code (Recommended) **Via Marketplace:** ```bash /plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills ``` **If SSH fails, use HTTPS:** ```bash /plugin marketplace add https://github.com/addyosmani/agent-skills.git /plugin install agent-skills@addy-agent-skills ``` **Local Development:** ```bash git clone https://github.com/addyosmani/agent-skills.git claude --plugin-dir /path/to/agent-skills ``` ### Cursor Copy individual `SKILL.md` files or the entire `skills/` directory into `.cursor/rules/`: ```bash # Clone the repo git clone https://github.com/addyosmani/agent-skills.git # Copy all skills cp -r agent-skills/skills/* .cursor/rules/ # Or copy specific skills cp agent-skills/skills/spec-driven-development/SKILL.md .cursor/rules/ ``` ### Gemini CLI **Install from GitHub:** ```bash gemini skills install https://github.com/addyosmani/agent-skills.git --path skills ``` **Install from local clone:** ```bash git clone https://github.com/addyosmani/agent-skills.git gemini skills install ./agent-skills/skills/ ``` ### Windsurf Add skill contents to `.windsurf/rules.md`: ```bash # Append skills to your rules file cat agent-skills/skills/*/SKILL.md >> .windsurf/rules.md ``` ### OpenCode Uses `AGENTS.md` and the `skill` tool for agent-driven execution: ```bash # Copy the agents configuration cp agent-skills/AGENTS.md . # Skills auto-discovered from skills/ directory ``` ### GitHub Copilot Use agent personas as Copilot personas and add skills to `.github/copilot-instructions.md`: ```bash # Copy agent definitions cp agent-skills/agents/* .github/copilot-agents/ # Add skill content cat agent-skills/skills/*/SKILL.md >> .github/copilot-instructions.md ``` ### Kiro IDE & CLI Skills stored under `.kiro/skills/` at project or global level: ```bash # Copy to project-level skills mkdir -p .kiro/skills cp -r agent-skills/skills/* .kiro/skills/ ``` ### Any Other Agent Skills are plain Markdown. Copy to your agent's instruction/context directory: ```bash # Generic approach cp -r agent-skills/skills/ /path/to/your/agent/context/ ``` ## Core Commands ### `/spec` - Spec Before Code Define what to build before writing code. Activates `spec-driven-development`: ```markdown /spec I need to build a URL shortener API with rate limiting ``` **Output:** PRD covering objectives, commands, structure, code style, testing strategy, and boundaries. ### `/plan` - Small, Atomic Tasks Break specs into implementable units. Activates `planning-and-task-breakdown`: ```markdown /plan Break down the URL shortener spec into tasks ``` **Output:** Ordered tasks with acceptance criteria, dependencies, and size estimates. ### `/build` - One Slice at a Time Implement incrementally with feature flags and safe defaults. Activates `incremental-implementation`: ```markdown /build Implement task #1: URL shortening endpoint ``` **Output:** Code + tests for one thin vertical slice, with feature flag wrapper. ### `/test` - Tests Are Proof Red-Green-Refactor TDD cycle. Activates `test-driven-development`: ```markdown /test Write tests for URL validation logic ``` **Output:** Test file following test pyramid (80% unit, 15% integration, 5% E2E). ### `/review` - Improve Code Health Five-axis code review with severity labels. Activates `code-review-and-quality`: ```markdown /review Review the URL shortener PR ``` **Output:** Structured feedback on correctness, maintainability, security, performance, testing. ### `/code-simplify` - Clarity Over Cleverness Reduce complexity while preserving behavior. Activates `code-simplification`: ```markdown /code-simplify Simplify the rate limiting middleware ``` **Output:** Refactored code with change justification and test confirmation. ### `/ship` - Faster Is Safer Pre-launch checklist and staged rollout. Activates `shipping-and-launch`: ```markdown /ship Prepare URL shortener for production ``` **Output:** Deployment plan, monitoring setup, rollback procedure, feature flag lifecycle. ## Key Skills Reference ### Meta: Discover Which Skill Applies **`using-agent-skills`** - Maps incoming work to the right skill: ```markdown User: "I want to add authentication to my app" Agent (activates using-agent-skills): → Detects: unclear spec + security concern → Activates: interview-me → spec-driven-development → security-and-hardening ``` ### Define Phase **`interview-me`** - One-question-at-a-time extraction until ~95% confidence: ```markdown Trigger: "interview me about the auth feature" Agent: Q1: What authentication method? (OAuth, JWT, sessions, magic links) [waits for answer] Q2: Which providers? (Google, GitHub, email, all three) [continues until clear] ``` **`spec-driven-development`** - PRD before code: ```markdown Activates when: Starting new project/feature Output structure: ## Objectives - User needs - Success criteria ## Commands & Usage - CLI/API surface ## Structure - File organization - Module boundaries ## Code Style & Patterns - Framework decisions - State management ## Testing Strategy - Coverage targets - Test types ## Boundaries & Constraints - What's in/out of scope ``` ### Plan Phase **`planning-and-task-breakdown`** - Decompose specs into tasks: ```markdown Input: PRD for URL shortener Output: Task 1: URL shortening endpoint Acceptance: POST /shorten returns short code Size: Small (~50 lines) Depends on: none Task 2: Redirect handler Acceptance: GET /:code redirects to original URL Size: Small (~30 lines) Depends on: Task 1 Task 3: Rate limiting middleware Acceptance: 429 after 100 req/min Size: Medium (~100 lines) Depends on: Task 1 ``` ### Build Phase **`incremental-implementation`** - Thin vertical slices: ```bash # Pattern for each task 1. Feature flag wrapper (if multi-step) 2. Minimal implementation 3. Tests (Red-Green-Refactor) 4. Verify locally 5. Atomic commit 6. Move to next slice ``` **Example commit sequence:** ```bash git commit -m "feat: Add URL shortening endpoint - POST /shorten accepts URL, returns short code - Feature flag: ENABLE_URL_SHORTENER (default: true) - Tests: valid URL, invalid URL, duplicate URL - Safe default: returns 503 if feature disabled" git commit -m "feat: Add redirect handler - GET /:code redirects to original URL - 404 for unknown codes - Tests: valid code, invalid code, expired code" ``` **`test-driven-development`** - Red-Green-Refactor: ```javascript // Step 1: RED - Write failing test describe('URL shortener', () => { test('generates unique short codes', () => { const code1 = generateShortCode('https://example.com'); const code2 = generateShortCode('https://example.com'); expect(code1).toHaveLength(6); expect(code2).toHaveLength(6); expect(code1).not.toBe(code2); // ❌ FAILS - not implemented }); }); // Step 2: GREEN - Minimal implementation function generateShortCode(url) { return crypto.randomBytes(3).toString('base64url'); } // ✅ PASSES // Step 3: REFACTOR - Improve without breaking function generateShortCode(url) { const hash = crypto.createHash('sha256').update(url).digest(); const timestamp = Date.now().toString(36); return (hash.toString('base64url') + timestamp).slice(0, 6); } // ✅ STILL PASSES ``` **`source-driven-development`** - Ground decisions in official docs: ```markdown User: "Add Redis caching to the URL shortener" Agent (activates source-driven-development): 1. Fetch Redis docs: https://redis.io/docs/latest/develop/connect/clients/nodejs/ 2. Verify connection pattern from official source 3. Implement with source citation // Citation in code: // Pattern from https://redis.io/docs/latest/develop/connect/clients/nodejs/ // Retrieved: 2026-05-16 const redis = require('redis'); const client = redis.createClient({ socket: { host: process.env.REDIS_HOST, port: 6379 } }); ``` **`doubt-driven-development`** - Adversarial review for high-stakes decisions: ```markdown Trigger: Production security change, unfamiliar code, irreversible migration Process: 1. CLAIM: "This JWT expiration is secure" 2. EXTRACT: ttl = 86400 (24 hours) 3. DOUBT: "24h is long for sensitive data; OWASP recommends 15min for access tokens" 4. RECONCILE: Change to 900s (15min) + refresh token pattern 5. STOP: Present change with justification ``` ### Verify Phase **`browser-testing-with-devtools`** - Live runtime data via Chrome DevTools MCP: ```bash # Activate DevTools connection chrome-devtools connect http://localhost:3000 # Inspect DOM query-selector 'button[data-testid="submit"]' # Check console errors get-console-logs --level error # Measure performance performance-profile --duration 5000 # Network waterfall get-network-log --filter fetch ``` **`debugging-and-error-recovery`** - Five-step triage: ```markdown 1. REPRODUCE - Minimal repro case - Consistent failure conditions 2. LOCALIZE - Binary search through call stack - Isolate failing component 3. REDUCE - Strip non-essential code - Minimal failing example 4. FIX - Root cause, not symptom - Safe fallback if fix unclear 5. GUARD - Add test for regression - Update error handling ``` ### Review Phase **`code-review-and-quality`** - Five-axis review: ```markdown Reviewing: URL shortener rate limiting PR ✅ CORRECTNESS - Logic handles edge cases (empty rate limit window) ⚠️ MAINTAINABILITY (Optional) - Extract magic number 100 to config constant ✅ SECURITY - Rate limit applied per IP, prevents abuse 📊 PERFORMANCE (FYI) - Redis lookup adds 2ms latency, acceptable for use case ✅ TESTING - Unit tests for rate limit logic - Integration test for 429 response - Missing: E2E test for reset after window expires (Nit) SIZE: 87 lines ✅ (target: ~100) ``` **`code-simplification`** - Chesterton's Fence + Rule of 500: ```javascript // BEFORE (complexity: 12, 500+ line file) function processUrl(url, options = {}) { const { validate = true, transform = true, cache = true } = options; if (validate && !isValidUrl(url)) throw new Error('Invalid URL'); let processed = url; if (transform) { processed = normalizeUrl(processed); processed = removeTracking(processed); processed = enforceHttps(processed); } if (cache) { const cached = getCache(processed); if (cached) return cached; } const result = shorten(processed); if (cache) setCache(processed, result); return result; } // AFTER (complexity: 4, extracted to modules) function processUrl(url) { const validated = validateUrl(url); // url-validator.js const normalized = normalizeUrl(validated); // url-normalizer.js return cachedShorten(normalized); // url-cache.js } ``` ### Ship Phase **`git-workflow-and-versioning`** - Atomic commits, trunk-based: ```bash # Commit pattern git commit -m "type(scope): description - Detail 1 - Detail 2 - Detail 3 [Tests: unit, integration] [Refs: #123]" # Example git commit -m "feat(api): Add rate limiting middleware - Redis-backed rate limiter (100 req/min per IP) - Configurable via RATE_LIMIT_MAX env var - Returns 429 with Retry-After header [Tests: unit, integration] [Refs: #456]"