diff --git a/README.md b/README.md index 621734e1..c74e719c 100644 --- a/README.md +++ b/README.md @@ -64,22 +64,25 @@ That's it! Your AI assistant now has 251 specialized skills. ๐ŸŽ‰ --- -## ๐Ÿ”Œ Compatibility +## ๐Ÿ”Œ Compatibility & Invocation -These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills: +These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills. -| Tool | Type | Compatibility | Installation Path | -| ------------------- | --------- | ------------- | ---------------------------------------- | -| **Claude Code** | CLI | โœ… Full | `.claude/skills/` or `.agent/skills/` | -| **Gemini CLI** | CLI | โœ… Full | `.gemini/skills/` or `.agent/skills/` | -| **Codex CLI** | CLI | โœ… Full | `.codex/skills/` or `.agent/skills/` | -| **Antigravity IDE** | IDE | โœ… Full | `.agent/skills/` | -| **Cursor** | IDE | โœ… Full | `.cursor/skills/` or project root | -| **GitHub Copilot** | Extension | โš ๏ธ Partial | Copy skill content to `.github/copilot/` | -| **OpenCode** | CLI | โœ… Full | `.opencode/skills/` or `.claude/skills/` | +| Tool | Type | Invocation Example | Path | +| :-------------- | :--- | :-------------------------------- | :---------------- | +| **Claude Code** | CLI | `>> /skill-name help me...` | `.claude/skills/` | +| **Gemini CLI** | CLI | `(User Prompt) Use skill-name...` | `.gemini/skills/` | +| **Antigravity** | IDE | `(Agent Mode) Use skill...` | `.agent/skills/` | +| **Cursor** | IDE | `@skill-name (in Chat)` | `.cursor/skills/` | +| **Copilot** | Ext | `(Paste content manually)` | N/A | > [!TIP] -> Most tools auto-discover skills in `.agent/skills/`. For maximum compatibility, clone to this directory. +> **Universal Path**: We recommend cloning to `.agent/skills/`. Most modern tools (Antigravity, recent CLIs) look here by default. + +> [!WARNING] +> **Windows Users**: This repository uses **symlinks** for official skills. +> You must enable Developer Mode or run Git as Administrator: +> `git clone -c core.symlinks=true https://github.com/...` --- diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md index ca9b9936..6ff2ff60 100644 --- a/docs/EXAMPLES.md +++ b/docs/EXAMPLES.md @@ -1,760 +1,56 @@ -# ๐Ÿ’ก Real-World Examples - See Skills in Action +# ๐Ÿงช Real-World Examples ("The Antigravity Cookbook") -**Learn by example!** This guide shows you real conversations using different skills. +Skills are powerful on their own, but unstoppable when combined. +Here are three common scenarios and how to solve them using this repository. + +## ๐Ÿฅ˜ Recipe 1: The "Legacy Code Audit" + +_Scenario: You just inherited a messy 5-year-old Node.js repo. You need to fix it safely._ + +**Skills Used:** + +1. `concise-planning` (To map the chaos) +2. `lint-and-validate` (To find the bugs) +3. `security-audit` (To find the holes) + +**The Workflow:** + +1. **Plan**: "Agent, use `concise-planning` to create a checklist for refactoring `src/legacy-api.js`." +2. **Audit**: "Run `security-audit` on the `package.json` to find vulnerable dependencies." +3. **Fix**: "Use `lint-and-validate` rules to auto-fix the formatting issues in `src/`." --- -## Example 1: Designing a Feature with @brainstorming +## ๐Ÿฅ˜ Recipe 2: The "Modern Web App" -### The Scenario -You want to add a "dark mode" feature to your app, but you're not sure how to approach it. +_Scenario: You need to build a high-performance Landing Page in 2 hours._ -### The Conversation +**Skills Used:** -``` -You: @brainstorming I want to add dark mode to my React app +1. `frontend-design` (For aesthetics) +2. `react-patterns` (For structure) +3. `tailwind-mastery` (For speed) -AI: Great! Let me help you think through this. First, let me check your - current project structure... - - [AI examines your files] - - I see you're using React with Tailwind CSS. Now, let's understand - your requirements: - - What's your primary goal for dark mode? - a) User preference (toggle in settings) - b) System preference (follow OS setting) - c) Both (with manual override) +**The Workflow:** -You: c) Both - -AI: Perfect! That's the best user experience. Next question: - - Where should the dark mode toggle be located? - a) In the main navigation - b) In a settings page - c) In a dropdown menu - d) Multiple locations - -You: a) In the main navigation - -AI: Good choice for accessibility. One more question: - - Should dark mode preference persist across sessions? - a) Yes, save to localStorage - b) Yes, save to user account (requires backend) - c) No, reset each session - -You: a) Yes, save to localStorage - -AI: Excellent! Now I have a clear picture. Let me present the design... - - ## Dark Mode Implementation Design - - ### Architecture Overview - We'll use React Context for state management, Tailwind's dark mode - utilities, and localStorage for persistence. The system will: - 1. Check OS preference on first visit - 2. Allow manual override via toggle - 3. Persist preference in localStorage - - Does this approach look good so far? - -You: Yes, continue - -AI: [Continues with detailed design sections...] - - [After design is complete] - - I've saved the design to docs/plans/2026-01-20-dark-mode-design.md - - Ready to set up for implementation? - -You: Yes - -AI: I'll create an isolated workspace using git worktrees and write an - implementation plan. One moment... -``` - -### What Happened -- โœ… AI asked focused questions one at a time -- โœ… Explored your specific context -- โœ… Presented design in sections -- โœ… Saved documentation -- โœ… Prepared for implementation +1. **Design**: "Use `frontend-design` to generate a color palette and typography for a 'Cyberpunk Coffee Shop'." +2. **Scaffold**: "Initialize a Vite project. Then apply `react-patterns` to create the 'Hero' component." +3. **Style**: "Use `tailwind-mastery` to make the buttons glassmorphic and responsive." --- -## Example 2: Debugging with @systematic-debugging +## ๐Ÿฅ˜ Recipe 3: The "Agent Architect" -### The Scenario -Your tests are failing, but you're not sure why. +_Scenario: You want to build a custom AI agent that can verify its own code._ -### The Conversation +**Skills Used:** -``` -You: @systematic-debugging My tests are failing with "Cannot read property - 'map' of undefined" +1. `mcp-builder` (To build tools) +2. `agent-evaluation` (To test reliability) +3. `prompt-engineering` (To refine instructions) -AI: Let me help you debug this systematically. First, I'll gather information: - - 1. Running the failing test to see the full error... - - [AI runs: npm test] - - I see the error occurs in UserList.test.tsx at line 45. Let me examine - the test file and the component... - - [AI reads both files] - - ## Hypothesis - The test is failing because `users` prop is undefined when the component - renders. This suggests the mock data isn't being passed correctly. - - ## Verification - Let me check the test setup... - - [AI examines test] - - Found it! The test is calling: - ```typescript - render() - ``` - - But UserList requires a `users` prop. The component expects: - ```typescript - interface UserListProps { - users: User[]; - } - ``` - - ## Solution - The test should pass the users prop: - ```typescript - const mockUsers = [ - { id: 1, name: 'Alice' }, - { id: 2, name: 'Bob' } - ]; - - render() - ``` - - Should I apply this fix? +**The Workflow:** -You: Yes - -AI: [Applies fix and runs tests] - - โœ… All tests passing! - - ## Root Cause - The test was missing required props. This is a common issue when - components are refactored to require props that were previously optional. - - ## Prevention - Consider adding TypeScript strict mode to catch these at compile time: - ```json - "strict": true, - "strictNullChecks": true - ``` - - Would you like me to add this to your tsconfig.json? -``` - -### What Happened -- โœ… Systematic investigation -- โœ… Clear hypothesis -- โœ… Verification before fixing -- โœ… Root cause analysis -- โœ… Prevention suggestions - ---- - -## Example 3: Adding Payments with @stripe-integration - -### The Scenario -You need to add subscription billing to your SaaS app. - -### The Conversation - -``` -You: @stripe-integration I need to add monthly subscription billing - -AI: I'll help you implement Stripe subscriptions. Let me understand your - requirements: - - Current stack detected: - - Next.js 14 (App Router) - - TypeScript - - Prisma with PostgreSQL - - For subscription billing, we'll need: - - 1. **Stripe Setup** - - Stripe account and API keys - - Webhook endpoint for events - - Product and price IDs - - 2. **Backend Implementation** - - API routes for checkout - - Webhook handler - - Database schema for subscriptions - - 3. **Frontend Implementation** - - Pricing page - - Checkout flow - - Subscription management - - Let's start with the backend. First, install dependencies: - - ```bash - npm install stripe @stripe/stripe-js - ``` - - Now, let's create the database schema... - - [AI provides Prisma schema] - - ```prisma - model User { - id String @id @default(cuid()) - email String @unique - stripeCustomerId String? @unique - subscriptions Subscription[] - } - - model Subscription { - id String @id @default(cuid()) - userId String - user User @relation(fields: [userId], references: [id]) - stripeSubscriptionId String @unique - status String - priceId String - currentPeriodEnd DateTime - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt - } - ``` - - Next, let's create the checkout API route... - - [AI provides complete implementation with:] - - API route for creating checkout sessions - - Webhook handler for subscription events - - Helper functions for Stripe operations - - Error handling and logging - - TypeScript types - - Now for the frontend... - - [AI provides:] - - Pricing page component - - Checkout button component - - Subscription status display - - Tailwind styling - - Finally, let's set up the webhook: - - 1. In Stripe Dashboard, add webhook endpoint: - `https://yourdomain.com/api/webhooks/stripe` - - 2. Select these events: - - customer.subscription.created - - customer.subscription.updated - - customer.subscription.deleted - - invoice.payment_succeeded - - invoice.payment_failed - - 3. Copy the webhook secret to your .env: - ``` - STRIPE_WEBHOOK_SECRET=whsec_... - ``` - - ## Testing - - Test locally with Stripe CLI: - ```bash - stripe listen --forward-to localhost:3000/api/webhooks/stripe - stripe trigger customer.subscription.created - ``` - - ## Security Checklist - - โœ… API keys in environment variables - - โœ… Webhook signature verification - - โœ… Server-side price validation - - โœ… Idempotency keys for operations - - Ready to test the implementation? -``` - -### What Happened -- โœ… Detected existing stack -- โœ… Provided complete implementation -- โœ… Included database schema -- โœ… Added security best practices -- โœ… Included testing instructions - ---- - -## Example 4: Writing Copy with @copywriting - -### The Scenario -You need compelling copy for your SaaS landing page. - -### The Conversation - -``` -You: @copywriting Write homepage copy for my project management tool - -AI: I'll help you create compelling homepage copy. First, let me understand - your product: - - What makes your project management tool different from competitors - like Asana, Trello, or Monday.com? - -You: It's specifically built for remote teams with built-in video standups - and async communication features - -AI: Excellent differentiator! Who is your primary target audience? - a) Startups and small teams (2-20 people) - b) Mid-size companies (20-200 people) - c) Enterprise (200+ people) - d) Freelancers and agencies - -You: a) Startups and small teams - -AI: Perfect. What's the main pain point you solve? - -You: Remote teams waste time in unnecessary meetings and lose context - in async communication - -AI: Great! Now I have what I need. Here's your homepage copy: - - --- - - ## Hero Section - - **Headline:** - Run Your Remote Team Without the Meeting Overload - - **Subheadline:** - The project management tool built for distributed teams. Replace - status meetings with async video standups and keep everyone in sync - without the Zoom fatigue. - - **CTA:** - Start Free Trial โ†’ (No credit card required) - - --- - - ## Problem Section - - **Headline:** - Remote Work Shouldn't Mean More Meetings - - **Body:** - Your team is distributed across time zones. You're spending hours in - status meetings just to stay aligned. Async updates get lost in Slack. - Context disappears. Productivity suffers. - - Sound familiar? - - --- - - ## Solution Section - - **Headline:** - Stay Aligned Without the Meeting Marathon - - **Features:** - - ๐Ÿ“น **Async Video Standups** - Record quick video updates on your schedule. Your team watches when - it works for them. No more 9am calls for your teammate in Tokyo. - - ๐Ÿ’ฌ **Context-Rich Communication** - Every task, comment, and decision stays connected. No more hunting - through Slack threads or email chains. - - ๐Ÿ“Š **Visual Progress Tracking** - See what's happening at a glance. Kanban boards, timelines, and - dashboards that actually make sense. - - ๐Ÿ”” **Smart Notifications** - Get notified about what matters. Ignore the rest. Your focus time - is sacred. - - --- - - ## Social Proof Section - - **Headline:** - Trusted by Remote Teams Worldwide - - [Testimonial placeholders with structure] - - --- - - ## CTA Section - - **Headline:** - Ready to Reclaim Your Calendar? - - **Body:** - Join 500+ remote teams who've cut meeting time by 60% while staying - more aligned than ever. - - **CTA:** - Start Your Free 14-Day Trial โ†’ - - No credit card required. Cancel anytime. - - --- - - ## Copy Notes - - **Tone:** Professional but conversational - **Focus:** Pain point (too many meetings) โ†’ Solution (async video) - **Differentiation:** Built specifically for remote teams - **Social proof:** Quantified benefit (60% fewer meetings) - - Would you like me to: - 1. Write alternative versions for A/B testing? - 2. Create copy for specific feature pages? - 3. Write email sequences for onboarding? -``` - -### What Happened -- โœ… Asked clarifying questions -- โœ… Identified unique value proposition -- โœ… Created benefit-focused copy -- โœ… Included clear CTAs -- โœ… Provided copy notes for consistency - ---- - -## Example 5: Test-Driven Development with @test-driven-development - -### The Scenario -You need to implement a new feature: user authentication. - -### The Conversation - -``` -You: @test-driven-development I need to implement user login functionality - -AI: Perfect! Let's use TDD to build this. Following the Red-Green-Refactor - cycle, we'll write tests first, then implement. - - ## Step 1: Write the First Test (RED) - - Let's start with the simplest case - successful login: - - ```typescript - // auth.test.ts - import { login } from './auth'; - - describe('login', () => { - it('should return user data for valid credentials', async () => { - const result = await login({ - email: 'user@example.com', - password: 'correct-password' - }); - - expect(result.success).toBe(true); - expect(result.user).toHaveProperty('id'); - expect(result.user).toHaveProperty('email'); - expect(result.token).toBeDefined(); - }); - }); - ``` - - Let's run this test to see it fail: - - [AI runs: npm test] - - โœ… Test fails as expected (auth.ts doesn't exist yet) - - ## Step 2: Write Minimal Implementation (GREEN) - - Now let's write just enough code to make this test pass: - - ```typescript - // auth.ts - interface LoginCredentials { - email: string; - password: string; - } - - interface LoginResult { - success: boolean; - user?: { - id: string; - email: string; - }; - token?: string; - } - - export async function login( - credentials: LoginCredentials - ): Promise { - // Minimal implementation to pass the test - return { - success: true, - user: { - id: '1', - email: credentials.email - }, - token: 'fake-token' - }; - } - ``` - - [AI runs: npm test] - - โœ… Test passes! - - ## Step 3: Add Next Test (RED) - - Now let's test the failure case: - - ```typescript - it('should return error for invalid credentials', async () => { - const result = await login({ - email: 'user@example.com', - password: 'wrong-password' - }); - - expect(result.success).toBe(false); - expect(result.error).toBe('Invalid credentials'); - expect(result.user).toBeUndefined(); - expect(result.token).toBeUndefined(); - }); - ``` - - [AI runs: npm test] - - โŒ Test fails (always returns success) - - ## Step 4: Implement Real Logic (GREEN) - - Now let's add actual authentication: - - ```typescript - import bcrypt from 'bcrypt'; - import jwt from 'jsonwebtoken'; - import { db } from './db'; - - export async function login( - credentials: LoginCredentials - ): Promise { - // Find user - const user = await db.user.findUnique({ - where: { email: credentials.email } - }); - - if (!user) { - return { - success: false, - error: 'Invalid credentials' - }; - } - - // Verify password - const validPassword = await bcrypt.compare( - credentials.password, - user.passwordHash - ); - - if (!validPassword) { - return { - success: false, - error: 'Invalid credentials' - }; - } - - // Generate token - const token = jwt.sign( - { userId: user.id }, - process.env.JWT_SECRET!, - { expiresIn: '7d' } - ); - - return { - success: true, - user: { - id: user.id, - email: user.email - }, - token - }; - } - ``` - - [AI runs: npm test] - - โœ… All tests pass! - - ## Step 5: Add Edge Cases - - Let's add more tests for edge cases: - - ```typescript - it('should handle missing email', async () => { - const result = await login({ - email: '', - password: 'password' - }); - - expect(result.success).toBe(false); - expect(result.error).toBe('Email is required'); - }); - - it('should handle missing password', async () => { - const result = await login({ - email: 'user@example.com', - password: '' - }); - - expect(result.success).toBe(false); - expect(result.error).toBe('Password is required'); - }); - - it('should handle database errors gracefully', async () => { - // Mock database error - jest.spyOn(db.user, 'findUnique').mockRejectedValue( - new Error('Database connection failed') - ); - - const result = await login({ - email: 'user@example.com', - password: 'password' - }); - - expect(result.success).toBe(false); - expect(result.error).toBe('An error occurred'); - }); - ``` - - [AI implements validation and error handling] - - ## Step 6: Refactor (REFACTOR) - - Now that all tests pass, let's refactor for better code quality: - - ```typescript - // Extract validation - function validateCredentials(credentials: LoginCredentials): string | null { - if (!credentials.email) return 'Email is required'; - if (!credentials.password) return 'Password is required'; - return null; - } - - // Extract user verification - async function verifyUser( - email: string, - password: string - ): Promise { - const user = await db.user.findUnique({ where: { email } }); - if (!user) return null; - - const valid = await bcrypt.compare(password, user.passwordHash); - return valid ? user : null; - } - - // Main function is now cleaner - export async function login( - credentials: LoginCredentials - ): Promise { - try { - const validationError = validateCredentials(credentials); - if (validationError) { - return { success: false, error: validationError }; - } - - const user = await verifyUser( - credentials.email, - credentials.password - ); - - if (!user) { - return { success: false, error: 'Invalid credentials' }; - } - - const token = generateToken(user.id); - - return { - success: true, - user: { id: user.id, email: user.email }, - token - }; - } catch (error) { - console.error('Login error:', error); - return { success: false, error: 'An error occurred' }; - } - } - ``` - - [AI runs: npm test] - - โœ… All tests still pass after refactoring! - - ## Summary - - We've implemented login functionality using TDD: - - โœ… 5 tests covering happy path, errors, and edge cases - - โœ… Clean, testable code - - โœ… Proper error handling - - โœ… Type safety with TypeScript - - Next steps: - 1. Add rate limiting tests - 2. Add session management tests - 3. Add logout functionality - - Should I continue with these? -``` - -### What Happened -- โœ… Followed Red-Green-Refactor cycle -- โœ… Wrote tests before implementation -- โœ… Covered edge cases -- โœ… Refactored with confidence -- โœ… Maintained test coverage - ---- - -## Key Takeaways - -### What Makes These Examples Effective? - -1. **Skills ask clarifying questions** before jumping to solutions -2. **Skills provide context-aware help** based on your project -3. **Skills follow best practices** for their domain -4. **Skills include complete examples** not just snippets -5. **Skills explain the "why"** not just the "how" - -### How to Get Similar Results - -1. **Be specific** in your requests -2. **Provide context** about your project -3. **Answer questions** the skill asks -4. **Review suggestions** before applying -5. **Iterate** based on results - ---- - -## Try These Yourself! - -Pick a skill and try it with your own project: - -- **Planning:** `@brainstorming` or `@writing-plans` -- **Development:** `@test-driven-development` or `@react-best-practices` -- **Debugging:** `@systematic-debugging` or `@test-fixing` -- **Integration:** `@stripe-integration` or `@firebase` -- **Marketing:** `@copywriting` or `@seo-audit` - ---- - -**Want more examples?** Check individual skill folders for additional examples and use cases! +1. **Build**: "Use `mcp-builder` to create a `verify-file` tool." +2. **Instruct**: "Apply `prompt-engineering` patterns to the System Prompt so the agent always checks file paths." +3. **Test**: "Run `agent-evaluation` to benchmark how often the agent fails to find the file."