firefrost-gaming/antigravity-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add files via upload

Browse Source
This commit is contained in:
Mohammad Faiz
2026-01-20 05:16:07 +05:30
committed by GitHub
parent d7be8ef49f
commit fd89fe2cef
7 changed files with 2966 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

760
docs/EXAMPLES.md Normal file
View File

@@ -0,0 +1,760 @@
# 💡 Real-World Examples - See Skills in Action
**Learn by example!** This guide shows you real conversations using different skills.
---
## 🎨 Example 1: Designing a Feature with @brainstorming
### The Scenario
You want to add a "dark mode" feature to your app, but you're not sure how to approach it.
### The Conversation
```
You: @brainstorming I want to add dark mode to my React app
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)
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
---
## 🐛 Example 2: Debugging with @systematic-debugging
### The Scenario
Your tests are failing, but you're not sure why.
### The Conversation
```
You: @systematic-debugging My tests are failing with "Cannot read property
'map' of undefined"
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(<UserList />)
```
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(<UserList users={mockUsers} />)
```
Should I apply this fix?
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<LoginResult> {
// 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<LoginResult> {
// 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<User | null> {
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<LoginResult> {
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!

545
docs/SKILL_ANATOMY.md Normal file
View File

@@ -0,0 +1,545 @@
# 🔬 Anatomy of a Skill - Understanding the Structure
**Want to understand how skills work under the hood?** This guide breaks down every part of a skill file.
---
## 📁 Basic Folder Structure
```
skills/
└── my-skill-name/
├── SKILL.md ← Required: The main skill definition
├── examples/ ← Optional: Example files
│ ├── example1.js
│ └── example2.py
├── scripts/ ← Optional: Helper scripts
│ └── helper.sh
├── templates/ ← Optional: Code templates
│ └── template.tsx
├── references/ ← Optional: Reference documentation
│ └── api-docs.md
└── README.md ← Optional: Additional documentation
```
**Key Rule:** Only `SKILL.md` is required. Everything else is optional!
---
## 📄 SKILL.md Structure
Every `SKILL.md` file has two main parts:
### 1. Frontmatter (Metadata)
### 2. Content (Instructions)
Let's break down each part:
---
## 🏷️ Part 1: Frontmatter
The frontmatter is at the very top, wrapped in `---`:
```markdown
---
name: my-skill-name
description: "Brief description of what this skill does"
---
```
### Required Fields
#### `name`
- **What it is:** The skill's identifier
- **Format:** lowercase-with-hyphens
- **Must match:** The folder name exactly
- **Example:** `stripe-integration`
#### `description`
- **What it is:** One-sentence summary
- **Format:** String in quotes
- **Length:** Keep it under 150 characters
- **Example:** `"Stripe payment integration patterns including checkout, subscriptions, and webhooks"`
### Optional Fields
Some skills include additional metadata:
```markdown
---
name: my-skill-name
description: "Brief description"
version: "1.0.0"
author: "Your Name"
tags: ["react", "typescript", "testing"]
---
```
---
## 📝 Part 2: Content
After the frontmatter comes the actual skill content. Here's the recommended structure:
### Recommended Sections
#### 1. Title (H1)
```markdown
# Skill Title
```
- Use a clear, descriptive title
- Usually matches or expands on the skill name
#### 2. Overview
```markdown
## Overview
A brief explanation of what this skill does and why it exists.
2-4 sentences is perfect.
```
#### 3. When to Use
```markdown
## When to Use This Skill
- Use when you need to [scenario 1]
- Use when working with [scenario 2]
- Use when the user asks about [scenario 3]
```
**Why this matters:** Helps the AI know when to activate this skill
#### 4. Core Instructions
```markdown
## How It Works
### Step 1: [Action]
Detailed instructions...
### Step 2: [Action]
More instructions...
```
**This is the heart of your skill** - clear, actionable steps
#### 5. Examples
```markdown
## Examples
### Example 1: [Use Case]
\`\`\`javascript
// Example code
\`\`\`
### Example 2: [Another Use Case]
\`\`\`javascript
// More code
\`\`\`
```
**Why examples matter:** They show the AI exactly what good output looks like
#### 6. Best Practices
```markdown
## Best Practices
- ✅ Do this
- ✅ Also do this
- ❌ Don't do this
- ❌ Avoid this
```
#### 7. Common Pitfalls
```markdown
## Common Pitfalls
- **Problem:** Description
**Solution:** How to fix it
```
#### 8. Related Skills
```markdown
## Related Skills
- `@other-skill` - When to use this instead
- `@complementary-skill` - How this works together
```
---
## 🎯 Writing Effective Instructions
### Use Clear, Direct Language
**❌ Bad:**
```markdown
You might want to consider possibly checking if the user has authentication.
```
**✅ Good:**
```markdown
Check if the user is authenticated before proceeding.
```
### Use Action Verbs
**❌ Bad:**
```markdown
The file should be created...
```
**✅ Good:**
```markdown
Create the file...
```
### Be Specific
**❌ Bad:**
```markdown
Set up the database properly.
```
**✅ Good:**
```markdown
1. Create a PostgreSQL database
2. Run migrations: `npm run migrate`
3. Seed initial data: `npm run seed`
```
---
## 🧩 Optional Components
### Scripts Directory
If your skill needs helper scripts:
```
scripts/
├── setup.sh ← Setup automation
├── validate.py ← Validation tools
└── generate.js ← Code generators
```
**Reference them in SKILL.md:**
```markdown
Run the setup script:
\`\`\`bash
bash scripts/setup.sh
\`\`\`
```
### Examples Directory
Real-world examples that demonstrate the skill:
```
examples/
├── basic-usage.js
├── advanced-pattern.ts
└── full-implementation/
├── index.js
└── config.json
```
### Templates Directory
Reusable code templates:
```
templates/
├── component.tsx
├── test.spec.ts
└── config.json
```
**Reference in SKILL.md:**
```markdown
Use this template as a starting point:
\`\`\`typescript
{{#include templates/component.tsx}}
\`\`\`
```
### References Directory
External documentation or API references:
```
references/
├── api-docs.md
├── best-practices.md
└── troubleshooting.md
```
---
## 📐 Skill Size Guidelines
### Minimum Viable Skill
- **Frontmatter:** name + description
- **Content:** 100-200 words
- **Sections:** Overview + Instructions
### Standard Skill
- **Frontmatter:** name + description
- **Content:** 300-800 words
- **Sections:** Overview + When to Use + Instructions + Examples
### Comprehensive Skill
- **Frontmatter:** name + description + optional fields
- **Content:** 800-2000 words
- **Sections:** All recommended sections
- **Extras:** Scripts, examples, templates
**Rule of thumb:** Start small, expand based on feedback
---
## 🎨 Formatting Best Practices
### Use Markdown Effectively
#### Code Blocks
Always specify the language:
```markdown
\`\`\`javascript
const example = "code";
\`\`\`
```
#### Lists
Use consistent formatting:
```markdown
- Item 1
- Item 2
- Sub-item 2.1
- Sub-item 2.2
```
#### Emphasis
- **Bold** for important terms: `**important**`
- *Italic* for emphasis: `*emphasis*`
- `Code` for commands/code: `` `code` ``
#### Links
```markdown
[Link text](https://example.com)
```
---
## ✅ Quality Checklist
Before finalizing your skill:
### Content Quality
- [ ] Instructions are clear and actionable
- [ ] Examples are realistic and helpful
- [ ] No typos or grammar errors
- [ ] Technical accuracy verified
### Structure
- [ ] Frontmatter is valid YAML
- [ ] Name matches folder name
- [ ] Sections are logically organized
- [ ] Headings follow hierarchy (H1 → H2 → H3)
### Completeness
- [ ] Overview explains the "why"
- [ ] Instructions explain the "how"
- [ ] Examples show the "what"
- [ ] Edge cases are addressed
### Usability
- [ ] A beginner could follow this
- [ ] An expert would find it useful
- [ ] The AI can parse it correctly
- [ ] It solves a real problem
---
## 🔍 Real-World Example Analysis
Let's analyze a real skill: `brainstorming`
```markdown
---
name: brainstorming
description: "You MUST use this before any creative work..."
---
```
**Analysis:**
- ✅ Clear name
- ✅ Strong description with urgency ("MUST use")
- ✅ Explains when to use it
```markdown
# Brainstorming Ideas Into Designs
## Overview
Help turn ideas into fully formed designs...
```
**Analysis:**
- ✅ Clear title
- ✅ Concise overview
- ✅ Explains the value proposition
```markdown
## The Process
**Understanding the idea:**
- Check out the current project state first
- Ask questions one at a time
```
**Analysis:**
- ✅ Broken into clear phases
- ✅ Specific, actionable steps
- ✅ Easy to follow
---
## 🚀 Advanced Patterns
### Conditional Logic
```markdown
## Instructions
If the user is working with React:
- Use functional components
- Prefer hooks over class components
If the user is working with Vue:
- Use Composition API
- Follow Vue 3 patterns
```
### Progressive Disclosure
```markdown
## Basic Usage
[Simple instructions for common cases]
## Advanced Usage
[Complex patterns for power users]
```
### Cross-References
```markdown
## Related Workflows
1. First, use `@brainstorming` to design
2. Then, use `@writing-plans` to plan
3. Finally, use `@test-driven-development` to implement
```
---
## 📊 Skill Effectiveness Metrics
How to know if your skill is good:
### Clarity Test
- Can someone unfamiliar with the topic follow it?
- Are there any ambiguous instructions?
### Completeness Test
- Does it cover the happy path?
- Does it handle edge cases?
- Are error scenarios addressed?
### Usefulness Test
- Does it solve a real problem?
- Would you use this yourself?
- Does it save time or improve quality?
---
## 🎓 Learning from Existing Skills
### Study These Examples
**For Beginners:**
- `skills/brainstorming/SKILL.md` - Clear structure
- `skills/git-pushing/SKILL.md` - Simple and focused
- `skills/copywriting/SKILL.md` - Good examples
**For Advanced:**
- `skills/systematic-debugging/SKILL.md` - Comprehensive
- `skills/react-best-practices/SKILL.md` - Multiple files
- `skills/loki-mode/SKILL.md` - Complex workflows
---
## 💡 Pro Tips
1. **Start with the "When to Use" section** - This clarifies the skill's purpose
2. **Write examples first** - They help you understand what you're teaching
3. **Test with an AI** - See if it actually works before submitting
4. **Get feedback** - Ask others to review your skill
5. **Iterate** - Skills improve over time based on usage
---
## 🆘 Common Mistakes to Avoid
### ❌ Mistake 1: Too Vague
```markdown
## Instructions
Make the code better.
```
**✅ Fix:**
```markdown
## Instructions
1. Extract repeated logic into functions
2. Add error handling for edge cases
3. Write unit tests for core functionality
```
### ❌ Mistake 2: Too Complex
```markdown
## Instructions
[5000 words of dense technical jargon]
```
**✅ Fix:**
Break into multiple skills or use progressive disclosure
### ❌ Mistake 3: No Examples
```markdown
## Instructions
[Instructions without any code examples]
```
**✅ Fix:**
Add at least 2-3 realistic examples
### ❌ Mistake 4: Outdated Information
```markdown
Use React class components...
```
**✅ Fix:**
Keep skills updated with current best practices
---
## 🎯 Next Steps
1. **Read 3-5 existing skills** to see different styles
2. **Try the skill template** from CONTRIBUTING_GUIDE.md
3. **Create a simple skill** for something you know well
4. **Test it** with your AI assistant
5. **Share it** via Pull Request
---
**Remember:** Every expert was once a beginner. Start simple, learn from feedback, and improve over time! 🚀

504
docs/VISUAL_GUIDE.md Normal file
View File

@@ -0,0 +1,504 @@
# 🎨 Visual Quick Start Guide
**Learn by seeing!** This guide uses diagrams and visual examples to help you understand skills.
---
## 🗺️ The Big Picture
```
┌─────────────────────────────────────────────────────────────┐
│ YOU (Developer) │
│ ↓ │
│ "Help me build a payment system" │
│ ↓ │
├─────────────────────────────────────────────────────────────┤
│ AI ASSISTANT │
│ ↓ │
│ Loads @stripe-integration skill │
│ ↓ │
│ Becomes an expert in Stripe payments │
│ ↓ │
│ Provides specialized help with code examples │
└─────────────────────────────────────────────────────────────┘
```
---
## 📦 Repository Structure (Visual)
```
antigravity-awesome-skills/
│
├── 📄 README.md ← Overview & skill list
├── 📄 GETTING_STARTED.md ← Start here! (NEW)
├── 📄 CONTRIBUTING_GUIDE.md ← How to contribute (NEW)
│
├── 📁 skills/ ← All 179 skills live here
│ │
│ ├── 📁 brainstorming/
│ │ └── 📄 SKILL.md ← Skill definition
│ │
│ ├── 📁 stripe-integration/
│ │ ├── 📄 SKILL.md
│ │ └── 📁 examples/ ← Optional extras
│ │
│ ├── 📁 react-best-practices/
│ │ ├── 📄 SKILL.md
│ │ ├── 📁 rules/
│ │ └── 📄 README.md
│ │
│ └── ... (176 more skills)
│
├── 📁 scripts/ ← Validation & management
│ ├── 🐍 validate_skills.py
│ └── 🐍 generate_index.py
│
└── 📁 docs/ ← Documentation (NEW)
├── 📄 SKILL_ANATOMY.md ← How skills work
└── 📄 QUICK_START_VISUAL.md ← This file!
```
---
## 🔄 How Skills Work (Flow Diagram)
```
┌──────────────┐
│ 1. INSTALL │ Copy skills to .agent/skills/
└──────┬───────┘
│
↓
┌──────────────┐
│ 2. INVOKE │ Type: @skill-name in AI chat
└──────┬───────┘
│
↓
┌──────────────┐
│ 3. LOAD │ AI reads SKILL.md file
└──────┬───────┘
│
↓
┌──────────────┐
│ 4. EXECUTE │ AI follows skill instructions
└──────┬───────┘
│
↓
┌──────────────┐
│ 5. RESULT │ You get specialized help!
└──────────────┘
```
---
## 🎯 Skill Categories (Visual Map)
```
┌─────────────────────────┐
│ 179 AWESOME SKILLS │
└────────────┬────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ CREATIVE│ │ DEVELOPMENT │ │ SECURITY │
│ (10) │ │ (25) │ │ (50) │
└────┬────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
• UI/UX Design • TDD • Ethical Hacking
• Canvas Art • Debugging • Metasploit
• Themes • React Patterns • Burp Suite
• SQLMap
│ │ │
└────────────────────────┼────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ AI │ │ DOCUMENTS │ │ MARKETING │
│ (30) │ │ (4) │ │ (23) │
└────┬────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
• RAG Systems • DOCX • SEO
• LangGraph • PDF • Copywriting
• Prompt Eng. • PPTX • CRO
• Voice Agents • XLSX • Paid Ads
```
---
## 📝 Skill File Anatomy (Visual)
```
┌─────────────────────────────────────────────────────────┐
│ SKILL.md │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ FRONTMATTER (Metadata) │ │
│ │ ───────────────────────────────────────────── │ │
│ │ --- │ │
│ │ name: my-skill │ │
│ │ description: "What this skill does" │ │
│ │ --- │ │
│ └───────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ CONTENT (Instructions) │ │
│ │ ───────────────────────────────────────────── │ │
│ │ │ │
│ │ # Skill Title │ │
│ │ │ │
│ │ ## Overview │ │
│ │ What this skill does... │ │
│ │ │ │
│ │ ## When to Use │ │
│ │ - Use when... │ │
│ │ │ │
│ │ ## Instructions │ │
│ │ 1. First step... │ │
│ │ 2. Second step... │ │
│ │ │ │
│ │ ## Examples │ │
│ │ ```javascript │ │
│ │ // Example code │ │
│ │ ``` │ │
│ │ │ │
│ └───────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## 🚀 Installation (Visual Steps)
### Step 1: Clone the Repository
```
┌─────────────────────────────────────────┐
│ Terminal │
├─────────────────────────────────────────┤
│ $ git clone https://github.com/ │
│ sickn33/antigravity-awesome-skills │
│ .agent/skills │
│ │
│ ✓ Cloning into '.agent/skills'... │
│ ✓ Done! │
└─────────────────────────────────────────┘
```
### Step 2: Verify Installation
```
┌─────────────────────────────────────────┐
│ File Explorer │
├─────────────────────────────────────────┤
│ 📁 .agent/ │
│ └── 📁 skills/ │
│ ├── 📁 brainstorming/ │
│ ├── 📁 stripe-integration/ │
│ ├── 📁 react-best-practices/ │
│ └── ... (176 more) │
└─────────────────────────────────────────┘
```
### Step 3: Use a Skill
```
┌─────────────────────────────────────────┐
│ AI Assistant Chat │
├─────────────────────────────────────────┤
│ You: @brainstorming help me design │
│ a todo app │
│ │
│ AI: Great! Let me help you think │
│ through this. First, let's │
│ understand your requirements... │
│ │
│ What's the primary use case? │
│ a) Personal task management │
│ b) Team collaboration │
│ c) Project planning │
└─────────────────────────────────────────┘
```
---
## 🎓 Example: Using a Skill (Step-by-Step)
### Scenario: You want to add Stripe payments to your app
```
┌─────────────────────────────────────────────────────────────┐
│ STEP 1: Identify the Need │
├─────────────────────────────────────────────────────────────┤
│ "I need to add payment processing to my app" │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 2: Find the Right Skill │
├─────────────────────────────────────────────────────────────┤
│ Search: "payment" or "stripe" │
│ Found: @stripe-integration │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 3: Invoke the Skill │
├─────────────────────────────────────────────────────────────┤
│ You: @stripe-integration help me add subscription billing │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 4: AI Loads Skill Knowledge │
├─────────────────────────────────────────────────────────────┤
│ • Stripe API patterns │
│ • Webhook handling │
│ • Subscription management │
│ • Best practices │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 5: Get Expert Help │
├─────────────────────────────────────────────────────────────┤
│ AI provides: │
│ • Code examples │
│ • Setup instructions │
│ • Security considerations │
│ • Testing strategies │
└─────────────────────────────────────────────────────────────┘
```
---
## 🔍 Finding Skills (Visual Guide)
### Method 1: Browse by Category
```
README.md → Scroll to "Full Skill Registry" → Find category → Pick skill
```
### Method 2: Search by Keyword
```
Terminal → ls skills/ | grep "keyword" → See matching skills
```
### Method 3: Use the Index
```
Open skills_index.json → Search for keyword → Find skill path
```
---
## 🛠️ Creating Your First Skill (Visual Workflow)
```
┌──────────────┐
│ 1. IDEA │ "I want to share my Docker knowledge"
└──────┬───────┘
│
↓
┌──────────────┐
│ 2. CREATE │ mkdir skills/docker-mastery
└──────┬───────┘ touch skills/docker-mastery/SKILL.md
│
↓
┌──────────────┐
│ 3. WRITE │ Add frontmatter + content
└──────┬───────┘ (Use template from CONTRIBUTING_GUIDE.md)
│
↓
┌──────────────┐
│ 4. TEST │ Copy to .agent/skills/
└──────┬───────┘ Try: @docker-mastery
│
↓
┌──────────────┐
│ 5. VALIDATE │ python3 scripts/validate_skills.py
└──────┬───────┘
│
↓
┌──────────────┐
│ 6. SUBMIT │ git commit + push + Pull Request
└──────────────┘
```
---
## 📊 Skill Complexity Levels
```
┌─────────────────────────────────────────────────────────────┐
│ SKILL COMPLEXITY │
├─────────────────────────────────────────────────────────────┤
│ │
│ SIMPLE STANDARD COMPLEX │
│ ────── ──────── ─────── │
│ │
│ • 1 file • 1 file • Multiple │
│ • 100-200 words • 300-800 words • 800-2000 │
│ • Basic structure • Full structure • Scripts │
│ • No extras • Examples • Examples │
│ • Best practices • Templates│
│ • Docs │
│ Example: Example: Example: │
│ git-pushing brainstorming loki-mode │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🎯 Contribution Impact (Visual)
```
Your Contribution
│
├─→ Improves Documentation
│ │
│ └─→ Helps 1000s of developers understand
│
├─→ Creates New Skill
│ │
│ └─→ Enables new capabilities for everyone
│
├─→ Fixes Bug/Typo
│ │
│ └─→ Prevents confusion for future users
│
└─→ Adds Example
│
└─→ Makes learning easier for beginners
```
---
## 🗺️ Learning Path (Visual Roadmap)
```
START HERE
│
↓
┌─────────────────┐
│ Read │
│ GETTING_STARTED │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Try 2-3 Skills │
│ in AI Assistant │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Read │
│ SKILL_ANATOMY │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Study Existing │
│ Skills │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Create Simple │
│ Skill │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Read │
│ CONTRIBUTING │
└────────┬────────┘
│
↓
┌─────────────────┐
│ Submit PR │
└────────┬────────┘
│
↓
CONTRIBUTOR! 🎉
```
---
## 💡 Quick Tips (Visual Cheatsheet)
```
┌─────────────────────────────────────────────────────────────┐
│ QUICK REFERENCE │
├─────────────────────────────────────────────────────────────┤
│ │
│ 📥 INSTALL │
│ git clone [repo] .agent/skills │
│ │
│ 🎯 USE │
│ @skill-name [your request] │
│ │
│ 🔍 FIND │
│ ls skills/ | grep "keyword" │
│ │
│ ✅ VALIDATE │
│ python3 scripts/validate_skills.py │
│ │
│ 📝 CREATE │
│ 1. mkdir skills/my-skill │
│ 2. Create SKILL.md with frontmatter │
│ 3. Add content │
│ 4. Test & validate │
│ 5. Submit PR │
│ │
│ 🆘 HELP │
│ • GETTING_STARTED.md - Basics │
│ • CONTRIBUTING_GUIDE.md - How to contribute │
│ • SKILL_ANATOMY.md - Deep dive │
│ • GitHub Issues - Ask questions │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🎉 Success Stories (Visual Timeline)
```
Day 1: Install skills
│
└─→ "Wow, @brainstorming helped me design my app!"
Day 3: Use 5 different skills
│
└─→ "These skills save me so much time!"
Week 1: Create first skill
│
└─→ "I shared my expertise as a skill!"
Week 2: Skill gets merged
│
└─→ "My skill is helping others! 🎉"
Month 1: Regular contributor
│
└─→ "I've contributed 5 skills and improved docs!"
```
---
## 🚀 Next Steps
1. ✅ **Understand** the visual structure
2. ✅ **Install** skills in your AI tool
3. ✅ **Try** 2-3 skills from different categories
4. ✅ **Read** CONTRIBUTING_GUIDE.md
5. ✅ **Create** your first skill
6. ✅ **Share** with the community
---
**Visual learner?** This guide should help! Still have questions? Check out:
- [GETTING_STARTED.md](../GETTING_STARTED.md) - Text-based intro
- [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Detailed breakdown
- [CONTRIBUTING_GUIDE.md](../CONTRIBUTING_GUIDE.md) - How to contribute
**Ready to contribute?** You've got this! 💪