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

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

undefined

undefined

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

git clone https://github.com/addyosmani/agent-skills.git
gemini skills install ./agent-skills/skills/

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

/spec

I need to build a URL shortener API with rate limiting

/plan

Break down the URL shortener spec into tasks

/build

Implement task #1: URL shortening endpoint

/test

Write tests for URL validation logic

/review

Review the URL shortener PR

/code-simplify

Simplify the rate limiting middleware

/ship

Prepare URL shortener for production

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

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]

Activates when: Starting new project/feature

Output structure:

undefined

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

undefined

**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"

// 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

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 }
});

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

undefined

**`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

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)

// 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
}

undefined

**`shipping-and-launch`** - Pre-launch checklist:

```markdown

undefined

undefined

**Review standard:** "Would a staff engineer approve this?"

**Five axes:** Correctness, Maintainability, Security, Performance, Testing

**Severity labels:**
- `Nit` - Polish, not blocking
- `Optional` - Suggested improvement
- `FYI` - Informational

/plugin use test-engineer

**Focus:**
- Test pyramid adherence (80/15/5)
- Coverage gaps
- Flakiness detection
- Prove-It pattern compliance

/plugin use security-auditor

**Checks:**
- Input validation (SQL injection, XSS)
- Authentication/authorization
- Secrets management
- Dependency vulnerabilities
- CORS/CSP headers

// Test naming convention
describe('[Unit] URL shortener', () => {
  test('generates 6-character codes for valid URLs', () => {
    // ARRANGE
    const url = 'https://example.com';
    
    // ACT
    const code = generateShortCode(url);
    
    // ASSERT
    expect(code).toHaveLength(6);
    expect(code).toMatch(/^[a-zA-Z0-9_-]{6}$/);
  });

  test('throws error for invalid URLs', () => {
    // ACT & ASSERT
    expect(() => generateShortCode('not-a-url')).toThrow('Invalid URL');
  });
});

// Integration test
describe('[Integration] URL shortener API', () => {
  test('POST /shorten → GET /:code roundtrip', async () => {
    const response = await request(app)
      .post('/shorten')
      .send({ url: 'https://example.com' });
    
    const { code } = response.body;
    
    const redirect = await request(app).get(`/${code}`);
    expect(redirect.status).toBe(302);
    expect(redirect.headers.location).toBe('https://example.com');
  });
});

// E2E test
describe('[E2E] URL shortener user flow', () => {
  test('user shortens URL and visits short link', async () => {
    await page.goto('http://localhost:3000');
    await page.fill('input[name="url"]', 'https://example.com');
    await page.click('button[type="submit"]');
    
    const shortUrl = await page.textContent('.short-url');
    await page.goto(shortUrl);
    
    expect(page.url()).toBe('https://example.com');
  });
});

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

User: "Migrate user passwords from MD5 to bcrypt"

Agent (activates doubt-driven-development - irreversible migration):

CLAIM: "This migration script safely rehashes all passwords"

EXTRACT:
- Reads user table (10M rows)
- Iterates, rehashing MD5 → bcrypt
- Updates in place

DOUBT:
1. No rollback plan (bcrypt hashes can't reverse to MD5)
2. Table lock during migration (10M rows = ~2 hour downtime)
3. No password verification after rehash
4. Missing feature flag for new hash check

RECONCILE:
Alternative: Lazy migration
1. Add `password_hash_version` column
2. Check version on login
3. If MD5, verify then rehash to bcrypt
4. Update version to 'bcrypt'
5. No downtime, automatic rollback (keep MD5 as fallback)

STOP:
Present both approaches with tradeoff analysis
→ Recommend lazy migration for safety

User: "Add Stripe payment processing"

Agent (activates source-driven-development):

1. Fetch official docs: https://stripe.com/docs/api
2. Verify Node.js SDK patterns
3. Extract canonical example

Implementation (with citations):

// Pattern from https://stripe.com/docs/api/payment_intents/create
// Retrieved: 2026-05-16
// SDK version: stripe@14.0.0
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

async function createPayment(amount, currency) {
  // Verified: amount in smallest currency unit (cents for USD)
  // Source: https://stripe.com/docs/currencies#zero-decimal
  const paymentIntent = await stripe.paymentIntents.create({
    amount,
    currency,
    automatic_payment_methods: { enabled: true },
  });
  
  return paymentIntent.client_secret;
}

// UNVERIFIED: Webhook signature verification pattern
// TODO: Consult https://stripe.com/docs/webhooks/signatures
// Current implementation is placeholder
function verifyWebhook(payload, signature) {
  // PLACEHOLDER - needs source verification
  return stripe.webhooks.constructEvent(payload, signature, process.env.STRIPE_WEBHOOK_SECRET);
}

undefined

undefined

undefined

undefined

undefined

undefined

User: "Follow the ~100 line change size rule from code-review-and-quality skill"

Agent: "This feature requires 347 lines. Splitting into 3 PRs:
1. Data model + migrations (94 lines)
2. API endpoints (118 lines)
3. Frontend integration (135 lines)"

Priority order:
1. Security (always wins)
2. Correctness (bugs block)
3. Testing (no code without tests)
4. Maintainability (long-term health)
5. Performance (optimize after working)

Example conflict:
- Performance skill: "Cache this database query"
- Security skill: "Don't cache user-specific data in shared cache"
→ Security wins, use per-user cache or skip caching

undefined

undefined

❌ Bad:
User: "Build a user dashboard"
Agent: *starts writing React components*

✅ Good:
User: "Build a user dashboard"
Agent (activates spec-driven-development):
"Let me create a spec first. What data should the dashboard show?"

// Wrap incomplete features
if (process.env.ENABLE_NEW_DASHBOARD === 'true') {
  return <NewDashboard />;
}
return <LegacyDashboard />;

// Deploy with flag off, enable gradually

undefined