diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 00000000..1c0a5621 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,41 @@ +{ + "permissions": { + "allow": [ + "Skill(connect-apps:setup)", + "Bash(python3 -c \"\nfrom composio import Composio\ncomposio = Composio\\(api_key='ak_KuIQ5_IMvfiOlKpSQjLS'\\)\nsession = composio.create\\(user_id='claude_user'\\)\nprint\\(session.mcp.url\\)\n\" 2>&1)", + "Bash(pip3 install:*)", + "Bash(pip3 show:*)", + "Bash(where pip3:*)", + "Bash(C:/Python314/python.exe -c \"\nfrom composio import Composio\ncomposio = Composio\\(api_key='ak_KuIQ5_IMvfiOlKpSQjLS'\\)\nsession = composio.create\\(user_id='claude_user'\\)\nprint\\(session.mcp.url\\)\n\" 2>&1)", + "Bash(ls *.md 2>/dev/null || ls *.yaml 2>/dev/null | head -20)", + "Bash(cd \"C:\\\\Users\\\\Mahmoud\\\\awesome-claude-skills\" && python send_test_email.py)", + "mcp__claude_ai_Notion__notion-create-pages", + "mcp__claude_ai_Notion__notion-search", + "mcp__claude_ai_Notion__notion-get-users", + "mcp__mcp-registry__search_mcp_registry", + "mcp__scheduled-tasks__list_scheduled_tasks", + "Bash(python3 -c \"import PyPDF2; print\\(''PyPDF2 available''\\)\")", + "Bash(python3 -c \"import pdfplumber; print\\(''pdfplumber available''\\)\")", + "Bash(python3 -c \"import fitz; print\\(''fitz available''\\)\")", + "Bash(pip install:*)", + "Bash(python3:*)", + "mcp__141e5e9d-c7b3-42a5-8bbe-29c926554ce8__notion-create-pages", + "Bash(node -e \":*)", + "Read(//c/Users/Mahmoud/.claude/**)", + "Bash(find ~/.claude/plugins -name *.json)", + "Bash(xargs grep:*)", + "Bash(find /c/Users/Mahmoud/.claude/plugins -name *.json -path */Notion/*)", + "Bash(ls /c/Users/Mahmoud/.claude/*.json)", + "Bash(find /c/Users/Mahmoud/.claude -name credentials*)", + "Bash(env)", + "Bash(find /c/Users/Mahmoud/.claude -name *.env -o -name .env)", + "Bash(find /c/Users/Mahmoud/.claude -name *.json -exec grep -l notion {})", + "Bash(2)", + "Bash(find /c/Users/Mahmoud -maxdepth 3 -name *.env -o -name .env)", + "Bash(head -10 grep -r NOTION /c/Users/Mahmoud/.claude/ --include=*.json -l)", + "Bash(grep -r \"ntn_\\\\|secret_\\\\|NOTION_TOKEN\\\\|notion_key\" /c/Users/Mahmoud/awesome-claude-skills/ --include=*.py --include=*.env --include=*.json -l)", + "Bash(head -5 find /c/Users/Mahmoud/awesome-claude-skills -name .env*)", + "Bash(cat ~/.claude/plugins/*/settings.json)" + ] + } +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..9ca40080 --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +# Claude Code local files +.claude/settings.local.json +.claude/worktrees/ +.claude/todos/ + +# OS +.DS_Store +Thumbs.db + +# Node +node_modules/ diff --git a/README.md b/README.md index a3719e9e..a787f681 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,7 @@ Claude Skills are customizable workflows that teach Claude how to perform specif ### Development & Code Tools - [artifacts-builder](https://github.com/anthropics/skills/tree/main/skills/web-artifacts-builder) - Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). +- [frontend-design](./frontend-design/) - Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. - [aws-skills](https://github.com/zxkane/aws-skills) - AWS development with CDK best practices, cost optimization MCP servers, and serverless/event-driven architecture patterns. - [Changelog Generator](./changelog-generator/) - Automatically creates user-facing changelogs from git commits by analyzing history and transforming technical commits into customer-friendly release notes. - [Chrome Relay](https://chrome-relay.kushalsm.com/) - Drives the user's already-open Chrome session — cookies, SSO, extensions, localhost — through a local CLI bridge. Real-Chrome counterpart to Playwright Browser Automation; install via `npx skills add chrome-relay` + a [Chrome Web Store extension](https://chromewebstore.google.com/detail/chrome-relay/cpdiapbifblhlcpnmlmfpgfjlacebokb). No remote relay, no Playwright fixtures, no MCP server needed. diff --git a/adspirer-ad-campaign-best-practices/SKILL.md b/adspirer-ad-campaign-best-practices/SKILL.md new file mode 100644 index 00000000..fca64baa --- /dev/null +++ b/adspirer-ad-campaign-best-practices/SKILL.md @@ -0,0 +1,22 @@ +--- +name: adspirer-ads-agent:ad-campaign-best-practices +description: Best practices for creating and managing ad campaigns across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads. Covers planning, budgets, targeting, and optimization. +--- + +## adspirer-ads-agent:ad-campaign-best-practices +**Category:** Adspirer Ads Agent + +**What it does:** +Best practices for creating and managing ad campaigns across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads. Covers planning campaigns, setting budgets, choosing targeting, and optimizing performance. + +**When to trigger:** +- Planning any paid ad campaign +- Setting budgets or targeting +- Optimizing campaign performance + +**How to install:** +```bash +npx claude install adspirer-ads-agent +``` + +**Trigger phrase:** Ask about ad campaign strategy, budgets, or targeting on any major ad platform. diff --git a/adspirer-keyword-research/SKILL.md b/adspirer-keyword-research/SKILL.md new file mode 100644 index 00000000..e99aa6a2 --- /dev/null +++ b/adspirer-keyword-research/SKILL.md @@ -0,0 +1,21 @@ +--- +name: adspirer-ads-agent:keyword-research +description: Researches Google Ads keywords with real CPC data, search volumes, and competition analysis. Gives you data-driven keyword intelligence for ad campaigns. +--- + +## adspirer-ads-agent:keyword-research +**Category:** Adspirer Ads Agent + +**What it does:** +Researches Google Ads keywords with real CPC data, search volumes, and competition analysis. Gives you data-driven keyword intelligence for ad campaigns. + +**When to trigger:** +- Planning Google Ads campaigns +- Researching keywords with real cost and volume data + +**How to install:** +```bash +npx claude install adspirer-ads-agent +``` + +**Trigger phrase:** Ask Claude to research keywords for Google Ads, or invoke `/adspirer-ads-agent:keyword-research`. diff --git a/adspirer/SKILL.md b/adspirer/SKILL.md new file mode 100644 index 00000000..e1f8ab53 --- /dev/null +++ b/adspirer/SKILL.md @@ -0,0 +1,123 @@ +--- +name: adspirer +description: Manage Google Ads and Meta (Facebook/Instagram) advertising campaigns — create, analyze, and optimize ads. Use this skill when the user wants to work with Google Ads or Meta Ads: creating campaigns, analyzing performance, writing ad copy, optimizing budgets, or troubleshooting ad issues. +--- + +# Adspirer — Google & Meta Ads Management + +Manage and optimize Google Ads and Meta Ads campaigns. + +## Capabilities + +- Analyze campaign performance and surface insights +- Write high-converting ad copy (headlines, descriptions, CTAs) +- Recommend targeting, bidding, and budget strategies +- Diagnose underperforming campaigns +- Build campaign structures for new products/promotions +- Interpret ad metrics and suggest optimizations + +## Key Metrics Reference + +### Google Ads +| Metric | Good benchmark | +|--------|---------------| +| CTR (Search) | > 3-5% | +| CTR (Display) | > 0.35% | +| Quality Score | 7-10 | +| Conversion Rate | Varies by industry; compare vs account average | +| ROAS | Depends on margins; typically target > 3x | +| CPA | Below target CPA set for campaign | + +### Meta Ads +| Metric | Good benchmark | +|--------|---------------| +| CTR (Link) | > 1% | +| CPM | Varies by audience/placement | +| Frequency | Keep < 3-4 for conversion campaigns | +| ROAS | Target varies; compare vs blended | +| Relevance Score / Quality Ranking | Above average | + +## Campaign Structure + +### Google Ads +``` +Account + └── Campaign (budget, bidding, location, device targets) + └── Ad Group (keyword/audience theme) + ├── Keywords (match types: broad, phrase, exact) + └── Ads (RSA, Performance Max, Display) +``` + +### Meta Ads +``` +Account + └── Campaign (objective: Awareness, Traffic, Conversions, etc.) + └── Ad Set (audience, budget, schedule, placement) + └── Ads (creative: image, video, carousel) +``` + +## Ad Copywriting + +### Google Search Ad (RSA) +- **Headlines**: Up to 15 headlines (30 chars each) — include keyword, benefit, CTA +- **Descriptions**: Up to 4 descriptions (90 chars each) — expand on benefits, USP +- **Best practices**: Pin headline 1 to brand/keyword, use all 15 headlines + +Example: +``` +Headline 1: [Keyword-based] "Buy Running Shoes Online" +Headline 2: [Benefit] "Free Shipping on Orders $50+" +Headline 3: [CTA] "Shop Top Brands Today" +Headline 4: [Social proof] "50,000+ Happy Customers" + +Description 1: "Discover our wide selection of running shoes from top brands. Find your perfect fit with free returns." +Description 2: "Shop Nike, Adidas, Brooks & more. Fast shipping available. Order by 3pm for same-day dispatch." +``` + +### Meta Ad +- **Primary text**: 125 chars visible before "See more" (key message first) +- **Headline**: 40 chars — punchy benefit or offer +- **Description**: 30 chars — supporting detail +- **CTA button**: Match to action (Shop Now, Learn More, Sign Up, etc.) + +## Audience Targeting + +### Google Ads +- **Search**: Keywords define audience intent — use negative keywords to exclude irrelevant traffic +- **Performance Max**: Asset-based; uses Google's signals +- **Audiences**: Remarketing, Customer Match, Similar Audiences, In-Market, Affinity + +### Meta Ads +- **Core audiences**: Demographics, interests, behaviors +- **Custom audiences**: Website visitors (pixel), email lists, app users, video views +- **Lookalike audiences**: 1-10% lookalike from Custom Audience source +- **Best practice**: Start with 3-5% lookalike from buyers; narrow with interest stacking + +## Optimization Workflow + +When asked to optimize a campaign: + +1. **Audit performance** — identify top/bottom performers at campaign, ad set, and ad level +2. **Budget allocation** — shift budget toward top performers +3. **Bid adjustments** — device, location, time-of-day adjustments +4. **Pause underperformers** — cut ad sets/ads below CPA threshold (after sufficient data) +5. **Test new creative** — if CTR low, test new headlines/images +6. **Audience refinement** — narrow or expand based on performance data +7. **Negative keywords** (Google) — review Search Terms report weekly + +## Troubleshooting Common Issues + +| Issue | Likely Cause | Fix | +|-------|-------------|-----| +| High CPC, low CTR | Low Quality Score / irrelevant audience | Improve ad relevance to keywords; tighten targeting | +| Good CTR, low conversions | Landing page issue | A/B test landing page; check tracking | +| Ads not delivering | Low budget, disapproved ads, narrow audience | Increase budget; fix policy issues; broaden audience | +| ROAS declining | Audience fatigue / increased competition | Refresh creative; test new audiences | +| Meta ads approved but no delivery | Audience too small, bid too low | Broaden audience; use Advantage+ placements | + +## Notes for Claude + +- Always ask for the user's goal before recommending (awareness vs leads vs sales vs ROAS) +- Ask for current metrics before optimization — don't recommend without data +- Budgets, bids, and targeting should be treated as hypotheses to test, not permanent decisions +- Follow platform policies — flag any creative that risks disapproval (misleading claims, restricted categories) diff --git a/brainstorming/SKILL.md b/brainstorming/SKILL.md new file mode 100644 index 00000000..c1ffc216 --- /dev/null +++ b/brainstorming/SKILL.md @@ -0,0 +1,68 @@ +--- +name: brainstorming +description: Facilitate creative brainstorming sessions to generate ideas, explore possibilities, and unlock novel solutions. Use this skill when the user wants to generate ideas, explore options, think through a problem from multiple angles, or needs creative inspiration. +--- + +# Brainstorming + +Facilitate high-quality brainstorming sessions that generate novel, diverse, and actionable ideas. + +## Core Approach + +Brainstorming works best when judgment is suspended during idea generation. Generate quantity first, then evaluate quality. Encourage divergent thinking before converging on solutions. + +## Brainstorming Modes + +### Mode 1: Open Exploration +When the user has a vague prompt or wants to explore broadly: +1. Reframe the problem in 2-3 different ways to unlock new angles +2. Generate ideas across different categories: conventional, unconventional, contrarian, and wild +3. Aim for at least 10-15 distinct ideas before filtering +4. Present ideas in clusters/themes, not just a flat list + +### Mode 2: Constrained Generation +When the user has specific constraints (time, budget, tech, audience): +1. Acknowledge constraints explicitly upfront +2. Generate ideas that respect hard constraints +3. Flag which ideas push soft constraints — sometimes constraints are negotiable +4. Include at least one idea that challenges a stated constraint + +### Mode 3: Build on Existing Ideas +When the user has partial ideas and wants to expand: +1. Extract the core insight from each existing idea +2. Generate variations: bigger, smaller, inverted, combined, applied elsewhere +3. Apply SCAMPER: Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse + +## Framing Techniques + +Use these to unlock stuck thinking: + +- **Analogy**: "How would [unrelated industry/person] solve this?" +- **First principles**: "What's the most fundamental version of this problem?" +- **Inversion**: "What would make this maximally worse? Now invert." +- **Time travel**: "What would a solution from 10 years ago / 10 years future look like?" +- **Scale extremes**: "What if this needed to work for 1 person? 1 billion people?" +- **Resource extremes**: "What if budget were zero? Unlimited?" + +## Output Format + +Structure brainstorming output as: +1. **Reframed problem** (1-2 sentences) — confirm the real problem being solved +2. **Idea clusters** — group related ideas under themes +3. **Wild card** — one deliberately unconventional or counterintuitive idea +4. **Top 3 picks** — brief rationale for the most promising ideas +5. **Next step** — a concrete action to move from ideas to execution + +## Facilitating Multi-Round Sessions + +If the user wants to iterate: +- Ask "Which of these resonates most? Why?" to identify promising directions +- Drill deeper into selected ideas: risks, variations, prerequisites +- Combine ideas from different clusters +- Narrow to 1-3 actionable concepts with clear next steps + +## Notes + +- Never dismiss an idea during generation — defer evaluation to later +- If the user seems stuck on one approach, introduce deliberate constraints to force new thinking +- Brainstorming sessions should end with clarity, not just more options diff --git a/claude-api/SKILL.md b/claude-api/SKILL.md new file mode 100644 index 00000000..e1620764 --- /dev/null +++ b/claude-api/SKILL.md @@ -0,0 +1,29 @@ +--- +name: claude-api +description: Guides building applications with the Claude API (Anthropic SDK) or Agent SDK. Covers API usage, tool use, streaming, and SDK patterns. Trigger when code imports anthropic or @anthropic-ai/sdk. +--- + +## claude-api +**Category:** Claude API / Anthropic SDK + +**What it does:** +Guides you in building applications with the Claude API (Anthropic SDK) or Agent SDK. Covers API usage, tool use, streaming, and SDK patterns. + +**When to trigger:** +- Your code imports `anthropic`, `@anthropic-ai/sdk`, or `claude_agent_sdk` +- You ask to use the Claude API or Anthropic SDK +- Building AI-powered apps with Claude as the backend + +**Do NOT trigger when:** code uses `openai` or other AI SDKs. + +**Latest model IDs:** +- Opus 4.6: `claude-opus-4-6` +- Sonnet 4.6: `claude-sonnet-4-6` +- Haiku 4.5: `claude-haiku-4-5-20251001` + +**How to install:** +```bash +npx claude install superpowers +``` + +**Trigger phrase:** Importing `anthropic` / asking to use the Claude or Anthropic API. diff --git a/code-review/SKILL.md b/code-review/SKILL.md new file mode 100644 index 00000000..7b7aaf22 --- /dev/null +++ b/code-review/SKILL.md @@ -0,0 +1,121 @@ +--- +name: code-review +description: Perform thorough, constructive code reviews covering correctness, security, performance, maintainability, and style. Use this skill when the user wants code reviewed, asks for feedback on their code, or needs a diff/PR reviewed. +--- + +# Code Review + +Perform thorough, actionable code reviews that improve code quality, catch bugs, and share knowledge. + +## Review Dimensions + +Review code across these dimensions, in order of importance: + +### 1. Correctness +Does the code do what it's supposed to do? +- Does it handle edge cases? (empty input, null/undefined, zero, large values) +- Are there off-by-one errors in loops or indices? +- Is the logic correct for all branches? +- Does error handling cover all failure paths? +- Are async operations handled correctly? (race conditions, unresolved promises) +- Are there any infinite loops or missing loop termination conditions? + +### 2. Security +Does the code introduce security vulnerabilities? +- **Injection** — SQL injection, XSS, command injection, template injection +- **Authentication/Authorization** — are permissions checked? Can users access others' data? +- **Input validation** — is user input sanitized/validated before use? +- **Secrets** — are credentials, tokens, or keys hardcoded or leaked in logs? +- **Sensitive data** — is PII/sensitive data logged, exposed in errors, or stored insecurely? +- **Dependencies** — are new dependencies vetted for known vulnerabilities? + +### 3. Performance +Does the code perform well at scale? +- **N+1 queries** — database queries inside loops +- **Unnecessary computation** — repeated calculations that could be cached +- **Memory leaks** — unreleased resources, growing collections +- **Blocking operations** — sync I/O in async contexts +- **Inefficient data structures** — O(n) lookups where O(1) is possible + +### 4. Maintainability +Will this code be easy to understand and change? +- Is the code readable? Would another developer understand it quickly? +- Are variable/function names descriptive and accurate? +- Is there duplication that should be extracted? +- Are functions/methods doing too much? (single responsibility) +- Is complexity appropriate? (avoid over-engineering) +- Are there magic numbers or strings that should be named constants? + +### 5. Tests +Is the change adequately tested? +- Are new features covered by tests? +- Are edge cases and error paths tested? +- Are tests meaningful? (not just asserting implementation details) +- Does test coverage actually test the behavior that matters? + +### 6. Style and Conventions +Does the code follow team/project conventions? +- Naming conventions (camelCase, snake_case, etc.) +- File and module organization +- Comment style and quality +- Import ordering + +## Review Output Format + +Structure reviews as: + +``` +## Summary +[1-3 sentence overview of the change and overall assessment] + +## Critical Issues (must fix) +- [issue]: [explanation] [line reference if applicable] + Suggestion: [how to fix] + +## Minor Issues (should fix) +- [issue]: [explanation] + Suggestion: [how to fix] + +## Nits (optional) +- [style/preference items] + +## Positives +- [things done well — always include at least one] +``` + +## Tone and Approach + +- **Be specific** — "this could be cleaner" is not useful; explain what and why +- **Explain the why** — don't just flag issues, explain why they matter +- **Suggest, don't dictate** — for style/preference: "consider X" not "do X" +- **Acknowledge good work** — point out what's done well, not just problems +- **Prioritize** — distinguish blocking issues from minor suggestions + +## Review Checklist + +Before submitting the review, verify: +- [ ] Correctness checked for all code paths +- [ ] Security vulnerabilities checked (injection, auth, input validation, secrets) +- [ ] Performance issues checked (N+1, unnecessary computation) +- [ ] Tests are present and meaningful +- [ ] Variable/function names are clear +- [ ] No debug code, console.logs, or TODOs left in +- [ ] Breaking changes identified +- [ ] Documentation updated if needed + +## Common Issues Quick Reference + +| Category | Pattern to Flag | +|----------|----------------| +| Security | `eval()`, string concatenation in SQL, `innerHTML =`, hardcoded credentials | +| Performance | Query inside loop, `.find()` in inner loop, sync file I/O | +| Correctness | Missing null check, uncaught promise, off-by-one in slice | +| Maintainability | Function >50 lines, nesting >3 levels, magic number | +| Tests | No error path test, mock returning wrong shape | + +## Notes for Claude + +- Read the full diff before commenting — context from other changes matters +- Check if tests were updated to cover the change +- Flag security issues as Critical regardless of other context +- If reviewing a PR, understand the PR description and intended goal first diff --git a/debugging/SKILL.md b/debugging/SKILL.md new file mode 100644 index 00000000..7a67d297 --- /dev/null +++ b/debugging/SKILL.md @@ -0,0 +1,117 @@ +--- +name: debugging +description: Systematically diagnose and fix bugs, errors, and unexpected behavior in code. Use this skill when the user has a bug, error message, unexpected behavior, or broken code that needs investigation and resolution. +--- + +# Debugging + +Systematically diagnose and resolve bugs using structured investigation rather than random trial and error. + +## Debugging Philosophy + +Debugging is hypothesis-driven. Each step should: +1. Form a hypothesis about the root cause +2. Design a minimal test to confirm or refute it +3. Act on the result — fix or form the next hypothesis + +Avoid random changes. Each change should test a specific hypothesis. + +## Step 1: Understand the Bug + +Before touching code, gather complete information: + +- **What is the expected behavior?** +- **What is the actual behavior?** +- **When does it happen?** Always? Under specific conditions? +- **When did it start?** After a recent change? Always present? +- **What's the error?** Exact error message, stack trace, log output +- **What's the environment?** OS, runtime version, dependencies, config + +Ask the user for any missing context before guessing. + +## Step 2: Reproduce the Bug + +Always reproduce before fixing: +- Find the minimal reproduction case +- Confirm the bug is reproducible consistently +- Rule out environment-specific issues (works on my machine?) +- If flaky: identify the conditions that trigger it + +## Step 3: Locate the Source + +Narrow down where the bug lives: + +**Read the error message carefully:** +- Stack traces point to the line — but the bug may be higher up the call stack +- Error types (TypeError, KeyError, etc.) hint at the category of problem + +**Bisect the problem:** +- Comment out / disable sections to isolate the faulty component +- Use binary search on recent commits if regression: `git bisect` +- Add logging/print statements to trace execution flow + +**Check common culprits first:** +- Off-by-one errors in loops/indices +- Null/undefined/None not handled +- Type mismatches (string vs int, etc.) +- Async/timing issues (race conditions, unresolved promises) +- Scope issues (variable shadowing, closures) +- Mutation of shared state +- Wrong assumptions about external data shape + +## Step 4: Fix and Verify + +Once the root cause is identified: +1. Write the fix — targeted and minimal; avoid refactoring while debugging +2. Verify the original bug is gone with the reproduction case +3. Check for regressions — does anything else break? +4. Consider edge cases: what related inputs might also fail? + +## Step 5: Document + +After fixing: +- Add a comment explaining WHY the fix works (not just what it does) +- Add a test that would have caught this bug +- Note if there are related areas that might have the same issue + +## Debugging Tools by Context + +**JavaScript/TypeScript:** +```js +console.log(), console.error(), console.trace() +debugger; // pause in browser/Node +// Chrome DevTools, VS Code debugger +``` + +**Python:** +```python +print(), logging.debug() +import pdb; pdb.set_trace() # or breakpoint() in Python 3.7+ +# VS Code debugger, pdb, ipdb +``` + +**Git bisect (for regressions):** +```bash +git bisect start +git bisect bad HEAD +git bisect good +# Run tests, mark good/bad, git will find the culprit commit +``` + +## Common Bug Patterns + +| Symptom | Likely Cause | +|---------|-------------| +| Works sometimes, fails sometimes | Race condition, async issue, flaky dependency | +| Only fails on specific input | Edge case, boundary condition | +| Fails only in production | Environment difference, missing config, different data | +| Was working, now broken | Recent change introduced regression | +| Wrong output, no error | Logic error, wrong algorithm, off-by-one | +| Correct output but crash later | Side effect, state mutation | + +## Notes for Claude + +- Read the full stack trace — the error origin is often not where the exception is thrown +- If the user has tried things already, ask what they tried — avoid repeating dead ends +- Never guess and apply multiple changes at once — test one hypothesis at a time +- If unable to reproduce locally, ask the user to add logging/print statements and share output diff --git a/figma-code-connect-components/SKILL.md b/figma-code-connect-components/SKILL.md new file mode 100644 index 00000000..1ff4824f --- /dev/null +++ b/figma-code-connect-components/SKILL.md @@ -0,0 +1,24 @@ +--- +name: figma:code-connect-components +description: Connects Figma design components to code components using Code Connect. Creates mappings between Figma designs and code implementations so design tools show the real code. +--- + +## figma:code-connect-components +**Category:** Figma + +**What it does:** +Connects Figma design components to code components using Code Connect. Creates mappings between Figma designs and code implementations so design tools show the real code. + +**When to trigger:** +- "Code connect this component" +- "Connect Figma to code" +- "Map this component to code" +- "Create code connect mapping" + +**How to install:** +```bash +npx claude install figma +``` +Also requires the **Figma MCP server** connected. + +**Trigger phrase:** Ask to connect or map a Figma component to its code equivalent. diff --git a/figma-code-connect/SKILL.md b/figma-code-connect/SKILL.md new file mode 100644 index 00000000..cceb0d54 --- /dev/null +++ b/figma-code-connect/SKILL.md @@ -0,0 +1,169 @@ +--- +name: figma-code-connect +description: Set up and manage Figma Code Connect — link Figma components to real code components so devs see actual code snippets in Figma Dev Mode. Use this skill when the user wants to connect their Figma design system to their React/other framework component library using Figma's Code Connect feature. +--- + +# Figma: Code Connect + +Link Figma components to real code components using Figma Code Connect. + +## What is Code Connect? + +Figma Code Connect maps Figma design components to their code implementations. When developers inspect a component in Figma Dev Mode, they see real code snippets from the actual codebase instead of generated CSS. + +## Prerequisites + +- Figma account with Dev Mode access +- Node.js project with a component library +- Figma personal access token + +## Installation + +```bash +npm install --save-dev @figma/code-connect +# or +npx figma connect +``` + +## Setup + +### 1. Authenticate + +```bash +npx figma connect login +# Enter your Figma personal access token when prompted +# Token: https://www.figma.com/settings → Personal access tokens +``` + +Or set via environment variable: +```bash +export FIGMA_ACCESS_TOKEN=figd_... +``` + +### 2. Initialize + +```bash +npx figma connect create +``` + +This creates a `figma.config.json`: +```json +{ + "codeConnect": { + "include": ["src/**/*.figma.tsx"], + "exclude": ["node_modules/**"] + } +} +``` + +## Creating Code Connect Files + +For each Figma component, create a `.figma.tsx` (or `.figma.ts`) file: + +### Basic Example — Button + +```tsx +// src/components/Button/Button.figma.tsx +import figma from '@figma/code-connect' +import { Button } from './Button' + +figma.connect(Button, 'https://www.figma.com/design/FILE_ID/DESIGN_NAME?node-id=COMPONENT_NODE_ID', { + props: { + variant: figma.enum('Variant', { + Default: 'default', + Primary: 'primary', + Destructive: 'destructive', + }), + size: figma.enum('Size', { + Small: 'sm', + Medium: 'md', + Large: 'lg', + }), + disabled: figma.boolean('Disabled'), + label: figma.string('Label'), + }, + example: ({ variant, size, disabled, label }) => ( + + ), +}) +``` + +### Input Component Example + +```tsx +import figma from '@figma/code-connect' +import { Input } from './Input' + +figma.connect(Input, 'FIGMA_URL?node-id=NODE_ID', { + props: { + placeholder: figma.string('Placeholder'), + disabled: figma.boolean('Disabled'), + error: figma.boolean('Error'), + }, + example: ({ placeholder, disabled, error }) => ( + + ), +}) +``` + +## Figma URL Format + +Get the component URL from Figma: +1. Open Figma file +2. Right-click the component in the canvas +3. "Copy link to selection" +4. URL format: `https://www.figma.com/design/FILE_ID/NAME?node-id=X-Y` + +## Publishing Code Connect + +```bash +# Preview what will be published +npx figma connect publish --dry-run + +# Publish to Figma +npx figma connect publish +``` + +## Prop Mappers Reference + +| Figma Prop Type | Code Connect Mapper | +|----------------|---------------------| +| Enum/Variant | `figma.enum('Prop Name', { FigmaOption: 'codeValue' })` | +| Boolean | `figma.boolean('Prop Name')` | +| String | `figma.string('Prop Name')` | +| Number | `figma.number('Prop Name')` | +| Instance swap | `figma.instance('Prop Name')` | +| Nested instance | `figma.nestedProps('Layer Name', { ... })` | + +## CI Integration + +Add to CI pipeline to keep Code Connect up to date: +```yaml +# .github/workflows/figma-code-connect.yml +- name: Publish Code Connect + run: npx figma connect publish + env: + FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }} +``` + +## Process for Connecting a Component Library + +1. Get component node IDs from Figma (right-click → copy link) +2. Create `.figma.tsx` file for each component +3. Map Figma property names to code prop names +4. Write the `example` render function +5. Run `npx figma connect publish --dry-run` to verify +6. Run `npx figma connect publish` to push live + +## Notes + +- Component node IDs change if components are moved between files +- Keep `.figma.tsx` files co-located with their components +- Test locally with `--dry-run` before publishing +- Figma Dev Mode must be enabled on the file to see Code Connect snippets diff --git a/figma-create-design-system-rules/SKILL.md b/figma-create-design-system-rules/SKILL.md new file mode 100644 index 00000000..729efc51 --- /dev/null +++ b/figma-create-design-system-rules/SKILL.md @@ -0,0 +1,24 @@ +--- +name: figma:create-design-system-rules +description: Generates custom design system rules for your codebase. Establishes project-specific conventions for Figma-to-code workflows — tokens, component naming, spacing scales, etc. +--- + +## figma:create-design-system-rules +**Category:** Figma + +**What it does:** +Generates custom design system rules for your codebase. Establishes project-specific conventions for Figma-to-code workflows — tokens, component naming, spacing scales, etc. + +**When to trigger:** +- "Create design system rules" +- "Generate rules for my project" +- "Set up design rules" +- "Customize design system guidelines" + +**How to install:** +```bash +npx claude install figma +``` +Also requires the **Figma MCP server** connected. + +**Trigger phrase:** Ask Claude to generate or set up design system rules for your project. diff --git a/figma-design-system-rules/SKILL.md b/figma-design-system-rules/SKILL.md new file mode 100644 index 00000000..58b40308 --- /dev/null +++ b/figma-design-system-rules/SKILL.md @@ -0,0 +1,211 @@ +--- +name: figma-design-system-rules +description: Extract, document, and enforce design system rules from a Figma design system. Use this skill when the user wants to document their design system, create design tokens, establish component usage rules, or ensure code follows a Figma design system. +--- + +# Figma: Design System Rules + +Extract and document design system rules from Figma for use in code implementation. + +## When to Use + +Use when the user: +- Wants to document their Figma design system for developers +- Needs to create a design tokens file from Figma specs +- Wants rules for how components should be used +- Is setting up a new codebase to match an existing Figma design system + +## Design System Components to Document + +### 1. Color Tokens + +Extract all color styles from Figma: + +```ts +// design-tokens/colors.ts +export const colors = { + // Brand + primary: { + 50: '#EFF6FF', + 100: '#DBEAFE', + 500: '#3B82F6', + 600: '#2563EB', + 700: '#1D4ED8', + }, + // Semantic + text: { + primary: '#111827', + secondary: '#6B7280', + disabled: '#D1D5DB', + }, + background: { + default: '#FFFFFF', + subtle: '#F9FAFB', + muted: '#F3F4F6', + }, + status: { + success: '#10B981', + warning: '#F59E0B', + error: '#EF4444', + info: '#3B82F6', + }, +} as const; +``` + +### 2. Typography Tokens + +```ts +export const typography = { + fonts: { + heading: '"Inter", system-ui, sans-serif', + body: '"Inter", system-ui, sans-serif', + mono: '"JetBrains Mono", monospace', + }, + sizes: { + xs: '0.75rem', // 12px + sm: '0.875rem', // 14px + base: '1rem', // 16px + lg: '1.125rem', // 18px + xl: '1.25rem', // 20px + '2xl': '1.5rem', // 24px + '3xl': '1.875rem',// 30px + '4xl': '2.25rem', // 36px + }, + weights: { + normal: 400, + medium: 500, + semibold: 600, + bold: 700, + }, + lineHeights: { + tight: 1.25, + normal: 1.5, + relaxed: 1.75, + }, +} as const; +``` + +### 3. Spacing Scale + +```ts +export const spacing = { + 0: '0', + 1: '4px', + 2: '8px', + 3: '12px', + 4: '16px', + 5: '20px', + 6: '24px', + 8: '32px', + 10: '40px', + 12: '48px', + 16: '64px', + 20: '80px', + 24: '96px', +} as const; +``` + +### 4. Border Radius + +```ts +export const radius = { + none: '0', + sm: '4px', + md: '8px', + lg: '12px', + xl: '16px', + '2xl': '24px', + full: '9999px', +} as const; +``` + +### 5. Shadows + +```ts +export const shadows = { + sm: '0 1px 2px 0 rgba(0, 0, 0, 0.05)', + md: '0 4px 6px -1px rgba(0, 0, 0, 0.1)', + lg: '0 10px 15px -3px rgba(0, 0, 0, 0.1)', + xl: '0 20px 25px -5px rgba(0, 0, 0, 0.1)', +} as const; +``` + +### 6. Breakpoints + +```ts +export const breakpoints = { + sm: '640px', + md: '768px', + lg: '1024px', + xl: '1280px', + '2xl': '1536px', +} as const; +``` + +## Component Usage Rules + +For each component in the design system, document: + +### Component Rule Template +```md +## [ComponentName] + +**Usage:** When to use this component +**Don't use when:** When NOT to use this component + +### Variants +- `default` — Standard usage +- `primary` — Main CTA +- `destructive` — Dangerous actions + +### Sizes +- `sm` — Compact layouts +- `md` — Default +- `lg` — Hero sections + +### States +- `default`, `hover`, `focus`, `disabled`, `loading` + +### Dos and Don'ts +✅ Do: [correct usage] +❌ Don't: [incorrect usage] +``` + +## CSS Custom Properties Export + +For use in CSS/Tailwind projects: +```css +:root { + /* Colors */ + --color-primary: #2563EB; + --color-primary-light: #DBEAFE; + --color-text: #111827; + --color-text-muted: #6B7280; + --color-bg: #FFFFFF; + --color-bg-subtle: #F9FAFB; + + /* Typography */ + --font-sans: 'Inter', system-ui, sans-serif; + --text-sm: 0.875rem; + --text-base: 1rem; + --text-lg: 1.125rem; + + /* Spacing */ + --space-4: 1rem; + --space-8: 2rem; + + /* Radius */ + --radius-md: 0.5rem; + --radius-lg: 0.75rem; + + /* Shadows */ + --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1); +} +``` + +## Notes + +- Ask the user to share Figma design system pages, color styles, and text styles +- Create tokens as a single source of truth — import everywhere +- Document rules that are NOT obvious from the tokens (e.g., "never use red for non-error states") +- For Tailwind projects, translate tokens into `tailwind.config.js` theme extensions diff --git a/figma-implement-design/SKILL.md b/figma-implement-design/SKILL.md new file mode 100644 index 00000000..ec4ac544 --- /dev/null +++ b/figma-implement-design/SKILL.md @@ -0,0 +1,103 @@ +--- +name: figma-implement-design +description: Implement a Figma design as production-ready frontend code. Use this skill when the user shares a Figma design link or screenshot and wants it converted to HTML/CSS, React, or another frontend framework. +--- + +# Figma: Implement Design + +Convert a Figma design into production-ready frontend code. + +## When to Use + +Use when the user: +- Shares a Figma link or screenshot and asks to "implement this" +- Says "build this design" / "code this mockup" +- Wants to convert a visual design to working code + +## Process + +### Step 1: Gather Design Information + +The user must provide one of: +- **Figma URL**: `https://www.figma.com/design/...` or `https://www.figma.com/file/...` +- **Screenshot/image**: Visual of the design to implement +- **Figma Dev Mode export**: CSS properties, component specs + +If only a URL is provided and no Figma MCP is configured, ask the user to: +1. Open Figma Dev Mode (Shift+D or bottom bar → Dev) +2. Share relevant CSS properties, spacing values, colors, and font specs +3. Export relevant assets (icons, images) + +### Step 2: Extract Design Tokens + +Before coding, identify and document: +- **Colors**: Background, text, border, accent colors (as hex/rgb) +- **Typography**: Font family, sizes, weights, line heights +- **Spacing**: Padding, margin, gap values +- **Border radius**: Corner radius values +- **Shadows**: Box shadow values +- **Breakpoints**: Responsive design specs if provided + +Example CSS variables to set up: +```css +:root { + --color-primary: #2563EB; + --color-text: #1F2937; + --color-bg: #F9FAFB; + --font-heading: 'Inter', sans-serif; + --radius-md: 8px; + --spacing-md: 16px; +} +``` + +### Step 3: Identify Components + +Break the design into reusable components: +- Identify repeated UI patterns +- Define component hierarchy (what contains what) +- Note interactive states: hover, active, focus, disabled + +### Step 4: Implement + +Implement using the stack the user specifies. Defaults: +- **No preference**: HTML + CSS (no framework) +- **React asked**: React with CSS modules or Tailwind +- **Vue asked**: Vue 3 SFCs +- **Tailwind available**: Use Tailwind utility classes + +**Implementation priorities:** +1. Layout (flexbox/grid structure matches design) +2. Typography (font, size, weight, color) +3. Colors and backgrounds +4. Spacing (padding, margin, gaps) +5. Border radius and shadows +6. Hover/interactive states +7. Responsive behavior + +### Step 5: Asset Handling + +For images and icons: +- Use placeholder images if real assets aren't provided: `https://placehold.co/400x300` +- For icons: use Lucide React, Heroicons, or inline SVG +- Note which assets need to be replaced with real ones + +## Code Quality Standards + +- Semantic HTML (`
`, `