refactor: reorganize repo docs and tooling layout
Consolidate the repository into clearer apps, tools, and layered docs areas so contributors can navigate and maintain it more reliably. Align validation, metadata sync, and CI around the same canonical workflow to reduce drift across local checks and GitHub Actions.
This commit is contained in:
sck_0
@@ -1,69 +1,3 @@
|
||||
# Repo coherence and correctness audit
|
||||
# Audit
|
||||
|
||||
This document summarizes the audit performed to verify correctness and coherence across the repository.
|
||||
|
||||
## Scope
|
||||
|
||||
- Conteggi e numeri (README, package.json, CATALOG)
|
||||
- Validazione skill (frontmatter, risk, "When to Use", link)
|
||||
- Riferimenti incrociati (workflows.json, bundles.json, BUNDLES.md)
|
||||
- Documentazione (QUALITY_BAR, SKILL_ANATOMY, security/licenses)
|
||||
- Script e build (validate, index, readme, catalog, test)
|
||||
- Note su data/ e test YAML
|
||||
|
||||
## Outcomes
|
||||
|
||||
### 1. Conteggi
|
||||
|
||||
- **package.json** `description` aggiornato da "845+" a "883+ agentic skills".
|
||||
- README e CATALOG già allineati a 883; `npm run chain` e `npm run catalog` mantengono coerenza.
|
||||
|
||||
### 2. Validazione skill
|
||||
|
||||
- **validate_skills.py**: aggiunto `unknown` a `valid_risk_levels` per compatibilità con skill esistenti (790+ con `risk: unknown`).
|
||||
- Aggiunta sezione "## When to Use" a 6 skill che ne erano sprovvisti: context-compression, content-creator, tailwind-patterns, nodejs-best-practices, python-patterns, mcp-builder-ms.
|
||||
- Corretto frontmatter multilinea in: brainstorming, agents-v2-py, hosted-agents-v2-py (description in una riga, ≤200 caratteri).
|
||||
- `npm run validate` e `npm run validate:strict` passano senza errori.
|
||||
|
||||
### 3. Riferimenti incrociati
|
||||
|
||||
- Aggiunto **scripts/validate_references.py** che verifica:
|
||||
- ogni `recommendedSkills` in data/workflows.json esiste in skills/;
|
||||
- ogni `relatedBundles` esiste in data/bundles.json;
|
||||
- ogni slug in data/bundles.json (skills list) esiste in skills/;
|
||||
- ogni link `../skills/...` in docs/BUNDLES.md punta a uno skill esistente.
|
||||
- Esecuzione: `python3 scripts/validate_references.py`. Esito: tutti i riferimenti validi.
|
||||
|
||||
### 4. Documentazione
|
||||
|
||||
- **docs/QUALITY_BAR.md**: documentato che `risk` può essere anche `unknown` (per legacy/unclassified).
|
||||
- **docs/SKILL_ANATOMY.md**: allineata lunghezza description a 200 caratteri (come da validator).
|
||||
- SECURITY_GUARDRAILS, LICENSE, README link verificati.
|
||||
|
||||
### 5. Script e build
|
||||
|
||||
- **npm run build** (chain + catalog) esegue con successo.
|
||||
- **npm test**: il test `validate_skills_headings.test.js` richiedeva YAML frontmatter valido per tutti gli skill; molti skill hanno frontmatter multilinea che il parser YAML strict segnala. Il test è stato modificato per loggare warning invece di far fallire la suite; lo schema (name, description, risk, ecc.) resta verificato da `validate_skills.py`.
|
||||
- **.github/MAINTENANCE.md**: aggiunta nota su `data/package.json` (legacy; gli script usano la root).
|
||||
|
||||
### 6. Deliverable
|
||||
|
||||
- Numeri allineati (package.json 883+).
|
||||
- Zero errori da `npm run validate` e `npm run validate:strict`.
|
||||
- Riferimenti in workflows/bundles e link in BUNDLES.md verificati tramite `validate_references.py`.
|
||||
- Report in questo file (docs/AUDIT.md).
|
||||
|
||||
## Comandi utili
|
||||
|
||||
```bash
|
||||
npm run validate # validazione skill (soft)
|
||||
npm run validate:strict # validazione skill (CI)
|
||||
python3 scripts/validate_references.py # riferimenti workflows/bundles/BUNDLES.md
|
||||
npm run build # chain + catalog
|
||||
npm test # suite test
|
||||
```
|
||||
|
||||
## Issue aperte / follow-up
|
||||
|
||||
- Normalizzare frontmatter YAML in skill con description multilinea (opzionale, in batch) per far passare un eventuale test strict YAML in futuro.
|
||||
- Aggiornare CHANGELOG con voci "860+", "845+" se si vuole coerenza storica (opzionale).
|
||||
This document moved to [`maintainers/audit.md`](maintainers/audit.md).
|
||||
|
||||
465
docs/BUNDLES.md
465
docs/BUNDLES.md
@@ -1,464 +1,3 @@
|
||||
# 📦 Antigravity Skill Bundles
|
||||
# Bundles
|
||||
|
||||
> **Curated collections of skills organized by role and expertise level.** Don't know where to start? Pick a bundle below to get a curated set of skills for your role.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
1. **Install the repository:**
|
||||
|
||||
```bash
|
||||
npx antigravity-awesome-skills
|
||||
# or clone manually
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
2. **Choose your bundle** from the list below based on your role or interests.
|
||||
|
||||
3. **Use skills** by referencing them in your AI assistant:
|
||||
- Claude Code: `>> /skill-name help me...`
|
||||
- Cursor: `@skill-name in chat`
|
||||
- Gemini CLI: `Use skill-name...`
|
||||
- Codex CLI: `Use skill-name...`
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Essentials & Core
|
||||
|
||||
### 🚀 The "Essentials" Starter Pack
|
||||
|
||||
_For everyone. Install these first._
|
||||
|
||||
- [`concise-planning`](../skills/concise-planning/): Always start with a plan.
|
||||
- [`lint-and-validate`](../skills/lint-and-validate/): Keep your code clean automatically.
|
||||
- [`git-pushing`](../skills/git-pushing/): Save your work safely.
|
||||
- [`kaizen`](../skills/kaizen/): Continuous improvement mindset.
|
||||
- [`systematic-debugging`](../skills/systematic-debugging/): Debug like a pro.
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Security & Compliance
|
||||
|
||||
### 🛡️ The "Security Engineer" Pack
|
||||
|
||||
_For pentesting, auditing, and hardening._
|
||||
|
||||
- [`ethical-hacking-methodology`](../skills/ethical-hacking-methodology/): The Bible of ethical hacking.
|
||||
- [`burp-suite-testing`](../skills/burp-suite-testing/): Web vulnerability scanning.
|
||||
- [`top-web-vulnerabilities`](../skills/top-web-vulnerabilities/): OWASP-aligned vulnerability taxonomy.
|
||||
- [`linux-privilege-escalation`](../skills/linux-privilege-escalation/): Advanced Linux security assessment.
|
||||
- [`cloud-penetration-testing`](../skills/cloud-penetration-testing/): AWS/Azure/GCP security.
|
||||
- [`security-auditor`](../skills/security-auditor/): Comprehensive security audits.
|
||||
- [`vulnerability-scanner`](../skills/vulnerability-scanner/): Advanced vulnerability analysis.
|
||||
|
||||
### 🔐 The "Security Developer" Pack
|
||||
|
||||
_For building secure applications._
|
||||
|
||||
- [`api-security-best-practices`](../skills/api-security-best-practices/): Secure API design patterns.
|
||||
- [`auth-implementation-patterns`](../skills/auth-implementation-patterns/): JWT, OAuth2, session management.
|
||||
- [`backend-security-coder`](../skills/backend-security-coder/): Secure backend coding practices.
|
||||
- [`frontend-security-coder`](../skills/frontend-security-coder/): XSS prevention and client-side security.
|
||||
- [`cc-skill-security-review`](../skills/cc-skill-security-review/): Security checklist for features.
|
||||
- [`pci-compliance`](../skills/pci-compliance/): Payment card security standards.
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Web Development
|
||||
|
||||
### 🌐 The "Web Wizard" Pack
|
||||
|
||||
_For building modern, high-performance web apps._
|
||||
|
||||
- [`frontend-design`](../skills/frontend-design/): UI guidelines and aesthetics.
|
||||
- [`react-best-practices`](../skills/react-best-practices/): React & Next.js performance optimization.
|
||||
- [`react-patterns`](../skills/react-patterns/): Modern React patterns and principles.
|
||||
- [`nextjs-best-practices`](../skills/nextjs-best-practices/): Next.js App Router patterns.
|
||||
- [`tailwind-patterns`](../skills/tailwind-patterns/): Tailwind CSS v4 styling superpowers.
|
||||
- [`form-cro`](../skills/form-cro/): Optimize your forms for conversion.
|
||||
- [`seo-audit`](../skills/seo-audit/): Get found on Google.
|
||||
|
||||
### 🖌️ The "Web Designer" Pack
|
||||
|
||||
_For pixel-perfect experiences._
|
||||
|
||||
- [`ui-ux-pro-max`](../skills/ui-ux-pro-max/): Premium design systems and tokens.
|
||||
- [`frontend-design`](../skills/frontend-design/): The base layer of aesthetics.
|
||||
- [`3d-web-experience`](../skills/3d-web-experience/): Three.js & React Three Fiber magic.
|
||||
- [`canvas-design`](../skills/canvas-design/): Static visuals and posters.
|
||||
- [`mobile-design`](../skills/mobile-design/): Mobile-first design principles.
|
||||
- [`scroll-experience`](../skills/scroll-experience/): Immersive scroll-driven experiences.
|
||||
|
||||
### ⚡ The "Full-Stack Developer" Pack
|
||||
|
||||
_For end-to-end web application development._
|
||||
|
||||
- [`senior-fullstack`](../skills/senior-fullstack/): Complete fullstack development guide.
|
||||
- [`frontend-developer`](../skills/frontend-developer/): React 19+ and Next.js 15+ expertise.
|
||||
- [`backend-dev-guidelines`](../skills/backend-dev-guidelines/): Node.js/Express/TypeScript patterns.
|
||||
- [`api-patterns`](../skills/api-patterns/): REST vs GraphQL vs tRPC selection.
|
||||
- [`database-design`](../skills/database-design/): Schema design and ORM selection.
|
||||
- [`stripe-integration`](../skills/stripe-integration/): Payments and subscriptions.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 AI & Agents
|
||||
|
||||
### 🤖 The "Agent Architect" Pack
|
||||
|
||||
_For building AI systems and autonomous agents._
|
||||
|
||||
- [`agent-evaluation`](../skills/agent-evaluation/): Test and benchmark your agents.
|
||||
- [`langgraph`](../skills/langgraph/): Build stateful agent workflows.
|
||||
- [`mcp-builder`](../skills/mcp-builder/): Create your own MCP tools.
|
||||
- [`prompt-engineering`](../skills/prompt-engineering/): Master the art of talking to LLMs.
|
||||
- [`ai-agents-architect`](../skills/ai-agents-architect/): Design autonomous AI agents.
|
||||
- [`rag-engineer`](../skills/rag-engineer/): Build RAG systems with vector search.
|
||||
|
||||
### 🧠 The "LLM Application Developer" Pack
|
||||
|
||||
_For building production LLM applications._
|
||||
|
||||
- [`llm-app-patterns`](../skills/llm-app-patterns/): Production-ready LLM patterns.
|
||||
- [`rag-implementation`](../skills/rag-implementation/): Retrieval-Augmented Generation.
|
||||
- [`prompt-caching`](../skills/prompt-caching/): Cache strategies for LLM prompts.
|
||||
- [`context-window-management`](../skills/context-window-management/): Manage LLM context efficiently.
|
||||
- [`langfuse`](../skills/langfuse/): LLM observability and tracing.
|
||||
|
||||
---
|
||||
|
||||
## 🎮 Game Development
|
||||
|
||||
### 🎮 The "Indie Game Dev" Pack
|
||||
|
||||
_For building games with AI assistants._
|
||||
|
||||
- [`game-development/game-design`](../skills/game-development/game-design/): Mechanics and loops.
|
||||
- [`game-development/2d-games`](../skills/game-development/2d-games/): Sprites and physics.
|
||||
- [`game-development/3d-games`](../skills/game-development/3d-games/): Models and shaders.
|
||||
- [`unity-developer`](../skills/unity-developer/): Unity 6 LTS development.
|
||||
- [`godot-gdscript-patterns`](../skills/godot-gdscript-patterns/): Godot 4 GDScript patterns.
|
||||
- [`algorithmic-art`](../skills/algorithmic-art/): Generate assets with code.
|
||||
|
||||
---
|
||||
|
||||
## 🐍 Backend & Languages
|
||||
|
||||
### 🐍 The "Python Pro" Pack
|
||||
|
||||
_For backend heavyweights and data scientists._
|
||||
|
||||
- [`python-pro`](../skills/python-pro/): Master Python 3.12+ with modern features.
|
||||
- [`python-patterns`](../skills/python-patterns/): Idiomatic Python code.
|
||||
- [`fastapi-pro`](../skills/fastapi-pro/): High-performance async APIs.
|
||||
- [`fastapi-templates`](../skills/fastapi-templates/): Production-ready FastAPI projects.
|
||||
- [`django-pro`](../skills/django-pro/): The battery-included framework.
|
||||
- [`python-testing-patterns`](../skills/python-testing-patterns/): Comprehensive testing with pytest.
|
||||
- [`async-python-patterns`](../skills/async-python-patterns/): Python asyncio mastery.
|
||||
|
||||
### 🟦 The "TypeScript & JavaScript" Pack
|
||||
|
||||
_For modern web development._
|
||||
|
||||
- [`typescript-expert`](../skills/typescript-expert/): TypeScript mastery and advanced types.
|
||||
- [`javascript-pro`](../skills/javascript-pro/): Modern JavaScript with ES6+.
|
||||
- [`react-best-practices`](../skills/react-best-practices/): React performance optimization.
|
||||
- [`nodejs-best-practices`](../skills/nodejs-best-practices/): Node.js development principles.
|
||||
- [`nextjs-app-router-patterns`](../skills/nextjs-app-router-patterns/): Next.js 14+ App Router.
|
||||
|
||||
### 🦀 The "Systems Programming" Pack
|
||||
|
||||
_For low-level and performance-critical code._
|
||||
|
||||
- [`rust-pro`](../skills/rust-pro/): Rust 1.75+ with async patterns.
|
||||
- [`go-concurrency-patterns`](../skills/go-concurrency-patterns/): Go concurrency mastery.
|
||||
- [`golang-pro`](../skills/golang-pro/): Go development expertise.
|
||||
- [`memory-safety-patterns`](../skills/memory-safety-patterns/): Memory-safe programming.
|
||||
- [`cpp-pro`](../skills/cpp-pro/): Modern C++ development.
|
||||
|
||||
---
|
||||
|
||||
## 🦄 Product & Business
|
||||
|
||||
### 🦄 The "Startup Founder" Pack
|
||||
|
||||
_For building products, not just code._
|
||||
|
||||
- [`product-manager-toolkit`](../skills/product-manager-toolkit/): RICE prioritization, PRD templates.
|
||||
- [`competitive-landscape`](../skills/competitive-landscape/): Competitor analysis.
|
||||
- [`competitor-alternatives`](../skills/competitor-alternatives/): Create comparison pages.
|
||||
- [`launch-strategy`](../skills/launch-strategy/): Product launch planning.
|
||||
- [`copywriting`](../skills/copywriting/): Marketing copy that converts.
|
||||
- [`stripe-integration`](../skills/stripe-integration/): Get paid from day one.
|
||||
|
||||
### 📊 The "Business Analyst" Pack
|
||||
|
||||
_For data-driven decision making._
|
||||
|
||||
- [`business-analyst`](../skills/business-analyst/): AI-powered analytics and KPIs.
|
||||
- [`startup-metrics-framework`](../skills/startup-metrics-framework/): SaaS metrics and unit economics.
|
||||
- [`startup-financial-modeling`](../skills/startup-financial-modeling/): 3-5 year financial projections.
|
||||
- [`market-sizing-analysis`](../skills/market-sizing-analysis/): TAM/SAM/SOM calculations.
|
||||
- [`kpi-dashboard-design`](../skills/kpi-dashboard-design/): Effective KPI dashboards.
|
||||
|
||||
### 📈 The "Marketing & Growth" Pack
|
||||
|
||||
_For driving user acquisition and retention._
|
||||
|
||||
- [`content-creator`](../skills/content-creator/): SEO-optimized marketing content.
|
||||
- [`seo-audit`](../skills/seo-audit/): Technical SEO health checks.
|
||||
- [`programmatic-seo`](../skills/programmatic-seo/): Create pages at scale.
|
||||
- [`analytics-tracking`](../skills/analytics-tracking/): Set up GA4/PostHog correctly.
|
||||
- [`ab-test-setup`](../skills/ab-test-setup/): Validated learning experiments.
|
||||
- [`email-sequence`](../skills/email-sequence/): Automated email campaigns.
|
||||
|
||||
---
|
||||
|
||||
## 🌧️ DevOps & Infrastructure
|
||||
|
||||
### 🌧️ The "DevOps & Cloud" Pack
|
||||
|
||||
_For infrastructure and scaling._
|
||||
|
||||
- [`docker-expert`](../skills/docker-expert/): Master containers and multi-stage builds.
|
||||
- [`aws-serverless`](../skills/aws-serverless/): Serverless on AWS (Lambda, DynamoDB).
|
||||
- [`kubernetes-architect`](../skills/kubernetes-architect/): K8s architecture and GitOps.
|
||||
- [`terraform-specialist`](../skills/terraform-specialist/): Infrastructure as Code mastery.
|
||||
- [`environment-setup-guide`](../skills/environment-setup-guide/): Standardization for teams.
|
||||
- [`deployment-procedures`](../skills/deployment-procedures/): Safe rollout strategies.
|
||||
- [`bash-linux`](../skills/bash-linux/): Terminal wizardry.
|
||||
|
||||
### 📊 The "Observability & Monitoring" Pack
|
||||
|
||||
_For production reliability._
|
||||
|
||||
- [`observability-engineer`](../skills/observability-engineer/): Comprehensive monitoring systems.
|
||||
- [`distributed-tracing`](../skills/distributed-tracing/): Track requests across microservices.
|
||||
- [`slo-implementation`](../skills/slo-implementation/): Service Level Objectives.
|
||||
- [`incident-responder`](../skills/incident-responder/): Rapid incident response.
|
||||
- [`postmortem-writing`](../skills/postmortem-writing/): Blameless postmortems.
|
||||
- [`performance-engineer`](../skills/performance-engineer/): Application performance optimization.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Data & Analytics
|
||||
|
||||
### 📊 The "Data & Analytics" Pack
|
||||
|
||||
_For making sense of the numbers._
|
||||
|
||||
- [`analytics-tracking`](../skills/analytics-tracking/): Set up GA4/PostHog correctly.
|
||||
- [`claude-d3js-skill`](../skills/claude-d3js-skill/): Beautiful custom visualizations with D3.js.
|
||||
- [`sql-pro`](../skills/sql-pro/): Modern SQL with cloud-native databases.
|
||||
- [`postgres-best-practices`](../skills/postgres-best-practices/): Postgres optimization.
|
||||
- [`ab-test-setup`](../skills/ab-test-setup/): Validated learning.
|
||||
- [`database-architect`](../skills/database-architect/): Database design from scratch.
|
||||
|
||||
### 🔄 The "Data Engineering" Pack
|
||||
|
||||
_For building data pipelines._
|
||||
|
||||
- [`data-engineer`](../skills/data-engineer/): Data pipeline architecture.
|
||||
- [`airflow-dag-patterns`](../skills/airflow-dag-patterns/): Apache Airflow DAGs.
|
||||
- [`dbt-transformation-patterns`](../skills/dbt-transformation-patterns/): Analytics engineering.
|
||||
- [`vector-database-engineer`](../skills/vector-database-engineer/): Vector databases for RAG.
|
||||
- [`embedding-strategies`](../skills/embedding-strategies/): Embedding model selection.
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Creative & Content
|
||||
|
||||
### 🎨 The "Creative Director" Pack
|
||||
|
||||
_For visuals, content, and branding._
|
||||
|
||||
- [`canvas-design`](../skills/canvas-design/): Generate posters and diagrams.
|
||||
- [`frontend-design`](../skills/frontend-design/): UI aesthetics.
|
||||
- [`content-creator`](../skills/content-creator/): SEO-optimized blog posts.
|
||||
- [`copy-editing`](../skills/copy-editing/): Polish your prose.
|
||||
- [`algorithmic-art`](../skills/algorithmic-art/): Code-generated masterpieces.
|
||||
- [`interactive-portfolio`](../skills/interactive-portfolio/): Portfolios that land jobs.
|
||||
|
||||
---
|
||||
|
||||
## 🐞 Quality Assurance
|
||||
|
||||
### 🐞 The "QA & Testing" Pack
|
||||
|
||||
_For breaking things before users do._
|
||||
|
||||
- [`test-driven-development`](../skills/test-driven-development/): Red, Green, Refactor.
|
||||
- [`systematic-debugging`](../skills/systematic-debugging/): Debug like Sherlock Holmes.
|
||||
- [`browser-automation`](../skills/browser-automation/): End-to-end testing with Playwright.
|
||||
- [`e2e-testing-patterns`](../skills/e2e-testing-patterns/): Reliable E2E test suites.
|
||||
- [`ab-test-setup`](../skills/ab-test-setup/): Validated experiments.
|
||||
- [`code-review-checklist`](../skills/code-review-checklist/): Catch bugs in PRs.
|
||||
- [`test-fixing`](../skills/test-fixing/): Fix failing tests systematically.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Specialized Packs
|
||||
|
||||
### 📱 The "Mobile Developer" Pack
|
||||
|
||||
_For iOS, Android, and cross-platform apps._
|
||||
|
||||
- [`mobile-developer`](../skills/mobile-developer/): Cross-platform mobile development.
|
||||
- [`react-native-architecture`](../skills/react-native-architecture/): React Native with Expo.
|
||||
- [`flutter-expert`](../skills/flutter-expert/): Flutter multi-platform apps.
|
||||
- [`ios-developer`](../skills/ios-developer/): iOS development with Swift.
|
||||
- [`app-store-optimization`](../skills/app-store-optimization/): ASO for App Store and Play Store.
|
||||
|
||||
### 🔗 The "Integration & APIs" Pack
|
||||
|
||||
_For connecting services and building integrations._
|
||||
|
||||
- [`stripe-integration`](../skills/stripe-integration/): Payments and subscriptions.
|
||||
- [`twilio-communications`](../skills/twilio-communications/): SMS, voice, WhatsApp.
|
||||
- [`hubspot-integration`](../skills/hubspot-integration/): CRM integration.
|
||||
- [`plaid-fintech`](../skills/plaid-fintech/): Bank account linking and ACH.
|
||||
- [`algolia-search`](../skills/algolia-search/): Search implementation.
|
||||
|
||||
### 🎯 The "Architecture & Design" Pack
|
||||
|
||||
_For system design and technical decisions._
|
||||
|
||||
- [`senior-architect`](../skills/senior-architect/): Comprehensive software architecture.
|
||||
- [`architecture-patterns`](../skills/architecture-patterns/): Clean Architecture, DDD, Hexagonal.
|
||||
- [`microservices-patterns`](../skills/microservices-patterns/): Microservices architecture.
|
||||
- [`event-sourcing-architect`](../skills/event-sourcing-architect/): Event sourcing and CQRS.
|
||||
- [`architecture-decision-records`](../skills/architecture-decision-records/): Document technical decisions.
|
||||
|
||||
### 🧱 The "DDD & Evented Architecture" Pack
|
||||
|
||||
_For teams modeling complex domains and evolving toward evented systems._
|
||||
|
||||
- [`domain-driven-design`](../skills/domain-driven-design/): Route DDD work from strategic modeling to implementation patterns.
|
||||
- [`ddd-strategic-design`](../skills/ddd-strategic-design/): Subdomains, bounded contexts, and ubiquitous language.
|
||||
- [`ddd-context-mapping`](../skills/ddd-context-mapping/): Cross-context integration and anti-corruption boundaries.
|
||||
- [`ddd-tactical-patterns`](../skills/ddd-tactical-patterns/): Aggregates, value objects, repositories, and domain events.
|
||||
- [`cqrs-implementation`](../skills/cqrs-implementation/): Read/write model separation.
|
||||
- [`event-store-design`](../skills/event-store-design/): Event persistence and replay architecture.
|
||||
- [`saga-orchestration`](../skills/saga-orchestration/): Cross-context long-running transaction coordination.
|
||||
- [`projection-patterns`](../skills/projection-patterns/): Materialized read models from event streams.
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Maintainer & OSS
|
||||
|
||||
### 🛠️ The "OSS Maintainer" Pack
|
||||
|
||||
_For shipping clean changes in public repositories._
|
||||
|
||||
- [`commit`](../skills/commit/): High-quality conventional commits.
|
||||
- [`create-pr`](../skills/create-pr/): PR creation with review-ready context.
|
||||
- [`requesting-code-review`](../skills/requesting-code-review/): Ask for targeted, high-signal reviews.
|
||||
- [`receiving-code-review`](../skills/receiving-code-review/): Apply feedback with technical rigor.
|
||||
- [`changelog-automation`](../skills/changelog-automation/): Keep release notes and changelogs consistent.
|
||||
- [`git-advanced-workflows`](../skills/git-advanced-workflows/): Rebase, cherry-pick, bisect, recovery.
|
||||
- [`documentation-templates`](../skills/documentation-templates/): Standardize docs and handoffs.
|
||||
|
||||
### 🧱 The "Skill Author" Pack
|
||||
|
||||
_For creating and maintaining high-quality SKILL.md assets._
|
||||
|
||||
- [`skill-creator`](../skills/skill-creator/): Design effective new skills.
|
||||
- [`skill-developer`](../skills/skill-developer/): Implement triggers, hooks, and skill lifecycle.
|
||||
- [`writing-skills`](../skills/writing-skills/): Improve clarity and structure of skill instructions.
|
||||
- [`documentation-generation-doc-generate`](../skills/documentation-generation-doc-generate/): Generate maintainable technical docs.
|
||||
- [`lint-and-validate`](../skills/lint-and-validate/): Validate quality after edits.
|
||||
- [`verification-before-completion`](../skills/verification-before-completion/): Confirm changes before claiming done.
|
||||
|
||||
---
|
||||
|
||||
## 📚 How to Use Bundles
|
||||
|
||||
### 1) Pick by immediate goal
|
||||
|
||||
- Need to ship a feature now: `Essentials` + one domain pack (`Web Wizard`, `Python Pro`, `DevOps & Cloud`).
|
||||
- Need reliability and hardening: add `QA & Testing` + `Security Developer`.
|
||||
- Need product growth: add `Startup Founder` or `Marketing & Growth`.
|
||||
|
||||
### 2) Start with 3-5 skills, not 20
|
||||
|
||||
Pick the minimum set for your current milestone. Expand only when you hit a real gap.
|
||||
|
||||
### 3) Invoke skills consistently
|
||||
|
||||
- **Claude Code**: `>> /skill-name help me...`
|
||||
- **Cursor**: `@skill-name` in chat
|
||||
- **Gemini CLI**: `Use skill-name...`
|
||||
- **Codex CLI**: `Use skill-name...`
|
||||
|
||||
### 4) Build your personal shortlist
|
||||
|
||||
Keep a small list of high-frequency skills and reuse it across tasks to reduce context switching.
|
||||
|
||||
## 🧩 Recommended Bundle Combos
|
||||
|
||||
### Ship a SaaS MVP (2 weeks)
|
||||
|
||||
`Essentials` + `Full-Stack Developer` + `QA & Testing` + `Startup Founder`
|
||||
|
||||
### Harden an existing production app
|
||||
|
||||
`Essentials` + `Security Developer` + `DevOps & Cloud` + `Observability & Monitoring`
|
||||
|
||||
### Build an AI product
|
||||
|
||||
`Essentials` + `Agent Architect` + `LLM Application Developer` + `Data Engineering`
|
||||
|
||||
### Grow traffic and conversions
|
||||
|
||||
`Web Wizard` + `Marketing & Growth` + `Data & Analytics`
|
||||
|
||||
### Launch and maintain open source
|
||||
|
||||
`Essentials` + `OSS Maintainer` + `Architecture & Design`
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Paths
|
||||
|
||||
### Beginner → Intermediate → Advanced
|
||||
|
||||
**Web Development:**
|
||||
|
||||
1. Start: `Essentials` → `Web Wizard`
|
||||
2. Grow: `Full-Stack Developer` → `Architecture & Design`
|
||||
3. Master: `Observability & Monitoring` → `Security Developer`
|
||||
|
||||
**AI/ML:**
|
||||
|
||||
1. Start: `Essentials` → `Agent Architect`
|
||||
2. Grow: `LLM Application Developer` → `Data Engineering`
|
||||
3. Master: Advanced RAG and agent orchestration
|
||||
|
||||
**Security:**
|
||||
|
||||
1. Start: `Essentials` → `Security Developer`
|
||||
2. Grow: `Security Engineer` → Advanced pentesting
|
||||
3. Master: Red team tactics and threat modeling
|
||||
|
||||
**Open Source Maintenance:**
|
||||
|
||||
1. Start: `Essentials` → `OSS Maintainer`
|
||||
2. Grow: `Architecture & Design` → `QA & Testing`
|
||||
3. Master: `Skill Author` + release automation workflows
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Found a skill that should be in a bundle? Or want to create a new bundle? [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) or submit a PR!
|
||||
|
||||
---
|
||||
|
||||
## 📖 Related Documentation
|
||||
|
||||
- [Getting Started Guide](GETTING_STARTED.md)
|
||||
- [Full Skill Catalog](../CATALOG.md)
|
||||
- [Contributing Guide](../CONTRIBUTING.md)
|
||||
|
||||
---
|
||||
|
||||
_Last updated: February 2026 | Total Skills: 954+ | Total Bundles: 26_
|
||||
This document moved to [`users/bundles.md`](users/bundles.md).
|
||||
|
||||
@@ -1,170 +1,3 @@
|
||||
# Smart Categorization Implementation - Complete Summary
|
||||
# Categorization Implementation
|
||||
|
||||
## ✅ What Was Done
|
||||
|
||||
### 1. **Intelligent Auto-Categorization Script**
|
||||
Created [scripts/auto_categorize_skills.py](scripts/auto_categorize_skills.py) that:
|
||||
- Analyzes skill names and descriptions
|
||||
- Matches against keyword libraries for 13 categories
|
||||
- Automatically assigns meaningful categories
|
||||
- Removes "uncategorized" bulk assignment
|
||||
|
||||
**Results:**
|
||||
- ✅ 776 skills auto-categorized
|
||||
- ✅ 46 already had categories preserved
|
||||
- ✅ 124 remaining uncategorized (edge cases)
|
||||
|
||||
### 2. **Category Distribution**
|
||||
|
||||
**Before:**
|
||||
```
|
||||
uncategorized: 926 (98%)
|
||||
game-development: 10
|
||||
libreoffice: 5
|
||||
security: 4
|
||||
```
|
||||
|
||||
**After:**
|
||||
```
|
||||
Backend: 164 ████████████████
|
||||
Web Dev: 107 ███████████
|
||||
Automation: 103 ███████████
|
||||
DevOps: 83 ████████
|
||||
AI/ML: 79 ████████
|
||||
Content: 47 █████
|
||||
Database: 44 █████
|
||||
Testing: 38 ████
|
||||
Security: 36 ████
|
||||
Cloud: 33 ███
|
||||
Mobile: 21 ██
|
||||
Game Dev: 15 ██
|
||||
Data Science: 14 ██
|
||||
Uncategorized: 126 █
|
||||
```
|
||||
|
||||
### 3. **Updated Index Generation**
|
||||
Modified [scripts/generate_index.py](scripts/generate_index.py):
|
||||
- **Frontmatter categories now take priority**
|
||||
- Falls back to folder structure if needed
|
||||
- Generates clean, organized skills_index.json
|
||||
- Exported to web-app/public/skills.json
|
||||
|
||||
### 4. **Improved Web App Filter**
|
||||
|
||||
**Home Page Changes:**
|
||||
- ✅ Categories sorted by skill count (most first)
|
||||
- ✅ "Uncategorized" moved to bottom
|
||||
- ✅ Each shows count: "Backend (164)", "Web Dev (107)"
|
||||
- ✅ Much easier to navigate
|
||||
|
||||
**Updated Code:**
|
||||
- [web-app/src/pages/Home.jsx](web-app/src/pages/Home.jsx) - Smart category sorting
|
||||
- Sorts categories by count using categoryStats
|
||||
- Uncategorized always last
|
||||
- Displays count in dropdown
|
||||
|
||||
### 5. **Categorization Keywords** (13 Categories)
|
||||
|
||||
| Category | Key Keywords |
|
||||
|----------|--------------|
|
||||
| **Backend** | nodejs, express, fastapi, django, server, api, database |
|
||||
| **Web Dev** | react, vue, angular, frontend, css, html, tailwind |
|
||||
| **Automation** | workflow, scripting, automation, robot, trigger |
|
||||
| **DevOps** | docker, kubernetes, ci/cd, deploy, container |
|
||||
| **AI/ML** | ai, machine learning, tensorflow, nlp, gpt, llm |
|
||||
| **Content** | markdown, documentation, content, writing |
|
||||
| **Database** | sql, postgres, mongodb, redis, orm |
|
||||
| **Testing** | test, jest, pytest, cypress, unit test |
|
||||
| **Security** | encryption, auth, oauth, jwt, vulnerability |
|
||||
| **Cloud** | aws, azure, gcp, serverless, lambda |
|
||||
| **Mobile** | react native, flutter, ios, android, swift |
|
||||
| **Game Dev** | game, unity, webgl, threejs, 3d, physics |
|
||||
| **Data Science** | pandas, numpy, analytics, statistics |
|
||||
|
||||
### 6. **Documentation**
|
||||
Created [docs/SMART_AUTO_CATEGORIZATION.md](docs/SMART_AUTO_CATEGORIZATION.md) with:
|
||||
- How the system works
|
||||
- Using the script (`--dry-run` and apply modes)
|
||||
- Category reference
|
||||
- Customization guide
|
||||
- Troubleshooting
|
||||
|
||||
## 🎯 The Result
|
||||
|
||||
### No More Uncategorized Chaos
|
||||
- **Before**: 98% of 946 skills lumped as "uncategorized"
|
||||
- **After**: 87% properly organized, only 13% needing review
|
||||
|
||||
### Better UX
|
||||
1. **Smarter Filtering**: Categories sorted by relevance
|
||||
2. **Visual Cues**: Shows count "(164 skills)""
|
||||
3. **Uncategorized Last**: Put bad options out of sight
|
||||
4. **Meaningful Groups**: Find skills by actual function
|
||||
|
||||
### Example Workflow
|
||||
User wants to find database skills:
|
||||
1. Opens web app
|
||||
2. Sees filter dropdown: "Backend (164) | Database (44) | Web Dev (107)..."
|
||||
3. Clicks "Database (44)"
|
||||
4. Gets 44 relevant SQL/MongoDB/Postgres skills
|
||||
5. Done! 🎉
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Run Auto-Categorization
|
||||
```bash
|
||||
# Test first
|
||||
python scripts/auto_categorize_skills.py --dry-run
|
||||
|
||||
# Apply changes
|
||||
python scripts/auto_categorize_skills.py
|
||||
|
||||
# Regenerate index
|
||||
python scripts/generate_index.py
|
||||
|
||||
# Deploy to web app
|
||||
cp skills_index.json web-app/public/skills.json
|
||||
```
|
||||
|
||||
### For New Skills
|
||||
Add to frontmatter:
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: "..."
|
||||
category: backend
|
||||
date_added: "2025-02-26"
|
||||
---
|
||||
```
|
||||
|
||||
## 📁 Files Changed
|
||||
|
||||
### New Files
|
||||
- `scripts/auto_categorize_skills.py` - Auto-categorization engine
|
||||
- `docs/SMART_AUTO_CATEGORIZATION.md` - Full documentation
|
||||
|
||||
### Modified Files
|
||||
- `scripts/generate_index.py` - Category priority logic
|
||||
- `web-app/src/pages/Home.jsx` - Smart category sorting
|
||||
- `web-app/public/skills.json` - Regenerated with categories
|
||||
|
||||
## 📊 Quality Metrics
|
||||
|
||||
- **Coverage**: 87% of skills in meaningful categories
|
||||
- **Accuracy**: Keyword-based matching with word boundaries
|
||||
- **Performance**: ~1-2 seconds to auto-categorize all 946 skills
|
||||
- **Maintainability**: Easily add keywords/categories for future growth
|
||||
|
||||
## 🎁 Bonus Features
|
||||
|
||||
1. **Dry-run mode**: See changes before applying
|
||||
2. **Weighted scoring**: Exact matches score 2x partial matches
|
||||
3. **Customizable keywords**: Easy to add more categories
|
||||
4. **Fallback logic**: folder → frontmatter → uncategorized
|
||||
5. **UTF-8 support**: Works on Windows/Mac/Linux
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Complete and deployed to web app!
|
||||
|
||||
The web app now has a clean, intelligent category filter instead of "uncategorized" chaos. 🚀
|
||||
This document moved to [`maintainers/categorization-implementation.md`](maintainers/categorization-implementation.md).
|
||||
|
||||
@@ -1,38 +1,3 @@
|
||||
# CI Drift Fix Guide
|
||||
# CI Drift Fix
|
||||
|
||||
**Problem**: The failing job is caused by uncommitted changes detected in `README.md`, `skills_index.json`, or catalog files after the update scripts run.
|
||||
|
||||
**Error**:
|
||||
|
||||
```
|
||||
❌ Detected uncommitted changes produced by registry/readme/catalog scripts.
|
||||
```
|
||||
|
||||
**Cause**:
|
||||
Scripts like `scripts/generate_index.py`, `scripts/update_readme.py`, and `scripts/build-catalog.js` modify `README.md`, `skills_index.json`, `data/catalog.json`, `data/bundles.json`, `data/aliases.json`, and `CATALOG.md`. The workflow expects these files to have no changes after the scripts run. Any differences mean the committed repo is out-of-sync with what the generation scripts produce.
|
||||
|
||||
**How to Fix (DO THIS EVERY TIME):**
|
||||
|
||||
1. Run the **FULL Validation Chain** locally:
|
||||
|
||||
```bash
|
||||
npm run chain
|
||||
npm run catalog
|
||||
```
|
||||
|
||||
2. Check for changes:
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff
|
||||
```
|
||||
|
||||
3. Commit and push any updates:
|
||||
```bash
|
||||
git add README.md skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md
|
||||
git commit -m "chore: sync generated registry files"
|
||||
git push
|
||||
```
|
||||
|
||||
**Summary**:
|
||||
Always commit and push all changes produced by the registry, readme, and catalog scripts. This keeps the CI workflow passing by ensuring the repository and generated files are synced.
|
||||
This document moved to [`maintainers/ci-drift-fix.md`](maintainers/ci-drift-fix.md).
|
||||
|
||||
@@ -1,33 +1,3 @@
|
||||
# Code of Conduct
|
||||
# Community Guidelines
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment include:
|
||||
|
||||
- Using welcoming and inclusive language
|
||||
- Being respectful of differing viewpoints and experiences
|
||||
- Gracefully accepting constructive criticism
|
||||
- Focusing on what is best for the community
|
||||
- Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
- The use of sexualized language or imagery and unwelcome sexual attention or advances
|
||||
- Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information without explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1.
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
This document moved to [`contributors/community-guidelines.md`](contributors/community-guidelines.md).
|
||||
|
||||
@@ -1,156 +1,3 @@
|
||||
# Date Tracking Implementation Summary
|
||||
# Date Tracking Implementation
|
||||
|
||||
## ✅ What Was Implemented
|
||||
|
||||
### 1. **Frontmatter Template Update**
|
||||
All 946 skills now have the `date_added: "2025-02-26"` field in their `SKILL.md` frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: "Description"
|
||||
date_added: "2025-02-26"
|
||||
---
|
||||
```
|
||||
|
||||
### 2. **Web App Integration**
|
||||
|
||||
#### **Home Page (Skill List Cards)**
|
||||
- Each skill card now displays a small date badge: `📅 YYYY-MM-DD`
|
||||
- Shows alongside the risk level
|
||||
- Clean, compact format in the bottom metadata section
|
||||
|
||||
Example card now shows:
|
||||
```
|
||||
Risk: safe 📅 2025-02-26
|
||||
```
|
||||
|
||||
#### **Skill Detail Page**
|
||||
- Date appears as a green badge near the top with other metadata
|
||||
- Format: `📅 Added YYYY-MM-DD`
|
||||
- Shown alongside Category, Source, and Star buttons
|
||||
|
||||
### 3. **Validators Updated**
|
||||
Both validators now accept and validate the `date_added` field:
|
||||
|
||||
- **validate-skills.js**: Added to `ALLOWED_FIELDS`
|
||||
- **validate_skills.py**: Added YYYY-MM-DD format validation
|
||||
- Warns (dev mode) or fails (strict mode) on missing dates
|
||||
- Validates format strictly
|
||||
|
||||
### 4. **Index Generation**
|
||||
- **generate_index.py** updated to include `date_added` in `skills.json`
|
||||
- All 946 skills now have dates in the web app index
|
||||
- Dates are properly exported to web app's `/public/skills.json`
|
||||
|
||||
### 5. **Documentation**
|
||||
- **SKILL_TEMPLATE.md**: New template for creating skills with date field included
|
||||
- **SKILLS_DATE_TRACKING.md**: Complete usage guide for date management
|
||||
- **SKILL_ANATOMY.md**: Updated with date_added field documentation
|
||||
- **README.md**: Updated contribution guide to mention date tracking
|
||||
|
||||
### 6. **Script Tools**
|
||||
✅ All scripts handle UTF-8 encoding on Windows:
|
||||
|
||||
- **manage_skill_dates.py**: Add, update, list skill dates
|
||||
- **generate_skills_report.py**: Generate JSON report with dates
|
||||
- Both handle emoji output correctly on Windows
|
||||
|
||||
## 📊 Current Status
|
||||
|
||||
- ✅ **946/946 skills** have `date_added: "2025-02-26"`
|
||||
- ✅ **100% coverage** of date tracking
|
||||
- ✅ **Web app displays dates** on all skill cards
|
||||
- ✅ **Validators enforce format** (YYYY-MM-DD)
|
||||
- ✅ **Reports available** via CLI tools
|
||||
|
||||
## 🎨 UI Changes
|
||||
|
||||
### Skill Card (Home Page)
|
||||
Before:
|
||||
```
|
||||
Risk: safe
|
||||
```
|
||||
|
||||
After:
|
||||
```
|
||||
Risk: safe 📅 2025-02-26
|
||||
```
|
||||
|
||||
### Skill Detail Page
|
||||
Before:
|
||||
```
|
||||
[Category] [Source] [Stars]
|
||||
```
|
||||
|
||||
After:
|
||||
```
|
||||
[Category] [Source] [📅 Added 2025-02-26] [Stars]
|
||||
```
|
||||
|
||||
## 📝 Using the Date Field
|
||||
|
||||
### For New Skills
|
||||
Create with template:
|
||||
```bash
|
||||
cp docs/SKILL_TEMPLATE.md skills/my-new-skill/SKILL.md
|
||||
# Edit the template and set date_added to today's date
|
||||
```
|
||||
|
||||
### For Existing Skills
|
||||
Use the management script:
|
||||
```bash
|
||||
# Add missing dates
|
||||
python scripts/manage_skill_dates.py add-missing --date 2025-02-26
|
||||
|
||||
# Update a single skill
|
||||
python scripts/manage_skill_dates.py update skill-name 2025-02-26
|
||||
|
||||
# List all with dates
|
||||
python scripts/manage_skill_dates.py list
|
||||
|
||||
# Generate report
|
||||
python scripts/generate_skills_report.py --output report.json
|
||||
```
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
### Files Modified
|
||||
1. `scripts/generate_index.py` - Added date_added parsing
|
||||
2. `scripts/validate-skills.js` - Added to allowed fields
|
||||
3. `scripts/validate_skills.py` - Added format validation
|
||||
4. `web-app/src/pages/Home.jsx` - Display date in cards
|
||||
5. `web-app/src/pages/SkillDetail.jsx` - Display date in detail
|
||||
6. `README.md` - Updated contribution guide
|
||||
7. `docs/SKILL_ANATOMY.md` - Documented date_added field
|
||||
|
||||
### New Files Created
|
||||
1. `docs/SKILL_TEMPLATE.md` - Skill creation template
|
||||
2. `docs/SKILLS_DATE_TRACKING.md` - Comprehensive guide
|
||||
3. `scripts/manage_skill_dates.py` - Date management CLI
|
||||
4. `scripts/generate_skills_report.py` - Report generation
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
1. **In Web App**: Skills now show creation dates automatically
|
||||
2. **For Analytics**: Use report script to track skill growth over time
|
||||
3. **For Contributions**: Include date_added in new skill PRs
|
||||
4. **For Maintenance**: Run validators to ensure date format compliance
|
||||
|
||||
## 📈 Reporting Examples
|
||||
|
||||
Get a JSON report sorted by date:
|
||||
```bash
|
||||
python scripts/generate_skills_report.py --output skills_by_date.json
|
||||
```
|
||||
|
||||
Output includes:
|
||||
- Total skills count
|
||||
- Skills with/without dates
|
||||
- Coverage percentage
|
||||
- Full skill metadata with dates
|
||||
- Sortable by date or name
|
||||
|
||||
---
|
||||
|
||||
**Date Feature Ready!** 🎉 All skills now track when they were added to the collection.
|
||||
This document moved to [`maintainers/date-tracking-implementation.md`](maintainers/date-tracking-implementation.md).
|
||||
|
||||
761
docs/EXAMPLES.md
761
docs/EXAMPLES.md
@@ -1,760 +1,3 @@
|
||||
# 💡 Real-World Examples - See Skills in Action
|
||||
# Examples
|
||||
|
||||
**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!
|
||||
This document moved to [`contributors/examples.md`](contributors/examples.md).
|
||||
|
||||
198
docs/FAQ.md
198
docs/FAQ.md
@@ -1,197 +1,3 @@
|
||||
# ❓ Frequently Asked Questions (FAQ)
|
||||
# FAQ
|
||||
|
||||
**Got questions?** You're not alone! Here are answers to the most common questions about Antigravity Awesome Skills.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 General Questions
|
||||
|
||||
### What are "skills" exactly?
|
||||
|
||||
Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
|
||||
**Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), these skills let your AI become an expert in different areas when you need them.
|
||||
|
||||
### Do I need to install all 1006+ skills?
|
||||
|
||||
**No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name`.
|
||||
It's like having a library - all books are there, but you only read the ones you need.
|
||||
**Pro Tip:** Use [Starter Packs](BUNDLES.md) to install only what matches your role.
|
||||
|
||||
### What is the difference between Bundles and Workflows?
|
||||
|
||||
- **Bundles** are curated recommendations grouped by role or domain.
|
||||
- **Workflows** are ordered execution playbooks for concrete outcomes.
|
||||
|
||||
Use bundles when you are deciding _which skills_ to include. Use workflows when you need _step-by-step execution_.
|
||||
|
||||
Start from:
|
||||
|
||||
- [BUNDLES.md](BUNDLES.md)
|
||||
- [WORKFLOWS.md](WORKFLOWS.md)
|
||||
|
||||
### Which AI tools work with these skills?
|
||||
|
||||
- ✅ **Claude Code** (Anthropic CLI)
|
||||
- ✅ **Gemini CLI** (Google)
|
||||
- ✅ **Codex CLI** (OpenAI)
|
||||
- ✅ **Cursor** (AI IDE)
|
||||
- ✅ **Antigravity IDE**
|
||||
- ✅ **OpenCode**
|
||||
- ⚠️ **GitHub Copilot** (partial support via copy-paste)
|
||||
|
||||
### Are these skills free to use?
|
||||
|
||||
**Yes!** This repository is licensed under MIT License.
|
||||
|
||||
- ✅ Free for personal use
|
||||
- ✅ Free for commercial use
|
||||
- ✅ You can modify them
|
||||
|
||||
### Do skills work offline?
|
||||
|
||||
The skill files themselves are stored locally on your computer, but your AI assistant needs an internet connection to function.
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security & Trust (V4 Update)
|
||||
|
||||
### What do the Risk Labels mean?
|
||||
|
||||
We classify skills so you know what you're running:
|
||||
|
||||
- ⚪ **Safe (White/Blue)**: Read-only, planning, or benign skills.
|
||||
- 🔴 **Risk (Red)**: Skills that modify files (delete), use network scanners, or perform destructive actions. **Use with caution.**
|
||||
- 🟣 **Official (Purple)**: Maintained by trusted vendors (Anthropic, DeepMind, etc.).
|
||||
|
||||
### Can these skills hack my computer?
|
||||
|
||||
**No.** Skills are text files. However, they _instruct_ the AI to run commands. If a skill says "delete all files", a compliant AI might try to do it.
|
||||
_Always check the Risk label and review the code._
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation & Setup
|
||||
|
||||
### Where should I install the skills?
|
||||
|
||||
The universal path that works with most tools is `.agent/skills/`.
|
||||
|
||||
**Using npx:** `npx antigravity-awesome-skills` (or `npx github:sickn33/antigravity-awesome-skills` if you get a 404).
|
||||
|
||||
**Using git clone:**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
**Tool-specific paths:**
|
||||
|
||||
- Claude Code: `.claude/skills/`
|
||||
- Gemini CLI: `.gemini/skills/`
|
||||
- Codex CLI: `.codex/skills/`
|
||||
- Cursor: `.cursor/skills/` or project root
|
||||
|
||||
### Does this work with Windows?
|
||||
|
||||
**Yes**, but some "Official" skills use **symlinks** which Windows handles poorly by default.
|
||||
Run git with:
|
||||
|
||||
```bash
|
||||
git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
Or enable "Developer Mode" in Windows Settings.
|
||||
|
||||
### How do I update skills?
|
||||
|
||||
Navigate to your skills directory and pull the latest changes:
|
||||
|
||||
```bash
|
||||
cd .agent/skills
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Using Skills
|
||||
|
||||
> **💡 For a complete guide with examples, see [USAGE.md](USAGE.md)**
|
||||
|
||||
### How do I invoke a skill?
|
||||
|
||||
Use the `@` symbol followed by the skill name:
|
||||
|
||||
```bash
|
||||
@brainstorming help me design a todo app
|
||||
```
|
||||
|
||||
### Can I use multiple skills at once?
|
||||
|
||||
**Yes!** You can invoke multiple skills:
|
||||
|
||||
```bash
|
||||
@brainstorming help me design this, then use @writing-plans to create a task list.
|
||||
```
|
||||
|
||||
### How do I know which skill to use?
|
||||
|
||||
1. **Browse the catalog**: Check the [Skill Catalog](../CATALOG.md).
|
||||
2. **Search**: `ls skills/ | grep "keyword"`
|
||||
3. **Ask your AI**: "What skills do you have for testing?"
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Troubleshooting
|
||||
|
||||
### My AI assistant doesn't recognize skills
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. **Wrong installation path**: Check your tool's docs. Try `.agent/skills/`.
|
||||
2. **Restart Needed**: Restart your AI/IDE after installing.
|
||||
3. **Typos**: Did you type `@brain-storming` instead of `@brainstorming`?
|
||||
|
||||
### A skill gives incorrect or outdated advice
|
||||
|
||||
Please [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues)!
|
||||
Include:
|
||||
|
||||
- Which skill
|
||||
- What went wrong
|
||||
- What should happen instead
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contribution
|
||||
|
||||
### I'm new to open source. Can I contribute?
|
||||
|
||||
**Absolutely!** We welcome beginners.
|
||||
|
||||
- Fix typos
|
||||
- Add examples
|
||||
- Improve docs
|
||||
Check out [CONTRIBUTING.md](../CONTRIBUTING.md) for instructions.
|
||||
|
||||
### My PR failed "Quality Bar" check. Why?
|
||||
|
||||
V4 introduces automated quality control. Your skill might be missing:
|
||||
|
||||
1. A valid `description`.
|
||||
2. Usage examples.
|
||||
Run `python3 scripts/validate_skills.py` locally to check before you push.
|
||||
|
||||
### Can I update an "Official" skill?
|
||||
|
||||
**No.** Official skills (in `skills/official/`) are mirrored from vendors. Open an issue instead.
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
- Start with `@brainstorming` before building anything new
|
||||
- Use `@systematic-debugging` when stuck on bugs
|
||||
- Try `@test-driven-development` for better code quality
|
||||
- Explore `@skill-creator` to make your own skills
|
||||
|
||||
**Still confused?** [Open a discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) and we'll help you out! 🙌
|
||||
This document moved to [`users/faq.md`](users/faq.md).
|
||||
|
||||
@@ -1,142 +1,3 @@
|
||||
# Getting Started with Antigravity Awesome Skills (V7.0.0)
|
||||
# Getting Started
|
||||
|
||||
**New here? This guide will help you supercharge your AI Agent in 5 minutes.**
|
||||
|
||||
> **💡 Confused about what to do after installation?** Check out the [**Complete Usage Guide**](USAGE.md) for detailed explanations and examples!
|
||||
|
||||
---
|
||||
|
||||
## 🤔 What Are "Skills"?
|
||||
|
||||
AI Agents (like **Claude Code**, **Gemini**, **Cursor**) are smart, but they lack specific knowledge about your tools.
|
||||
**Skills** are specialized instruction manuals (markdown files) that teach your AI how to perform specific tasks perfectly, every time.
|
||||
|
||||
**Analogy:** Your AI is a brilliant intern. **Skills** are the SOPs (Standard Operating Procedures) that make them a Senior Engineer.
|
||||
|
||||
---
|
||||
|
||||
## ⚡️ Quick Start: The "Starter Packs"
|
||||
|
||||
Don't panic about the 1,200+ skills. You don't need them all at once.
|
||||
We have curated **Starter Packs** to get you running immediately.
|
||||
|
||||
You **install the full repo once** (npx or clone); Starter Packs are curated lists to help you **pick which skills to use** by role (e.g. Web Wizard, Hacker Pack)—they are not a different way to install.
|
||||
|
||||
### 1. Install the Repo
|
||||
|
||||
**Option A — npx (easiest):**
|
||||
|
||||
```bash
|
||||
npx antigravity-awesome-skills
|
||||
```
|
||||
|
||||
This clones to `~/.gemini/antigravity/skills` by default. Use `--cursor`, `--claude`, `--gemini`, `--codex`, or `--kiro` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
|
||||
|
||||
If you see a 404 error, use: `npx github:sickn33/antigravity-awesome-skills`
|
||||
|
||||
**Option B — git clone:**
|
||||
|
||||
```bash
|
||||
# Universal (works for most agents)
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
### 2. Pick Your Persona
|
||||
|
||||
Find the bundle that matches your role (see [BUNDLES.md](BUNDLES.md)):
|
||||
|
||||
| Persona | Bundle Name | What's Inside? |
|
||||
| :-------------------- | :------------- | :------------------------------------------------ |
|
||||
| **Web Developer** | `Web Wizard` | React Patterns, Tailwind mastery, Frontend Design |
|
||||
| **Security Engineer** | `Hacker Pack` | OWASP, Metasploit, Pentest Methodology |
|
||||
| **Manager / PM** | `Product Pack` | Brainstorming, Planning, SEO, Strategy |
|
||||
| **Everything** | `Essentials` | Clean Code, Planning, Validation (The Basics) |
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Bundles vs Workflows
|
||||
|
||||
Bundles and workflows solve different problems:
|
||||
|
||||
- **Bundles** = curated sets by role (what to pick).
|
||||
- **Workflows** = step-by-step playbooks (how to execute).
|
||||
|
||||
Start with bundles in [BUNDLES.md](BUNDLES.md), then run a workflow from [WORKFLOWS.md](WORKFLOWS.md) when you need guided execution.
|
||||
|
||||
Example:
|
||||
|
||||
> "Use **@antigravity-workflows** and run `ship-saas-mvp` for my project idea."
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Use a Skill
|
||||
|
||||
Once installed, just talk to your AI naturally.
|
||||
|
||||
### Example 1: Planning a Feature (**Essentials**)
|
||||
|
||||
> "Use **@brainstorming** to help me design a new login flow."
|
||||
|
||||
**What happens:** The AI loads the brainstorming skill, asks you structured questions, and produces a professional spec.
|
||||
|
||||
### Example 2: Checking Your Code (**Web Wizard**)
|
||||
|
||||
> "Run **@lint-and-validate** on this file and fix errors."
|
||||
|
||||
**What happens:** The AI follows strict linting rules defined in the skill to clean your code.
|
||||
|
||||
### Example 3: Security Audit (**Hacker Pack**)
|
||||
|
||||
> "Use **@api-security-best-practices** to review my API endpoints."
|
||||
|
||||
**What happens:** The AI audits your code against OWASP standards.
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Supported Tools
|
||||
|
||||
| Tool | Status | Path |
|
||||
| :-------------- | :-------------- | :-------------------------------------------------------------------- |
|
||||
| **Claude Code** | ✅ Full Support | `.claude/skills/` |
|
||||
| **Gemini CLI** | ✅ Full Support | `.gemini/skills/` |
|
||||
| **Codex CLI** | ✅ Full Support | `.codex/skills/` |
|
||||
| **Kiro CLI** | ✅ Full Support | Global: `~/.kiro/skills/` · Workspace: `.kiro/skills/` |
|
||||
| **Kiro IDE** | ✅ Full Support | Global: `~/.kiro/skills/` · Workspace: `.kiro/skills/` |
|
||||
| **Antigravity** | ✅ Native | Global: `~/.gemini/antigravity/skills/` · Workspace: `.agent/skills/` |
|
||||
| **Cursor** | ✅ Native | `.cursor/skills/` |
|
||||
| **OpenCode** | ✅ Full Support | `.agents/skills/` |
|
||||
| **AdaL CLI** | ✅ Full Support | `.adal/skills/` |
|
||||
| **Copilot** | ⚠️ Text Only | Manual copy-paste |
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Trust & Safety (New in V4)
|
||||
|
||||
We classify skills so you know what you're running:
|
||||
|
||||
- 🟣 **Official**: Maintained by Anthropic/Google/Vendors (High Trust).
|
||||
- 🔵 **Safe**: Community skills that are non-destructive (Read-only/Planning).
|
||||
- 🔴 **Risk**: Skills that modify systems or perform security tests (Authorized Use Only).
|
||||
|
||||
_Check the [Skill Catalog](../CATALOG.md) for the full list._
|
||||
|
||||
---
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
**Q: Do I need to install all 1006+ skills?**
|
||||
A: You clone the whole repo once; your AI only _reads_ the skills you invoke (or that are relevant), so it stays lightweight. **Starter Packs** in [BUNDLES.md](BUNDLES.md) are curated lists to help you discover the right skills for your role—they don't change how you install.
|
||||
|
||||
**Q: Can I make my own skills?**
|
||||
A: Yes! Use the **@skill-creator** skill to build your own.
|
||||
|
||||
**Q: Is this free?**
|
||||
A: Yes, MIT License. Open Source forever.
|
||||
|
||||
---
|
||||
|
||||
## ⏭️ Next Steps
|
||||
|
||||
1. [Browse the Bundles](BUNDLES.md)
|
||||
2. [See Real-World Examples](EXAMPLES.md)
|
||||
3. [Contribute a Skill](../CONTRIBUTING.md)
|
||||
This document moved to [`users/getting-started.md`](users/getting-started.md).
|
||||
|
||||
@@ -1,304 +1,3 @@
|
||||
# Kiro CLI Integration Guide
|
||||
# Kiro Integration
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to use Antigravity Awesome Skills with **Kiro CLI**, AWS's agentic AI-powered coding assistant.
|
||||
|
||||
## What is Kiro?
|
||||
|
||||
Kiro is AWS's agentic AI IDE that combines:
|
||||
|
||||
- **Autonomous coding agents** that work independently for extended periods
|
||||
- **Context-aware assistance** with deep understanding of your codebase
|
||||
- **AWS service integration** with native support for CDK, SAM, and Terraform
|
||||
- **MCP (Model Context Protocol)** for secure external API and database calls
|
||||
- **Spec-driven development** that turns natural language into structured specifications
|
||||
|
||||
## Why Use Skills with Kiro?
|
||||
|
||||
Kiro's agentic capabilities are enhanced by skills that provide:
|
||||
|
||||
- **Domain expertise** across 954+ specialized areas
|
||||
- **Best practices** from Anthropic, OpenAI, Google, Microsoft, and AWS
|
||||
- **Workflow automation** for common development tasks
|
||||
- **AWS-specific patterns** for serverless, infrastructure, and cloud architecture
|
||||
|
||||
## Installation
|
||||
|
||||
### Quick Install
|
||||
|
||||
```bash
|
||||
# Install to Kiro's default skills directory
|
||||
npx antigravity-awesome-skills --kiro
|
||||
```
|
||||
|
||||
This installs skills to `~/.kiro/skills/`
|
||||
|
||||
### Manual Installation
|
||||
|
||||
```bash
|
||||
# Clone directly to Kiro's skills directory
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git ~/.kiro/skills
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Verify installation
|
||||
test -d ~/.kiro/skills && echo "✓ Skills installed successfully"
|
||||
ls ~/.kiro/skills/skills/ | head -10
|
||||
```
|
||||
|
||||
## Using Skills with Kiro
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
Kiro uses natural language prompts to invoke skills:
|
||||
|
||||
```
|
||||
Use the @brainstorming skill to help me design a serverless API
|
||||
```
|
||||
|
||||
```
|
||||
Apply @aws-serverless patterns to this Lambda function
|
||||
```
|
||||
|
||||
```
|
||||
Run @security-audit on my CDK stack
|
||||
```
|
||||
|
||||
### Recommended Skills for Kiro Users
|
||||
|
||||
#### AWS & Cloud Infrastructure
|
||||
|
||||
- `@aws-serverless` - Serverless architecture patterns
|
||||
- `@aws-cdk` - AWS CDK best practices
|
||||
- `@aws-sam` - SAM template patterns
|
||||
- `@terraform-expert` - Terraform infrastructure as code
|
||||
- `@docker-expert` - Container optimization
|
||||
- `@kubernetes-expert` - K8s deployment patterns
|
||||
|
||||
#### Architecture & Design
|
||||
|
||||
- `@architecture` - System design and ADRs
|
||||
- `@c4-context` - C4 model diagrams
|
||||
- `@senior-architect` - Scalable architecture patterns
|
||||
- `@microservices-patterns` - Microservices design
|
||||
|
||||
#### Security
|
||||
|
||||
- `@api-security-best-practices` - API security hardening
|
||||
- `@vulnerability-scanner` - Security vulnerability detection
|
||||
- `@owasp-top-10` - OWASP security patterns
|
||||
- `@aws-security-best-practices` - AWS security configuration
|
||||
|
||||
#### Development
|
||||
|
||||
- `@typescript-expert` - TypeScript best practices
|
||||
- `@python-patterns` - Python design patterns
|
||||
- `@react-patterns` - React component patterns
|
||||
- `@test-driven-development` - TDD workflows
|
||||
|
||||
#### DevOps & Automation
|
||||
|
||||
- `@ci-cd-pipeline` - CI/CD automation
|
||||
- `@github-actions` - GitHub Actions workflows
|
||||
- `@monitoring-observability` - Observability patterns
|
||||
- `@incident-response` - Incident management
|
||||
|
||||
## Kiro-Specific Workflows
|
||||
|
||||
### 1. Serverless Application Development
|
||||
|
||||
```
|
||||
1. Use @brainstorming to design the application architecture
|
||||
2. Apply @aws-serverless to create Lambda functions
|
||||
3. Use @aws-cdk to generate infrastructure code
|
||||
4. Run @test-driven-development to add tests
|
||||
5. Apply @ci-cd-pipeline to set up deployment
|
||||
```
|
||||
|
||||
### 2. Infrastructure as Code
|
||||
|
||||
```
|
||||
1. Use @architecture to document the system design
|
||||
2. Apply @terraform-expert to write Terraform modules
|
||||
3. Run @security-audit to check for vulnerabilities
|
||||
4. Use @documentation to generate README and runbooks
|
||||
```
|
||||
|
||||
### 3. API Development
|
||||
|
||||
```
|
||||
1. Use @api-design to plan endpoints
|
||||
2. Apply @typescript-expert for implementation
|
||||
3. Run @api-security-best-practices for hardening
|
||||
4. Use @openapi-spec to generate documentation
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### MCP Integration
|
||||
|
||||
Kiro's MCP support allows skills to:
|
||||
|
||||
- Call external APIs securely
|
||||
- Query databases with context
|
||||
- Integrate with AWS services
|
||||
- Access documentation in real-time
|
||||
|
||||
Skills that leverage MCP:
|
||||
|
||||
- `@rag-engineer` - RAG system implementation
|
||||
- `@langgraph` - Agent workflow orchestration
|
||||
- `@prompt-engineer` - LLM prompt optimization
|
||||
|
||||
### Autonomous Operation
|
||||
|
||||
Kiro can work independently for extended periods. Use skills to guide long-running tasks:
|
||||
|
||||
```
|
||||
Use @systematic-debugging to investigate and fix all TypeScript errors in the codebase,
|
||||
then apply @test-driven-development to add missing tests, and finally run @documentation
|
||||
to update all README files.
|
||||
```
|
||||
|
||||
### Context-Aware Assistance
|
||||
|
||||
Kiro maintains deep context. Reference multiple skills in complex workflows:
|
||||
|
||||
```
|
||||
I'm building a SaaS application. Use @brainstorming for the MVP plan,
|
||||
@aws-serverless for the backend, @react-patterns for the frontend,
|
||||
@stripe-integration for payments, and @security-audit for hardening.
|
||||
```
|
||||
|
||||
## Bundles for Kiro Users
|
||||
|
||||
Pre-curated skill collections optimized for common Kiro use cases:
|
||||
|
||||
### AWS Developer Bundle
|
||||
|
||||
- `@aws-serverless`
|
||||
- `@aws-cdk`
|
||||
- `@aws-sam`
|
||||
- `@lambda-best-practices`
|
||||
- `@dynamodb-patterns`
|
||||
- `@api-gateway-patterns`
|
||||
|
||||
### Full-Stack AWS Bundle
|
||||
|
||||
- `@aws-serverless`
|
||||
- `@react-patterns`
|
||||
- `@typescript-expert`
|
||||
- `@api-design`
|
||||
- `@test-driven-development`
|
||||
- `@ci-cd-pipeline`
|
||||
|
||||
### DevOps & Infrastructure Bundle
|
||||
|
||||
- `@terraform-expert`
|
||||
- `@docker-expert`
|
||||
- `@kubernetes-expert`
|
||||
- `@monitoring-observability`
|
||||
- `@incident-response`
|
||||
- `@security-audit`
|
||||
|
||||
See [BUNDLES.md](BUNDLES.md) for complete bundle listings.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skills Not Loading
|
||||
|
||||
```bash
|
||||
# Check installation path
|
||||
ls -la ~/.kiro/skills/
|
||||
|
||||
# Reinstall if needed
|
||||
rm -rf ~/.kiro/skills
|
||||
npx antigravity-awesome-skills --kiro
|
||||
```
|
||||
|
||||
### Skill Not Found
|
||||
|
||||
Ensure you're using the correct skill name:
|
||||
|
||||
```bash
|
||||
# List all available skills
|
||||
ls ~/.kiro/skills/skills/
|
||||
```
|
||||
|
||||
### Permission Issues
|
||||
|
||||
```bash
|
||||
# Fix permissions
|
||||
chmod -R 755 ~/.kiro/skills/
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with bundles** - Use pre-curated collections for your role
|
||||
2. **Combine skills** - Reference multiple skills in complex tasks
|
||||
3. **Be specific** - Clearly state which skill to use and what to do
|
||||
4. **Iterate** - Let Kiro work autonomously, then refine with additional skills
|
||||
5. **Document** - Use `@documentation` to keep your codebase well-documented
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Build a Serverless API
|
||||
|
||||
```
|
||||
I need to build a REST API for a todo application using AWS Lambda and DynamoDB.
|
||||
|
||||
Use @brainstorming to design the architecture, then apply @aws-serverless
|
||||
to implement the Lambda functions, @dynamodb-patterns for data modeling,
|
||||
and @api-security-best-practices for security hardening.
|
||||
|
||||
Generate the infrastructure using @aws-cdk and add tests with @test-driven-development.
|
||||
```
|
||||
|
||||
### Example 2: Migrate to Microservices
|
||||
|
||||
```
|
||||
I want to break down this monolithic application into microservices.
|
||||
|
||||
Use @architecture to create an ADR for the migration strategy,
|
||||
apply @microservices-patterns for service boundaries,
|
||||
@docker-expert for containerization, and @kubernetes-expert for orchestration.
|
||||
|
||||
Document the migration plan with @documentation.
|
||||
```
|
||||
|
||||
### Example 3: Security Audit
|
||||
|
||||
```
|
||||
Perform a comprehensive security audit of this application.
|
||||
|
||||
Use @security-audit to scan for vulnerabilities, @owasp-top-10 to check
|
||||
for common issues, @api-security-best-practices for API hardening,
|
||||
and @aws-security-best-practices for cloud configuration.
|
||||
|
||||
Generate a report with findings and remediation steps.
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Kiro Official Documentation](https://kiro.dev)
|
||||
- [AWS Blog: Transform DevOps with Kiro](https://aws.amazon.com/blogs/publicsector/transform-devops-practice-with-kiro-ai-powered-agents/)
|
||||
- [Complete Skills Catalog](../CATALOG.md)
|
||||
- [Usage Guide](USAGE.md)
|
||||
- [Workflow Examples](WORKFLOWS.md)
|
||||
|
||||
## Contributing
|
||||
|
||||
Found a Kiro-specific use case or workflow? Contribute to this guide:
|
||||
|
||||
1. Fork the repository
|
||||
2. Add your examples to this file
|
||||
3. Submit a pull request
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/sickn33/antigravity-awesome-skills/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/sickn33/antigravity-awesome-skills/discussions)
|
||||
- **Community**: [Community Guidelines](COMMUNITY_GUIDELINES.md)
|
||||
This document moved to [`users/kiro-integration.md`](users/kiro-integration.md).
|
||||
|
||||
@@ -1,66 +1,3 @@
|
||||
# 🏆 Quality Bar & Validation Standards
|
||||
# Quality Bar
|
||||
|
||||
To transform **Antigravity Awesome Skills** from a collection of scripts into a trusted platform, every skill must meet a specific standard of quality and safety.
|
||||
|
||||
## The "Validated" Badge ✅
|
||||
|
||||
A skill earns the "Validated" badge only if it passes these **5 automated checks**:
|
||||
|
||||
### 1. Metadata Integrity
|
||||
|
||||
The `SKILL.md` frontmatter must be valid YAML and contain:
|
||||
|
||||
- `name`: Kebab-case, matches folder name.
|
||||
- `description`: Under 200 chars, clear value prop.
|
||||
- `risk`: One of `[none, safe, critical, offensive, unknown]`. Use `unknown` only for legacy or unclassified skills; prefer a concrete level for new skills.
|
||||
- `source`: URL to original source (or "self" if original).
|
||||
|
||||
### 2. Clear Triggers ("When to use")
|
||||
|
||||
The skill MUST have a section explicitly stating when to trigger it.
|
||||
|
||||
- **Good**: "Use when the user asks to debug a React component."
|
||||
- **Bad**: "This skill helps you with code."
|
||||
Accepted headings: `## When to Use`, `## Use this skill when`, `## When to Use This Skill`.
|
||||
|
||||
### 3. Safety & Risk Classification
|
||||
|
||||
Every skill must declare its risk level:
|
||||
|
||||
- 🟢 **none**: Pure text/reasoning (e.g., Brainstorming).
|
||||
- 🔵 **safe**: Reads files, runs safe commands (e.g., Linter).
|
||||
- 🟠 **critical**: Modifies state, deletes files, pushes to prod (e.g., Git Push).
|
||||
- 🔴 **offensive**: Pentesting/Red Team tools. **MUST** have "Authorized Use Only" warning.
|
||||
|
||||
### 4. Copy-Pasteable Examples
|
||||
|
||||
At least one code block or interaction example that a user (or agent) can immediately use.
|
||||
|
||||
### 5. Explicit Limitations
|
||||
|
||||
A list of known edge cases or things the skill _cannot_ do.
|
||||
|
||||
- _Example_: "Does not work on Windows without WSL."
|
||||
|
||||
---
|
||||
|
||||
## Support Levels
|
||||
|
||||
We also categorize skills by who maintains them:
|
||||
|
||||
| Level | Badge | Meaning |
|
||||
| :------------ | :---- | :-------------------------------------------------- |
|
||||
| **Official** | 🟣 | Maintained by the core team. High reliability. |
|
||||
| **Community** | ⚪ | Contributed by the ecosystem. Best effort support. |
|
||||
| **Verified** | ✨ | Community skill that has passed deep manual review. |
|
||||
|
||||
---
|
||||
|
||||
## How to Validate Your Skill
|
||||
|
||||
The canonical validator is `scripts/validate_skills.py`. Run `npm run validate` (or `npm run validate:strict`) before submitting a PR:
|
||||
|
||||
```bash
|
||||
npm run validate # soft mode (warnings only)
|
||||
npm run validate:strict # strict mode (CI uses this)
|
||||
```
|
||||
This document moved to [`contributors/quality-bar.md`](contributors/quality-bar.md).
|
||||
|
||||
38
docs/README.md
Normal file
38
docs/README.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# Documentation Index
|
||||
|
||||
## Users
|
||||
|
||||
- [`users/getting-started.md`](users/getting-started.md)
|
||||
- [`users/usage.md`](users/usage.md)
|
||||
- [`users/faq.md`](users/faq.md)
|
||||
- [`users/bundles.md`](users/bundles.md)
|
||||
- [`users/workflows.md`](users/workflows.md)
|
||||
- [`users/kiro-integration.md`](users/kiro-integration.md)
|
||||
- [`users/visual-guide.md`](users/visual-guide.md)
|
||||
|
||||
## Contributors
|
||||
|
||||
- [`../CONTRIBUTING.md`](../CONTRIBUTING.md)
|
||||
- [`contributors/skill-template.md`](contributors/skill-template.md)
|
||||
- [`contributors/skill-anatomy.md`](contributors/skill-anatomy.md)
|
||||
- [`contributors/examples.md`](contributors/examples.md)
|
||||
- [`contributors/quality-bar.md`](contributors/quality-bar.md)
|
||||
- [`contributors/security-guardrails.md`](contributors/security-guardrails.md)
|
||||
- [`contributors/community-guidelines.md`](contributors/community-guidelines.md)
|
||||
|
||||
## Maintainers
|
||||
|
||||
- [`maintainers/release-process.md`](maintainers/release-process.md)
|
||||
- [`maintainers/rollback-procedure.md`](maintainers/rollback-procedure.md)
|
||||
- [`maintainers/audit.md`](maintainers/audit.md)
|
||||
- [`maintainers/ci-drift-fix.md`](maintainers/ci-drift-fix.md)
|
||||
- [`maintainers/skills-update-guide.md`](maintainers/skills-update-guide.md)
|
||||
- [`maintainers/categorization-implementation.md`](maintainers/categorization-implementation.md)
|
||||
- [`maintainers/date-tracking-implementation.md`](maintainers/date-tracking-implementation.md)
|
||||
- [`maintainers/skills-date-tracking.md`](maintainers/skills-date-tracking.md)
|
||||
|
||||
## Sources
|
||||
|
||||
- [`sources/sources.md`](sources/sources.md)
|
||||
- [`sources/LICENSE-MICROSOFT`](sources/LICENSE-MICROSOFT)
|
||||
- [`sources/microsoft-skills-attribution.json`](sources/microsoft-skills-attribution.json)
|
||||
@@ -1,51 +1,3 @@
|
||||
# 🛡️ Security Guardrails & Policy
|
||||
# Security Guardrails
|
||||
|
||||
Antigravity Awesome Skills is a powerful toolkit. With great power comes great responsibility. This document defines the **Rules of Engagement** for all security and offensive capabilities in this repository.
|
||||
|
||||
## 🔴 Offensive Skills Policy (The "Red Line")
|
||||
|
||||
**What is an Offensive Skill?**
|
||||
Any skill designed to penetrate, exploit, disrupt, or simulate attacks against systems.
|
||||
_Examples: Pentesting, SQL Injection, Phishing Simulation, Red Teaming._
|
||||
|
||||
### 1. The "Authorized Use Only" Disclaimer
|
||||
|
||||
Every offensive skill **MUST** begin with this exact disclaimer in its `SKILL.md`:
|
||||
|
||||
> **⚠️ AUTHORIZED USE ONLY**
|
||||
> This skill is for educational purposes or authorized security assessments only.
|
||||
> You must have explicit, written permission from the system owner before using this tool.
|
||||
> Misuse of this tool is illegal and strictly prohibited.
|
||||
|
||||
### 2. Mandatory User Confirmation
|
||||
|
||||
Offensive skills must **NEVER** run fully autonomously.
|
||||
|
||||
- **Requirement**: The skill description/instructions must explicitly tell the agent to _ask for user confirmation_ before executing any exploit or attack command.
|
||||
- **Agent Instruction**: "Ask the user to verify the target URL/IP before running."
|
||||
|
||||
### 3. Safe by Design
|
||||
|
||||
- **No Weaponized Payloads**: Skills should not include active malware, ransomware, or non-educational exploits.
|
||||
- **Sandbox Recommended**: Instructions should recommend running in a contained environment (Docker/VM).
|
||||
|
||||
---
|
||||
|
||||
## 🔵 Defensive Skills Policy
|
||||
|
||||
**What is a Defensive Skill?**
|
||||
Tools for hardening, auditing, monitoring, or protecting systems.
|
||||
_Examples: Linting, Log Analysis, Configuration Auditing._
|
||||
|
||||
- **Data Privacy**: Defensive skills must not upload data to 3rd party servers without explicit user consent.
|
||||
- **Non-Destructive**: Audits should be read-only by default.
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Legal Disclaimer
|
||||
|
||||
By using this repository, you agree that:
|
||||
|
||||
1. You are responsible for your own actions.
|
||||
2. The authors and contributors are not liable for any damage caused by these tools.
|
||||
3. You will comply with all local, state, and federal laws regarding cybersecurity.
|
||||
This document moved to [`contributors/security-guardrails.md`](contributors/security-guardrails.md).
|
||||
|
||||
1723
docs/SEC_SKILLS.md
1723
docs/SEC_SKILLS.md
File diff suppressed because it is too large
Load Diff
@@ -1,221 +1,3 @@
|
||||
# Skills Date Tracking Guide
|
||||
# Skills Date Tracking
|
||||
|
||||
This guide explains how to use the new `date_added` feature for tracking when skills were created or added to the collection.
|
||||
|
||||
## Overview
|
||||
|
||||
The `date_added` field in skill frontmatter allows you to track when each skill was created. This is useful for:
|
||||
|
||||
- **Versioning**: Understanding skill age and maturity
|
||||
- **Changelog generation**: Tracking new skills over time
|
||||
- **Reporting**: Analyzing skill collection growth
|
||||
- **Organization**: Grouping skills by creation date
|
||||
|
||||
## Format
|
||||
|
||||
The `date_added` field uses ISO 8601 date format: **YYYY-MM-DD**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill-name
|
||||
description: "Brief description"
|
||||
date_added: "2024-01-15"
|
||||
---
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. View All Skills with Their Dates
|
||||
|
||||
```bash
|
||||
python scripts/manage_skill_dates.py list
|
||||
```
|
||||
|
||||
Output example:
|
||||
```
|
||||
📅 Skills with Date Added (245):
|
||||
============================================================
|
||||
2025-02-26 │ recent-skill
|
||||
2025-02-20 │ another-new-skill
|
||||
2024-12-15 │ older-skill
|
||||
...
|
||||
|
||||
⏳ Skills without Date Added (5):
|
||||
============================================================
|
||||
some-legacy-skill
|
||||
undated-skill
|
||||
...
|
||||
|
||||
📊 Coverage: 245/250 (98.0%)
|
||||
```
|
||||
|
||||
### 2. Add Missing Dates
|
||||
|
||||
Add today's date to all skills that don't have a `date_added` field:
|
||||
|
||||
```bash
|
||||
python scripts/manage_skill_dates.py add-missing
|
||||
```
|
||||
|
||||
Or specify a custom date:
|
||||
|
||||
```bash
|
||||
python scripts/manage_skill_dates.py add-missing --date 2024-01-15
|
||||
```
|
||||
|
||||
### 3. Add/Update All Skills
|
||||
|
||||
Set a date for all skills at once:
|
||||
|
||||
```bash
|
||||
python scripts/manage_skill_dates.py add-all --date 2024-01-01
|
||||
```
|
||||
|
||||
### 4. Update a Single Skill
|
||||
|
||||
Update a specific skill's date:
|
||||
|
||||
```bash
|
||||
python scripts/manage_skill_dates.py update my-skill-name 2024-06-15
|
||||
```
|
||||
|
||||
### 5. Generate a Report
|
||||
|
||||
Generate a JSON report of all skills with their metadata:
|
||||
|
||||
```bash
|
||||
python scripts/generate_skills_report.py
|
||||
```
|
||||
|
||||
Save to file:
|
||||
|
||||
```bash
|
||||
python scripts/generate_skills_report.py --output skills_report.json
|
||||
```
|
||||
|
||||
Sort by name:
|
||||
|
||||
```bash
|
||||
python scripts/generate_skills_report.py --sort name --output sorted_skills.json
|
||||
```
|
||||
|
||||
## Usage in Your Workflow
|
||||
|
||||
### When Creating a New Skill
|
||||
|
||||
Add the `date_added` field to your SKILL.md frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: new-awesome-skill
|
||||
description: "Does something awesome"
|
||||
date_added: "2025-02-26"
|
||||
---
|
||||
```
|
||||
|
||||
### Automated Addition
|
||||
|
||||
When onboarding many skills, use:
|
||||
|
||||
```bash
|
||||
python scripts/manage_skill_dates.py add-missing --date 2025-02-26
|
||||
```
|
||||
|
||||
This adds today's date to all skills that are missing the field.
|
||||
|
||||
### Validation
|
||||
|
||||
The validators now check `date_added` format:
|
||||
|
||||
```bash
|
||||
# Run Python validator (strict mode)
|
||||
python scripts/validate_skills.py --strict
|
||||
|
||||
# Run JavaScript validator
|
||||
npm run validate
|
||||
```
|
||||
|
||||
Both will flag invalid dates (must be YYYY-MM-DD format).
|
||||
|
||||
## Generated Reports
|
||||
|
||||
The `generate_skills_report.py` script produces a JSON report with statistics:
|
||||
|
||||
```json
|
||||
{
|
||||
"generated_at": "2025-02-26T10:30:00.123456",
|
||||
"total_skills": 250,
|
||||
"skills_with_dates": 245,
|
||||
"skills_without_dates": 5,
|
||||
"coverage_percentage": 98.0,
|
||||
"sorted_by": "date",
|
||||
"skills": [
|
||||
{
|
||||
"id": "recent-skill",
|
||||
"name": "recent-skill",
|
||||
"description": "A newly added skill",
|
||||
"date_added": "2025-02-26",
|
||||
"source": "community",
|
||||
"risk": "safe",
|
||||
"category": "recent"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Use this for:
|
||||
- Dashboard displays
|
||||
- Growth metrics
|
||||
- Automated reports
|
||||
- Analytics
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
Add to your pipeline:
|
||||
|
||||
```bash
|
||||
# In pre-commit or CI pipeline
|
||||
python scripts/validate_skills.py --strict
|
||||
|
||||
# Generate stats report
|
||||
python scripts/generate_skills_report.py --output reports/skills_report.json
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use consistent format**: Always use `YYYY-MM-DD`
|
||||
2. **Use real dates**: Reflect actual skill creation dates when possible
|
||||
3. **Update on creation**: Add the date when creating new skills
|
||||
4. **Validate regularly**: Run validators to catch format errors
|
||||
5. **Review reports**: Use generated reports to understand collection trends
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Invalid date_added format"
|
||||
|
||||
Make sure the date is in `YYYY-MM-DD` format:
|
||||
- ✅ Correct: `2024-01-15`
|
||||
- ❌ Wrong: `01/15/2024` or `2024-1-15`
|
||||
|
||||
### Script not found
|
||||
|
||||
Make sure you're running from the project root:
|
||||
```bash
|
||||
cd path/to/antigravity-awesome-skills
|
||||
python scripts/manage_skill_dates.py list
|
||||
```
|
||||
|
||||
### Python not found
|
||||
|
||||
Install Python 3.x from [python.org](https://python.org/)
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [SKILL_ANATOMY.md](docs/SKILL_ANATOMY.md) - Complete skill structure guide
|
||||
- [SKILLS_UPDATE_GUIDE.md](SKILLS_UPDATE_GUIDE.md) - How to update the skill collection
|
||||
- [EXAMPLES.md](docs/EXAMPLES.md) - Example skills
|
||||
|
||||
## Questions or Issues?
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
|
||||
This document moved to [`maintainers/skills-date-tracking.md`](maintainers/skills-date-tracking.md).
|
||||
|
||||
@@ -1,545 +1,3 @@
|
||||
# Anatomy of a Skill - Understanding the Structure
|
||||
# Skill Anatomy
|
||||
|
||||
**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! 🚀
|
||||
This document moved to [`contributors/skill-anatomy.md`](contributors/skill-anatomy.md).
|
||||
|
||||
@@ -1,62 +1,3 @@
|
||||
---
|
||||
name: your-skill-name
|
||||
description: "Brief one-sentence description of what this skill does (under 200 characters)"
|
||||
category: your-category
|
||||
risk: safe
|
||||
source: community
|
||||
date_added: "YYYY-MM-DD"
|
||||
---
|
||||
# Skill Template
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Overview
|
||||
|
||||
A brief explanation of what this skill does and why it exists.
|
||||
2-4 sentences is perfect.
|
||||
|
||||
## 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]
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: [Action]
|
||||
|
||||
Detailed instructions...
|
||||
|
||||
### Step 2: [Action]
|
||||
|
||||
More instructions...
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: [Use Case]
|
||||
|
||||
\`\`\`javascript
|
||||
// Example code
|
||||
\`\`\`
|
||||
|
||||
### Example 2: [Another Use Case]
|
||||
|
||||
\`\`\`javascript
|
||||
// More code
|
||||
\`\`\`
|
||||
|
||||
## Best Practices
|
||||
|
||||
- ✅ Do this
|
||||
- ✅ Also do this
|
||||
- ❌ Don't do this
|
||||
- ❌ Avoid this
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** Description
|
||||
**Solution:** How to fix it
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@other-skill` - When to use this instead
|
||||
- `@complementary-skill` - How this works together
|
||||
This document moved to [`contributors/skill-template.md`](contributors/skill-template.md).
|
||||
|
||||
@@ -1,219 +1,3 @@
|
||||
# Smart Auto-Categorization Guide
|
||||
# Smart Auto Categorization
|
||||
|
||||
## Overview
|
||||
|
||||
The skill collection now uses intelligent auto-categorization to eliminate "uncategorized" and organize skills into meaningful categories based on their content.
|
||||
|
||||
## Current Status
|
||||
|
||||
✅ **946 total skills**
|
||||
- 820 skills in meaningful categories (87%)
|
||||
- 126 skills still uncategorized (13%)
|
||||
- 11 primary categories
|
||||
- Categories sorted by skill count (most first)
|
||||
|
||||
## Category Distribution
|
||||
|
||||
| Category | Count | Examples |
|
||||
|----------|-------|----------|
|
||||
| Backend | 164 | Node.js, Django, Express, FastAPI |
|
||||
| Web Development | 107 | React, Vue, Tailwind, CSS |
|
||||
| Automation | 103 | Workflow, Scripting, RPA |
|
||||
| DevOps | 83 | Docker, Kubernetes, CI/CD, Git |
|
||||
| AI/ML | 79 | TensorFlow, PyTorch, NLP, LLM |
|
||||
| Content | 47 | Documentation, SEO, Writing |
|
||||
| Database | 44 | SQL, MongoDB, PostgreSQL |
|
||||
| Testing | 38 | Jest, Cypress, Unit Testing |
|
||||
| Security | 36 | Encryption, Authentication |
|
||||
| Cloud | 33 | AWS, Azure, GCP |
|
||||
| Mobile | 21 | React Native, Flutter, iOS |
|
||||
| Game Dev | 15 | Unity, WebGL, 3D |
|
||||
| Data Science | 14 | Pandas, NumPy, Analytics |
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. **Keyword-Based Analysis**
|
||||
The system analyzes skill names and descriptions for keywords:
|
||||
- **Backend**: nodejs, express, fastapi, django, server, api, database
|
||||
- **Web Dev**: react, vue, angular, frontend, css, html, tailwind
|
||||
- **AI/ML**: ai, machine learning, tensorflow, nlp, gpt
|
||||
- **DevOps**: docker, kubernetes, ci/cd, deploy
|
||||
- And more...
|
||||
|
||||
### 2. **Priority System**
|
||||
Frontmatter category > Detected Keywords > Fallback (uncategorized)
|
||||
|
||||
If a skill already has a category in frontmatter, that's preserved.
|
||||
|
||||
### 3. **Scope-Based Matching**
|
||||
- Exact phrase matches weighted 2x higher than partial matches
|
||||
- Uses word boundaries to avoid false positives
|
||||
|
||||
## Using the Auto-Categorization
|
||||
|
||||
### Run on Uncategorized Skills
|
||||
```bash
|
||||
python scripts/auto_categorize_skills.py
|
||||
```
|
||||
|
||||
### Preview Changes First (Dry Run)
|
||||
```bash
|
||||
python scripts/auto_categorize_skills.py --dry-run
|
||||
```
|
||||
|
||||
### Output
|
||||
```
|
||||
======================================================================
|
||||
AUTO-CATEGORIZATION REPORT
|
||||
======================================================================
|
||||
|
||||
Summary:
|
||||
✅ Categorized: 776
|
||||
⏭️ Already categorized: 46
|
||||
❌ Failed to categorize: 124
|
||||
📈 Total processed: 946
|
||||
|
||||
Sample changes:
|
||||
• 3d-web-experience
|
||||
uncategorized → web-development
|
||||
• ab-test-setup
|
||||
uncategorized → testing
|
||||
• agent-framework-azure-ai-py
|
||||
uncategorized → backend
|
||||
```
|
||||
|
||||
## Web App Improvements
|
||||
|
||||
### Category Filter
|
||||
**Before:**
|
||||
- Unordered list including "uncategorized"
|
||||
- No indication of category size
|
||||
|
||||
**After:**
|
||||
- Categories sorted by skill count (most first, "uncategorized" last)
|
||||
- Shows count: "Backend (164)" "Web Development (107)"
|
||||
- Much easier to browse
|
||||
|
||||
### Example Dropdowns
|
||||
|
||||
**Sorted Order:**
|
||||
1. All Categories
|
||||
2. Backend (164)
|
||||
3. Web Development (107)
|
||||
4. Automation (103)
|
||||
5. DevOps (83)
|
||||
6. AI/ML (79)
|
||||
7. ... more categories ...
|
||||
8. Uncategorized (126) ← at the end
|
||||
|
||||
## For Skill Creators
|
||||
|
||||
### When Adding a New Skill
|
||||
|
||||
Include category in frontmatter:
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: "..."
|
||||
category: web-development
|
||||
date_added: "2025-02-26"
|
||||
---
|
||||
```
|
||||
|
||||
### If You're Not Sure
|
||||
|
||||
The system will automatically categorize on next index regeneration:
|
||||
```bash
|
||||
python scripts/generate_index.py
|
||||
```
|
||||
|
||||
## Keyword Reference
|
||||
|
||||
Available auto-categorization keywords by category:
|
||||
|
||||
**Backend**: nodejs, node.js, express, fastapi, django, flask, spring, java, python, golang, rust, server, api, rest, graphql, database, sql, mongodb
|
||||
|
||||
**Web Development**: react, vue, angular, html, css, javascript, typescript, frontend, tailwind, bootstrap, webpack, vite, pwa, responsive, seo
|
||||
|
||||
**Database**: database, sql, postgres, mysql, mongodb, firestore, redis, orm, schema
|
||||
|
||||
**AI/ML**: ai, machine learning, ml, tensorflow, pytorch, nlp, llm, gpt, transformer, embedding, training
|
||||
|
||||
**DevOps**: docker, kubernetes, ci/cd, git, jenkins, terraform, ansible, deploy, container, monitoring
|
||||
|
||||
**Cloud**: aws, azure, gcp, serverless, lambda, storage, cdn
|
||||
|
||||
**Security**: encryption, cryptography, jwt, oauth, authentication, authorization, vulnerability
|
||||
|
||||
**Testing**: test, jest, mocha, pytest, cypress, selenium, unit test, e2e
|
||||
|
||||
**Mobile**: mobile, react native, flutter, ios, android, swift, kotlin
|
||||
|
||||
**Automation**: automation, workflow, scripting, robot, trigger, integration
|
||||
|
||||
**Game Development**: game, unity, unreal, godot, threejs, 2d, 3d, physics
|
||||
|
||||
**Data Science**: data, analytics, pandas, numpy, statistics, visualization
|
||||
|
||||
## Customization
|
||||
|
||||
### Add Custom Keywords
|
||||
|
||||
Edit [scripts/auto_categorize_skills.py](scripts/auto_categorize_skills.py):
|
||||
|
||||
```python
|
||||
CATEGORY_KEYWORDS = {
|
||||
'your-category': [
|
||||
'keyword1', 'keyword2', 'exact phrase', 'another-keyword'
|
||||
],
|
||||
# ... other categories
|
||||
}
|
||||
```
|
||||
|
||||
Then re-run:
|
||||
```bash
|
||||
python scripts/auto_categorize_skills.py
|
||||
python scripts/generate_index.py
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Failed to categorize" Skills
|
||||
|
||||
Some skills may be too generic or unique. You can:
|
||||
|
||||
1. **Manually set category** in the skill's frontmatter:
|
||||
```yaml
|
||||
category: your-chosen-category
|
||||
```
|
||||
|
||||
2. **Add keywords** to CATEGORY_KEYWORDS config
|
||||
|
||||
3. **Move to folder** if it fits a broader category:
|
||||
```
|
||||
skills/backend/my-new-skill/SKILL.md
|
||||
```
|
||||
|
||||
### Regenerating Index
|
||||
|
||||
After making changes to SKILL.md files:
|
||||
```bash
|
||||
python scripts/generate_index.py
|
||||
```
|
||||
|
||||
This will:
|
||||
- Parse frontmatter categories
|
||||
- Fallback to folder structure
|
||||
- Generate new skills_index.json
|
||||
- Copy to web-app/public/skills.json
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Test in web app**: Try the improved category filter
|
||||
2. **Add missing keywords**: If certain skills are still uncategorized
|
||||
3. **Organize remaining 126**: Either auto-assign or manually review
|
||||
4. **Monitor growth**: Use reports to track new vs categorized skills
|
||||
|
||||
---
|
||||
|
||||
**Result**: Much cleaner category filter with smart, meaningful organization! 🎉
|
||||
This document moved to [`maintainers/smart-auto-categorization.md`](maintainers/smart-auto-categorization.md).
|
||||
|
||||
146
docs/SOURCES.md
146
docs/SOURCES.md
@@ -1,145 +1,3 @@
|
||||
# 📜 Sources & Attributions
|
||||
# Sources
|
||||
|
||||
We believe in giving credit where credit is due.
|
||||
If you recognize your work here and it is not properly attributed, please open an Issue.
|
||||
|
||||
| Skill / Category | Original Source | License | Notes |
|
||||
| :-------------------------- | :------------------------------------------------------------------------- | :------------- | :---------------------------- |
|
||||
| `cloud-penetration-testing` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Adapted for agentic use. |
|
||||
| `active-directory-attacks` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Adapted for agentic use. |
|
||||
| `owasp-top-10` | [OWASP](https://owasp.org/) | CC-BY-SA | Methodology adapted. |
|
||||
| `burp-suite-testing` | [PortSwigger](https://portswigger.net/burp) | N/A | Usage guide only (no binary). |
|
||||
| `crewai` | [CrewAI](https://github.com/joaomdmoura/crewAI) | MIT | Framework guides. |
|
||||
| `langgraph` | [LangGraph](https://github.com/langchain-ai/langgraph) | MIT | Framework guides. |
|
||||
| `react-patterns` | [React Docs](https://react.dev/) | CC-BY | Official patterns. |
|
||||
| **All Official Skills** | [Anthropic / Google / OpenAI / Microsoft / Supabase / Apify / Vercel Labs] | Proprietary | Usage encouraged by vendors. |
|
||||
|
||||
## Skills from VoltAgent/awesome-agent-skills
|
||||
|
||||
The following skills were added from the curated collection at [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills):
|
||||
|
||||
### Official Team Skills
|
||||
|
||||
| Skill | Original Source | License | Notes |
|
||||
| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :--------- | :--------------------------------- |
|
||||
| `vercel-deploy-claimable` | [Vercel Labs](https://github.com/vercel-labs/agent-skills) | MIT | Official Vercel skill |
|
||||
| `design-md` | [Google Labs (Stitch)](https://github.com/google-labs-code/stitch-skills) | Compatible | Google Labs Stitch skills |
|
||||
| `hugging-face-cli`, `hugging-face-jobs` | [Hugging Face](https://github.com/huggingface/skills) | Compatible | Official Hugging Face skills |
|
||||
| `culture-index`, `fix-review`, `sharp-edges` | [Trail of Bits](https://github.com/trailofbits/skills) | Compatible | Security skills from Trail of Bits |
|
||||
| `expo-deployment`, `upgrading-expo` | [Expo](https://github.com/expo/skills) | Compatible | Official Expo skills |
|
||||
| `commit`, `create-pr`, `find-bugs`, `iterate-pr` | [Sentry](https://github.com/getsentry/skills) | Compatible | Sentry dev team skills |
|
||||
| `using-neon` | [Neon](https://github.com/neondatabase/agent-skills) | Compatible | Neon Postgres best practices |
|
||||
| `fal-audio`, `fal-generate`, `fal-image-edit`, `fal-platform`, `fal-upscale`, `fal-workflow` | [fal.ai Community](https://github.com/fal-ai-community/skills) | Compatible | fal.ai AI model skills |
|
||||
|
||||
### Community Skills
|
||||
|
||||
| Skill | Original Source | License | Notes |
|
||||
| :------------------------------------------------------------------ | :-------------------------------------------------------------------------- | :--------- | :----------------------------- |
|
||||
| `automate-whatsapp`, `observe-whatsapp` | [gokapso](https://github.com/gokapso/agent-skills) | Compatible | WhatsApp automation skills |
|
||||
| `readme` | [Shpigford](https://github.com/Shpigford/skills) | Compatible | README generation |
|
||||
| `screenshots` | [Shpigford](https://github.com/Shpigford/skills) | Compatible | Marketing screenshots |
|
||||
| `aws-skills` | [zxkane](https://github.com/zxkane/aws-skills) | Compatible | AWS development patterns |
|
||||
| `deep-research` | [sanjay3290](https://github.com/sanjay3290/ai-skills) | Compatible | Gemini Deep Research Agent |
|
||||
| `ffuf-claude-skill` | [jthack](https://github.com/jthack/ffuf_claude_skill) | Compatible | Web fuzzing with ffuf |
|
||||
| `ui-skills` | [ibelick](https://github.com/ibelick/ui-skills) | Compatible | UI development constraints |
|
||||
| `vexor` | [scarletkc](https://github.com/scarletkc/vexor) | Compatible | Vector-powered CLI |
|
||||
| `pypict-skill` | [omkamal](https://github.com/omkamal/pypict-claude-skill) | Compatible | Pairwise test generation |
|
||||
| `makepad-skills` | [ZhangHanDong](https://github.com/ZhangHanDong/makepad-skills) | Compatible | Makepad UI development |
|
||||
| `swiftui-expert-skill` | [AvdLee](https://github.com/AvdLee/SwiftUI-Agent-Skill) | Compatible | SwiftUI best practices |
|
||||
| `threejs-skills` | [CloudAI-X](https://github.com/CloudAI-X/threejs-skills) | Compatible | Three.js 3D experiences |
|
||||
| `claude-scientific-skills` | [K-Dense-AI](https://github.com/K-Dense-AI/claude-scientific-skills) | Compatible | Scientific research skills |
|
||||
| `claude-win11-speckit-update-skill` | [NotMyself](https://github.com/NotMyself/claude-win11-speckit-update-skill) | Compatible | Windows 11 management |
|
||||
| `imagen` | [sanjay3290](https://github.com/sanjay3290/ai-skills) | Compatible | Google Gemini image generation |
|
||||
| `security-bluebook-builder` | [SHADOWPR0](https://github.com/SHADOWPR0/security-bluebook-builder) | Compatible | Security documentation |
|
||||
| `claude-ally-health` | [huifer](https://github.com/huifer/Claude-Ally-Health) | Compatible | Health assistant |
|
||||
| `clarity-gate` | [frmoretto](https://github.com/frmoretto/clarity-gate) | Compatible | RAG quality verification |
|
||||
| `n8n-code-python`, `n8n-mcp-tools-expert`, `n8n-node-configuration` | [czlonkowski](https://github.com/czlonkowski/n8n-skills) | Compatible | n8n automation skills |
|
||||
| `varlock-claude-skill` | [wrsmith108](https://github.com/wrsmith108/varlock-claude-skill) | Compatible | Secure environment variables |
|
||||
| `beautiful-prose` | [SHADOWPR0](https://github.com/SHADOWPR0/beautiful_prose) | Compatible | Writing style guide |
|
||||
| `claude-speed-reader` | [SeanZoR](https://github.com/SeanZoR/claude-speed-reader) | Compatible | Speed reading tool |
|
||||
| `skill-seekers` | [yusufkaraaslan](https://github.com/yusufkaraaslan/Skill_Seekers) | Compatible | Skill conversion tool |
|
||||
|
||||
- **frontend-slides** - [zarazhangrui](https://github.com/zarazhangrui/frontend-slides)
|
||||
- **linear-claude-skill** - [wrsmith108](https://github.com/wrsmith108/linear-claude-skill)
|
||||
- **skill-rails-upgrade** - [robzolkos](https://github.com/robzolkos/skill-rails-upgrade)
|
||||
- **context-fundamentals** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **context-degradation** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **context-compression** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **context-optimization** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **multi-agent-patterns** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **tool-design** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **evaluation** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **memory-systems** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **terraform-skill** - [antonbabenko](https://github.com/antonbabenko/terraform-skill)
|
||||
|
||||
## Skills from whatiskadudoing/fp-ts-skills (v4.4.0)
|
||||
|
||||
| Skill | Original Source | License | Notes |
|
||||
| :---------------- | :------------------------------------------------------------------------------ | :--------- | :------------------------------------------------------- |
|
||||
| `fp-ts-pragmatic` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | Pragmatic fp-ts guide – pipe, Option, Either, TaskEither |
|
||||
| `fp-ts-react` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | fp-ts with React 18/19 and Next.js |
|
||||
| `fp-ts-errors` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | Type-safe error handling with Either and TaskEither |
|
||||
|
||||
---
|
||||
|
||||
## Recently Added Skills (March 2026)
|
||||
|
||||
The following skills were added during the March 2026 skills update:
|
||||
|
||||
### UI/UX & Frontend
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `baseline-ui`, `fixing-accessibility`, `fixing-metadata`, `fixing-motion-performance` | [ibelick/ui-skills](https://github.com/ibelick/ui-skills) | Compatible | UI polish and validation |
|
||||
| `expo-ui-swift-ui`, `expo-ui-jetpack-compose`, `expo-tailwind-setup`, `building-native-ui`, `expo-api-routes`, `expo-dev-client`, `expo-cicd-workflows`, `native-data-fetching` | [expo/skills](https://github.com/expo/skills) | MIT | Expo/React Native skills |
|
||||
| `swiftui-expert-skill` | [AvdLee/SwiftUI-Agent-Skill](https://github.com/AvdLee/SwiftUI-Agent-Skill) | Compatible | SwiftUI development |
|
||||
| `threejs-fundamentals`, `threejs-geometry`, `threejs-materials`, `threejs-lighting`, `threejs-textures`, `threejs-animation`, `threejs-loaders`, `threejs-shaders`, `threejs-postprocessing`, `threejs-interaction` | [CloudAI-X/threejs-skills](https://github.com/CloudAI-X/threejs-skills) | Compatible | Three.js 3D graphics |
|
||||
| `frontend-slides` | [zarazhangrui](https://github.com/zarazhangrui/frontend-slides) | Compatible | HTML presentations |
|
||||
|
||||
### Automation & Integration
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `gmail-automation`, `google-calendar-automation`, `google-docs-automation`, `google-sheets-automation`, `google-drive-automation`, `google-slides-automation` | [sanjay3290/ai-skills](https://github.com/sanjay3290/ai-skills) | Compatible | Google Workspace integration |
|
||||
| `n8n-expression-syntax`, `n8n-mcp-tools-expert`, `n8n-workflow-patterns`, `n8n-validation-expert`, `n8n-node-configuration`, `n8n-code-javascript`, `n8n-code-python` | [czlonkowski/n8n-skills](https://github.com/czlonkowski/n8n-skills) | Compatible | n8n workflow automation |
|
||||
| `automate-whatsapp` | [gokapso/agent-skills](https://github.com/gokapso/agent-skills) | Compatible | WhatsApp automation |
|
||||
| `linear` | [wrsmith108/linear-claude-skill](https://github.com/wrsmith108/linear-claude-skill) | Compatible | Linear project management |
|
||||
| `rails-upgrade` | [robzolkos](https://github.com/robzolkos/skill-rails-upgrade) | Compatible | Rails upgrade assistant |
|
||||
| `vexor-cli` | [scarletkc/vexor](https://github.com/scarletkc/vexor) | Compatible | Semantic file discovery |
|
||||
|
||||
### Machine Learning & Data
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `hugging-face-dataset-viewer`, `hugging-face-datasets`, `hugging-face-evaluation`, `hugging-face-model-trainer`, `hugging-face-paper-publisher`, `hugging-face-tool-builder` | [huggingface/skills](https://github.com/huggingface/skills) | Compatible | HuggingFace ML tools |
|
||||
| `numpy`, `pandas`, `scipy`, `matplotlib`, `scikit-learn`, `jupyter-workflow` | [K-Dense-AI/claude-scientific-skills](https://github.com/K-Dense-AI/claude-scientific-skills) | Compatible | Data science essentials |
|
||||
| `biopython`, `scanpy`, `uniprot-database`, `pubmed-database` | [K-Dense-AI/claude-scientific-skills](https://github.com/K-Dense-AI/claude-scientific-skills) | Compatible | Bioinformatics tools |
|
||||
|
||||
### Security & Auditing
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `semgrep-rule-creator`, `semgrep-rule-variant-creator`, `static-analysis`, `variant-analysis` | [trailofbits/skills](https://github.com/trailofbits/skills) | Compatible | Code security analysis |
|
||||
| `golang-security-auditor`, `python-security-auditor`, `rust-security-auditor` | [trailofbits/skills](https://github.com/trailofbits/skills) | Compatible | Language-specific security |
|
||||
| `burpsuite-project-parser`, `agentic-actions-auditor`, `audit-context-building`, `proof-of-vulnerability`, `yara-authoring` | [trailofbits/skills](https://github.com/trailofbits/skills) | Compatible | Security testing tools |
|
||||
|
||||
### Context Engineering & AI
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `context-fundamentals`, `context-degradation`, `context-compression`, `context-optimization`, `multi-agent-patterns`, `filesystem-context` | [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) | Compatible | Context engineering patterns |
|
||||
|
||||
### Health & Wellness
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `sleep-analyzer`, `nutrition-analyzer`, `fitness-analyzer` | [huifer/Claude-Ally-Health](https://github.com/huifer/Claude-Ally-Health) | Compatible | Health tracking |
|
||||
|
||||
### Quality & Verification
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `clarity-gate` | [frmoretto/clarity-gate](https://github.com/frmoretto/clarity-gate) | Compatible | RAG quality verification |
|
||||
|
||||
**Total: 80+ new skills added**
|
||||
|
||||
---
|
||||
|
||||
## License Policy
|
||||
|
||||
- **Code**: All original code in this repository is **MIT**.
|
||||
- **Content**: Documentation is **CC-BY-4.0**.
|
||||
- **Third Party**: We respect the upstream licenses. If an imported skill is GPL, it will be marked clearly or excluded (we aim for MIT/Apache compatibility).
|
||||
This document moved to [`sources/sources.md`](sources/sources.md).
|
||||
|
||||
395
docs/USAGE.md
395
docs/USAGE.md
@@ -1,394 +1,3 @@
|
||||
# 📖 Usage Guide: How to Actually Use These Skills
|
||||
# Usage Guide
|
||||
|
||||
> **Confused after installation?** This guide walks you through exactly what to do next, step by step.
|
||||
|
||||
---
|
||||
|
||||
## 🤔 "I just installed the repository. Now what?"
|
||||
|
||||
Great question! Here's what just happened and what to do next:
|
||||
|
||||
### What You Just Did
|
||||
|
||||
When you ran `npx antigravity-awesome-skills` or cloned the repository, you:
|
||||
|
||||
✅ **Downloaded 978+ skill files** to your computer (default: `~/.gemini/antigravity/skills/`; or `~/.agent/skills/` if you used `--path`)
|
||||
✅ **Made them available** to your AI assistant
|
||||
❌ **Did NOT enable them all automatically** (they're just sitting there, waiting)
|
||||
|
||||
Think of it like installing a toolbox. You have all the tools now, but you need to **pick which ones to use** for each job.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Step 1: Understanding "Bundles" (This is NOT Another Install!)
|
||||
|
||||
**Common confusion:** "Do I need to download each skill separately?"
|
||||
|
||||
**Answer: NO!** Here's what bundles actually are:
|
||||
|
||||
### What Bundles Are
|
||||
|
||||
Bundles are **recommended lists** of skills grouped by role. They help you decide which skills to start using.
|
||||
|
||||
**Analogy:**
|
||||
|
||||
- You installed a toolbox with 978+ tools (✅ done)
|
||||
- Bundles are like **labeled organizer trays** saying: "If you're a carpenter, start with these 10 tools"
|
||||
- You don't install bundles—you **pick skills from them**
|
||||
|
||||
### What Bundles Are NOT
|
||||
|
||||
❌ Separate installations
|
||||
❌ Different download commands
|
||||
❌ Something you need to "activate"
|
||||
|
||||
### Example: The "Web Wizard" Bundle
|
||||
|
||||
When you see the [Web Wizard bundle](BUNDLES.md#-the-web-wizard-pack), it lists:
|
||||
|
||||
- `frontend-design`
|
||||
- `react-best-practices`
|
||||
- `tailwind-patterns`
|
||||
- etc.
|
||||
|
||||
These are **recommendations** for which skills a web developer should try first. They're already installed—you just need to **use them in your prompts**.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Step 2: How to Actually Execute/Use a Skill
|
||||
|
||||
This is the part that should have been explained better! Here's how to use skills:
|
||||
|
||||
### The Simple Answer
|
||||
|
||||
**Just mention the skill name in your conversation with your AI assistant.**
|
||||
|
||||
### Different Tools, Different Syntax
|
||||
|
||||
The exact syntax varies by tool, but it's always simple:
|
||||
|
||||
#### Claude Code (CLI)
|
||||
|
||||
```bash
|
||||
# In your terminal/chat with Claude Code:
|
||||
>> Use @brainstorming to help me design a todo app
|
||||
```
|
||||
|
||||
#### Cursor (IDE)
|
||||
|
||||
```bash
|
||||
# In the Cursor chat panel:
|
||||
@brainstorming help me design a todo app
|
||||
```
|
||||
|
||||
#### Gemini CLI
|
||||
|
||||
```bash
|
||||
# In your conversation with Gemini:
|
||||
Use the brainstorming skill to help me plan my app
|
||||
```
|
||||
|
||||
#### Codex CLI
|
||||
|
||||
```bash
|
||||
# In your conversation with Codex:
|
||||
Apply @brainstorming to design a new feature
|
||||
```
|
||||
|
||||
#### Antigravity IDE
|
||||
|
||||
```bash
|
||||
# In agent mode:
|
||||
Use @brainstorming to plan this feature
|
||||
```
|
||||
|
||||
> **Pro Tip:** Most modern tools use the `@skill-name` syntax. When in doubt, try that first!
|
||||
|
||||
---
|
||||
|
||||
## 💬 Step 3: What Should My Prompts Look Like?
|
||||
|
||||
Here are **real-world examples** of good prompts:
|
||||
|
||||
### Example 1: Starting a New Project
|
||||
|
||||
**Bad Prompt:**
|
||||
|
||||
> "Help me build a todo app"
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @brainstorming to help me design a todo app with user authentication and cloud sync"
|
||||
|
||||
**Why it's better:** You're explicitly invoking the skill and providing context.
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Reviewing Code
|
||||
|
||||
**Bad Prompt:**
|
||||
|
||||
> "Check my code"
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @lint-and-validate to check `src/components/Button.tsx` for issues"
|
||||
|
||||
**Why it's better:** Specific skill + specific file = precise results.
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Security Audit
|
||||
|
||||
**Bad Prompt:**
|
||||
|
||||
> "Make my API secure"
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @api-security-best-practices to review my REST endpoints in `routes/api/users.js`"
|
||||
|
||||
**Why it's better:** The AI knows exactly which skill's standards to apply.
|
||||
|
||||
---
|
||||
|
||||
### Example 4: Combining Multiple Skills
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @brainstorming to design a payment flow, then apply @stripe-integration to implement it"
|
||||
|
||||
**Why it's good:** You can chain skills together in a single prompt!
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Step 4: Your First Skill (Hands-On Tutorial)
|
||||
|
||||
Let's actually use a skill right now. Follow these steps:
|
||||
|
||||
### Scenario: You want to plan a new feature
|
||||
|
||||
1. **Pick a skill:** Let's use `brainstorming` (from the "Essentials" bundle)
|
||||
|
||||
2. **Open your AI assistant** (Claude Code, Cursor, etc.)
|
||||
|
||||
3. **Type this exact prompt:**
|
||||
|
||||
```
|
||||
Use @brainstorming to help me design a user profile page for my app
|
||||
```
|
||||
|
||||
4. **Press Enter**
|
||||
|
||||
5. **What happens next:**
|
||||
- The AI loads the brainstorming skill
|
||||
- It will start asking you structured questions (one at a time)
|
||||
- It will guide you through understanding, requirements, and design
|
||||
- You answer each question, and it builds a complete spec
|
||||
|
||||
6. **Result:** You'll end up with a detailed design document—without writing a single line of code yet!
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Step 5: Picking Your First Skills (Practical Advice)
|
||||
|
||||
Don't try to use all 954+ skills! Here's a sensible approach:
|
||||
|
||||
### Start with "The Essentials" (5 skills, everyone needs these)
|
||||
|
||||
1. **`@brainstorming`** - Plan before you build
|
||||
2. **`@lint-and-validate`** - Keep code clean
|
||||
3. **`@git-pushing`** - Save work safely
|
||||
4. **`@systematic-debugging`** - Fix bugs faster
|
||||
5. **`@concise-planning`** - Organize tasks
|
||||
|
||||
**How to use them:**
|
||||
|
||||
- Before writing new code → `@brainstorming`
|
||||
- After writing code → `@lint-and-validate`
|
||||
- Before committing → `@git-pushing`
|
||||
- When stuck → `@systematic-debugging`
|
||||
|
||||
### Then Add Role-Specific Skills (5-10 more)
|
||||
|
||||
Find your role in [BUNDLES.md](BUNDLES.md) and pick 5-10 skills from that bundle.
|
||||
|
||||
**Example for Web Developer:**
|
||||
|
||||
- `@frontend-design`
|
||||
- `@react-best-practices`
|
||||
- `@tailwind-patterns`
|
||||
- `@seo-audit`
|
||||
|
||||
**Example for Security Engineer:**
|
||||
|
||||
- `@api-security-best-practices`
|
||||
- `@vulnerability-scanner`
|
||||
- `@ethical-hacking-methodology`
|
||||
|
||||
### Finally, Add On-Demand Skills (as needed)
|
||||
|
||||
Keep the [CATALOG.md](../CATALOG.md) open as reference. When you need something specific:
|
||||
|
||||
> "I need to integrate Stripe payments"
|
||||
> → Search catalog → Find `@stripe-integration` → Use it!
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Complete Example: Building a Feature End-to-End
|
||||
|
||||
Let's walk through a realistic scenario:
|
||||
|
||||
### Task: "Add a blog to my Next.js website"
|
||||
|
||||
#### Step 1: Plan (use @brainstorming)
|
||||
|
||||
```
|
||||
You: Use @brainstorming to design a blog system for my Next.js site
|
||||
|
||||
AI: [Asks structured questions about requirements]
|
||||
You: [Answer questions]
|
||||
AI: [Produces detailed design spec]
|
||||
```
|
||||
|
||||
#### Step 2: Implement (use @nextjs-best-practices)
|
||||
|
||||
```
|
||||
You: Use @nextjs-best-practices to scaffold the blog with App Router
|
||||
|
||||
AI: [Creates file structure, sets up routes, adds components]
|
||||
```
|
||||
|
||||
#### Step 3: Style (use @tailwind-patterns)
|
||||
|
||||
```
|
||||
You: Use @tailwind-patterns to make the blog posts look modern
|
||||
|
||||
AI: [Applies Tailwind styling with responsive design]
|
||||
```
|
||||
|
||||
#### Step 4: SEO (use @seo-audit)
|
||||
|
||||
```
|
||||
You: Use @seo-audit to optimize the blog for search engines
|
||||
|
||||
AI: [Adds meta tags, sitemaps, structured data]
|
||||
```
|
||||
|
||||
#### Step 5: Test & Deploy
|
||||
|
||||
```
|
||||
You: Use @test-driven-development to add tests, then @vercel-deployment to deploy
|
||||
|
||||
AI: [Creates tests, sets up CI/CD, deploys to Vercel]
|
||||
```
|
||||
|
||||
**Result:** Professional blog built with best practices, without manually researching each step!
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Common Questions
|
||||
|
||||
### "Which tool should I use? Claude Code, Cursor, Gemini?"
|
||||
|
||||
**Any of them!** Skills work universally. Pick the tool you already use or prefer:
|
||||
|
||||
- **Claude Code** - Best for terminal/CLI workflows
|
||||
- **Cursor** - Best for IDE integration
|
||||
- **Gemini CLI** - Best for Google ecosystem
|
||||
- **Codex CLI** - Best for OpenAI ecosystem
|
||||
|
||||
### "Can I see all available skills?"
|
||||
|
||||
Yes! Three ways:
|
||||
|
||||
1. Browse [CATALOG.md](../CATALOG.md) (searchable list)
|
||||
2. Run `ls ~/.agent/skills/` (if installed there)
|
||||
3. Ask your AI: "What skills do you have for [topic]?"
|
||||
|
||||
### "Do I need to restart my IDE after installing?"
|
||||
|
||||
Usually no, but if your AI doesn't recognize a skill:
|
||||
|
||||
1. Try restarting your IDE/CLI
|
||||
2. Check the installation path matches your tool
|
||||
3. Try the explicit path: `npx antigravity-awesome-skills --claude` (or `--cursor`, `--gemini`, etc.)
|
||||
|
||||
### "Can I create my own skills?"
|
||||
|
||||
Yes! Use the `@skill-creator` skill:
|
||||
|
||||
```
|
||||
Use @skill-creator to help me build a custom skill for [your task]
|
||||
```
|
||||
|
||||
### "What if a skill doesn't work as expected?"
|
||||
|
||||
1. Check the skill's SKILL.md file directly: `~/.agent/skills/[skill-name]/SKILL.md`
|
||||
2. Read the description to ensure you're using it correctly
|
||||
3. [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) with details
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Reference Card
|
||||
|
||||
**Save this for quick lookup:**
|
||||
|
||||
| Task | Skill to Use | Example Prompt |
|
||||
| ---------------- | ------------------------------ | --------------------------------------------------- |
|
||||
| Plan new feature | `@brainstorming` | `Use @brainstorming to design a login system` |
|
||||
| Review code | `@lint-and-validate` | `Use @lint-and-validate on src/app.js` |
|
||||
| Debug issue | `@systematic-debugging` | `Use @systematic-debugging to fix login error` |
|
||||
| Security audit | `@api-security-best-practices` | `Use @api-security-best-practices on my API routes` |
|
||||
| SEO check | `@seo-audit` | `Use @seo-audit on my landing page` |
|
||||
| React component | `@react-patterns` | `Use @react-patterns to build a form component` |
|
||||
| Deploy app | `@vercel-deployment` | `Use @vercel-deployment to ship this to production` |
|
||||
|
||||
---
|
||||
|
||||
## 🚦 Next Steps
|
||||
|
||||
Now that you understand how to use skills:
|
||||
|
||||
1. ✅ **Try one skill right now** - Start with `@brainstorming` on any idea you have
|
||||
2. 📚 **Pick 3-5 skills** from your role's bundle in [BUNDLES.md](BUNDLES.md)
|
||||
3. 🔖 **Bookmark** [CATALOG.md](../CATALOG.md) for when you need something specific
|
||||
4. 🎯 **Try a workflow** from [WORKFLOWS.md](WORKFLOWS.md) for a complete end-to-end process
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips for Maximum Effectiveness
|
||||
|
||||
### Tip 1: Start Every Feature with @brainstorming
|
||||
|
||||
> Before writing code, use `@brainstorming` to plan. You'll save hours of refactoring.
|
||||
|
||||
### Tip 2: Chain Skills in Order
|
||||
|
||||
> Don't try to do everything at once. Use skills sequentially: Plan → Build → Test → Deploy
|
||||
|
||||
### Tip 3: Be Specific in Prompts
|
||||
|
||||
> Bad: "Use @react-patterns"
|
||||
> Good: "Use @react-patterns to build a modal component with animations"
|
||||
|
||||
### Tip 4: Reference File Paths
|
||||
|
||||
> Help the AI focus: "Use @security-auditor on routes/api/auth.js"
|
||||
|
||||
### Tip 5: Combine Skills for Complex Tasks
|
||||
|
||||
> "Use @brainstorming to design, then @test-driven-development to implement with tests"
|
||||
|
||||
---
|
||||
|
||||
## 📞 Still Confused?
|
||||
|
||||
If something still doesn't make sense:
|
||||
|
||||
1. Check the [FAQ](FAQ.md)
|
||||
2. See [Real-World Examples](EXAMPLES.md)
|
||||
3. [Open a Discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions)
|
||||
4. [File an Issue](https://github.com/sickn33/antigravity-awesome-skills/issues) to help us improve this guide!
|
||||
|
||||
Remember: You're not alone! The whole point of this project is to make AI assistants easier to use. If this guide didn't help, let us know so we can fix it. 🙌
|
||||
This document moved to [`users/usage.md`](users/usage.md).
|
||||
|
||||
@@ -1,504 +1,3 @@
|
||||
# Visual Quick Start Guide
|
||||
# Visual 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! 💪
|
||||
This document moved to [`users/visual-guide.md`](users/visual-guide.md).
|
||||
|
||||
@@ -1,215 +1,3 @@
|
||||
# Antigravity Workflows
|
||||
# Workflows
|
||||
|
||||
> Workflow playbooks to orchestrate multiple skills with less friction.
|
||||
|
||||
## What Is a Workflow?
|
||||
|
||||
A workflow is a guided, step-by-step execution path that combines multiple skills for one concrete outcome.
|
||||
|
||||
- **Bundles** tell you which skills are relevant for a role.
|
||||
- **Workflows** tell you how to use those skills in sequence to complete a real objective.
|
||||
|
||||
If bundles are your toolbox, workflows are your execution playbook.
|
||||
|
||||
---
|
||||
|
||||
## How to Use Workflows
|
||||
|
||||
1. Install the repository once (`npx antigravity-awesome-skills`).
|
||||
2. Pick a workflow matching your immediate goal.
|
||||
3. Execute steps in order and invoke the listed skills in each step.
|
||||
4. Keep output artifacts at each step (plan, decisions, tests, validation evidence).
|
||||
|
||||
You can combine workflows with bundles from [BUNDLES.md](BUNDLES.md) when you need broader coverage.
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Ship a SaaS MVP
|
||||
|
||||
Build and ship a minimal but production-minded SaaS product.
|
||||
|
||||
**Related bundles:** `Essentials`, `Full-Stack Developer`, `QA & Testing`, `DevOps & Cloud`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Local repository and runtime configured.
|
||||
- Clear user problem and MVP scope.
|
||||
- Basic deployment target selected.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Plan the scope**
|
||||
- **Goal:** Define MVP boundaries and acceptance criteria.
|
||||
- **Skills:** [`@brainstorming`](../skills/brainstorming/), [`@concise-planning`](../skills/concise-planning/), [`@writing-plans`](../skills/writing-plans/)
|
||||
- **Prompt example:** `Usa @concise-planning per definire milestones e criteri di accettazione del mio MVP SaaS.`
|
||||
|
||||
2. **Build backend and API**
|
||||
- **Goal:** Implement core entities, APIs, and auth baseline.
|
||||
- **Skills:** [`@backend-dev-guidelines`](../skills/backend-dev-guidelines/), [`@api-patterns`](../skills/api-patterns/), [`@database-design`](../skills/database-design/)
|
||||
- **Prompt example:** `Usa @backend-dev-guidelines per creare API e servizi del dominio billing.`
|
||||
|
||||
3. **Build frontend**
|
||||
- **Goal:** Ship core user flow with clear UX states.
|
||||
- **Skills:** [`@frontend-developer`](../skills/frontend-developer/), [`@react-patterns`](../skills/react-patterns/), [`@frontend-design`](../skills/frontend-design/)
|
||||
- **Prompt example:** `Usa @frontend-developer per implementare onboarding, empty state e dashboard iniziale.`
|
||||
|
||||
4. **Test and validate**
|
||||
- **Goal:** Cover critical user journeys before release.
|
||||
- **Skills:** [`@test-driven-development`](../skills/test-driven-development/), [`@browser-automation`](../skills/browser-automation/), `@go-playwright` (optional, Go stack)
|
||||
- **Prompt example:** `Usa @browser-automation per creare test E2E sui flussi signup e checkout.`
|
||||
- **Go note:** Se il progetto QA e tooling sono in Go, preferisci `@go-playwright`.
|
||||
|
||||
5. **Ship safely**
|
||||
- **Goal:** Release with observability and rollback plan.
|
||||
- **Skills:** [`@deployment-procedures`](../skills/deployment-procedures/), [`@observability-engineer`](../skills/observability-engineer/)
|
||||
- **Prompt example:** `Usa @deployment-procedures per una checklist di rilascio con rollback.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Security Audit for a Web App
|
||||
|
||||
Run a focused security review from scope definition to remediation validation.
|
||||
|
||||
**Related bundles:** `Security Engineer`, `Security Developer`, `Observability & Monitoring`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Explicit authorization for testing.
|
||||
- In-scope targets documented.
|
||||
- Logging and environment details available.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Define scope and threat model**
|
||||
- **Goal:** Identify assets, trust boundaries, and attack paths.
|
||||
- **Skills:** [`@ethical-hacking-methodology`](../skills/ethical-hacking-methodology/), [`@threat-modeling-expert`](../skills/threat-modeling-expert/), [`@attack-tree-construction`](../skills/attack-tree-construction/)
|
||||
- **Prompt example:** `Usa @threat-modeling-expert per mappare asset critici e trust boundaries della mia web app.`
|
||||
|
||||
2. **Review auth and access control**
|
||||
- **Goal:** Detect account takeover and authorization flaws.
|
||||
- **Skills:** [`@broken-authentication`](../skills/broken-authentication/), [`@auth-implementation-patterns`](../skills/auth-implementation-patterns/), [`@idor-testing`](../skills/idor-testing/)
|
||||
- **Prompt example:** `Usa @idor-testing per verificare accessi non autorizzati su endpoint multitenant.`
|
||||
|
||||
3. **Assess API and input security**
|
||||
- **Goal:** Uncover high-impact API and injection vulnerabilities.
|
||||
- **Skills:** [`@api-security-best-practices`](../skills/api-security-best-practices/), [`@api-fuzzing-bug-bounty`](../skills/api-fuzzing-bug-bounty/), [`@top-web-vulnerabilities`](../skills/top-web-vulnerabilities/)
|
||||
- **Prompt example:** `Usa @api-security-best-practices per audit endpoint auth, billing e admin.`
|
||||
|
||||
4. **Harden and verify**
|
||||
- **Goal:** Convert findings into fixes and verify evidence of mitigation.
|
||||
- **Skills:** [`@security-auditor`](../skills/security-auditor/), [`@sast-configuration`](../skills/sast-configuration/), [`@verification-before-completion`](../skills/verification-before-completion/)
|
||||
- **Prompt example:** `Usa @verification-before-completion per provare che le mitigazioni sono effettive.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Build an AI Agent System
|
||||
|
||||
Design and deliver a production-grade agent with measurable reliability.
|
||||
|
||||
**Related bundles:** `Agent Architect`, `LLM Application Developer`, `Data Engineering`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Narrow use case with measurable outcomes.
|
||||
- Access to model provider(s) and observability tooling.
|
||||
- Initial dataset or knowledge corpus.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Define target behavior and KPIs**
|
||||
- **Goal:** Set quality, latency, and failure thresholds.
|
||||
- **Skills:** [`@ai-agents-architect`](../skills/ai-agents-architect/), [`@agent-evaluation`](../skills/agent-evaluation/), [`@product-manager-toolkit`](../skills/product-manager-toolkit/)
|
||||
- **Prompt example:** `Usa @agent-evaluation per definire benchmark e criteri di successo del mio agente.`
|
||||
|
||||
2. **Design retrieval and memory**
|
||||
- **Goal:** Build reliable retrieval and context architecture.
|
||||
- **Skills:** [`@llm-app-patterns`](../skills/llm-app-patterns/), [`@rag-implementation`](../skills/rag-implementation/), [`@vector-database-engineer`](../skills/vector-database-engineer/)
|
||||
- **Prompt example:** `Usa @rag-implementation per progettare pipeline di chunking, embedding e retrieval.`
|
||||
|
||||
3. **Implement orchestration**
|
||||
- **Goal:** Implement deterministic orchestration and tool boundaries.
|
||||
- **Skills:** [`@langgraph`](../skills/langgraph/), [`@mcp-builder`](../skills/mcp-builder/), [`@workflow-automation`](../skills/workflow-automation/)
|
||||
- **Prompt example:** `Usa @langgraph per implementare il grafo agente con fallback e human-in-the-loop.`
|
||||
|
||||
4. **Evaluate and iterate**
|
||||
- **Goal:** Improve weak points with a structured loop.
|
||||
- **Skills:** [`@agent-evaluation`](../skills/agent-evaluation/), [`@langfuse`](../skills/langfuse/), [`@kaizen`](../skills/kaizen/)
|
||||
- **Prompt example:** `Usa @kaizen per prioritizzare le correzioni sulle failure modes rilevate dai test.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: QA and Browser Automation
|
||||
|
||||
Create resilient browser automation with deterministic execution in CI.
|
||||
|
||||
**Related bundles:** `QA & Testing`, `Full-Stack Developer`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Test environments and stable credentials.
|
||||
- Critical user journeys identified.
|
||||
- CI pipeline available.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Prepare test strategy**
|
||||
- **Goal:** Scope journeys, fixtures, and execution environments.
|
||||
- **Skills:** [`@e2e-testing-patterns`](../skills/e2e-testing-patterns/), [`@test-driven-development`](../skills/test-driven-development/)
|
||||
- **Prompt example:** `Usa @e2e-testing-patterns per definire suite E2E minima ma ad alto impatto.`
|
||||
|
||||
2. **Implement browser tests**
|
||||
- **Goal:** Build robust test coverage with stable selectors.
|
||||
- **Skills:** [`@browser-automation`](../skills/browser-automation/), `@go-playwright` (optional, Go stack)
|
||||
- **Prompt example:** `Usa @go-playwright per implementare browser automation in un progetto Go.`
|
||||
|
||||
3. **Triage and harden**
|
||||
- **Goal:** Remove flaky behavior and enforce repeatability.
|
||||
- **Skills:** [`@systematic-debugging`](../skills/systematic-debugging/), [`@test-fixing`](../skills/test-fixing/), [`@verification-before-completion`](../skills/verification-before-completion/)
|
||||
- **Prompt example:** `Usa @systematic-debugging per classificare e risolvere le flakiness in CI.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Design a DDD Core Domain
|
||||
|
||||
Model a complex domain coherently, then implement tactical and evented patterns only where justified.
|
||||
|
||||
**Related bundles:** `Architecture & Design`, `DDD & Evented Architecture`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Access to at least one domain expert or product owner proxy.
|
||||
- Current system context and integration landscape available.
|
||||
- Agreement on business goals and key domain outcomes.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Assess DDD fit and scope**
|
||||
- **Goal:** Decide whether full DDD, partial DDD, or simple modular architecture is appropriate.
|
||||
- **Skills:** [`@domain-driven-design`](../skills/domain-driven-design/), [`@architecture-decision-records`](../skills/architecture-decision-records/)
|
||||
- **Prompt example:** `Use @domain-driven-design to evaluate if full DDD is justified for our billing and fulfillment platform.`
|
||||
|
||||
2. **Create strategic model**
|
||||
- **Goal:** Define subdomains, bounded contexts, and ubiquitous language.
|
||||
- **Skills:** [`@ddd-strategic-design`](../skills/ddd-strategic-design/)
|
||||
- **Prompt example:** `Use @ddd-strategic-design to classify subdomains and propose bounded contexts with ownership.`
|
||||
|
||||
3. **Map context relationships**
|
||||
- **Goal:** Define upstream/downstream contracts and anti-corruption boundaries.
|
||||
- **Skills:** [`@ddd-context-mapping`](../skills/ddd-context-mapping/)
|
||||
- **Prompt example:** `Use @ddd-context-mapping to model Checkout, Billing, and Inventory interactions with clear contract ownership.`
|
||||
|
||||
4. **Implement tactical model**
|
||||
- **Goal:** Encode invariants with aggregates, value objects, and domain events.
|
||||
- **Skills:** [`@ddd-tactical-patterns`](../skills/ddd-tactical-patterns/), [`@test-driven-development`](../skills/test-driven-development/)
|
||||
- **Prompt example:** `Use @ddd-tactical-patterns to design aggregates and invariants for order lifecycle transitions.`
|
||||
|
||||
5. **Adopt evented patterns selectively**
|
||||
- **Goal:** Apply CQRS, event store, projections, and sagas only where complexity and scale require them.
|
||||
- **Skills:** [`@cqrs-implementation`](../skills/cqrs-implementation/), [`@event-store-design`](../skills/event-store-design/), [`@projection-patterns`](../skills/projection-patterns/), [`@saga-orchestration`](../skills/saga-orchestration/)
|
||||
- **Prompt example:** `Use @cqrs-implementation and @projection-patterns to scale read-side reporting without compromising domain invariants.`
|
||||
|
||||
---
|
||||
|
||||
## Machine-Readable Workflows
|
||||
|
||||
For tooling and automation, workflow metadata is available in [data/workflows.json](../data/workflows.json).
|
||||
This document moved to [`users/workflows.md`](users/workflows.md).
|
||||
|
||||
33
docs/contributors/community-guidelines.md
Normal file
33
docs/contributors/community-guidelines.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment include:
|
||||
|
||||
- Using welcoming and inclusive language
|
||||
- Being respectful of differing viewpoints and experiences
|
||||
- Gracefully accepting constructive criticism
|
||||
- Focusing on what is best for the community
|
||||
- Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
- The use of sexualized language or imagery and unwelcome sexual attention or advances
|
||||
- Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information without explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1.
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
760
docs/contributors/examples.md
Normal file
760
docs/contributors/examples.md
Normal 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!
|
||||
73
docs/contributors/quality-bar.md
Normal file
73
docs/contributors/quality-bar.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# 🏆 Quality Bar & Validation Standards
|
||||
|
||||
To transform **Antigravity Awesome Skills** from a collection of scripts into a trusted platform, every skill must meet a specific standard of quality and safety.
|
||||
|
||||
## The "Validated" Badge ✅
|
||||
|
||||
A skill earns the "Validated" badge only if it meets these **5 quality checks**. Some are enforced automatically today, while others still require reviewer judgment:
|
||||
|
||||
### 1. Metadata Integrity
|
||||
|
||||
The `SKILL.md` frontmatter must be valid YAML and contain:
|
||||
|
||||
- `name`: Kebab-case, matches folder name.
|
||||
- `description`: Under 200 chars, clear value prop.
|
||||
- `risk`: One of `[none, safe, critical, offensive, unknown]`. Use `unknown` only for legacy or unclassified skills; prefer a concrete level for new skills.
|
||||
- `source`: URL to original source (or "self" if original).
|
||||
|
||||
### 2. Clear Triggers ("When to use")
|
||||
|
||||
The skill MUST have a section explicitly stating when to trigger it.
|
||||
|
||||
- **Good**: "Use when the user asks to debug a React component."
|
||||
- **Bad**: "This skill helps you with code."
|
||||
Accepted headings: `## When to Use`, `## Use this skill when`, `## When to Use This Skill`.
|
||||
|
||||
### 3. Safety & Risk Classification
|
||||
|
||||
Every skill must declare its risk level:
|
||||
|
||||
- 🟢 **none**: Pure text/reasoning (e.g., Brainstorming).
|
||||
- 🔵 **safe**: Reads files, runs safe commands (e.g., Linter).
|
||||
- 🟠 **critical**: Modifies state, deletes files, pushes to prod (e.g., Git Push).
|
||||
- 🔴 **offensive**: Pentesting/Red Team tools. **MUST** have "Authorized Use Only" warning.
|
||||
|
||||
### 4. Copy-Pasteable Examples
|
||||
|
||||
At least one code block or interaction example that a user (or agent) can immediately use.
|
||||
|
||||
### 5. Explicit Limitations
|
||||
|
||||
A list of known edge cases or things the skill _cannot_ do.
|
||||
|
||||
- _Example_: "Does not work on Windows without WSL."
|
||||
|
||||
---
|
||||
|
||||
## Support Levels
|
||||
|
||||
We also categorize skills by who maintains them:
|
||||
|
||||
| Level | Badge | Meaning |
|
||||
| :------------ | :---- | :-------------------------------------------------- |
|
||||
| **Official** | 🟣 | Maintained by the core team. High reliability. |
|
||||
| **Community** | ⚪ | Contributed by the ecosystem. Best effort support. |
|
||||
| **Verified** | ✨ | Community skill that has passed deep manual review. |
|
||||
|
||||
---
|
||||
|
||||
## How to Validate Your Skill
|
||||
|
||||
The canonical validator is `tools/scripts/validate_skills.py`, but the recommended entrypoint is `npm run validate` before submitting a PR:
|
||||
|
||||
```bash
|
||||
npm run validate
|
||||
npm run validate:references
|
||||
npm test
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `npm run validate` is the operational contributor gate.
|
||||
- `npm run validate:strict` is a useful hardening pass, but the repository still contains legacy skills that do not yet satisfy strict validation.
|
||||
- Examples and limitations remain part of the quality bar even when they are not fully auto-enforced by the current validator.
|
||||
51
docs/contributors/security-guardrails.md
Normal file
51
docs/contributors/security-guardrails.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# 🛡️ Security Guardrails & Policy
|
||||
|
||||
Antigravity Awesome Skills is a powerful toolkit. With great power comes great responsibility. This document defines the **Rules of Engagement** for all security and offensive capabilities in this repository.
|
||||
|
||||
## 🔴 Offensive Skills Policy (The "Red Line")
|
||||
|
||||
**What is an Offensive Skill?**
|
||||
Any skill designed to penetrate, exploit, disrupt, or simulate attacks against systems.
|
||||
_Examples: Pentesting, SQL Injection, Phishing Simulation, Red Teaming._
|
||||
|
||||
### 1. The "Authorized Use Only" Disclaimer
|
||||
|
||||
Every offensive skill **MUST** begin with this exact disclaimer in its `SKILL.md`:
|
||||
|
||||
> **⚠️ AUTHORIZED USE ONLY**
|
||||
> This skill is for educational purposes or authorized security assessments only.
|
||||
> You must have explicit, written permission from the system owner before using this tool.
|
||||
> Misuse of this tool is illegal and strictly prohibited.
|
||||
|
||||
### 2. Mandatory User Confirmation
|
||||
|
||||
Offensive skills must **NEVER** run fully autonomously.
|
||||
|
||||
- **Requirement**: The skill description/instructions must explicitly tell the agent to _ask for user confirmation_ before executing any exploit or attack command.
|
||||
- **Agent Instruction**: "Ask the user to verify the target URL/IP before running."
|
||||
|
||||
### 3. Safe by Design
|
||||
|
||||
- **No Weaponized Payloads**: Skills should not include active malware, ransomware, or non-educational exploits.
|
||||
- **Sandbox Recommended**: Instructions should recommend running in a contained environment (Docker/VM).
|
||||
|
||||
---
|
||||
|
||||
## 🔵 Defensive Skills Policy
|
||||
|
||||
**What is a Defensive Skill?**
|
||||
Tools for hardening, auditing, monitoring, or protecting systems.
|
||||
_Examples: Linting, Log Analysis, Configuration Auditing._
|
||||
|
||||
- **Data Privacy**: Defensive skills must not upload data to 3rd party servers without explicit user consent.
|
||||
- **Non-Destructive**: Audits should be read-only by default.
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Legal Disclaimer
|
||||
|
||||
By using this repository, you agree that:
|
||||
|
||||
1. You are responsible for your own actions.
|
||||
2. The authors and contributors are not liable for any damage caused by these tools.
|
||||
3. You will comply with all local, state, and federal laws regarding cybersecurity.
|
||||
545
docs/contributors/skill-anatomy.md
Normal file
545
docs/contributors/skill-anatomy.md
Normal 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.md`](../../CONTRIBUTING.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! 🚀
|
||||
65
docs/contributors/skill-template.md
Normal file
65
docs/contributors/skill-template.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
name: your-skill-name
|
||||
description: "Brief one-sentence description of what this skill does (under 200 characters)"
|
||||
category: your-category
|
||||
risk: safe
|
||||
source: community
|
||||
date_added: "YYYY-MM-DD"
|
||||
author: your-name-or-handle
|
||||
tags: [tag-one, tag-two]
|
||||
tools: [claude, cursor, gemini]
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Overview
|
||||
|
||||
A brief explanation of what this skill does and why it exists.
|
||||
2-4 sentences is perfect.
|
||||
|
||||
## 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]
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: [Action]
|
||||
|
||||
Detailed instructions...
|
||||
|
||||
### Step 2: [Action]
|
||||
|
||||
More instructions...
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: [Use Case]
|
||||
|
||||
\`\`\`javascript
|
||||
// Example code
|
||||
\`\`\`
|
||||
|
||||
### Example 2: [Another Use Case]
|
||||
|
||||
\`\`\`javascript
|
||||
// More code
|
||||
\`\`\`
|
||||
|
||||
## Best Practices
|
||||
|
||||
- ✅ Do this
|
||||
- ✅ Also do this
|
||||
- ❌ Don't do this
|
||||
- ❌ Avoid this
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** Description
|
||||
**Solution:** How to fix it
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@other-skill` - When to use this instead
|
||||
- `@complementary-skill` - How this works together
|
||||
68
docs/maintainers/audit.md
Normal file
68
docs/maintainers/audit.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Repo coherence and correctness audit
|
||||
|
||||
This document summarizes the repository coherence audit performed after the `apps/` + `tools/` + layered `docs/` refactor.
|
||||
|
||||
## Scope
|
||||
|
||||
- Conteggi e numeri (README, package.json, CATALOG)
|
||||
- Validazione skill (frontmatter, risk, "When to Use", link)
|
||||
- Riferimenti incrociati (workflows.json, bundles.json, `docs/users/bundles.md`)
|
||||
- Documentazione (`docs/contributors/quality-bar.md`, `docs/contributors/skill-anatomy.md`, security/licenses)
|
||||
- Script e build (validate, index, readme, catalog, test)
|
||||
- Note su data/ e test YAML
|
||||
|
||||
## Outcomes
|
||||
|
||||
### 1. Conteggi
|
||||
|
||||
- `README.md`, `package.json`, and generated artifacts are aligned to the current collection size (`1,204+` skills).
|
||||
- `npm run sync:all` and `npm run catalog` are the canonical commands for keeping counts and generated files synchronized.
|
||||
|
||||
### 2. Validazione skill
|
||||
|
||||
- `npm run validate` is the operational contributor gate.
|
||||
- `npm run validate:strict` is currently a diagnostic hardening pass: it still surfaces repository-wide legacy metadata/content gaps across many older skills.
|
||||
- The validator accepts `risk: unknown` for legacy/unclassified skills while still preferring concrete risk values for new skills.
|
||||
|
||||
### 3. Riferimenti incrociati
|
||||
|
||||
- Added `tools/scripts/validate_references.py` (also exposed as `npm run validate:references`), which verifies:
|
||||
- ogni `recommendedSkills` in data/workflows.json esiste in skills/;
|
||||
- ogni `relatedBundles` esiste in data/bundles.json;
|
||||
- ogni slug in data/bundles.json (skills list) esiste in skills/;
|
||||
- every skill link in `docs/users/bundles.md` points to an existing skill.
|
||||
- Execution: `npm run validate:references`. Result: all references valid.
|
||||
|
||||
### 4. Documentazione
|
||||
|
||||
- Canonical contributor docs now live under `docs/contributors/`.
|
||||
- Canonical maintainer docs now live under `docs/maintainers/`.
|
||||
- README, security docs, licenses, and internal markdown links were rechecked after the refactor.
|
||||
|
||||
### 5. Script e build
|
||||
|
||||
- `npm run test` and `npm run app:build` complete successfully on the refactored layout.
|
||||
- `validate_skills_headings.test.js` acts as a lightweight regression/smoke test, not as the source of truth for full metadata compliance.
|
||||
- The maintainer docs now need to stay aligned with the root `package.json` and the refactored `tools/scripts/*` paths.
|
||||
|
||||
### 6. Deliverable
|
||||
|
||||
- Counts aligned to the current generated registry.
|
||||
- Reference validation wired to the refactored paths.
|
||||
- User and maintainer docs checked for path drift after the layout change.
|
||||
- Follow-up still open: repository-wide cleanup required to make `validate:strict` fully green.
|
||||
|
||||
## Comandi utili
|
||||
|
||||
```bash
|
||||
npm run validate # validazione skill (soft)
|
||||
npm run validate:strict # hardening / diagnostic pass
|
||||
npm run validate:references # workflow, bundle, and docs/users/bundles.md references
|
||||
npm run build # chain + catalog
|
||||
npm test # suite test
|
||||
```
|
||||
|
||||
## Issue aperte / follow-up
|
||||
|
||||
- Gradual cleanup of legacy skills so `npm run validate:strict` can become a hard CI gate in the future.
|
||||
- Keep translated docs aligned in a separate pass after the canonical English docs are stable.
|
||||
170
docs/maintainers/categorization-implementation.md
Normal file
170
docs/maintainers/categorization-implementation.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Smart Categorization Implementation - Complete Summary
|
||||
|
||||
## ✅ What Was Done
|
||||
|
||||
### 1. **Intelligent Auto-Categorization Script**
|
||||
Created [`tools/scripts/auto_categorize_skills.py`](../../tools/scripts/auto_categorize_skills.py) that:
|
||||
- Analyzes skill names and descriptions
|
||||
- Matches against keyword libraries for 13 categories
|
||||
- Automatically assigns meaningful categories
|
||||
- Removes "uncategorized" bulk assignment
|
||||
|
||||
**Results:**
|
||||
- ✅ 776 skills auto-categorized
|
||||
- ✅ 46 already had categories preserved
|
||||
- ✅ 124 remaining uncategorized (edge cases)
|
||||
|
||||
### 2. **Category Distribution**
|
||||
|
||||
**Before:**
|
||||
```
|
||||
uncategorized: 926 (98%)
|
||||
game-development: 10
|
||||
libreoffice: 5
|
||||
security: 4
|
||||
```
|
||||
|
||||
**After:**
|
||||
```
|
||||
Backend: 164 ████████████████
|
||||
Web Dev: 107 ███████████
|
||||
Automation: 103 ███████████
|
||||
DevOps: 83 ████████
|
||||
AI/ML: 79 ████████
|
||||
Content: 47 █████
|
||||
Database: 44 █████
|
||||
Testing: 38 ████
|
||||
Security: 36 ████
|
||||
Cloud: 33 ███
|
||||
Mobile: 21 ██
|
||||
Game Dev: 15 ██
|
||||
Data Science: 14 ██
|
||||
Uncategorized: 126 █
|
||||
```
|
||||
|
||||
### 3. **Updated Index Generation**
|
||||
Modified [`tools/scripts/generate_index.py`](../../tools/scripts/generate_index.py):
|
||||
- **Frontmatter categories now take priority**
|
||||
- Falls back to folder structure if needed
|
||||
- Generates clean, organized skills_index.json
|
||||
- Exported to apps/web-app/public/skills.json
|
||||
|
||||
### 4. **Improved Web App Filter**
|
||||
|
||||
**Home Page Changes:**
|
||||
- ✅ Categories sorted by skill count (most first)
|
||||
- ✅ "Uncategorized" moved to bottom
|
||||
- ✅ Each shows count: "Backend (164)", "Web Dev (107)"
|
||||
- ✅ Much easier to navigate
|
||||
|
||||
**Updated Code:**
|
||||
- [`apps/web-app/src/pages/Home.tsx`](../../apps/web-app/src/pages/Home.tsx) - Smart category sorting
|
||||
- Sorts categories by count using categoryStats
|
||||
- Uncategorized always last
|
||||
- Displays count in dropdown
|
||||
|
||||
### 5. **Categorization Keywords** (13 Categories)
|
||||
|
||||
| Category | Key Keywords |
|
||||
|----------|--------------|
|
||||
| **Backend** | nodejs, express, fastapi, django, server, api, database |
|
||||
| **Web Dev** | react, vue, angular, frontend, css, html, tailwind |
|
||||
| **Automation** | workflow, scripting, automation, robot, trigger |
|
||||
| **DevOps** | docker, kubernetes, ci/cd, deploy, container |
|
||||
| **AI/ML** | ai, machine learning, tensorflow, nlp, gpt, llm |
|
||||
| **Content** | markdown, documentation, content, writing |
|
||||
| **Database** | sql, postgres, mongodb, redis, orm |
|
||||
| **Testing** | test, jest, pytest, cypress, unit test |
|
||||
| **Security** | encryption, auth, oauth, jwt, vulnerability |
|
||||
| **Cloud** | aws, azure, gcp, serverless, lambda |
|
||||
| **Mobile** | react native, flutter, ios, android, swift |
|
||||
| **Game Dev** | game, unity, webgl, threejs, 3d, physics |
|
||||
| **Data Science** | pandas, numpy, analytics, statistics |
|
||||
|
||||
### 6. **Documentation**
|
||||
Created [`smart-auto-categorization.md`](smart-auto-categorization.md) with:
|
||||
- How the system works
|
||||
- Using the script (`--dry-run` and apply modes)
|
||||
- Category reference
|
||||
- Customization guide
|
||||
- Troubleshooting
|
||||
|
||||
## 🎯 The Result
|
||||
|
||||
### No More Uncategorized Chaos
|
||||
- **Before**: the vast majority of skills were lumped into "uncategorized"
|
||||
- **After**: most skills are organized into meaningful buckets, with a much smaller review queue remaining
|
||||
|
||||
### Better UX
|
||||
1. **Smarter Filtering**: Categories sorted by relevance
|
||||
2. **Visual Cues**: Shows count "(164 skills)""
|
||||
3. **Uncategorized Last**: Put bad options out of sight
|
||||
4. **Meaningful Groups**: Find skills by actual function
|
||||
|
||||
### Example Workflow
|
||||
User wants to find database skills:
|
||||
1. Opens web app
|
||||
2. Sees filter dropdown: "Backend (164) | Database (44) | Web Dev (107)..."
|
||||
3. Clicks "Database (44)"
|
||||
4. Gets 44 relevant SQL/MongoDB/Postgres skills
|
||||
5. Done! 🎉
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Run Auto-Categorization
|
||||
```bash
|
||||
# Test first
|
||||
python tools/scripts/auto_categorize_skills.py --dry-run
|
||||
|
||||
# Apply changes
|
||||
python tools/scripts/auto_categorize_skills.py
|
||||
|
||||
# Regenerate index
|
||||
python tools/scripts/generate_index.py
|
||||
|
||||
# Deploy to web app
|
||||
cp skills_index.json apps/web-app/public/skills.json
|
||||
```
|
||||
|
||||
### For New Skills
|
||||
Add to frontmatter:
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: "..."
|
||||
category: backend
|
||||
date_added: "2026-03-06"
|
||||
---
|
||||
```
|
||||
|
||||
## 📁 Files Changed
|
||||
|
||||
### New Files
|
||||
- `tools/scripts/auto_categorize_skills.py` - Auto-categorization engine
|
||||
- `docs/maintainers/smart-auto-categorization.md` - Full documentation
|
||||
|
||||
### Modified Files
|
||||
- `tools/scripts/generate_index.py` - Category priority logic
|
||||
- `apps/web-app/src/pages/Home.tsx` - Smart category sorting
|
||||
- `apps/web-app/public/skills.json` - Regenerated with categories
|
||||
|
||||
## 📊 Quality Metrics
|
||||
|
||||
- **Coverage**: 87% of skills in meaningful categories
|
||||
- **Accuracy**: Keyword-based matching with word boundaries
|
||||
- **Performance**: fast enough to categorize the full repository in a single local pass
|
||||
- **Maintainability**: Easily add keywords/categories for future growth
|
||||
|
||||
## 🎁 Bonus Features
|
||||
|
||||
1. **Dry-run mode**: See changes before applying
|
||||
2. **Weighted scoring**: Exact matches score 2x partial matches
|
||||
3. **Customizable keywords**: Easy to add more categories
|
||||
4. **Fallback logic**: folder → frontmatter → uncategorized
|
||||
5. **UTF-8 support**: Works on Windows/Mac/Linux
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Complete and deployed to web app!
|
||||
|
||||
The web app now has a clean, intelligent category filter instead of "uncategorized" chaos. 🚀
|
||||
38
docs/maintainers/ci-drift-fix.md
Normal file
38
docs/maintainers/ci-drift-fix.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# CI Drift Fix Guide
|
||||
|
||||
**Problem**: The failing job is caused by uncommitted changes detected in `README.md`, `skills_index.json`, or catalog files after the update scripts run.
|
||||
|
||||
**Error**:
|
||||
|
||||
```
|
||||
❌ Detected uncommitted changes produced by registry/readme/catalog scripts.
|
||||
```
|
||||
|
||||
**Cause**:
|
||||
Scripts like `tools/scripts/generate_index.py`, `tools/scripts/update_readme.py`, and `tools/scripts/build-catalog.js` modify `README.md`, `skills_index.json`, `data/catalog.json`, `data/bundles.json`, `data/aliases.json`, and `CATALOG.md`. The workflow expects these files to have no changes after the scripts run. Any differences mean the committed repo is out-of-sync with what the generation scripts produce.
|
||||
|
||||
**How to Fix (DO THIS EVERY TIME):**
|
||||
|
||||
1. Run the **FULL Validation Chain** locally:
|
||||
|
||||
```bash
|
||||
npm run chain
|
||||
npm run catalog
|
||||
```
|
||||
|
||||
2. Check for changes:
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff
|
||||
```
|
||||
|
||||
3. Commit and push any updates:
|
||||
```bash
|
||||
git add README.md skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md
|
||||
git commit -m "chore: sync generated registry files"
|
||||
git push
|
||||
```
|
||||
|
||||
**Summary**:
|
||||
Always commit and push all changes produced by the registry, README sync, and catalog scripts. This keeps CI passing by ensuring the repository and generated artifacts stay in sync with the canonical `tools/scripts/*` pipeline.
|
||||
66
docs/maintainers/date-tracking-implementation.md
Normal file
66
docs/maintainers/date-tracking-implementation.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# Date Tracking Implementation Summary
|
||||
|
||||
This note explains how `date_added` support fits into the current repository structure after the `apps/` and `tools/` refactor.
|
||||
|
||||
## What Exists Today
|
||||
|
||||
### Frontmatter support
|
||||
|
||||
New skills can include a `date_added` field in `SKILL.md` frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: "Description"
|
||||
date_added: "2026-03-06"
|
||||
---
|
||||
```
|
||||
|
||||
### Validator support
|
||||
|
||||
The active validators understand `date_added`:
|
||||
|
||||
- `tools/scripts/validate_skills.py` checks the `YYYY-MM-DD` format.
|
||||
- Supporting JS validation/test helpers are aware of the field where relevant.
|
||||
|
||||
### Index and web app support
|
||||
|
||||
- `tools/scripts/generate_index.py` exports `date_added` into `skills_index.json`.
|
||||
- `npm run app:setup` copies the generated index to `apps/web-app/public/skills.json`.
|
||||
- The web app can render the field anywhere the UI surfaces it.
|
||||
|
||||
### Maintenance scripts
|
||||
|
||||
- `tools/scripts/manage_skill_dates.py` manages skill dates.
|
||||
- `tools/scripts/generate_skills_report.py` produces JSON reports from current skill metadata.
|
||||
|
||||
## Canonical Documentation
|
||||
|
||||
The canonical docs for date tracking now live here:
|
||||
|
||||
- [`skills-date-tracking.md`](skills-date-tracking.md)
|
||||
- [`../contributors/skill-template.md`](../contributors/skill-template.md)
|
||||
- [`../contributors/skill-anatomy.md`](../contributors/skill-anatomy.md)
|
||||
|
||||
Use those files as the source of truth instead of older root-level doc names.
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# View current date coverage
|
||||
python tools/scripts/manage_skill_dates.py list
|
||||
|
||||
# Add missing dates
|
||||
python tools/scripts/manage_skill_dates.py add-missing
|
||||
|
||||
# Update one skill
|
||||
python tools/scripts/manage_skill_dates.py update skill-name 2026-03-06
|
||||
|
||||
# Generate a report
|
||||
python tools/scripts/generate_skills_report.py --output reports/skills_report.json
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Repository-wide coverage can change over time as new community skills are added, so this document avoids hardcoding counts.
|
||||
- `date_added` is useful metadata, but the operational contributor gate remains `npm run validate`; strict validation is a separate hardening target for legacy cleanup.
|
||||
62
docs/maintainers/release-process.md
Normal file
62
docs/maintainers/release-process.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Release Process
|
||||
|
||||
This is the maintainer playbook for cutting a repository release. Historical release notes belong in [`CHANGELOG.md`](../../CHANGELOG.md); this file documents the repeatable process.
|
||||
|
||||
## Preconditions
|
||||
|
||||
- The working tree is clean, or you have explicitly isolated the release changes.
|
||||
- `package.json` contains the version you intend to publish.
|
||||
- Generated registry files are synchronized.
|
||||
- README counts, badges, and acknowledgements are up to date.
|
||||
|
||||
## Release Checklist
|
||||
|
||||
1. Run the operational verification suite:
|
||||
|
||||
```bash
|
||||
npm run validate
|
||||
npm run validate:references
|
||||
npm run sync:all
|
||||
npm run test
|
||||
npm run app:build
|
||||
```
|
||||
|
||||
2. Optional hardening pass:
|
||||
|
||||
```bash
|
||||
npm run validate:strict
|
||||
```
|
||||
|
||||
Use this as a diagnostic signal. It is useful for spotting legacy quality debt, but it is not yet the release blocker for the whole repository.
|
||||
|
||||
3. Update release-facing docs:
|
||||
|
||||
- Add the release entry to [`CHANGELOG.md`](../../CHANGELOG.md).
|
||||
- Confirm `README.md` reflects the current version and generated counts.
|
||||
- Confirm Credits & Sources, contributors, and support links are still correct.
|
||||
|
||||
4. Create the release commit and tag:
|
||||
|
||||
```bash
|
||||
git add README.md CHANGELOG.md CATALOG.md data/ skills_index.json package.json package-lock.json
|
||||
git commit -m "chore: release vX.Y.Z"
|
||||
git tag vX.Y.Z
|
||||
```
|
||||
|
||||
5. Publish the GitHub release:
|
||||
|
||||
```bash
|
||||
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file CHANGELOG.md
|
||||
```
|
||||
|
||||
6. Publish to npm if needed:
|
||||
|
||||
```bash
|
||||
npm publish
|
||||
```
|
||||
|
||||
## Rollback Notes
|
||||
|
||||
- If the release tag is wrong, delete the tag locally and remotely before republishing.
|
||||
- If generated files drift after tagging, cut a follow-up patch release instead of mutating a published tag.
|
||||
- If npm publish fails after tagging, fix the issue, bump the version, and publish a new release instead of reusing the same version.
|
||||
43
docs/maintainers/rollback-procedure.md
Normal file
43
docs/maintainers/rollback-procedure.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Rollback Procedure
|
||||
|
||||
Use this when a structural refactor, generated artifact refresh, or release prep needs to be backed out safely.
|
||||
|
||||
## Before Rolling Back
|
||||
|
||||
- Capture the current branch name with `git branch --show-current`.
|
||||
- Review changed files with `git status --short`.
|
||||
- Decide whether you need to keep any generated files before reverting.
|
||||
|
||||
## Safe Rollback Flow
|
||||
|
||||
1. Create a temporary safety branch:
|
||||
|
||||
```bash
|
||||
git switch -c rollback-safety-check
|
||||
```
|
||||
|
||||
2. Verify the repository still reports the expected changed files:
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
```
|
||||
|
||||
3. Switch back to the original branch:
|
||||
|
||||
```bash
|
||||
git switch -
|
||||
```
|
||||
|
||||
4. If you need to discard only this refactor later, revert the relevant commit(s) or restore specific files explicitly:
|
||||
|
||||
```bash
|
||||
git restore README.md CONTRIBUTING.md package.json package-lock.json
|
||||
git restore --staged README.md CONTRIBUTING.md package.json package-lock.json
|
||||
```
|
||||
|
||||
5. If the refactor has already been committed, prefer `git revert <commit>` over history-rewriting commands.
|
||||
|
||||
## Notes
|
||||
|
||||
- Avoid `git reset --hard` unless you have explicit approval and understand the impact on unrelated work.
|
||||
- For generated artifacts, regenerate after rollback with the standard scripts instead of manually editing them.
|
||||
228
docs/maintainers/skills-date-tracking.md
Normal file
228
docs/maintainers/skills-date-tracking.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Skills Date Tracking Guide
|
||||
|
||||
This guide explains how to use the new `date_added` feature for tracking when skills were created or added to the collection.
|
||||
|
||||
## Overview
|
||||
|
||||
The `date_added` field in skill frontmatter allows you to track when each skill was created. This is useful for:
|
||||
|
||||
- **Versioning**: Understanding skill age and maturity
|
||||
- **Changelog generation**: Tracking new skills over time
|
||||
- **Reporting**: Analyzing skill collection growth
|
||||
- **Organization**: Grouping skills by creation date
|
||||
|
||||
## Format
|
||||
|
||||
The `date_added` field uses ISO 8601 date format: **YYYY-MM-DD**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill-name
|
||||
description: "Brief description"
|
||||
date_added: "2024-01-15"
|
||||
---
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. View All Skills with Their Dates
|
||||
|
||||
```bash
|
||||
python tools/scripts/manage_skill_dates.py list
|
||||
```
|
||||
|
||||
Output example:
|
||||
```
|
||||
📅 Skills with Date Added (example):
|
||||
============================================================
|
||||
2025-02-26 │ recent-skill
|
||||
2025-02-20 │ another-new-skill
|
||||
2024-12-15 │ older-skill
|
||||
...
|
||||
|
||||
⏳ Skills without Date Added (example):
|
||||
============================================================
|
||||
some-legacy-skill
|
||||
undated-skill
|
||||
...
|
||||
|
||||
📊 Coverage: example output only
|
||||
```
|
||||
|
||||
### 2. Add Missing Dates
|
||||
|
||||
Add today's date to all skills that don't have a `date_added` field:
|
||||
|
||||
```bash
|
||||
python tools/scripts/manage_skill_dates.py add-missing
|
||||
```
|
||||
|
||||
Or specify a custom date:
|
||||
|
||||
```bash
|
||||
python tools/scripts/manage_skill_dates.py add-missing --date 2026-03-06
|
||||
```
|
||||
|
||||
### 3. Add/Update All Skills
|
||||
|
||||
Set a date for all skills at once:
|
||||
|
||||
```bash
|
||||
python tools/scripts/manage_skill_dates.py add-all --date 2026-03-06
|
||||
```
|
||||
|
||||
### 4. Update a Single Skill
|
||||
|
||||
Update a specific skill's date:
|
||||
|
||||
```bash
|
||||
python tools/scripts/manage_skill_dates.py update my-skill-name 2026-03-06
|
||||
```
|
||||
|
||||
### 5. Generate a Report
|
||||
|
||||
Generate a JSON report of all skills with their metadata:
|
||||
|
||||
```bash
|
||||
python tools/scripts/generate_skills_report.py
|
||||
```
|
||||
|
||||
Save to file:
|
||||
|
||||
```bash
|
||||
python tools/scripts/generate_skills_report.py --output skills_report.json
|
||||
```
|
||||
|
||||
Sort by name:
|
||||
|
||||
```bash
|
||||
python tools/scripts/generate_skills_report.py --sort name --output sorted_skills.json
|
||||
```
|
||||
|
||||
## Usage in Your Workflow
|
||||
|
||||
### When Creating a New Skill
|
||||
|
||||
Add the `date_added` field to your SKILL.md frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: new-awesome-skill
|
||||
description: "Does something awesome"
|
||||
date_added: "2026-03-06"
|
||||
---
|
||||
```
|
||||
|
||||
### Automated Addition
|
||||
|
||||
When onboarding many skills, use:
|
||||
|
||||
```bash
|
||||
python tools/scripts/manage_skill_dates.py add-missing --date 2026-03-06
|
||||
```
|
||||
|
||||
This adds today's date to all skills that are missing the field.
|
||||
|
||||
### Validation
|
||||
|
||||
The validators now check `date_added` format:
|
||||
|
||||
```bash
|
||||
# Run the operational validator
|
||||
npm run validate
|
||||
|
||||
# Optional hardening pass
|
||||
npm run validate:strict
|
||||
|
||||
# Reference validation
|
||||
npm run validate:references
|
||||
|
||||
# Run smoke tests
|
||||
npm test
|
||||
```
|
||||
|
||||
These checks catch invalid dates, broken references, and related regressions.
|
||||
|
||||
## Generated Reports
|
||||
|
||||
The `generate_skills_report.py` script produces a JSON report with statistics:
|
||||
|
||||
```json
|
||||
{
|
||||
"generated_at": "2026-03-06T10:30:00.123456",
|
||||
"total_skills": 1234,
|
||||
"skills_with_dates": 1200,
|
||||
"skills_without_dates": 34,
|
||||
"coverage_percentage": 97.2,
|
||||
"sorted_by": "date",
|
||||
"skills": [
|
||||
{
|
||||
"id": "recent-skill",
|
||||
"name": "recent-skill",
|
||||
"description": "A newly added skill",
|
||||
"date_added": "2026-03-06",
|
||||
"source": "community",
|
||||
"risk": "safe",
|
||||
"category": "recent"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Use this for:
|
||||
- Dashboard displays
|
||||
- Growth metrics
|
||||
- Automated reports
|
||||
- Analytics
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
Add to your pipeline:
|
||||
|
||||
```bash
|
||||
# In pre-commit or CI pipeline
|
||||
npm run validate
|
||||
npm run validate:references
|
||||
|
||||
# Generate stats report
|
||||
python tools/scripts/generate_skills_report.py --output reports/skills_report.json
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use consistent format**: Always use `YYYY-MM-DD`
|
||||
2. **Use real dates**: Reflect actual skill creation dates when possible
|
||||
3. **Update on creation**: Add the date when creating new skills
|
||||
4. **Validate regularly**: Run validators to catch format errors
|
||||
5. **Review reports**: Use generated reports to understand collection trends
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Invalid date_added format"
|
||||
|
||||
Make sure the date is in `YYYY-MM-DD` format:
|
||||
- ✅ Correct: `2024-01-15`
|
||||
- ❌ Wrong: `01/15/2024` or `2024-1-15`
|
||||
|
||||
### Script not found
|
||||
|
||||
Make sure you're running from the project root:
|
||||
```bash
|
||||
cd path/to/antigravity-awesome-skills
|
||||
python tools/scripts/manage_skill_dates.py list
|
||||
```
|
||||
|
||||
### Python not found
|
||||
|
||||
Install Python 3.x from [python.org](https://python.org/)
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [`../contributors/skill-anatomy.md`](../contributors/skill-anatomy.md) - Complete skill structure guide
|
||||
- [`skills-update-guide.md`](skills-update-guide.md) - How to update the skill collection
|
||||
- [`../contributors/examples.md`](../contributors/examples.md) - Example skills
|
||||
|
||||
## Questions or Issues?
|
||||
|
||||
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.
|
||||
89
docs/maintainers/skills-update-guide.md
Normal file
89
docs/maintainers/skills-update-guide.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# Skills Update Guide
|
||||
|
||||
This guide explains how to update the skills in the Antigravity Awesome Skills web application.
|
||||
|
||||
## Automatic Updates (Recommended)
|
||||
|
||||
The `START_APP.bat` file automatically checks for and updates skills when you run it. It uses multiple methods:
|
||||
|
||||
1. **Git method** (if Git is installed): Fast and efficient
|
||||
2. **PowerShell download** (fallback): Works without Git
|
||||
|
||||
## Manual Update Options
|
||||
|
||||
### Option 1: Using npm script (Recommended for manual updates)
|
||||
```bash
|
||||
npm run update:skills
|
||||
```
|
||||
|
||||
This command:
|
||||
- Generates the latest skills index from the skills directory
|
||||
- Copies it to the web app's public directory
|
||||
- Requires Python and PyYAML to be installed
|
||||
|
||||
### Option 2: Using START_APP.bat (Integrated solution)
|
||||
```bash
|
||||
START_APP.bat
|
||||
```
|
||||
|
||||
The START_APP.bat file includes integrated update functionality that:
|
||||
- Automatically checks for updates on startup
|
||||
- Uses Git if available (fast method)
|
||||
- Falls back to HTTPS download if Git is not installed
|
||||
- Handles all dependencies automatically
|
||||
- Provides clear status messages
|
||||
- Works without any additional setup
|
||||
|
||||
### Option 3: Manual steps
|
||||
```bash
|
||||
# 1. Generate skills index
|
||||
python tools/scripts/generate_index.py
|
||||
|
||||
# 2. Copy to web app
|
||||
copy skills_index.json apps\web-app\public\skills.json
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
For manual updates, you need:
|
||||
|
||||
- **Python 3.x**: Download from [python.org](https://python.org/)
|
||||
- **PyYAML**: Install with `pip install PyYAML`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Python is not recognized"
|
||||
- Install Python from [python.org](https://python.org/)
|
||||
- Make sure to check "Add Python to PATH" during installation
|
||||
|
||||
### "PyYAML not found"
|
||||
- Install with: `pip install PyYAML`
|
||||
- Or run the update script which will install it automatically
|
||||
|
||||
### "Failed to copy skills"
|
||||
- Make sure the `apps\web-app\public\` directory exists
|
||||
- Check file permissions
|
||||
|
||||
## What Gets Updated
|
||||
|
||||
The update process refreshes:
|
||||
- Skills index (`skills_index.json`)
|
||||
- Web app skills data (`apps\web-app\public\skills.json`)
|
||||
- All 1,204+ skills from the skills directory
|
||||
|
||||
## When to Update
|
||||
|
||||
Update skills when:
|
||||
- New skills are added to the repository
|
||||
- You want the latest skill descriptions
|
||||
- Skills appear missing or outdated in the web app
|
||||
|
||||
## Git Users
|
||||
|
||||
If you have Git installed and want to update the entire repository:
|
||||
```bash
|
||||
git pull origin main
|
||||
npm run update:skills
|
||||
```
|
||||
|
||||
This pulls the latest code and updates the skills data.
|
||||
219
docs/maintainers/smart-auto-categorization.md
Normal file
219
docs/maintainers/smart-auto-categorization.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Smart Auto-Categorization Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The skill collection now uses intelligent auto-categorization to eliminate "uncategorized" and organize skills into meaningful categories based on their content.
|
||||
|
||||
## Current Status
|
||||
|
||||
✅ Current repository indexed through the generated catalog
|
||||
- Most skills are in meaningful categories
|
||||
- A smaller tail still needs manual review or better keyword coverage
|
||||
- 11 primary categories
|
||||
- Categories sorted by skill count (most first)
|
||||
|
||||
## Category Distribution
|
||||
|
||||
| Category | Count | Examples |
|
||||
|----------|-------|----------|
|
||||
| Backend | 164 | Node.js, Django, Express, FastAPI |
|
||||
| Web Development | 107 | React, Vue, Tailwind, CSS |
|
||||
| Automation | 103 | Workflow, Scripting, RPA |
|
||||
| DevOps | 83 | Docker, Kubernetes, CI/CD, Git |
|
||||
| AI/ML | 79 | TensorFlow, PyTorch, NLP, LLM |
|
||||
| Content | 47 | Documentation, SEO, Writing |
|
||||
| Database | 44 | SQL, MongoDB, PostgreSQL |
|
||||
| Testing | 38 | Jest, Cypress, Unit Testing |
|
||||
| Security | 36 | Encryption, Authentication |
|
||||
| Cloud | 33 | AWS, Azure, GCP |
|
||||
| Mobile | 21 | React Native, Flutter, iOS |
|
||||
| Game Dev | 15 | Unity, WebGL, 3D |
|
||||
| Data Science | 14 | Pandas, NumPy, Analytics |
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. **Keyword-Based Analysis**
|
||||
The system analyzes skill names and descriptions for keywords:
|
||||
- **Backend**: nodejs, express, fastapi, django, server, api, database
|
||||
- **Web Dev**: react, vue, angular, frontend, css, html, tailwind
|
||||
- **AI/ML**: ai, machine learning, tensorflow, nlp, gpt
|
||||
- **DevOps**: docker, kubernetes, ci/cd, deploy
|
||||
- And more...
|
||||
|
||||
### 2. **Priority System**
|
||||
Frontmatter category > Detected Keywords > Fallback (uncategorized)
|
||||
|
||||
If a skill already has a category in frontmatter, that's preserved.
|
||||
|
||||
### 3. **Scope-Based Matching**
|
||||
- Exact phrase matches weighted 2x higher than partial matches
|
||||
- Uses word boundaries to avoid false positives
|
||||
|
||||
## Using the Auto-Categorization
|
||||
|
||||
### Run on Uncategorized Skills
|
||||
```bash
|
||||
python tools/scripts/auto_categorize_skills.py
|
||||
```
|
||||
|
||||
### Preview Changes First (Dry Run)
|
||||
```bash
|
||||
python tools/scripts/auto_categorize_skills.py --dry-run
|
||||
```
|
||||
|
||||
### Output
|
||||
```
|
||||
======================================================================
|
||||
AUTO-CATEGORIZATION REPORT
|
||||
======================================================================
|
||||
|
||||
Summary:
|
||||
✅ Categorized: 776
|
||||
⏭️ Already categorized: 46
|
||||
❌ Failed to categorize: 124
|
||||
📈 Total processed: full repository
|
||||
|
||||
Sample changes:
|
||||
• 3d-web-experience
|
||||
uncategorized → web-development
|
||||
• ab-test-setup
|
||||
uncategorized → testing
|
||||
• agent-framework-azure-ai-py
|
||||
uncategorized → backend
|
||||
```
|
||||
|
||||
## Web App Improvements
|
||||
|
||||
### Category Filter
|
||||
**Before:**
|
||||
- Unordered list including "uncategorized"
|
||||
- No indication of category size
|
||||
|
||||
**After:**
|
||||
- Categories sorted by skill count (most first, "uncategorized" last)
|
||||
- Shows count: "Backend (164)" "Web Development (107)"
|
||||
- Much easier to browse
|
||||
|
||||
### Example Dropdowns
|
||||
|
||||
**Sorted Order:**
|
||||
1. All Categories
|
||||
2. Backend (164)
|
||||
3. Web Development (107)
|
||||
4. Automation (103)
|
||||
5. DevOps (83)
|
||||
6. AI/ML (79)
|
||||
7. ... more categories ...
|
||||
8. Uncategorized (126) ← at the end
|
||||
|
||||
## For Skill Creators
|
||||
|
||||
### When Adding a New Skill
|
||||
|
||||
Include category in frontmatter:
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: "..."
|
||||
category: web-development
|
||||
date_added: "2026-03-06"
|
||||
---
|
||||
```
|
||||
|
||||
### If You're Not Sure
|
||||
|
||||
The system will automatically categorize on next index regeneration:
|
||||
```bash
|
||||
python tools/scripts/generate_index.py
|
||||
```
|
||||
|
||||
## Keyword Reference
|
||||
|
||||
Available auto-categorization keywords by category:
|
||||
|
||||
**Backend**: nodejs, node.js, express, fastapi, django, flask, spring, java, python, golang, rust, server, api, rest, graphql, database, sql, mongodb
|
||||
|
||||
**Web Development**: react, vue, angular, html, css, javascript, typescript, frontend, tailwind, bootstrap, webpack, vite, pwa, responsive, seo
|
||||
|
||||
**Database**: database, sql, postgres, mysql, mongodb, firestore, redis, orm, schema
|
||||
|
||||
**AI/ML**: ai, machine learning, ml, tensorflow, pytorch, nlp, llm, gpt, transformer, embedding, training
|
||||
|
||||
**DevOps**: docker, kubernetes, ci/cd, git, jenkins, terraform, ansible, deploy, container, monitoring
|
||||
|
||||
**Cloud**: aws, azure, gcp, serverless, lambda, storage, cdn
|
||||
|
||||
**Security**: encryption, cryptography, jwt, oauth, authentication, authorization, vulnerability
|
||||
|
||||
**Testing**: test, jest, mocha, pytest, cypress, selenium, unit test, e2e
|
||||
|
||||
**Mobile**: mobile, react native, flutter, ios, android, swift, kotlin
|
||||
|
||||
**Automation**: automation, workflow, scripting, robot, trigger, integration
|
||||
|
||||
**Game Development**: game, unity, unreal, godot, threejs, 2d, 3d, physics
|
||||
|
||||
**Data Science**: data, analytics, pandas, numpy, statistics, visualization
|
||||
|
||||
## Customization
|
||||
|
||||
### Add Custom Keywords
|
||||
|
||||
Edit [`tools/scripts/auto_categorize_skills.py`](../../tools/scripts/auto_categorize_skills.py):
|
||||
|
||||
```python
|
||||
CATEGORY_KEYWORDS = {
|
||||
'your-category': [
|
||||
'keyword1', 'keyword2', 'exact phrase', 'another-keyword'
|
||||
],
|
||||
# ... other categories
|
||||
}
|
||||
```
|
||||
|
||||
Then re-run:
|
||||
```bash
|
||||
python tools/scripts/auto_categorize_skills.py
|
||||
python tools/scripts/generate_index.py
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Failed to categorize" Skills
|
||||
|
||||
Some skills may be too generic or unique. You can:
|
||||
|
||||
1. **Manually set category** in the skill's frontmatter:
|
||||
```yaml
|
||||
category: your-chosen-category
|
||||
```
|
||||
|
||||
2. **Add keywords** to CATEGORY_KEYWORDS config
|
||||
|
||||
3. **Move to folder** if it fits a broader category:
|
||||
```
|
||||
skills/backend/my-new-skill/SKILL.md
|
||||
```
|
||||
|
||||
### Regenerating Index
|
||||
|
||||
After making changes to SKILL.md files:
|
||||
```bash
|
||||
python tools/scripts/generate_index.py
|
||||
```
|
||||
|
||||
This will:
|
||||
- Parse frontmatter categories
|
||||
- Fallback to folder structure
|
||||
- Generate new skills_index.json
|
||||
- Copy to apps/web-app/public/skills.json
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Test in web app**: Try the improved category filter
|
||||
2. **Add missing keywords**: If certain skills are still uncategorized
|
||||
3. **Organize remaining uncategorized skills**: Either auto-assign or manually review
|
||||
4. **Monitor growth**: Use reports to track new vs categorized skills
|
||||
|
||||
---
|
||||
|
||||
**Result**: Much cleaner category filter with smart, meaningful organization! 🎉
|
||||
145
docs/sources/sources.md
Normal file
145
docs/sources/sources.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# 📜 Sources & Attributions
|
||||
|
||||
We believe in giving credit where credit is due.
|
||||
If you recognize your work here and it is not properly attributed, please open an Issue.
|
||||
|
||||
| Skill / Category | Original Source | License | Notes |
|
||||
| :-------------------------- | :------------------------------------------------------------------------- | :------------- | :---------------------------- |
|
||||
| `cloud-penetration-testing` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Adapted for agentic use. |
|
||||
| `active-directory-attacks` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Adapted for agentic use. |
|
||||
| `owasp-top-10` | [OWASP](https://owasp.org/) | CC-BY-SA | Methodology adapted. |
|
||||
| `burp-suite-testing` | [PortSwigger](https://portswigger.net/burp) | N/A | Usage guide only (no binary). |
|
||||
| `crewai` | [CrewAI](https://github.com/joaomdmoura/crewAI) | MIT | Framework guides. |
|
||||
| `langgraph` | [LangGraph](https://github.com/langchain-ai/langgraph) | MIT | Framework guides. |
|
||||
| `react-patterns` | [React Docs](https://react.dev/) | CC-BY | Official patterns. |
|
||||
| **All Official Skills** | [Anthropic / Google / OpenAI / Microsoft / Supabase / Apify / Vercel Labs] | Proprietary | Usage encouraged by vendors. |
|
||||
|
||||
## Skills from VoltAgent/awesome-agent-skills
|
||||
|
||||
The following skills were added from the curated collection at [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills):
|
||||
|
||||
### Official Team Skills
|
||||
|
||||
| Skill | Original Source | License | Notes |
|
||||
| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :--------- | :--------------------------------- |
|
||||
| `vercel-deploy-claimable` | [Vercel Labs](https://github.com/vercel-labs/agent-skills) | MIT | Official Vercel skill |
|
||||
| `design-md` | [Google Labs (Stitch)](https://github.com/google-labs-code/stitch-skills) | Compatible | Google Labs Stitch skills |
|
||||
| `hugging-face-cli`, `hugging-face-jobs` | [Hugging Face](https://github.com/huggingface/skills) | Compatible | Official Hugging Face skills |
|
||||
| `culture-index`, `fix-review`, `sharp-edges` | [Trail of Bits](https://github.com/trailofbits/skills) | Compatible | Security skills from Trail of Bits |
|
||||
| `expo-deployment`, `upgrading-expo` | [Expo](https://github.com/expo/skills) | Compatible | Official Expo skills |
|
||||
| `commit`, `create-pr`, `find-bugs`, `iterate-pr` | [Sentry](https://github.com/getsentry/skills) | Compatible | Sentry dev team skills |
|
||||
| `using-neon` | [Neon](https://github.com/neondatabase/agent-skills) | Compatible | Neon Postgres best practices |
|
||||
| `fal-audio`, `fal-generate`, `fal-image-edit`, `fal-platform`, `fal-upscale`, `fal-workflow` | [fal.ai Community](https://github.com/fal-ai-community/skills) | Compatible | fal.ai AI model skills |
|
||||
|
||||
### Community Skills
|
||||
|
||||
| Skill | Original Source | License | Notes |
|
||||
| :------------------------------------------------------------------ | :-------------------------------------------------------------------------- | :--------- | :----------------------------- |
|
||||
| `automate-whatsapp`, `observe-whatsapp` | [gokapso](https://github.com/gokapso/agent-skills) | Compatible | WhatsApp automation skills |
|
||||
| `readme` | [Shpigford](https://github.com/Shpigford/skills) | Compatible | README generation |
|
||||
| `screenshots` | [Shpigford](https://github.com/Shpigford/skills) | Compatible | Marketing screenshots |
|
||||
| `aws-skills` | [zxkane](https://github.com/zxkane/aws-skills) | Compatible | AWS development patterns |
|
||||
| `deep-research` | [sanjay3290](https://github.com/sanjay3290/ai-skills) | Compatible | Gemini Deep Research Agent |
|
||||
| `ffuf-claude-skill` | [jthack](https://github.com/jthack/ffuf_claude_skill) | Compatible | Web fuzzing with ffuf |
|
||||
| `ui-skills` | [ibelick](https://github.com/ibelick/ui-skills) | Compatible | UI development constraints |
|
||||
| `vexor` | [scarletkc](https://github.com/scarletkc/vexor) | Compatible | Vector-powered CLI |
|
||||
| `pypict-skill` | [omkamal](https://github.com/omkamal/pypict-claude-skill) | Compatible | Pairwise test generation |
|
||||
| `makepad-skills` | [ZhangHanDong](https://github.com/ZhangHanDong/makepad-skills) | Compatible | Makepad UI development |
|
||||
| `swiftui-expert-skill` | [AvdLee](https://github.com/AvdLee/SwiftUI-Agent-Skill) | Compatible | SwiftUI best practices |
|
||||
| `threejs-skills` | [CloudAI-X](https://github.com/CloudAI-X/threejs-skills) | Compatible | Three.js 3D experiences |
|
||||
| `claude-scientific-skills` | [K-Dense-AI](https://github.com/K-Dense-AI/claude-scientific-skills) | Compatible | Scientific research skills |
|
||||
| `claude-win11-speckit-update-skill` | [NotMyself](https://github.com/NotMyself/claude-win11-speckit-update-skill) | Compatible | Windows 11 management |
|
||||
| `imagen` | [sanjay3290](https://github.com/sanjay3290/ai-skills) | Compatible | Google Gemini image generation |
|
||||
| `security-bluebook-builder` | [SHADOWPR0](https://github.com/SHADOWPR0/security-bluebook-builder) | Compatible | Security documentation |
|
||||
| `claude-ally-health` | [huifer](https://github.com/huifer/Claude-Ally-Health) | Compatible | Health assistant |
|
||||
| `clarity-gate` | [frmoretto](https://github.com/frmoretto/clarity-gate) | Compatible | RAG quality verification |
|
||||
| `n8n-code-python`, `n8n-mcp-tools-expert`, `n8n-node-configuration` | [czlonkowski](https://github.com/czlonkowski/n8n-skills) | Compatible | n8n automation skills |
|
||||
| `varlock-claude-skill` | [wrsmith108](https://github.com/wrsmith108/varlock-claude-skill) | Compatible | Secure environment variables |
|
||||
| `beautiful-prose` | [SHADOWPR0](https://github.com/SHADOWPR0/beautiful_prose) | Compatible | Writing style guide |
|
||||
| `claude-speed-reader` | [SeanZoR](https://github.com/SeanZoR/claude-speed-reader) | Compatible | Speed reading tool |
|
||||
| `skill-seekers` | [yusufkaraaslan](https://github.com/yusufkaraaslan/Skill_Seekers) | Compatible | Skill conversion tool |
|
||||
|
||||
- **frontend-slides** - [zarazhangrui](https://github.com/zarazhangrui/frontend-slides)
|
||||
- **linear-claude-skill** - [wrsmith108](https://github.com/wrsmith108/linear-claude-skill)
|
||||
- **skill-rails-upgrade** - [robzolkos](https://github.com/robzolkos/skill-rails-upgrade)
|
||||
- **context-fundamentals** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **context-degradation** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **context-compression** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **context-optimization** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **multi-agent-patterns** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **tool-design** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **evaluation** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **memory-systems** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
|
||||
- **terraform-skill** - [antonbabenko](https://github.com/antonbabenko/terraform-skill)
|
||||
|
||||
## Skills from whatiskadudoing/fp-ts-skills (v4.4.0)
|
||||
|
||||
| Skill | Original Source | License | Notes |
|
||||
| :---------------- | :------------------------------------------------------------------------------ | :--------- | :------------------------------------------------------- |
|
||||
| `fp-ts-pragmatic` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | Pragmatic fp-ts guide – pipe, Option, Either, TaskEither |
|
||||
| `fp-ts-react` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | fp-ts with React 18/19 and Next.js |
|
||||
| `fp-ts-errors` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | Type-safe error handling with Either and TaskEither |
|
||||
|
||||
---
|
||||
|
||||
## Recently Added Skills (March 2026)
|
||||
|
||||
The following skills were added during the March 2026 skills update:
|
||||
|
||||
### UI/UX & Frontend
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `baseline-ui`, `fixing-accessibility`, `fixing-metadata`, `fixing-motion-performance` | [ibelick/ui-skills](https://github.com/ibelick/ui-skills) | Compatible | UI polish and validation |
|
||||
| `expo-ui-swift-ui`, `expo-ui-jetpack-compose`, `expo-tailwind-setup`, `building-native-ui`, `expo-api-routes`, `expo-dev-client`, `expo-cicd-workflows`, `native-data-fetching` | [expo/skills](https://github.com/expo/skills) | MIT | Expo/React Native skills |
|
||||
| `swiftui-expert-skill` | [AvdLee/SwiftUI-Agent-Skill](https://github.com/AvdLee/SwiftUI-Agent-Skill) | Compatible | SwiftUI development |
|
||||
| `threejs-fundamentals`, `threejs-geometry`, `threejs-materials`, `threejs-lighting`, `threejs-textures`, `threejs-animation`, `threejs-loaders`, `threejs-shaders`, `threejs-postprocessing`, `threejs-interaction` | [CloudAI-X/threejs-skills](https://github.com/CloudAI-X/threejs-skills) | Compatible | Three.js 3D graphics |
|
||||
| `frontend-slides` | [zarazhangrui](https://github.com/zarazhangrui/frontend-slides) | Compatible | HTML presentations |
|
||||
|
||||
### Automation & Integration
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `gmail-automation`, `google-calendar-automation`, `google-docs-automation`, `google-sheets-automation`, `google-drive-automation`, `google-slides-automation` | [sanjay3290/ai-skills](https://github.com/sanjay3290/ai-skills) | Compatible | Google Workspace integration |
|
||||
| `n8n-expression-syntax`, `n8n-mcp-tools-expert`, `n8n-workflow-patterns`, `n8n-validation-expert`, `n8n-node-configuration`, `n8n-code-javascript`, `n8n-code-python` | [czlonkowski/n8n-skills](https://github.com/czlonkowski/n8n-skills) | Compatible | n8n workflow automation |
|
||||
| `automate-whatsapp` | [gokapso/agent-skills](https://github.com/gokapso/agent-skills) | Compatible | WhatsApp automation |
|
||||
| `linear` | [wrsmith108/linear-claude-skill](https://github.com/wrsmith108/linear-claude-skill) | Compatible | Linear project management |
|
||||
| `rails-upgrade` | [robzolkos](https://github.com/robzolkos/skill-rails-upgrade) | Compatible | Rails upgrade assistant |
|
||||
| `vexor-cli` | [scarletkc/vexor](https://github.com/scarletkc/vexor) | Compatible | Semantic file discovery |
|
||||
|
||||
### Machine Learning & Data
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `hugging-face-dataset-viewer`, `hugging-face-datasets`, `hugging-face-evaluation`, `hugging-face-model-trainer`, `hugging-face-paper-publisher`, `hugging-face-tool-builder` | [huggingface/skills](https://github.com/huggingface/skills) | Compatible | HuggingFace ML tools |
|
||||
| `numpy`, `pandas`, `scipy`, `matplotlib`, `scikit-learn`, `jupyter-workflow` | [K-Dense-AI/claude-scientific-skills](https://github.com/K-Dense-AI/claude-scientific-skills) | Compatible | Data science essentials |
|
||||
| `biopython`, `scanpy`, `uniprot-database`, `pubmed-database` | [K-Dense-AI/claude-scientific-skills](https://github.com/K-Dense-AI/claude-scientific-skills) | Compatible | Bioinformatics tools |
|
||||
|
||||
### Security & Auditing
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `semgrep-rule-creator`, `semgrep-rule-variant-creator`, `static-analysis`, `variant-analysis` | [trailofbits/skills](https://github.com/trailofbits/skills) | Compatible | Code security analysis |
|
||||
| `golang-security-auditor`, `python-security-auditor`, `rust-security-auditor` | [trailofbits/skills](https://github.com/trailofbits/skills) | Compatible | Language-specific security |
|
||||
| `burpsuite-project-parser`, `agentic-actions-auditor`, `audit-context-building`, `proof-of-vulnerability`, `yara-authoring` | [trailofbits/skills](https://github.com/trailofbits/skills) | Compatible | Security testing tools |
|
||||
|
||||
### Context Engineering & AI
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `context-fundamentals`, `context-degradation`, `context-compression`, `context-optimization`, `multi-agent-patterns`, `filesystem-context` | [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) | Compatible | Context engineering patterns |
|
||||
|
||||
### Health & Wellness
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `sleep-analyzer`, `nutrition-analyzer`, `fitness-analyzer` | [huifer/Claude-Ally-Health](https://github.com/huifer/Claude-Ally-Health) | Compatible | Health tracking |
|
||||
|
||||
### Quality & Verification
|
||||
| Skill | Source | License | Notes |
|
||||
|-------|--------|---------|-------|
|
||||
| `clarity-gate` | [frmoretto/clarity-gate](https://github.com/frmoretto/clarity-gate) | Compatible | RAG quality verification |
|
||||
|
||||
**Total: 80+ new skills added**
|
||||
|
||||
---
|
||||
|
||||
## License Policy
|
||||
|
||||
- **Code**: All original code in this repository is **MIT**.
|
||||
- **Content**: Documentation is **CC-BY-4.0**.
|
||||
- **Third Party**: We respect the upstream licenses. If an imported skill is GPL, it will be marked clearly or excluded (we aim for MIT/Apache compatibility).
|
||||
464
docs/users/bundles.md
Normal file
464
docs/users/bundles.md
Normal file
@@ -0,0 +1,464 @@
|
||||
# 📦 Antigravity Skill Bundles
|
||||
|
||||
> **Curated collections of skills organized by role and expertise level.** Don't know where to start? Pick a bundle below to get a curated set of skills for your role.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
1. **Install the repository:**
|
||||
|
||||
```bash
|
||||
npx antigravity-awesome-skills
|
||||
# or clone manually
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
2. **Choose your bundle** from the list below based on your role or interests.
|
||||
|
||||
3. **Use skills** by referencing them in your AI assistant:
|
||||
- Claude Code: `>> /skill-name help me...`
|
||||
- Cursor: `@skill-name in chat`
|
||||
- Gemini CLI: `Use skill-name...`
|
||||
- Codex CLI: `Use skill-name...`
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Essentials & Core
|
||||
|
||||
### 🚀 The "Essentials" Starter Pack
|
||||
|
||||
_For everyone. Install these first._
|
||||
|
||||
- [`concise-planning`](../../skills/concise-planning/): Always start with a plan.
|
||||
- [`lint-and-validate`](../../skills/lint-and-validate/): Keep your code clean automatically.
|
||||
- [`git-pushing`](../../skills/git-pushing/): Save your work safely.
|
||||
- [`kaizen`](../../skills/kaizen/): Continuous improvement mindset.
|
||||
- [`systematic-debugging`](../../skills/systematic-debugging/): Debug like a pro.
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Security & Compliance
|
||||
|
||||
### 🛡️ The "Security Engineer" Pack
|
||||
|
||||
_For pentesting, auditing, and hardening._
|
||||
|
||||
- [`ethical-hacking-methodology`](../../skills/ethical-hacking-methodology/): The Bible of ethical hacking.
|
||||
- [`burp-suite-testing`](../../skills/burp-suite-testing/): Web vulnerability scanning.
|
||||
- [`top-web-vulnerabilities`](../../skills/top-web-vulnerabilities/): OWASP-aligned vulnerability taxonomy.
|
||||
- [`linux-privilege-escalation`](../../skills/linux-privilege-escalation/): Advanced Linux security assessment.
|
||||
- [`cloud-penetration-testing`](../../skills/cloud-penetration-testing/): AWS/Azure/GCP security.
|
||||
- [`security-auditor`](../../skills/security-auditor/): Comprehensive security audits.
|
||||
- [`vulnerability-scanner`](../../skills/vulnerability-scanner/): Advanced vulnerability analysis.
|
||||
|
||||
### 🔐 The "Security Developer" Pack
|
||||
|
||||
_For building secure applications._
|
||||
|
||||
- [`api-security-best-practices`](../../skills/api-security-best-practices/): Secure API design patterns.
|
||||
- [`auth-implementation-patterns`](../../skills/auth-implementation-patterns/): JWT, OAuth2, session management.
|
||||
- [`backend-security-coder`](../../skills/backend-security-coder/): Secure backend coding practices.
|
||||
- [`frontend-security-coder`](../../skills/frontend-security-coder/): XSS prevention and client-side security.
|
||||
- [`cc-skill-security-review`](../../skills/cc-skill-security-review/): Security checklist for features.
|
||||
- [`pci-compliance`](../../skills/pci-compliance/): Payment card security standards.
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Web Development
|
||||
|
||||
### 🌐 The "Web Wizard" Pack
|
||||
|
||||
_For building modern, high-performance web apps._
|
||||
|
||||
- [`frontend-design`](../../skills/frontend-design/): UI guidelines and aesthetics.
|
||||
- [`react-best-practices`](../../skills/react-best-practices/): React & Next.js performance optimization.
|
||||
- [`react-patterns`](../../skills/react-patterns/): Modern React patterns and principles.
|
||||
- [`nextjs-best-practices`](../../skills/nextjs-best-practices/): Next.js App Router patterns.
|
||||
- [`tailwind-patterns`](../../skills/tailwind-patterns/): Tailwind CSS v4 styling superpowers.
|
||||
- [`form-cro`](../../skills/form-cro/): Optimize your forms for conversion.
|
||||
- [`seo-audit`](../../skills/seo-audit/): Get found on Google.
|
||||
|
||||
### 🖌️ The "Web Designer" Pack
|
||||
|
||||
_For pixel-perfect experiences._
|
||||
|
||||
- [`ui-ux-pro-max`](../../skills/ui-ux-pro-max/): Premium design systems and tokens.
|
||||
- [`frontend-design`](../../skills/frontend-design/): The base layer of aesthetics.
|
||||
- [`3d-web-experience`](../../skills/3d-web-experience/): Three.js & React Three Fiber magic.
|
||||
- [`canvas-design`](../../skills/canvas-design/): Static visuals and posters.
|
||||
- [`mobile-design`](../../skills/mobile-design/): Mobile-first design principles.
|
||||
- [`scroll-experience`](../../skills/scroll-experience/): Immersive scroll-driven experiences.
|
||||
|
||||
### ⚡ The "Full-Stack Developer" Pack
|
||||
|
||||
_For end-to-end web application development._
|
||||
|
||||
- [`senior-fullstack`](../../skills/senior-fullstack/): Complete fullstack development guide.
|
||||
- [`frontend-developer`](../../skills/frontend-developer/): React 19+ and Next.js 15+ expertise.
|
||||
- [`backend-dev-guidelines`](../../skills/backend-dev-guidelines/): Node.js/Express/TypeScript patterns.
|
||||
- [`api-patterns`](../../skills/api-patterns/): REST vs GraphQL vs tRPC selection.
|
||||
- [`database-design`](../../skills/database-design/): Schema design and ORM selection.
|
||||
- [`stripe-integration`](../../skills/stripe-integration/): Payments and subscriptions.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 AI & Agents
|
||||
|
||||
### 🤖 The "Agent Architect" Pack
|
||||
|
||||
_For building AI systems and autonomous agents._
|
||||
|
||||
- [`agent-evaluation`](../../skills/agent-evaluation/): Test and benchmark your agents.
|
||||
- [`langgraph`](../../skills/langgraph/): Build stateful agent workflows.
|
||||
- [`mcp-builder`](../../skills/mcp-builder/): Create your own MCP tools.
|
||||
- [`prompt-engineering`](../../skills/prompt-engineering/): Master the art of talking to LLMs.
|
||||
- [`ai-agents-architect`](../../skills/ai-agents-architect/): Design autonomous AI agents.
|
||||
- [`rag-engineer`](../../skills/rag-engineer/): Build RAG systems with vector search.
|
||||
|
||||
### 🧠 The "LLM Application Developer" Pack
|
||||
|
||||
_For building production LLM applications._
|
||||
|
||||
- [`llm-app-patterns`](../../skills/llm-app-patterns/): Production-ready LLM patterns.
|
||||
- [`rag-implementation`](../../skills/rag-implementation/): Retrieval-Augmented Generation.
|
||||
- [`prompt-caching`](../../skills/prompt-caching/): Cache strategies for LLM prompts.
|
||||
- [`context-window-management`](../../skills/context-window-management/): Manage LLM context efficiently.
|
||||
- [`langfuse`](../../skills/langfuse/): LLM observability and tracing.
|
||||
|
||||
---
|
||||
|
||||
## 🎮 Game Development
|
||||
|
||||
### 🎮 The "Indie Game Dev" Pack
|
||||
|
||||
_For building games with AI assistants._
|
||||
|
||||
- [`game-development/game-design`](../../skills/game-development/game-design/): Mechanics and loops.
|
||||
- [`game-development/2d-games`](../../skills/game-development/2d-games/): Sprites and physics.
|
||||
- [`game-development/3d-games`](../../skills/game-development/3d-games/): Models and shaders.
|
||||
- [`unity-developer`](../../skills/unity-developer/): Unity 6 LTS development.
|
||||
- [`godot-gdscript-patterns`](../../skills/godot-gdscript-patterns/): Godot 4 GDScript patterns.
|
||||
- [`algorithmic-art`](../../skills/algorithmic-art/): Generate assets with code.
|
||||
|
||||
---
|
||||
|
||||
## 🐍 Backend & Languages
|
||||
|
||||
### 🐍 The "Python Pro" Pack
|
||||
|
||||
_For backend heavyweights and data scientists._
|
||||
|
||||
- [`python-pro`](../../skills/python-pro/): Master Python 3.12+ with modern features.
|
||||
- [`python-patterns`](../../skills/python-patterns/): Idiomatic Python code.
|
||||
- [`fastapi-pro`](../../skills/fastapi-pro/): High-performance async APIs.
|
||||
- [`fastapi-templates`](../../skills/fastapi-templates/): Production-ready FastAPI projects.
|
||||
- [`django-pro`](../../skills/django-pro/): The battery-included framework.
|
||||
- [`python-testing-patterns`](../../skills/python-testing-patterns/): Comprehensive testing with pytest.
|
||||
- [`async-python-patterns`](../../skills/async-python-patterns/): Python asyncio mastery.
|
||||
|
||||
### 🟦 The "TypeScript & JavaScript" Pack
|
||||
|
||||
_For modern web development._
|
||||
|
||||
- [`typescript-expert`](../../skills/typescript-expert/): TypeScript mastery and advanced types.
|
||||
- [`javascript-pro`](../../skills/javascript-pro/): Modern JavaScript with ES6+.
|
||||
- [`react-best-practices`](../../skills/react-best-practices/): React performance optimization.
|
||||
- [`nodejs-best-practices`](../../skills/nodejs-best-practices/): Node.js development principles.
|
||||
- [`nextjs-app-router-patterns`](../../skills/nextjs-app-router-patterns/): Next.js 14+ App Router.
|
||||
|
||||
### 🦀 The "Systems Programming" Pack
|
||||
|
||||
_For low-level and performance-critical code._
|
||||
|
||||
- [`rust-pro`](../../skills/rust-pro/): Rust 1.75+ with async patterns.
|
||||
- [`go-concurrency-patterns`](../../skills/go-concurrency-patterns/): Go concurrency mastery.
|
||||
- [`golang-pro`](../../skills/golang-pro/): Go development expertise.
|
||||
- [`memory-safety-patterns`](../../skills/memory-safety-patterns/): Memory-safe programming.
|
||||
- [`cpp-pro`](../../skills/cpp-pro/): Modern C++ development.
|
||||
|
||||
---
|
||||
|
||||
## 🦄 Product & Business
|
||||
|
||||
### 🦄 The "Startup Founder" Pack
|
||||
|
||||
_For building products, not just code._
|
||||
|
||||
- [`product-manager-toolkit`](../../skills/product-manager-toolkit/): RICE prioritization, PRD templates.
|
||||
- [`competitive-landscape`](../../skills/competitive-landscape/): Competitor analysis.
|
||||
- [`competitor-alternatives`](../../skills/competitor-alternatives/): Create comparison pages.
|
||||
- [`launch-strategy`](../../skills/launch-strategy/): Product launch planning.
|
||||
- [`copywriting`](../../skills/copywriting/): Marketing copy that converts.
|
||||
- [`stripe-integration`](../../skills/stripe-integration/): Get paid from day one.
|
||||
|
||||
### 📊 The "Business Analyst" Pack
|
||||
|
||||
_For data-driven decision making._
|
||||
|
||||
- [`business-analyst`](../../skills/business-analyst/): AI-powered analytics and KPIs.
|
||||
- [`startup-metrics-framework`](../../skills/startup-metrics-framework/): SaaS metrics and unit economics.
|
||||
- [`startup-financial-modeling`](../../skills/startup-financial-modeling/): 3-5 year financial projections.
|
||||
- [`market-sizing-analysis`](../../skills/market-sizing-analysis/): TAM/SAM/SOM calculations.
|
||||
- [`kpi-dashboard-design`](../../skills/kpi-dashboard-design/): Effective KPI dashboards.
|
||||
|
||||
### 📈 The "Marketing & Growth" Pack
|
||||
|
||||
_For driving user acquisition and retention._
|
||||
|
||||
- [`content-creator`](../../skills/content-creator/): SEO-optimized marketing content.
|
||||
- [`seo-audit`](../../skills/seo-audit/): Technical SEO health checks.
|
||||
- [`programmatic-seo`](../../skills/programmatic-seo/): Create pages at scale.
|
||||
- [`analytics-tracking`](../../skills/analytics-tracking/): Set up GA4/PostHog correctly.
|
||||
- [`ab-test-setup`](../../skills/ab-test-setup/): Validated learning experiments.
|
||||
- [`email-sequence`](../../skills/email-sequence/): Automated email campaigns.
|
||||
|
||||
---
|
||||
|
||||
## 🌧️ DevOps & Infrastructure
|
||||
|
||||
### 🌧️ The "DevOps & Cloud" Pack
|
||||
|
||||
_For infrastructure and scaling._
|
||||
|
||||
- [`docker-expert`](../../skills/docker-expert/): Master containers and multi-stage builds.
|
||||
- [`aws-serverless`](../../skills/aws-serverless/): Serverless on AWS (Lambda, DynamoDB).
|
||||
- [`kubernetes-architect`](../../skills/kubernetes-architect/): K8s architecture and GitOps.
|
||||
- [`terraform-specialist`](../../skills/terraform-specialist/): Infrastructure as Code mastery.
|
||||
- [`environment-setup-guide`](../../skills/environment-setup-guide/): Standardization for teams.
|
||||
- [`deployment-procedures`](../../skills/deployment-procedures/): Safe rollout strategies.
|
||||
- [`bash-linux`](../../skills/bash-linux/): Terminal wizardry.
|
||||
|
||||
### 📊 The "Observability & Monitoring" Pack
|
||||
|
||||
_For production reliability._
|
||||
|
||||
- [`observability-engineer`](../../skills/observability-engineer/): Comprehensive monitoring systems.
|
||||
- [`distributed-tracing`](../../skills/distributed-tracing/): Track requests across microservices.
|
||||
- [`slo-implementation`](../../skills/slo-implementation/): Service Level Objectives.
|
||||
- [`incident-responder`](../../skills/incident-responder/): Rapid incident response.
|
||||
- [`postmortem-writing`](../../skills/postmortem-writing/): Blameless postmortems.
|
||||
- [`performance-engineer`](../../skills/performance-engineer/): Application performance optimization.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Data & Analytics
|
||||
|
||||
### 📊 The "Data & Analytics" Pack
|
||||
|
||||
_For making sense of the numbers._
|
||||
|
||||
- [`analytics-tracking`](../../skills/analytics-tracking/): Set up GA4/PostHog correctly.
|
||||
- [`claude-d3js-skill`](../../skills/claude-d3js-skill/): Beautiful custom visualizations with D3.js.
|
||||
- [`sql-pro`](../../skills/sql-pro/): Modern SQL with cloud-native databases.
|
||||
- [`postgres-best-practices`](../../skills/postgres-best-practices/): Postgres optimization.
|
||||
- [`ab-test-setup`](../../skills/ab-test-setup/): Validated learning.
|
||||
- [`database-architect`](../../skills/database-architect/): Database design from scratch.
|
||||
|
||||
### 🔄 The "Data Engineering" Pack
|
||||
|
||||
_For building data pipelines._
|
||||
|
||||
- [`data-engineer`](../../skills/data-engineer/): Data pipeline architecture.
|
||||
- [`airflow-dag-patterns`](../../skills/airflow-dag-patterns/): Apache Airflow DAGs.
|
||||
- [`dbt-transformation-patterns`](../../skills/dbt-transformation-patterns/): Analytics engineering.
|
||||
- [`vector-database-engineer`](../../skills/vector-database-engineer/): Vector databases for RAG.
|
||||
- [`embedding-strategies`](../../skills/embedding-strategies/): Embedding model selection.
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Creative & Content
|
||||
|
||||
### 🎨 The "Creative Director" Pack
|
||||
|
||||
_For visuals, content, and branding._
|
||||
|
||||
- [`canvas-design`](../../skills/canvas-design/): Generate posters and diagrams.
|
||||
- [`frontend-design`](../../skills/frontend-design/): UI aesthetics.
|
||||
- [`content-creator`](../../skills/content-creator/): SEO-optimized blog posts.
|
||||
- [`copy-editing`](../../skills/copy-editing/): Polish your prose.
|
||||
- [`algorithmic-art`](../../skills/algorithmic-art/): Code-generated masterpieces.
|
||||
- [`interactive-portfolio`](../../skills/interactive-portfolio/): Portfolios that land jobs.
|
||||
|
||||
---
|
||||
|
||||
## 🐞 Quality Assurance
|
||||
|
||||
### 🐞 The "QA & Testing" Pack
|
||||
|
||||
_For breaking things before users do._
|
||||
|
||||
- [`test-driven-development`](../../skills/test-driven-development/): Red, Green, Refactor.
|
||||
- [`systematic-debugging`](../../skills/systematic-debugging/): Debug like Sherlock Holmes.
|
||||
- [`browser-automation`](../../skills/browser-automation/): End-to-end testing with Playwright.
|
||||
- [`e2e-testing-patterns`](../../skills/e2e-testing-patterns/): Reliable E2E test suites.
|
||||
- [`ab-test-setup`](../../skills/ab-test-setup/): Validated experiments.
|
||||
- [`code-review-checklist`](../../skills/code-review-checklist/): Catch bugs in PRs.
|
||||
- [`test-fixing`](../../skills/test-fixing/): Fix failing tests systematically.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Specialized Packs
|
||||
|
||||
### 📱 The "Mobile Developer" Pack
|
||||
|
||||
_For iOS, Android, and cross-platform apps._
|
||||
|
||||
- [`mobile-developer`](../../skills/mobile-developer/): Cross-platform mobile development.
|
||||
- [`react-native-architecture`](../../skills/react-native-architecture/): React Native with Expo.
|
||||
- [`flutter-expert`](../../skills/flutter-expert/): Flutter multi-platform apps.
|
||||
- [`ios-developer`](../../skills/ios-developer/): iOS development with Swift.
|
||||
- [`app-store-optimization`](../../skills/app-store-optimization/): ASO for App Store and Play Store.
|
||||
|
||||
### 🔗 The "Integration & APIs" Pack
|
||||
|
||||
_For connecting services and building integrations._
|
||||
|
||||
- [`stripe-integration`](../../skills/stripe-integration/): Payments and subscriptions.
|
||||
- [`twilio-communications`](../../skills/twilio-communications/): SMS, voice, WhatsApp.
|
||||
- [`hubspot-integration`](../../skills/hubspot-integration/): CRM integration.
|
||||
- [`plaid-fintech`](../../skills/plaid-fintech/): Bank account linking and ACH.
|
||||
- [`algolia-search`](../../skills/algolia-search/): Search implementation.
|
||||
|
||||
### 🎯 The "Architecture & Design" Pack
|
||||
|
||||
_For system design and technical decisions._
|
||||
|
||||
- [`senior-architect`](../../skills/senior-architect/): Comprehensive software architecture.
|
||||
- [`architecture-patterns`](../../skills/architecture-patterns/): Clean Architecture, DDD, Hexagonal.
|
||||
- [`microservices-patterns`](../../skills/microservices-patterns/): Microservices architecture.
|
||||
- [`event-sourcing-architect`](../../skills/event-sourcing-architect/): Event sourcing and CQRS.
|
||||
- [`architecture-decision-records`](../../skills/architecture-decision-records/): Document technical decisions.
|
||||
|
||||
### 🧱 The "DDD & Evented Architecture" Pack
|
||||
|
||||
_For teams modeling complex domains and evolving toward evented systems._
|
||||
|
||||
- [`domain-driven-design`](../../skills/domain-driven-design/): Route DDD work from strategic modeling to implementation patterns.
|
||||
- [`ddd-strategic-design`](../../skills/ddd-strategic-design/): Subdomains, bounded contexts, and ubiquitous language.
|
||||
- [`ddd-context-mapping`](../../skills/ddd-context-mapping/): Cross-context integration and anti-corruption boundaries.
|
||||
- [`ddd-tactical-patterns`](../../skills/ddd-tactical-patterns/): Aggregates, value objects, repositories, and domain events.
|
||||
- [`cqrs-implementation`](../../skills/cqrs-implementation/): Read/write model separation.
|
||||
- [`event-store-design`](../../skills/event-store-design/): Event persistence and replay architecture.
|
||||
- [`saga-orchestration`](../../skills/saga-orchestration/): Cross-context long-running transaction coordination.
|
||||
- [`projection-patterns`](../../skills/projection-patterns/): Materialized read models from event streams.
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Maintainer & OSS
|
||||
|
||||
### 🛠️ The "OSS Maintainer" Pack
|
||||
|
||||
_For shipping clean changes in public repositories._
|
||||
|
||||
- [`commit`](../../skills/commit/): High-quality conventional commits.
|
||||
- [`create-pr`](../../skills/create-pr/): PR creation with review-ready context.
|
||||
- [`requesting-code-review`](../../skills/requesting-code-review/): Ask for targeted, high-signal reviews.
|
||||
- [`receiving-code-review`](../../skills/receiving-code-review/): Apply feedback with technical rigor.
|
||||
- [`changelog-automation`](../../skills/changelog-automation/): Keep release notes and changelogs consistent.
|
||||
- [`git-advanced-workflows`](../../skills/git-advanced-workflows/): Rebase, cherry-pick, bisect, recovery.
|
||||
- [`documentation-templates`](../../skills/documentation-templates/): Standardize docs and handoffs.
|
||||
|
||||
### 🧱 The "Skill Author" Pack
|
||||
|
||||
_For creating and maintaining high-quality SKILL.md assets._
|
||||
|
||||
- [`skill-creator`](../../skills/skill-creator/): Design effective new skills.
|
||||
- [`skill-developer`](../../skills/skill-developer/): Implement triggers, hooks, and skill lifecycle.
|
||||
- [`writing-skills`](../../skills/writing-skills/): Improve clarity and structure of skill instructions.
|
||||
- [`documentation-generation-doc-generate`](../../skills/documentation-generation-doc-generate/): Generate maintainable technical docs.
|
||||
- [`lint-and-validate`](../../skills/lint-and-validate/): Validate quality after edits.
|
||||
- [`verification-before-completion`](../../skills/verification-before-completion/): Confirm changes before claiming done.
|
||||
|
||||
---
|
||||
|
||||
## 📚 How to Use Bundles
|
||||
|
||||
### 1) Pick by immediate goal
|
||||
|
||||
- Need to ship a feature now: `Essentials` + one domain pack (`Web Wizard`, `Python Pro`, `DevOps & Cloud`).
|
||||
- Need reliability and hardening: add `QA & Testing` + `Security Developer`.
|
||||
- Need product growth: add `Startup Founder` or `Marketing & Growth`.
|
||||
|
||||
### 2) Start with 3-5 skills, not 20
|
||||
|
||||
Pick the minimum set for your current milestone. Expand only when you hit a real gap.
|
||||
|
||||
### 3) Invoke skills consistently
|
||||
|
||||
- **Claude Code**: `>> /skill-name help me...`
|
||||
- **Cursor**: `@skill-name` in chat
|
||||
- **Gemini CLI**: `Use skill-name...`
|
||||
- **Codex CLI**: `Use skill-name...`
|
||||
|
||||
### 4) Build your personal shortlist
|
||||
|
||||
Keep a small list of high-frequency skills and reuse it across tasks to reduce context switching.
|
||||
|
||||
## 🧩 Recommended Bundle Combos
|
||||
|
||||
### Ship a SaaS MVP (2 weeks)
|
||||
|
||||
`Essentials` + `Full-Stack Developer` + `QA & Testing` + `Startup Founder`
|
||||
|
||||
### Harden an existing production app
|
||||
|
||||
`Essentials` + `Security Developer` + `DevOps & Cloud` + `Observability & Monitoring`
|
||||
|
||||
### Build an AI product
|
||||
|
||||
`Essentials` + `Agent Architect` + `LLM Application Developer` + `Data Engineering`
|
||||
|
||||
### Grow traffic and conversions
|
||||
|
||||
`Web Wizard` + `Marketing & Growth` + `Data & Analytics`
|
||||
|
||||
### Launch and maintain open source
|
||||
|
||||
`Essentials` + `OSS Maintainer` + `Architecture & Design`
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Paths
|
||||
|
||||
### Beginner → Intermediate → Advanced
|
||||
|
||||
**Web Development:**
|
||||
|
||||
1. Start: `Essentials` → `Web Wizard`
|
||||
2. Grow: `Full-Stack Developer` → `Architecture & Design`
|
||||
3. Master: `Observability & Monitoring` → `Security Developer`
|
||||
|
||||
**AI/ML:**
|
||||
|
||||
1. Start: `Essentials` → `Agent Architect`
|
||||
2. Grow: `LLM Application Developer` → `Data Engineering`
|
||||
3. Master: Advanced RAG and agent orchestration
|
||||
|
||||
**Security:**
|
||||
|
||||
1. Start: `Essentials` → `Security Developer`
|
||||
2. Grow: `Security Engineer` → Advanced pentesting
|
||||
3. Master: Red team tactics and threat modeling
|
||||
|
||||
**Open Source Maintenance:**
|
||||
|
||||
1. Start: `Essentials` → `OSS Maintainer`
|
||||
2. Grow: `Architecture & Design` → `QA & Testing`
|
||||
3. Master: `Skill Author` + release automation workflows
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Found a skill that should be in a bundle? Or want to create a new bundle? [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) or submit a PR!
|
||||
|
||||
---
|
||||
|
||||
## 📖 Related Documentation
|
||||
|
||||
- [Getting Started Guide](getting-started.md)
|
||||
- [Full Skill Catalog](../../CATALOG.md)
|
||||
- [Contributing Guide](../../CONTRIBUTING.md)
|
||||
|
||||
---
|
||||
|
||||
_Last updated: March 2026 | Total Skills: 1,204+ | Total Bundles: 26_
|
||||
197
docs/users/faq.md
Normal file
197
docs/users/faq.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# ❓ Frequently Asked Questions (FAQ)
|
||||
|
||||
**Got questions?** You're not alone! Here are answers to the most common questions about Antigravity Awesome Skills.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 General Questions
|
||||
|
||||
### What are "skills" exactly?
|
||||
|
||||
Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
|
||||
**Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), these skills let your AI become an expert in different areas when you need them.
|
||||
|
||||
### Do I need to install all 1,204+ skills?
|
||||
|
||||
**No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name`.
|
||||
It's like having a library - all books are there, but you only read the ones you need.
|
||||
**Pro Tip:** Use [Starter Packs](bundles.md) to install only what matches your role.
|
||||
|
||||
### What is the difference between Bundles and Workflows?
|
||||
|
||||
- **Bundles** are curated recommendations grouped by role or domain.
|
||||
- **Workflows** are ordered execution playbooks for concrete outcomes.
|
||||
|
||||
Use bundles when you are deciding _which skills_ to include. Use workflows when you need _step-by-step execution_.
|
||||
|
||||
Start from:
|
||||
|
||||
- [bundles.md](bundles.md)
|
||||
- [workflows.md](workflows.md)
|
||||
|
||||
### Which AI tools work with these skills?
|
||||
|
||||
- ✅ **Claude Code** (Anthropic CLI)
|
||||
- ✅ **Gemini CLI** (Google)
|
||||
- ✅ **Codex CLI** (OpenAI)
|
||||
- ✅ **Cursor** (AI IDE)
|
||||
- ✅ **Antigravity IDE**
|
||||
- ✅ **OpenCode**
|
||||
- ⚠️ **GitHub Copilot** (partial support via copy-paste)
|
||||
|
||||
### Are these skills free to use?
|
||||
|
||||
**Yes!** This repository is licensed under MIT License.
|
||||
|
||||
- ✅ Free for personal use
|
||||
- ✅ Free for commercial use
|
||||
- ✅ You can modify them
|
||||
|
||||
### Do skills work offline?
|
||||
|
||||
The skill files themselves are stored locally on your computer, but your AI assistant needs an internet connection to function.
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security & Trust (V4 Update)
|
||||
|
||||
### What do the Risk Labels mean?
|
||||
|
||||
We classify skills so you know what you're running:
|
||||
|
||||
- ⚪ **Safe (White/Blue)**: Read-only, planning, or benign skills.
|
||||
- 🔴 **Risk (Red)**: Skills that modify files (delete), use network scanners, or perform destructive actions. **Use with caution.**
|
||||
- 🟣 **Official (Purple)**: Maintained by trusted vendors (Anthropic, DeepMind, etc.).
|
||||
|
||||
### Can these skills hack my computer?
|
||||
|
||||
**No.** Skills are text files. However, they _instruct_ the AI to run commands. If a skill says "delete all files", a compliant AI might try to do it.
|
||||
_Always check the Risk label and review the code._
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation & Setup
|
||||
|
||||
### Where should I install the skills?
|
||||
|
||||
The universal path that works with most tools is `.agent/skills/`.
|
||||
|
||||
**Using npx:** `npx antigravity-awesome-skills` (or `npx github:sickn33/antigravity-awesome-skills` if you get a 404).
|
||||
|
||||
**Using git clone:**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
**Tool-specific paths:**
|
||||
|
||||
- Claude Code: `.claude/skills/`
|
||||
- Gemini CLI: `.gemini/skills/`
|
||||
- Codex CLI: `.codex/skills/`
|
||||
- Cursor: `.cursor/skills/` or project root
|
||||
|
||||
### Does this work with Windows?
|
||||
|
||||
**Yes**, but some "Official" skills use **symlinks** which Windows handles poorly by default.
|
||||
Run git with:
|
||||
|
||||
```bash
|
||||
git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
Or enable "Developer Mode" in Windows Settings.
|
||||
|
||||
### How do I update skills?
|
||||
|
||||
Navigate to your skills directory and pull the latest changes:
|
||||
|
||||
```bash
|
||||
cd .agent/skills
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Using Skills
|
||||
|
||||
> **💡 For a complete guide with examples, see [usage.md](usage.md)**
|
||||
|
||||
### How do I invoke a skill?
|
||||
|
||||
Use the `@` symbol followed by the skill name:
|
||||
|
||||
```bash
|
||||
@brainstorming help me design a todo app
|
||||
```
|
||||
|
||||
### Can I use multiple skills at once?
|
||||
|
||||
**Yes!** You can invoke multiple skills:
|
||||
|
||||
```bash
|
||||
@brainstorming help me design this, then use @writing-plans to create a task list.
|
||||
```
|
||||
|
||||
### How do I know which skill to use?
|
||||
|
||||
1. **Browse the catalog**: Check the [Skill Catalog](../../CATALOG.md).
|
||||
2. **Search**: `ls skills/ | grep "keyword"`
|
||||
3. **Ask your AI**: "What skills do you have for testing?"
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Troubleshooting
|
||||
|
||||
### My AI assistant doesn't recognize skills
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. **Wrong installation path**: Check your tool's docs. Try `.agent/skills/`.
|
||||
2. **Restart Needed**: Restart your AI/IDE after installing.
|
||||
3. **Typos**: Did you type `@brain-storming` instead of `@brainstorming`?
|
||||
|
||||
### A skill gives incorrect or outdated advice
|
||||
|
||||
Please [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues)!
|
||||
Include:
|
||||
|
||||
- Which skill
|
||||
- What went wrong
|
||||
- What should happen instead
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contribution
|
||||
|
||||
### I'm new to open source. Can I contribute?
|
||||
|
||||
**Absolutely!** We welcome beginners.
|
||||
|
||||
- Fix typos
|
||||
- Add examples
|
||||
- Improve docs
|
||||
Check out [CONTRIBUTING.md](../../CONTRIBUTING.md) for instructions.
|
||||
|
||||
### My PR failed "Quality Bar" check. Why?
|
||||
|
||||
V4 introduces automated quality control. Your skill might be missing:
|
||||
|
||||
1. A valid `description`.
|
||||
2. Usage examples.
|
||||
Run `npm run validate` locally to check before you push.
|
||||
|
||||
### Can I update an "Official" skill?
|
||||
|
||||
**No.** Official skills (in `skills/official/`) are mirrored from vendors. Open an issue instead.
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
- Start with `@brainstorming` before building anything new
|
||||
- Use `@systematic-debugging` when stuck on bugs
|
||||
- Try `@test-driven-development` for better code quality
|
||||
- Explore `@skill-creator` to make your own skills
|
||||
|
||||
**Still confused?** [Open a discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) and we'll help you out! 🙌
|
||||
142
docs/users/getting-started.md
Normal file
142
docs/users/getting-started.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Getting Started with Antigravity Awesome Skills (V7.0.0)
|
||||
|
||||
**New here? This guide will help you supercharge your AI Agent in 5 minutes.**
|
||||
|
||||
> **💡 Confused about what to do after installation?** Check out the [**Complete Usage Guide**](usage.md) for detailed explanations and examples!
|
||||
|
||||
---
|
||||
|
||||
## 🤔 What Are "Skills"?
|
||||
|
||||
AI Agents (like **Claude Code**, **Gemini**, **Cursor**) are smart, but they lack specific knowledge about your tools.
|
||||
**Skills** are specialized instruction manuals (markdown files) that teach your AI how to perform specific tasks perfectly, every time.
|
||||
|
||||
**Analogy:** Your AI is a brilliant intern. **Skills** are the SOPs (Standard Operating Procedures) that make them a Senior Engineer.
|
||||
|
||||
---
|
||||
|
||||
## ⚡️ Quick Start: The "Starter Packs"
|
||||
|
||||
Don't panic about the 1,200+ skills. You don't need them all at once.
|
||||
We have curated **Starter Packs** to get you running immediately.
|
||||
|
||||
You **install the full repo once** (npx or clone); Starter Packs are curated lists to help you **pick which skills to use** by role (e.g. Web Wizard, Hacker Pack)—they are not a different way to install.
|
||||
|
||||
### 1. Install the Repo
|
||||
|
||||
**Option A — npx (easiest):**
|
||||
|
||||
```bash
|
||||
npx antigravity-awesome-skills
|
||||
```
|
||||
|
||||
This clones to `~/.gemini/antigravity/skills` by default. Use `--cursor`, `--claude`, `--gemini`, `--codex`, or `--kiro` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
|
||||
|
||||
If you see a 404 error, use: `npx github:sickn33/antigravity-awesome-skills`
|
||||
|
||||
**Option B — git clone:**
|
||||
|
||||
```bash
|
||||
# Universal (works for most agents)
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
### 2. Pick Your Persona
|
||||
|
||||
Find the bundle that matches your role (see [bundles.md](bundles.md)):
|
||||
|
||||
| Persona | Bundle Name | What's Inside? |
|
||||
| :-------------------- | :------------- | :------------------------------------------------ |
|
||||
| **Web Developer** | `Web Wizard` | React Patterns, Tailwind mastery, Frontend Design |
|
||||
| **Security Engineer** | `Hacker Pack` | OWASP, Metasploit, Pentest Methodology |
|
||||
| **Manager / PM** | `Product Pack` | Brainstorming, Planning, SEO, Strategy |
|
||||
| **Everything** | `Essentials` | Clean Code, Planning, Validation (The Basics) |
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Bundles vs Workflows
|
||||
|
||||
Bundles and workflows solve different problems:
|
||||
|
||||
- **Bundles** = curated sets by role (what to pick).
|
||||
- **Workflows** = step-by-step playbooks (how to execute).
|
||||
|
||||
Start with bundles in [bundles.md](bundles.md), then run a workflow from [workflows.md](workflows.md) when you need guided execution.
|
||||
|
||||
Example:
|
||||
|
||||
> "Use **@antigravity-workflows** and run `ship-saas-mvp` for my project idea."
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Use a Skill
|
||||
|
||||
Once installed, just talk to your AI naturally.
|
||||
|
||||
### Example 1: Planning a Feature (**Essentials**)
|
||||
|
||||
> "Use **@brainstorming** to help me design a new login flow."
|
||||
|
||||
**What happens:** The AI loads the brainstorming skill, asks you structured questions, and produces a professional spec.
|
||||
|
||||
### Example 2: Checking Your Code (**Web Wizard**)
|
||||
|
||||
> "Run **@lint-and-validate** on this file and fix errors."
|
||||
|
||||
**What happens:** The AI follows strict linting rules defined in the skill to clean your code.
|
||||
|
||||
### Example 3: Security Audit (**Hacker Pack**)
|
||||
|
||||
> "Use **@api-security-best-practices** to review my API endpoints."
|
||||
|
||||
**What happens:** The AI audits your code against OWASP standards.
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Supported Tools
|
||||
|
||||
| Tool | Status | Path |
|
||||
| :-------------- | :-------------- | :-------------------------------------------------------------------- |
|
||||
| **Claude Code** | ✅ Full Support | `.claude/skills/` |
|
||||
| **Gemini CLI** | ✅ Full Support | `.gemini/skills/` |
|
||||
| **Codex CLI** | ✅ Full Support | `.codex/skills/` |
|
||||
| **Kiro CLI** | ✅ Full Support | Global: `~/.kiro/skills/` · Workspace: `.kiro/skills/` |
|
||||
| **Kiro IDE** | ✅ Full Support | Global: `~/.kiro/skills/` · Workspace: `.kiro/skills/` |
|
||||
| **Antigravity** | ✅ Native | Global: `~/.gemini/antigravity/skills/` · Workspace: `.agent/skills/` |
|
||||
| **Cursor** | ✅ Native | `.cursor/skills/` |
|
||||
| **OpenCode** | ✅ Full Support | `.agents/skills/` |
|
||||
| **AdaL CLI** | ✅ Full Support | `.adal/skills/` |
|
||||
| **Copilot** | ⚠️ Text Only | Manual copy-paste |
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Trust & Safety (New in V4)
|
||||
|
||||
We classify skills so you know what you're running:
|
||||
|
||||
- 🟣 **Official**: Maintained by Anthropic/Google/Vendors (High Trust).
|
||||
- 🔵 **Safe**: Community skills that are non-destructive (Read-only/Planning).
|
||||
- 🔴 **Risk**: Skills that modify systems or perform security tests (Authorized Use Only).
|
||||
|
||||
_Check the [Skill Catalog](../../CATALOG.md) for the full list._
|
||||
|
||||
---
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
**Q: Do I need to install all 1,204+ skills?**
|
||||
A: You clone the whole repo once; your AI only _reads_ the skills you invoke (or that are relevant), so it stays lightweight. **Starter Packs** in [bundles.md](bundles.md) are curated lists to help you discover the right skills for your role—they don't change how you install.
|
||||
|
||||
**Q: Can I make my own skills?**
|
||||
A: Yes! Use the **@skill-creator** skill to build your own.
|
||||
|
||||
**Q: Is this free?**
|
||||
A: Yes, MIT License. Open Source forever.
|
||||
|
||||
---
|
||||
|
||||
## ⏭️ Next Steps
|
||||
|
||||
1. [Browse the Bundles](bundles.md)
|
||||
2. [See Real-World Examples](../contributors/examples.md)
|
||||
3. [Contribute a Skill](../../CONTRIBUTING.md)
|
||||
304
docs/users/kiro-integration.md
Normal file
304
docs/users/kiro-integration.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# Kiro CLI Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to use Antigravity Awesome Skills with **Kiro CLI**, AWS's agentic AI-powered coding assistant.
|
||||
|
||||
## What is Kiro?
|
||||
|
||||
Kiro is AWS's agentic AI IDE that combines:
|
||||
|
||||
- **Autonomous coding agents** that work independently for extended periods
|
||||
- **Context-aware assistance** with deep understanding of your codebase
|
||||
- **AWS service integration** with native support for CDK, SAM, and Terraform
|
||||
- **MCP (Model Context Protocol)** for secure external API and database calls
|
||||
- **Spec-driven development** that turns natural language into structured specifications
|
||||
|
||||
## Why Use Skills with Kiro?
|
||||
|
||||
Kiro's agentic capabilities are enhanced by skills that provide:
|
||||
|
||||
- **Domain expertise** across 1,204+ specialized areas
|
||||
- **Best practices** from Anthropic, OpenAI, Google, Microsoft, and AWS
|
||||
- **Workflow automation** for common development tasks
|
||||
- **AWS-specific patterns** for serverless, infrastructure, and cloud architecture
|
||||
|
||||
## Installation
|
||||
|
||||
### Quick Install
|
||||
|
||||
```bash
|
||||
# Install to Kiro's default skills directory
|
||||
npx antigravity-awesome-skills --kiro
|
||||
```
|
||||
|
||||
This installs skills to `~/.kiro/skills/`
|
||||
|
||||
### Manual Installation
|
||||
|
||||
```bash
|
||||
# Clone directly to Kiro's skills directory
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git ~/.kiro/skills
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Verify installation
|
||||
test -d ~/.kiro/skills && echo "✓ Skills installed successfully"
|
||||
ls ~/.kiro/skills/skills/ | head -10
|
||||
```
|
||||
|
||||
## Using Skills with Kiro
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
Kiro uses natural language prompts to invoke skills:
|
||||
|
||||
```
|
||||
Use the @brainstorming skill to help me design a serverless API
|
||||
```
|
||||
|
||||
```
|
||||
Apply @aws-serverless patterns to this Lambda function
|
||||
```
|
||||
|
||||
```
|
||||
Run @security-audit on my CDK stack
|
||||
```
|
||||
|
||||
### Recommended Skills for Kiro Users
|
||||
|
||||
#### AWS & Cloud Infrastructure
|
||||
|
||||
- `@aws-serverless` - Serverless architecture patterns
|
||||
- `@aws-cdk` - AWS CDK best practices
|
||||
- `@aws-sam` - SAM template patterns
|
||||
- `@terraform-expert` - Terraform infrastructure as code
|
||||
- `@docker-expert` - Container optimization
|
||||
- `@kubernetes-expert` - K8s deployment patterns
|
||||
|
||||
#### Architecture & Design
|
||||
|
||||
- `@architecture` - System design and ADRs
|
||||
- `@c4-context` - C4 model diagrams
|
||||
- `@senior-architect` - Scalable architecture patterns
|
||||
- `@microservices-patterns` - Microservices design
|
||||
|
||||
#### Security
|
||||
|
||||
- `@api-security-best-practices` - API security hardening
|
||||
- `@vulnerability-scanner` - Security vulnerability detection
|
||||
- `@owasp-top-10` - OWASP security patterns
|
||||
- `@aws-security-best-practices` - AWS security configuration
|
||||
|
||||
#### Development
|
||||
|
||||
- `@typescript-expert` - TypeScript best practices
|
||||
- `@python-patterns` - Python design patterns
|
||||
- `@react-patterns` - React component patterns
|
||||
- `@test-driven-development` - TDD workflows
|
||||
|
||||
#### DevOps & Automation
|
||||
|
||||
- `@ci-cd-pipeline` - CI/CD automation
|
||||
- `@github-actions` - GitHub Actions workflows
|
||||
- `@monitoring-observability` - Observability patterns
|
||||
- `@incident-response` - Incident management
|
||||
|
||||
## Kiro-Specific Workflows
|
||||
|
||||
### 1. Serverless Application Development
|
||||
|
||||
```
|
||||
1. Use @brainstorming to design the application architecture
|
||||
2. Apply @aws-serverless to create Lambda functions
|
||||
3. Use @aws-cdk to generate infrastructure code
|
||||
4. Run @test-driven-development to add tests
|
||||
5. Apply @ci-cd-pipeline to set up deployment
|
||||
```
|
||||
|
||||
### 2. Infrastructure as Code
|
||||
|
||||
```
|
||||
1. Use @architecture to document the system design
|
||||
2. Apply @terraform-expert to write Terraform modules
|
||||
3. Run @security-audit to check for vulnerabilities
|
||||
4. Use @documentation to generate README and runbooks
|
||||
```
|
||||
|
||||
### 3. API Development
|
||||
|
||||
```
|
||||
1. Use @api-design to plan endpoints
|
||||
2. Apply @typescript-expert for implementation
|
||||
3. Run @api-security-best-practices for hardening
|
||||
4. Use @openapi-spec to generate documentation
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### MCP Integration
|
||||
|
||||
Kiro's MCP support allows skills to:
|
||||
|
||||
- Call external APIs securely
|
||||
- Query databases with context
|
||||
- Integrate with AWS services
|
||||
- Access documentation in real-time
|
||||
|
||||
Skills that leverage MCP:
|
||||
|
||||
- `@rag-engineer` - RAG system implementation
|
||||
- `@langgraph` - Agent workflow orchestration
|
||||
- `@prompt-engineer` - LLM prompt optimization
|
||||
|
||||
### Autonomous Operation
|
||||
|
||||
Kiro can work independently for extended periods. Use skills to guide long-running tasks:
|
||||
|
||||
```
|
||||
Use @systematic-debugging to investigate and fix all TypeScript errors in the codebase,
|
||||
then apply @test-driven-development to add missing tests, and finally run @documentation
|
||||
to update all README files.
|
||||
```
|
||||
|
||||
### Context-Aware Assistance
|
||||
|
||||
Kiro maintains deep context. Reference multiple skills in complex workflows:
|
||||
|
||||
```
|
||||
I'm building a SaaS application. Use @brainstorming for the MVP plan,
|
||||
@aws-serverless for the backend, @react-patterns for the frontend,
|
||||
@stripe-integration for payments, and @security-audit for hardening.
|
||||
```
|
||||
|
||||
## Bundles for Kiro Users
|
||||
|
||||
Pre-curated skill collections optimized for common Kiro use cases:
|
||||
|
||||
### AWS Developer Bundle
|
||||
|
||||
- `@aws-serverless`
|
||||
- `@aws-cdk`
|
||||
- `@aws-sam`
|
||||
- `@lambda-best-practices`
|
||||
- `@dynamodb-patterns`
|
||||
- `@api-gateway-patterns`
|
||||
|
||||
### Full-Stack AWS Bundle
|
||||
|
||||
- `@aws-serverless`
|
||||
- `@react-patterns`
|
||||
- `@typescript-expert`
|
||||
- `@api-design`
|
||||
- `@test-driven-development`
|
||||
- `@ci-cd-pipeline`
|
||||
|
||||
### DevOps & Infrastructure Bundle
|
||||
|
||||
- `@terraform-expert`
|
||||
- `@docker-expert`
|
||||
- `@kubernetes-expert`
|
||||
- `@monitoring-observability`
|
||||
- `@incident-response`
|
||||
- `@security-audit`
|
||||
|
||||
See [bundles.md](bundles.md) for complete bundle listings.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skills Not Loading
|
||||
|
||||
```bash
|
||||
# Check installation path
|
||||
ls -la ~/.kiro/skills/
|
||||
|
||||
# Reinstall if needed
|
||||
rm -rf ~/.kiro/skills
|
||||
npx antigravity-awesome-skills --kiro
|
||||
```
|
||||
|
||||
### Skill Not Found
|
||||
|
||||
Ensure you're using the correct skill name:
|
||||
|
||||
```bash
|
||||
# List all available skills
|
||||
ls ~/.kiro/skills/skills/
|
||||
```
|
||||
|
||||
### Permission Issues
|
||||
|
||||
```bash
|
||||
# Fix permissions
|
||||
chmod -R 755 ~/.kiro/skills/
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with bundles** - Use pre-curated collections for your role
|
||||
2. **Combine skills** - Reference multiple skills in complex tasks
|
||||
3. **Be specific** - Clearly state which skill to use and what to do
|
||||
4. **Iterate** - Let Kiro work autonomously, then refine with additional skills
|
||||
5. **Document** - Use `@documentation` to keep your codebase well-documented
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Build a Serverless API
|
||||
|
||||
```
|
||||
I need to build a REST API for a todo application using AWS Lambda and DynamoDB.
|
||||
|
||||
Use @brainstorming to design the architecture, then apply @aws-serverless
|
||||
to implement the Lambda functions, @dynamodb-patterns for data modeling,
|
||||
and @api-security-best-practices for security hardening.
|
||||
|
||||
Generate the infrastructure using @aws-cdk and add tests with @test-driven-development.
|
||||
```
|
||||
|
||||
### Example 2: Migrate to Microservices
|
||||
|
||||
```
|
||||
I want to break down this monolithic application into microservices.
|
||||
|
||||
Use @architecture to create an ADR for the migration strategy,
|
||||
apply @microservices-patterns for service boundaries,
|
||||
@docker-expert for containerization, and @kubernetes-expert for orchestration.
|
||||
|
||||
Document the migration plan with @documentation.
|
||||
```
|
||||
|
||||
### Example 3: Security Audit
|
||||
|
||||
```
|
||||
Perform a comprehensive security audit of this application.
|
||||
|
||||
Use @security-audit to scan for vulnerabilities, @owasp-top-10 to check
|
||||
for common issues, @api-security-best-practices for API hardening,
|
||||
and @aws-security-best-practices for cloud configuration.
|
||||
|
||||
Generate a report with findings and remediation steps.
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Kiro Official Documentation](https://kiro.dev)
|
||||
- [AWS Blog: Transform DevOps with Kiro](https://aws.amazon.com/blogs/publicsector/transform-devops-practice-with-kiro-ai-powered-agents/)
|
||||
- [Complete Skills Catalog](../../CATALOG.md)
|
||||
- [Usage Guide](usage.md)
|
||||
- [Workflow Examples](workflows.md)
|
||||
|
||||
## Contributing
|
||||
|
||||
Found a Kiro-specific use case or workflow? Contribute to this guide:
|
||||
|
||||
1. Fork the repository
|
||||
2. Add your examples to this file
|
||||
3. Submit a pull request
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/sickn33/antigravity-awesome-skills/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/sickn33/antigravity-awesome-skills/discussions)
|
||||
- **Community**: [Community Guidelines](../contributors/community-guidelines.md)
|
||||
1722
docs/users/security-skills.md
Normal file
1722
docs/users/security-skills.md
Normal file
File diff suppressed because it is too large
Load Diff
394
docs/users/usage.md
Normal file
394
docs/users/usage.md
Normal file
@@ -0,0 +1,394 @@
|
||||
# 📖 Usage Guide: How to Actually Use These Skills
|
||||
|
||||
> **Confused after installation?** This guide walks you through exactly what to do next, step by step.
|
||||
|
||||
---
|
||||
|
||||
## 🤔 "I just installed the repository. Now what?"
|
||||
|
||||
Great question! Here's what just happened and what to do next:
|
||||
|
||||
### What You Just Did
|
||||
|
||||
When you ran `npx antigravity-awesome-skills` or cloned the repository, you:
|
||||
|
||||
✅ **Downloaded 1,204+ skill files** to your computer (default: `~/.gemini/antigravity/skills/`; or `~/.agent/skills/` if you used `--path`)
|
||||
✅ **Made them available** to your AI assistant
|
||||
❌ **Did NOT enable them all automatically** (they're just sitting there, waiting)
|
||||
|
||||
Think of it like installing a toolbox. You have all the tools now, but you need to **pick which ones to use** for each job.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Step 1: Understanding "Bundles" (This is NOT Another Install!)
|
||||
|
||||
**Common confusion:** "Do I need to download each skill separately?"
|
||||
|
||||
**Answer: NO!** Here's what bundles actually are:
|
||||
|
||||
### What Bundles Are
|
||||
|
||||
Bundles are **recommended lists** of skills grouped by role. They help you decide which skills to start using.
|
||||
|
||||
**Analogy:**
|
||||
|
||||
- You installed a toolbox with 1,204+ tools (✅ done)
|
||||
- Bundles are like **labeled organizer trays** saying: "If you're a carpenter, start with these 10 tools"
|
||||
- You don't install bundles—you **pick skills from them**
|
||||
|
||||
### What Bundles Are NOT
|
||||
|
||||
❌ Separate installations
|
||||
❌ Different download commands
|
||||
❌ Something you need to "activate"
|
||||
|
||||
### Example: The "Web Wizard" Bundle
|
||||
|
||||
When you see the [Web Wizard bundle](bundles.md#-the-web-wizard-pack), it lists:
|
||||
|
||||
- `frontend-design`
|
||||
- `react-best-practices`
|
||||
- `tailwind-patterns`
|
||||
- etc.
|
||||
|
||||
These are **recommendations** for which skills a web developer should try first. They're already installed—you just need to **use them in your prompts**.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Step 2: How to Actually Execute/Use a Skill
|
||||
|
||||
This is the part that should have been explained better! Here's how to use skills:
|
||||
|
||||
### The Simple Answer
|
||||
|
||||
**Just mention the skill name in your conversation with your AI assistant.**
|
||||
|
||||
### Different Tools, Different Syntax
|
||||
|
||||
The exact syntax varies by tool, but it's always simple:
|
||||
|
||||
#### Claude Code (CLI)
|
||||
|
||||
```bash
|
||||
# In your terminal/chat with Claude Code:
|
||||
>> Use @brainstorming to help me design a todo app
|
||||
```
|
||||
|
||||
#### Cursor (IDE)
|
||||
|
||||
```bash
|
||||
# In the Cursor chat panel:
|
||||
@brainstorming help me design a todo app
|
||||
```
|
||||
|
||||
#### Gemini CLI
|
||||
|
||||
```bash
|
||||
# In your conversation with Gemini:
|
||||
Use the brainstorming skill to help me plan my app
|
||||
```
|
||||
|
||||
#### Codex CLI
|
||||
|
||||
```bash
|
||||
# In your conversation with Codex:
|
||||
Apply @brainstorming to design a new feature
|
||||
```
|
||||
|
||||
#### Antigravity IDE
|
||||
|
||||
```bash
|
||||
# In agent mode:
|
||||
Use @brainstorming to plan this feature
|
||||
```
|
||||
|
||||
> **Pro Tip:** Most modern tools use the `@skill-name` syntax. When in doubt, try that first!
|
||||
|
||||
---
|
||||
|
||||
## 💬 Step 3: What Should My Prompts Look Like?
|
||||
|
||||
Here are **real-world examples** of good prompts:
|
||||
|
||||
### Example 1: Starting a New Project
|
||||
|
||||
**Bad Prompt:**
|
||||
|
||||
> "Help me build a todo app"
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @brainstorming to help me design a todo app with user authentication and cloud sync"
|
||||
|
||||
**Why it's better:** You're explicitly invoking the skill and providing context.
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Reviewing Code
|
||||
|
||||
**Bad Prompt:**
|
||||
|
||||
> "Check my code"
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @lint-and-validate to check `src/components/Button.tsx` for issues"
|
||||
|
||||
**Why it's better:** Specific skill + specific file = precise results.
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Security Audit
|
||||
|
||||
**Bad Prompt:**
|
||||
|
||||
> "Make my API secure"
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @api-security-best-practices to review my REST endpoints in `routes/api/users.js`"
|
||||
|
||||
**Why it's better:** The AI knows exactly which skill's standards to apply.
|
||||
|
||||
---
|
||||
|
||||
### Example 4: Combining Multiple Skills
|
||||
|
||||
**Good Prompt:**
|
||||
|
||||
> "Use @brainstorming to design a payment flow, then apply @stripe-integration to implement it"
|
||||
|
||||
**Why it's good:** You can chain skills together in a single prompt!
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Step 4: Your First Skill (Hands-On Tutorial)
|
||||
|
||||
Let's actually use a skill right now. Follow these steps:
|
||||
|
||||
### Scenario: You want to plan a new feature
|
||||
|
||||
1. **Pick a skill:** Let's use `brainstorming` (from the "Essentials" bundle)
|
||||
|
||||
2. **Open your AI assistant** (Claude Code, Cursor, etc.)
|
||||
|
||||
3. **Type this exact prompt:**
|
||||
|
||||
```
|
||||
Use @brainstorming to help me design a user profile page for my app
|
||||
```
|
||||
|
||||
4. **Press Enter**
|
||||
|
||||
5. **What happens next:**
|
||||
- The AI loads the brainstorming skill
|
||||
- It will start asking you structured questions (one at a time)
|
||||
- It will guide you through understanding, requirements, and design
|
||||
- You answer each question, and it builds a complete spec
|
||||
|
||||
6. **Result:** You'll end up with a detailed design document—without writing a single line of code yet!
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Step 5: Picking Your First Skills (Practical Advice)
|
||||
|
||||
Don't try to use all 1,204+ skills at once. Here's a sensible approach:
|
||||
|
||||
### Start with "The Essentials" (5 skills, everyone needs these)
|
||||
|
||||
1. **`@brainstorming`** - Plan before you build
|
||||
2. **`@lint-and-validate`** - Keep code clean
|
||||
3. **`@git-pushing`** - Save work safely
|
||||
4. **`@systematic-debugging`** - Fix bugs faster
|
||||
5. **`@concise-planning`** - Organize tasks
|
||||
|
||||
**How to use them:**
|
||||
|
||||
- Before writing new code → `@brainstorming`
|
||||
- After writing code → `@lint-and-validate`
|
||||
- Before committing → `@git-pushing`
|
||||
- When stuck → `@systematic-debugging`
|
||||
|
||||
### Then Add Role-Specific Skills (5-10 more)
|
||||
|
||||
Find your role in [bundles.md](bundles.md) and pick 5-10 skills from that bundle.
|
||||
|
||||
**Example for Web Developer:**
|
||||
|
||||
- `@frontend-design`
|
||||
- `@react-best-practices`
|
||||
- `@tailwind-patterns`
|
||||
- `@seo-audit`
|
||||
|
||||
**Example for Security Engineer:**
|
||||
|
||||
- `@api-security-best-practices`
|
||||
- `@vulnerability-scanner`
|
||||
- `@ethical-hacking-methodology`
|
||||
|
||||
### Finally, Add On-Demand Skills (as needed)
|
||||
|
||||
Keep the [CATALOG.md](../../CATALOG.md) open as reference. When you need something specific:
|
||||
|
||||
> "I need to integrate Stripe payments"
|
||||
> → Search catalog → Find `@stripe-integration` → Use it!
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Complete Example: Building a Feature End-to-End
|
||||
|
||||
Let's walk through a realistic scenario:
|
||||
|
||||
### Task: "Add a blog to my Next.js website"
|
||||
|
||||
#### Step 1: Plan (use @brainstorming)
|
||||
|
||||
```
|
||||
You: Use @brainstorming to design a blog system for my Next.js site
|
||||
|
||||
AI: [Asks structured questions about requirements]
|
||||
You: [Answer questions]
|
||||
AI: [Produces detailed design spec]
|
||||
```
|
||||
|
||||
#### Step 2: Implement (use @nextjs-best-practices)
|
||||
|
||||
```
|
||||
You: Use @nextjs-best-practices to scaffold the blog with App Router
|
||||
|
||||
AI: [Creates file structure, sets up routes, adds components]
|
||||
```
|
||||
|
||||
#### Step 3: Style (use @tailwind-patterns)
|
||||
|
||||
```
|
||||
You: Use @tailwind-patterns to make the blog posts look modern
|
||||
|
||||
AI: [Applies Tailwind styling with responsive design]
|
||||
```
|
||||
|
||||
#### Step 4: SEO (use @seo-audit)
|
||||
|
||||
```
|
||||
You: Use @seo-audit to optimize the blog for search engines
|
||||
|
||||
AI: [Adds meta tags, sitemaps, structured data]
|
||||
```
|
||||
|
||||
#### Step 5: Test & Deploy
|
||||
|
||||
```
|
||||
You: Use @test-driven-development to add tests, then @vercel-deployment to deploy
|
||||
|
||||
AI: [Creates tests, sets up CI/CD, deploys to Vercel]
|
||||
```
|
||||
|
||||
**Result:** Professional blog built with best practices, without manually researching each step!
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Common Questions
|
||||
|
||||
### "Which tool should I use? Claude Code, Cursor, Gemini?"
|
||||
|
||||
**Any of them!** Skills work universally. Pick the tool you already use or prefer:
|
||||
|
||||
- **Claude Code** - Best for terminal/CLI workflows
|
||||
- **Cursor** - Best for IDE integration
|
||||
- **Gemini CLI** - Best for Google ecosystem
|
||||
- **Codex CLI** - Best for OpenAI ecosystem
|
||||
|
||||
### "Can I see all available skills?"
|
||||
|
||||
Yes! Three ways:
|
||||
|
||||
1. Browse [CATALOG.md](../../CATALOG.md) (searchable list)
|
||||
2. Run `ls ~/.agent/skills/` (if installed there)
|
||||
3. Ask your AI: "What skills do you have for [topic]?"
|
||||
|
||||
### "Do I need to restart my IDE after installing?"
|
||||
|
||||
Usually no, but if your AI doesn't recognize a skill:
|
||||
|
||||
1. Try restarting your IDE/CLI
|
||||
2. Check the installation path matches your tool
|
||||
3. Try the explicit path: `npx antigravity-awesome-skills --claude` (or `--cursor`, `--gemini`, etc.)
|
||||
|
||||
### "Can I create my own skills?"
|
||||
|
||||
Yes! Use the `@skill-creator` skill:
|
||||
|
||||
```
|
||||
Use @skill-creator to help me build a custom skill for [your task]
|
||||
```
|
||||
|
||||
### "What if a skill doesn't work as expected?"
|
||||
|
||||
1. Check the skill's SKILL.md file directly: `~/.agent/skills/[skill-name]/SKILL.md`
|
||||
2. Read the description to ensure you're using it correctly
|
||||
3. [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) with details
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Reference Card
|
||||
|
||||
**Save this for quick lookup:**
|
||||
|
||||
| Task | Skill to Use | Example Prompt |
|
||||
| ---------------- | ------------------------------ | --------------------------------------------------- |
|
||||
| Plan new feature | `@brainstorming` | `Use @brainstorming to design a login system` |
|
||||
| Review code | `@lint-and-validate` | `Use @lint-and-validate on src/app.js` |
|
||||
| Debug issue | `@systematic-debugging` | `Use @systematic-debugging to fix login error` |
|
||||
| Security audit | `@api-security-best-practices` | `Use @api-security-best-practices on my API routes` |
|
||||
| SEO check | `@seo-audit` | `Use @seo-audit on my landing page` |
|
||||
| React component | `@react-patterns` | `Use @react-patterns to build a form component` |
|
||||
| Deploy app | `@vercel-deployment` | `Use @vercel-deployment to ship this to production` |
|
||||
|
||||
---
|
||||
|
||||
## 🚦 Next Steps
|
||||
|
||||
Now that you understand how to use skills:
|
||||
|
||||
1. ✅ **Try one skill right now** - Start with `@brainstorming` on any idea you have
|
||||
2. 📚 **Pick 3-5 skills** from your role's bundle in [bundles.md](bundles.md)
|
||||
3. 🔖 **Bookmark** [CATALOG.md](../../CATALOG.md) for when you need something specific
|
||||
4. 🎯 **Try a workflow** from [workflows.md](workflows.md) for a complete end-to-end process
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips for Maximum Effectiveness
|
||||
|
||||
### Tip 1: Start Every Feature with @brainstorming
|
||||
|
||||
> Before writing code, use `@brainstorming` to plan. You'll save hours of refactoring.
|
||||
|
||||
### Tip 2: Chain Skills in Order
|
||||
|
||||
> Don't try to do everything at once. Use skills sequentially: Plan → Build → Test → Deploy
|
||||
|
||||
### Tip 3: Be Specific in Prompts
|
||||
|
||||
> Bad: "Use @react-patterns"
|
||||
> Good: "Use @react-patterns to build a modal component with animations"
|
||||
|
||||
### Tip 4: Reference File Paths
|
||||
|
||||
> Help the AI focus: "Use @security-auditor on routes/api/auth.js"
|
||||
|
||||
### Tip 5: Combine Skills for Complex Tasks
|
||||
|
||||
> "Use @brainstorming to design, then @test-driven-development to implement with tests"
|
||||
|
||||
---
|
||||
|
||||
## 📞 Still Confused?
|
||||
|
||||
If something still doesn't make sense:
|
||||
|
||||
1. Check the [FAQ](faq.md)
|
||||
2. See [Real-World Examples](../contributors/examples.md)
|
||||
3. [Open a Discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions)
|
||||
4. [File an Issue](https://github.com/sickn33/antigravity-awesome-skills/issues) to help us improve this guide!
|
||||
|
||||
Remember: You're not alone! The whole point of this project is to make AI assistants easier to use. If this guide didn't help, let us know so we can fix it. 🙌
|
||||
509
docs/users/visual-guide.md
Normal file
509
docs/users/visual-guide.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# 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 and quick start
|
||||
├── 📄 CONTRIBUTING.md ← Contributor workflow
|
||||
├── 📄 CATALOG.md ← Full generated catalog
|
||||
│
|
||||
├── 📁 skills/ ← 1,204+ skills live here
|
||||
│ │
|
||||
│ ├── 📁 brainstorming/
|
||||
│ │ └── 📄 SKILL.md ← Skill definition
|
||||
│ │
|
||||
│ ├── 📁 stripe-integration/
|
||||
│ │ ├── 📄 SKILL.md
|
||||
│ │ └── 📁 examples/ ← Optional extras
|
||||
│ │
|
||||
│ ├── 📁 game-development/
|
||||
│ │ └── 📁 2d-games/
|
||||
│ │ └── 📄 SKILL.md ← Nested skills also supported
|
||||
│ │
|
||||
│ └── ... (1,200+ total)
|
||||
│
|
||||
├── 📁 apps/
|
||||
│ └── 📁 web-app/ ← Interactive browser
|
||||
│
|
||||
├── 📁 tools/
|
||||
│ ├── 📁 scripts/ ← Validators and generators
|
||||
│ ├── 📁 lib/ ← Shared helpers
|
||||
│ └── 📁 bin/ ← Installer entrypoint
|
||||
│
|
||||
└── 📁 docs/
|
||||
├── 📁 users/ ← Getting started, bundles, workflows
|
||||
├── 📁 contributors/ ← Template, anatomy, quality bar
|
||||
├── 📁 maintainers/ ← Release and maintenance docs
|
||||
└── 📁 sources/ ← Attribution and licenses
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
```
|
||||
┌─────────────────────────┐
|
||||
│ 1,204+ SKILLS │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────────────────┼────────────────────────┐
|
||||
│ │ │
|
||||
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||
│ PRODUCT │ │ DEVELOPMENT │ │ SECURITY │
|
||||
│ & UX │ │ & TESTING │ │ & RELIAB. │
|
||||
└────┬────┘ └──────┬──────┘ └──────┬──────┘
|
||||
│ │ │
|
||||
• Brainstorming • React / Next.js • AppSec reviews
|
||||
• Design systems • TDD / debugging • Pentest guides
|
||||
• Copywriting • API / backend • Cloud hardening
|
||||
• Incident response
|
||||
│ │ │
|
||||
└────────────────────────┼────────────────────────┘
|
||||
│
|
||||
┌────────────────────────┼────────────────────────┐
|
||||
│ │ │
|
||||
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||
│ AI │ │ DATA / OPS │ │ DOCS / OSS │
|
||||
│ AGENTS │ │ & CLOUD │ │ MAINTENANCE │
|
||||
└────┬────┘ └──────┬──────┘ └──────┬──────┘
|
||||
│ │ │
|
||||
• RAG systems • SQL / analytics • Release flow
|
||||
• LangGraph • Docker / K8s • Changelog
|
||||
• Prompt engineering • Terraform / AWS • PR / review
|
||||
• Tooling / MCP • Observability • Skill authoring
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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/ │
|
||||
│ └── ... (1,200+ total) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 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 docs/contributors/skill-template.md)
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 4. TEST │ Copy to .agent/skills/
|
||||
└──────┬───────┘ Try: @docker-mastery
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 5. VALIDATE │ npm run validate
|
||||
└──────┬───────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 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 │
|
||||
│ npm run validate │
|
||||
│ │
|
||||
│ 📝 CREATE │
|
||||
│ 1. mkdir skills/my-skill │
|
||||
│ 2. Create SKILL.md with frontmatter │
|
||||
│ 3. Add content │
|
||||
│ 4. Test & validate │
|
||||
│ 5. Submit PR │
|
||||
│ │
|
||||
│ 🆘 HELP │
|
||||
│ • docs/users/getting-started.md │
|
||||
│ • CONTRIBUTING.md │
|
||||
│ • docs/contributors/skill-anatomy.md │
|
||||
│ • 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.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](../contributors/skill-anatomy.md) - Detailed breakdown
|
||||
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - How to contribute
|
||||
|
||||
**Ready to contribute?** You've got this! 💪
|
||||
215
docs/users/workflows.md
Normal file
215
docs/users/workflows.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Antigravity Workflows
|
||||
|
||||
> Workflow playbooks to orchestrate multiple skills with less friction.
|
||||
|
||||
## What Is a Workflow?
|
||||
|
||||
A workflow is a guided, step-by-step execution path that combines multiple skills for one concrete outcome.
|
||||
|
||||
- **Bundles** tell you which skills are relevant for a role.
|
||||
- **Workflows** tell you how to use those skills in sequence to complete a real objective.
|
||||
|
||||
If bundles are your toolbox, workflows are your execution playbook.
|
||||
|
||||
---
|
||||
|
||||
## How to Use Workflows
|
||||
|
||||
1. Install the repository once (`npx antigravity-awesome-skills`).
|
||||
2. Pick a workflow matching your immediate goal.
|
||||
3. Execute steps in order and invoke the listed skills in each step.
|
||||
4. Keep output artifacts at each step (plan, decisions, tests, validation evidence).
|
||||
|
||||
You can combine workflows with bundles from [bundles.md](bundles.md) when you need broader coverage.
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Ship a SaaS MVP
|
||||
|
||||
Build and ship a minimal but production-minded SaaS product.
|
||||
|
||||
**Related bundles:** `Essentials`, `Full-Stack Developer`, `QA & Testing`, `DevOps & Cloud`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Local repository and runtime configured.
|
||||
- Clear user problem and MVP scope.
|
||||
- Basic deployment target selected.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Plan the scope**
|
||||
- **Goal:** Define MVP boundaries and acceptance criteria.
|
||||
- **Skills:** [`@brainstorming`](../../skills/brainstorming/), [`@concise-planning`](../../skills/concise-planning/), [`@writing-plans`](../../skills/writing-plans/)
|
||||
- **Prompt example:** `Usa @concise-planning per definire milestones e criteri di accettazione del mio MVP SaaS.`
|
||||
|
||||
2. **Build backend and API**
|
||||
- **Goal:** Implement core entities, APIs, and auth baseline.
|
||||
- **Skills:** [`@backend-dev-guidelines`](../../skills/backend-dev-guidelines/), [`@api-patterns`](../../skills/api-patterns/), [`@database-design`](../../skills/database-design/)
|
||||
- **Prompt example:** `Usa @backend-dev-guidelines per creare API e servizi del dominio billing.`
|
||||
|
||||
3. **Build frontend**
|
||||
- **Goal:** Ship core user flow with clear UX states.
|
||||
- **Skills:** [`@frontend-developer`](../../skills/frontend-developer/), [`@react-patterns`](../../skills/react-patterns/), [`@frontend-design`](../../skills/frontend-design/)
|
||||
- **Prompt example:** `Usa @frontend-developer per implementare onboarding, empty state e dashboard iniziale.`
|
||||
|
||||
4. **Test and validate**
|
||||
- **Goal:** Cover critical user journeys before release.
|
||||
- **Skills:** [`@test-driven-development`](../../skills/test-driven-development/), [`@browser-automation`](../../skills/browser-automation/), `@go-playwright` (optional, Go stack)
|
||||
- **Prompt example:** `Usa @browser-automation per creare test E2E sui flussi signup e checkout.`
|
||||
- **Go note:** Se il progetto QA e tooling sono in Go, preferisci `@go-playwright`.
|
||||
|
||||
5. **Ship safely**
|
||||
- **Goal:** Release with observability and rollback plan.
|
||||
- **Skills:** [`@deployment-procedures`](../../skills/deployment-procedures/), [`@observability-engineer`](../../skills/observability-engineer/)
|
||||
- **Prompt example:** `Usa @deployment-procedures per una checklist di rilascio con rollback.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Security Audit for a Web App
|
||||
|
||||
Run a focused security review from scope definition to remediation validation.
|
||||
|
||||
**Related bundles:** `Security Engineer`, `Security Developer`, `Observability & Monitoring`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Explicit authorization for testing.
|
||||
- In-scope targets documented.
|
||||
- Logging and environment details available.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Define scope and threat model**
|
||||
- **Goal:** Identify assets, trust boundaries, and attack paths.
|
||||
- **Skills:** [`@ethical-hacking-methodology`](../../skills/ethical-hacking-methodology/), [`@threat-modeling-expert`](../../skills/threat-modeling-expert/), [`@attack-tree-construction`](../../skills/attack-tree-construction/)
|
||||
- **Prompt example:** `Usa @threat-modeling-expert per mappare asset critici e trust boundaries della mia web app.`
|
||||
|
||||
2. **Review auth and access control**
|
||||
- **Goal:** Detect account takeover and authorization flaws.
|
||||
- **Skills:** [`@broken-authentication`](../../skills/broken-authentication/), [`@auth-implementation-patterns`](../../skills/auth-implementation-patterns/), [`@idor-testing`](../../skills/idor-testing/)
|
||||
- **Prompt example:** `Usa @idor-testing per verificare accessi non autorizzati su endpoint multitenant.`
|
||||
|
||||
3. **Assess API and input security**
|
||||
- **Goal:** Uncover high-impact API and injection vulnerabilities.
|
||||
- **Skills:** [`@api-security-best-practices`](../../skills/api-security-best-practices/), [`@api-fuzzing-bug-bounty`](../../skills/api-fuzzing-bug-bounty/), [`@top-web-vulnerabilities`](../../skills/top-web-vulnerabilities/)
|
||||
- **Prompt example:** `Usa @api-security-best-practices per audit endpoint auth, billing e admin.`
|
||||
|
||||
4. **Harden and verify**
|
||||
- **Goal:** Convert findings into fixes and verify evidence of mitigation.
|
||||
- **Skills:** [`@security-auditor`](../../skills/security-auditor/), [`@sast-configuration`](../../skills/sast-configuration/), [`@verification-before-completion`](../../skills/verification-before-completion/)
|
||||
- **Prompt example:** `Usa @verification-before-completion per provare che le mitigazioni sono effettive.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Build an AI Agent System
|
||||
|
||||
Design and deliver a production-grade agent with measurable reliability.
|
||||
|
||||
**Related bundles:** `Agent Architect`, `LLM Application Developer`, `Data Engineering`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Narrow use case with measurable outcomes.
|
||||
- Access to model provider(s) and observability tooling.
|
||||
- Initial dataset or knowledge corpus.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Define target behavior and KPIs**
|
||||
- **Goal:** Set quality, latency, and failure thresholds.
|
||||
- **Skills:** [`@ai-agents-architect`](../../skills/ai-agents-architect/), [`@agent-evaluation`](../../skills/agent-evaluation/), [`@product-manager-toolkit`](../../skills/product-manager-toolkit/)
|
||||
- **Prompt example:** `Usa @agent-evaluation per definire benchmark e criteri di successo del mio agente.`
|
||||
|
||||
2. **Design retrieval and memory**
|
||||
- **Goal:** Build reliable retrieval and context architecture.
|
||||
- **Skills:** [`@llm-app-patterns`](../../skills/llm-app-patterns/), [`@rag-implementation`](../../skills/rag-implementation/), [`@vector-database-engineer`](../../skills/vector-database-engineer/)
|
||||
- **Prompt example:** `Usa @rag-implementation per progettare pipeline di chunking, embedding e retrieval.`
|
||||
|
||||
3. **Implement orchestration**
|
||||
- **Goal:** Implement deterministic orchestration and tool boundaries.
|
||||
- **Skills:** [`@langgraph`](../../skills/langgraph/), [`@mcp-builder`](../../skills/mcp-builder/), [`@workflow-automation`](../../skills/workflow-automation/)
|
||||
- **Prompt example:** `Usa @langgraph per implementare il grafo agente con fallback e human-in-the-loop.`
|
||||
|
||||
4. **Evaluate and iterate**
|
||||
- **Goal:** Improve weak points with a structured loop.
|
||||
- **Skills:** [`@agent-evaluation`](../../skills/agent-evaluation/), [`@langfuse`](../../skills/langfuse/), [`@kaizen`](../../skills/kaizen/)
|
||||
- **Prompt example:** `Usa @kaizen per prioritizzare le correzioni sulle failure modes rilevate dai test.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: QA and Browser Automation
|
||||
|
||||
Create resilient browser automation with deterministic execution in CI.
|
||||
|
||||
**Related bundles:** `QA & Testing`, `Full-Stack Developer`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Test environments and stable credentials.
|
||||
- Critical user journeys identified.
|
||||
- CI pipeline available.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Prepare test strategy**
|
||||
- **Goal:** Scope journeys, fixtures, and execution environments.
|
||||
- **Skills:** [`@e2e-testing-patterns`](../../skills/e2e-testing-patterns/), [`@test-driven-development`](../../skills/test-driven-development/)
|
||||
- **Prompt example:** `Usa @e2e-testing-patterns per definire suite E2E minima ma ad alto impatto.`
|
||||
|
||||
2. **Implement browser tests**
|
||||
- **Goal:** Build robust test coverage with stable selectors.
|
||||
- **Skills:** [`@browser-automation`](../../skills/browser-automation/), `@go-playwright` (optional, Go stack)
|
||||
- **Prompt example:** `Usa @go-playwright per implementare browser automation in un progetto Go.`
|
||||
|
||||
3. **Triage and harden**
|
||||
- **Goal:** Remove flaky behavior and enforce repeatability.
|
||||
- **Skills:** [`@systematic-debugging`](../../skills/systematic-debugging/), [`@test-fixing`](../../skills/test-fixing/), [`@verification-before-completion`](../../skills/verification-before-completion/)
|
||||
- **Prompt example:** `Usa @systematic-debugging per classificare e risolvere le flakiness in CI.`
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Design a DDD Core Domain
|
||||
|
||||
Model a complex domain coherently, then implement tactical and evented patterns only where justified.
|
||||
|
||||
**Related bundles:** `Architecture & Design`, `DDD & Evented Architecture`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Access to at least one domain expert or product owner proxy.
|
||||
- Current system context and integration landscape available.
|
||||
- Agreement on business goals and key domain outcomes.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Assess DDD fit and scope**
|
||||
- **Goal:** Decide whether full DDD, partial DDD, or simple modular architecture is appropriate.
|
||||
- **Skills:** [`@domain-driven-design`](../../skills/domain-driven-design/), [`@architecture-decision-records`](../../skills/architecture-decision-records/)
|
||||
- **Prompt example:** `Use @domain-driven-design to evaluate if full DDD is justified for our billing and fulfillment platform.`
|
||||
|
||||
2. **Create strategic model**
|
||||
- **Goal:** Define subdomains, bounded contexts, and ubiquitous language.
|
||||
- **Skills:** [`@ddd-strategic-design`](../../skills/ddd-strategic-design/)
|
||||
- **Prompt example:** `Use @ddd-strategic-design to classify subdomains and propose bounded contexts with ownership.`
|
||||
|
||||
3. **Map context relationships**
|
||||
- **Goal:** Define upstream/downstream contracts and anti-corruption boundaries.
|
||||
- **Skills:** [`@ddd-context-mapping`](../../skills/ddd-context-mapping/)
|
||||
- **Prompt example:** `Use @ddd-context-mapping to model Checkout, Billing, and Inventory interactions with clear contract ownership.`
|
||||
|
||||
4. **Implement tactical model**
|
||||
- **Goal:** Encode invariants with aggregates, value objects, and domain events.
|
||||
- **Skills:** [`@ddd-tactical-patterns`](../../skills/ddd-tactical-patterns/), [`@test-driven-development`](../../skills/test-driven-development/)
|
||||
- **Prompt example:** `Use @ddd-tactical-patterns to design aggregates and invariants for order lifecycle transitions.`
|
||||
|
||||
5. **Adopt evented patterns selectively**
|
||||
- **Goal:** Apply CQRS, event store, projections, and sagas only where complexity and scale require them.
|
||||
- **Skills:** [`@cqrs-implementation`](../../skills/cqrs-implementation/), [`@event-store-design`](../../skills/event-store-design/), [`@projection-patterns`](../../skills/projection-patterns/), [`@saga-orchestration`](../../skills/saga-orchestration/)
|
||||
- **Prompt example:** `Use @cqrs-implementation and @projection-patterns to scale read-side reporting without compromising domain invariants.`
|
||||
|
||||
---
|
||||
|
||||
## Machine-Readable Workflows
|
||||
|
||||
For tooling and automation, workflow metadata is available in [data/workflows.json](../../data/workflows.json).
|
||||
Reference in New Issue
Block a user