diff --git a/README.md b/README.md index 42f983cb..38649a3c 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,12 @@ Antigravity Awesome Skills is a GitHub repository and installer CLI for reusable - [🚀 New Here? Start Here!](#new-here-start-here) - [📖 Complete Usage Guide](docs/users/usage.md) - **Start here if confused after installation!** +- [🧠 Core Concepts](#core-concepts) - [🔌 Compatibility & Invocation](#compatibility--invocation) - [🛠️ Installation](#installation) +- [🧭 Integration Guides](#integration-guides) - [🧰 Best Skills By Tool](#best-skills-by-tool) +- [❓ Quick FAQ](#quick-faq) - [🛡️ Security Posture](#security-posture) - [🧯 Troubleshooting](#troubleshooting) - [🎁 Curated Collections (Bundles)](#curated-collections) @@ -102,6 +105,53 @@ Once installed, just ask your agent naturally: --- +## Core Concepts + +Before you compare bundles or start installing tool-specific paths, it helps to separate four ideas: + +- **Skills**: reusable `SKILL.md` playbooks that teach an AI assistant how to execute a workflow well. +- **MCP tools**: integrations and external capabilities the assistant can call. Tools provide actions; skills provide operating instructions. +- **Bundles**: curated recommendations for which skills to start with for a role or domain. +- **Workflows**: ordered execution playbooks that show how to combine multiple skills step by step. + +If you want the clearest explanation of **skills vs MCP/tools**, start here: + +- [Skills vs MCP Tools](docs/users/skills-vs-mcp-tools.md) +- [Bundles](docs/users/bundles.md) +- [Workflows](docs/users/workflows.md) + +## Integration Guides + +If your real question is "how do I use Antigravity Awesome Skills with my tool?", use the matching guide: + +- **[Claude Code](docs/users/claude-code-skills.md)**: install paths, starter prompts, plugin marketplace flow, and first-use guidance. +- **[Cursor](docs/users/cursor-skills.md)**: chat-first usage, frontend/full-stack starter skills, and practical prompts. +- **[Codex CLI](docs/users/codex-cli-skills.md)**: planning, implementation, debugging, testing, and review loops for local coding work. +- **[Gemini CLI](docs/users/gemini-cli-skills.md)**: broad engineering, agent systems, integrations, and AI workflow coverage. +- **[AI agent skills guide](docs/users/ai-agent-skills.md)**: how to evaluate this repo against broader or narrower alternatives. + +## Quick FAQ + +### What is Antigravity Awesome Skills? + +It is an installable GitHub library of reusable `SKILL.md` playbooks for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and related AI coding assistants. + +### How do I install it? + +Use `npx antigravity-awesome-skills`, or a tool-specific flag like `--codex`, `--cursor`, `--gemini`, or `--claude` when you want the installer to target a specific skills directory. + +### What is the difference between skills and MCP tools? + +Skills are reusable playbooks that tell an AI assistant how to execute a workflow. MCP tools expose external systems or actions the assistant can call. Skills guide behavior; MCP tools provide capabilities. + +### What is the difference between bundles and workflows? + +Bundles are curated sets of recommended skills. Workflows are ordered execution playbooks for concrete outcomes. + +For the expanded version, read [FAQ](docs/users/faq.md). + +--- + ## Compatibility & Invocation These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills. diff --git a/apps/web-app/index.html b/apps/web-app/index.html index bd1e36c1..9b9dbffc 100644 --- a/apps/web-app/index.html +++ b/apps/web-app/index.html @@ -6,22 +6,22 @@ - + - - + + - - + + - Antigravity Awesome Skills | 1,273+ installable AI skills catalog + Antigravity Awesome Skills | 1,326+ installable AI skills catalog
diff --git a/apps/web-app/src/pages/Home.tsx b/apps/web-app/src/pages/Home.tsx index 8f79ee6b..7ac86a93 100644 --- a/apps/web-app/src/pages/Home.tsx +++ b/apps/web-app/src/pages/Home.tsx @@ -5,7 +5,49 @@ import { useSkills } from '../context/SkillContext'; import { SkillCard } from '../components/SkillCard'; import type { SyncMessage, CategoryStats } from '../types'; import { usePageMeta } from '../hooks/usePageMeta'; -import { APP_HOME_CATALOG_COUNT, buildHomeMeta } from '../utils/seo'; +import { APP_HOME_CATALOG_COUNT, buildHomeMeta, getHomeFaqItems } from '../utils/seo'; + +const conceptCards = [ + { + title: 'Skills', + body: 'Reusable SKILL.md playbooks that teach an AI assistant how to execute a workflow with better structure and context.', + }, + { + title: 'MCP tools', + body: 'External capabilities and system integrations the assistant can call. Tools provide actions; skills tell the assistant how to use them well.', + }, + { + title: 'Bundles', + body: 'Curated starting sets of recommended skills for a role, domain, or team that wants a smaller shortlist first.', + }, + { + title: 'Workflows', + body: 'Ordered execution playbooks that show how to combine multiple skills step by step for a concrete outcome.', + }, +] as const; + +const integrationGuides = [ + { + name: 'Claude Code', + href: 'https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/users/claude-code-skills.md', + body: 'Install paths, starter prompts, plugin marketplace flow, and first skills to try.', + }, + { + name: 'Cursor', + href: 'https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/users/cursor-skills.md', + body: 'A practical guide for chat-first UI, frontend, and full-stack workflows in Cursor.', + }, + { + name: 'Codex CLI', + href: 'https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/users/codex-cli-skills.md', + body: 'How to use Antigravity Awesome Skills with Codex CLI for planning, implementation, testing, and review.', + }, + { + name: 'Gemini CLI', + href: 'https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/users/gemini-cli-skills.md', + body: 'A broad starting point for engineering, agent systems, integrations, and applied AI workflows.', + }, +] as const; export function Home(): React.ReactElement { const { skills, stars, loading, error, refreshSkills } = useSkills(); @@ -19,6 +61,7 @@ export function Home(): React.ReactElement { const installCommand = 'npx antigravity-awesome-skills'; const docsLink = 'https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/users/usage.md'; const installLink = 'https://www.npmjs.com/package/antigravity-awesome-skills'; + const faqItems = getHomeFaqItems(); usePageMeta(buildHomeMeta(skills.length)); @@ -262,6 +305,110 @@ export function Home(): React.ReactElement { /> )} + +
+
+

+ Concepts +

+

+ Understand the moving pieces before you install everything +

+

+ The catalog is easier to navigate once you separate reusable playbooks from external tool integrations. + Skills explain how to execute a workflow well, MCP tools expose external systems, bundles narrow the + starting set, and workflows show the order of operations. +

+
+ {conceptCards.map((card) => ( +
+

{card.title}

+

{card.body}

+
+ ))} +
+
+ + Read skills vs MCP/tools + + + Browse bundles + + + Explore workflows + +
+
+ +
+

+ Integration Guides +

+

+ Start from the guide that matches your AI assistant +

+
+ {integrationGuides.map((guide) => ( + +

{guide.name}

+

{guide.body}

+ + ))} +
+
+ +
+

+ Quick FAQ +

+

+ Answers to the first questions most users ask +

+
+ {faqItems.map((item) => ( +
+

{item.question}

+

{item.answer}

+
+ ))} +
+ + Read the full FAQ + +
+
); } diff --git a/apps/web-app/src/pages/__tests__/Home.test.tsx b/apps/web-app/src/pages/__tests__/Home.test.tsx index d844af67..05b198a4 100644 --- a/apps/web-app/src/pages/__tests__/Home.test.tsx +++ b/apps/web-app/src/pages/__tests__/Home.test.tsx @@ -89,7 +89,8 @@ describe('Home', () => { }); expect(screen.getByRole('button', { name: /Copy install command/i })).toBeInTheDocument(); - expect(screen.getByText(/npx antigravity-awesome-skills/i)).toBeInTheDocument(); + expect(screen.getAllByText(/npx antigravity-awesome-skills/i).length).toBeGreaterThan(0); + expect(screen.getByText(/What is the difference between skills and MCP tools/i)).toBeInTheDocument(); expect(document.querySelector('meta[property="og:title"]')).toHaveAttribute( 'content', expect.stringContaining('Antigravity Awesome Skills'), diff --git a/apps/web-app/src/utils/__tests__/seo.test.ts b/apps/web-app/src/utils/__tests__/seo.test.ts index 574ca92c..42f0f4d2 100644 --- a/apps/web-app/src/utils/__tests__/seo.test.ts +++ b/apps/web-app/src/utils/__tests__/seo.test.ts @@ -28,8 +28,8 @@ describe('SEO helpers', () => { it('builds homepage metadata with the canonical catalog message', () => { const meta = buildHomeMeta(10); - expect(meta.title).toContain('1,273+'); - expect(meta.description).toContain('1273+ installable agentic skills'); + expect(meta.title).toContain('1,326+'); + expect(meta.description).toContain('1,326+ installable agentic skills'); expect(meta.canonicalPath).toBe('/'); expect(meta.ogTitle).toBe(meta.title); expect(meta.ogImage).toBe(DEFAULT_SOCIAL_IMAGE); diff --git a/apps/web-app/src/utils/seo.ts b/apps/web-app/src/utils/seo.ts index 9d9c5f67..fd55d164 100644 --- a/apps/web-app/src/utils/seo.ts +++ b/apps/web-app/src/utils/seo.ts @@ -1,9 +1,31 @@ import type { SeoJsonLdValue, SeoMeta, TwitterCard, Skill } from '../types'; -export const APP_HOME_CATALOG_COUNT = 1273; +export const APP_HOME_CATALOG_COUNT = 1326; export const DEFAULT_TOP_SKILL_COUNT = 40; export const DEFAULT_SOCIAL_IMAGE = 'social-card.svg'; const SITE_NAME = 'Antigravity Awesome Skills'; +const FAQ_ITEMS = [ + { + question: 'What is Antigravity Awesome Skills?', + answer: + 'Antigravity Awesome Skills is an installable GitHub library of reusable SKILL.md playbooks for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and related AI coding assistants.', + }, + { + question: 'How do I install Antigravity Awesome Skills?', + answer: + 'Install the library with npx antigravity-awesome-skills, then use tool-specific flags such as --codex, --cursor, --gemini, or --claude when you want the installer to target a specific skills directory.', + }, + { + question: 'What is the difference between skills and MCP tools?', + answer: + 'Skills are reusable playbooks that tell an AI assistant how to execute a workflow, while MCP tools expose external systems or actions the assistant can call. Skills guide behavior; MCP tools provide capabilities.', + }, + { + question: 'What is the difference between bundles and workflows?', + answer: + 'Bundles are curated sets of recommended skills for a role or domain, while workflows are ordered execution playbooks that show how to combine skills step by step for a concrete outcome.', + }, +] as const; export function toCanonicalPath(pathname: string): string { if (!pathname || pathname === '/') { @@ -70,6 +92,44 @@ function buildWebSiteSchema(canonicalUrl: string): Record { }; } +function buildSoftwareSourceCodeSchema(canonicalUrl: string, visibleCount: number): Record { + const visibleCountLabel = `${visibleCount.toLocaleString('en-US')}+`; + return { + '@context': 'https://schema.org', + '@type': 'SoftwareSourceCode', + name: SITE_NAME, + description: `Installable GitHub library of ${visibleCountLabel} agentic skills for AI coding assistants.`, + url: canonicalUrl, + codeRepository: 'https://github.com/sickn33/antigravity-awesome-skills', + programmingLanguage: { + '@type': 'ComputerLanguage', + name: 'Markdown', + url: 'https://en.wikipedia.org/wiki/Markdown', + }, + license: 'https://github.com/sickn33/antigravity-awesome-skills/blob/main/LICENSE', + }; +} + +function buildHomeFaqSchema(canonicalUrl: string): Record { + return { + '@context': 'https://schema.org', + '@type': 'FAQPage', + url: canonicalUrl, + mainEntity: FAQ_ITEMS.map((item) => ({ + '@type': 'Question', + name: item.question, + acceptedAnswer: { + '@type': 'Answer', + text: item.answer, + }, + })), + }; +} + +export function getHomeFaqItems(): Array<{ question: string; answer: string }> { + return [...FAQ_ITEMS]; +} + function ensureMetaTag(name: string, content: string, attributeName: 'name' | 'property'): void { const selector = `meta[${attributeName}="${name}"]`; let tag = document.querySelector(selector) as HTMLMetaElement | null; @@ -216,8 +276,9 @@ export function isTopSkill(skillId: string, skills: ReadonlyArray, limit export function buildHomeMeta(skillCount: number): SeoMeta { const visibleCount = Math.max(skillCount, APP_HOME_CATALOG_COUNT); - const title = 'Antigravity Awesome Skills | 1,273+ installable AI skills catalog'; - const description = `Explore ${visibleCount}+ installable agentic skills and prompt templates. Discover what fits your workflow, copy prompts fast, and launch AI-powered actions with confidence.`; + const visibleCountLabel = `${visibleCount.toLocaleString('en-US')}+`; + const title = `Antigravity Awesome Skills | ${visibleCountLabel} installable AI skills catalog`; + const description = `Explore ${visibleCountLabel} installable agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, and Antigravity. Browse bundles, workflows, FAQs, and integration guides in one place.`; return { title, description, @@ -241,6 +302,8 @@ export function buildHomeMeta(skillCount: number): SeoMeta { }, buildOrganizationSchema(), buildWebSiteSchema(canonicalUrl), + buildSoftwareSourceCodeSchema(canonicalUrl, visibleCount), + buildHomeFaqSchema(canonicalUrl), ], }; } diff --git a/docs/users/claude-code-skills.md b/docs/users/claude-code-skills.md index 42d2a5ca..a5650e90 100644 --- a/docs/users/claude-code-skills.md +++ b/docs/users/claude-code-skills.md @@ -4,6 +4,10 @@ If you are looking for **Claude Code skills** you can install from GitHub, this Antigravity Awesome Skills gives Claude Code users an installable library of `SKILL.md` playbooks, role-based bundles, and execution workflows. The goal is not just to collect prompts, but to make repeatable engineering tasks easier to invoke, review, and reuse. +## How to use Antigravity Awesome Skills with Claude Code + +Install the library into Claude Code, then invoke focused skills directly in the conversation or through the plugin marketplace path. Claude Code benefits most when you keep the prompt specific about the skill, the scope, and the intended output. + ## Why use this repo for Claude Code - It includes 1,326+ skills instead of a narrow single-domain starter pack. diff --git a/docs/users/codex-cli-skills.md b/docs/users/codex-cli-skills.md index 9b7d4e20..d99732b0 100644 --- a/docs/users/codex-cli-skills.md +++ b/docs/users/codex-cli-skills.md @@ -4,6 +4,14 @@ If you want **Codex CLI skills** that are easy to install and practical in a loc Antigravity Awesome Skills supports Codex CLI through the `.codex/skills/` path and gives you a wide set of reusable task playbooks for planning, implementation, debugging, testing, security review, and delivery. +## How to use Antigravity Awesome Skills with Codex CLI + +Install the library into your Codex path, then invoke focused skills directly in your prompt. The most common pattern is: + +1. install with `npx antigravity-awesome-skills --codex` +2. choose one workflow-oriented skill such as `@brainstorming`, `@concise-planning`, or `@test-driven-development` +3. ask Codex to apply that skill to a concrete file, feature, test, or bugfix + ## Why use this repo for Codex CLI - It supports Codex CLI with a dedicated install flag and a standard skills layout. diff --git a/docs/users/cursor-skills.md b/docs/users/cursor-skills.md index 020fa282..fa8ecc9f 100644 --- a/docs/users/cursor-skills.md +++ b/docs/users/cursor-skills.md @@ -4,6 +4,10 @@ If you searched for **Cursor skills** on GitHub, this repository is built to be Antigravity Awesome Skills supports Cursor through the `.cursor/skills/` path and keeps the entry point simple: install once, then invoke the skills you need in chat. +## How to use Antigravity Awesome Skills with Cursor + +Install the library into Cursor's skills directory, then call skills directly in chat with `@skill-name`. Cursor works especially well when you combine planning, implementation, and validation skills inside one conversation. + ## Why use this repo for Cursor - It supports Cursor directly with a dedicated install flag. diff --git a/docs/users/faq.md b/docs/users/faq.md index b6dda789..7b4d8e36 100644 --- a/docs/users/faq.md +++ b/docs/users/faq.md @@ -29,6 +29,15 @@ Start from: - [bundles.md](bundles.md) - [workflows.md](workflows.md) +### What is the difference between skills and MCP tools? + +- **Skills** are reusable `SKILL.md` playbooks that guide an AI assistant through a workflow. +- **MCP tools** are integrations or callable capabilities that let the assistant interact with external systems. + +Use skills when you want better process, structure, and execution quality. Use MCP tools when you need access to APIs, services, databases, or other systems. Use both when you want reliable workflows plus external capabilities. + +For the longer explanation, read [skills-vs-mcp-tools.md](skills-vs-mcp-tools.md). + ### Which AI tools work with these skills? - ✅ **Claude Code** (Anthropic CLI) diff --git a/docs/users/gemini-cli-skills.md b/docs/users/gemini-cli-skills.md index fc7ecbad..7c96be8c 100644 --- a/docs/users/gemini-cli-skills.md +++ b/docs/users/gemini-cli-skills.md @@ -4,6 +4,10 @@ If you are evaluating **Gemini CLI skills** on GitHub, this repository is a stro Antigravity Awesome Skills supports Gemini CLI through the `.gemini/skills/` path and combines general engineering playbooks with specialized skills for AI systems, integrations, infrastructure, testing, product, and growth. +## How to use Antigravity Awesome Skills with Gemini CLI + +Install into the Gemini skills path, then ask Gemini to apply one skill at a time to a specific task. This works best when you keep the active set small and choose a clear workflow-oriented skill for the job in front of you. + ## Why use this repo for Gemini CLI - It installs directly into the expected Gemini skills path. diff --git a/docs/users/skills-vs-mcp-tools.md b/docs/users/skills-vs-mcp-tools.md new file mode 100644 index 00000000..5fbe8f3b --- /dev/null +++ b/docs/users/skills-vs-mcp-tools.md @@ -0,0 +1,89 @@ +# Skills vs MCP Tools + +If you are trying to understand the difference between **Antigravity skills** and **MCP tools**, the short version is: + +- **Skills** are reusable `SKILL.md` playbooks that tell an AI assistant how to execute a workflow. +- **MCP tools** are integrations or callable capabilities that let the assistant interact with external systems. + +The two are complementary, not competing. + +## What a skill does + +A skill gives the model better instructions for a repeated task such as: + +- planning a feature +- reviewing code +- running a security audit +- writing a README +- debugging a failing test suite + +In practice, a skill improves the assistant's decision-making, structure, and process for a task. + +Example: + +- `@brainstorming` helps the model clarify requirements before implementation. +- `@lint-and-validate` helps the model run the right quality checks before claiming success. + +## What an MCP tool does + +An MCP tool gives the model a capability it would not otherwise have, such as: + +- reading from a database +- calling GitHub APIs +- fetching docs from a service +- creating calendar events +- querying an external system + +In practice, an MCP tool expands what the assistant can do in the world. + +## The easiest mental model + +Use this rule: + +- **Skills tell the assistant how to work.** +- **MCP tools tell the assistant what systems it can touch.** + +If you only install tools, the assistant may have access but still behave inconsistently. + +If you only install skills, the assistant may know the workflow but still lack the capability to reach the external system it needs. + +Together, they are much stronger. + +## Which one should you start with? + +Start with **skills** if: + +- you want better planning, coding, debugging, testing, or review behavior immediately +- you are working mostly in local files and terminal flows +- you want reusable playbooks before adding more integrations + +Start with **MCP tools** if: + +- your main blocker is access to external systems +- you need the model to call APIs, query services, or interact with hosted platforms +- you already like the model's workflow quality, but need more reach + +Use **both** when: + +- you want reliable workflows plus external capabilities +- you are building agent systems, internal tooling, or multi-step operational flows + +## How this repo fits in + +Antigravity Awesome Skills is primarily a **skill library**: + +- installable `SKILL.md` playbooks +- bundles for role-based starting points +- workflows for ordered execution patterns +- tool-specific guides for Claude Code, Cursor, Codex CLI, Gemini CLI, and others + +Many skills in this repo also explain how to work with MCP, APIs, and other integrations, but the repository itself is centered on reusable workflow guidance rather than acting as an MCP server. + +## Good next reads + +- [FAQ](faq.md) +- [Bundles](bundles.md) +- [Workflows](workflows.md) +- [AI Agent Skills](ai-agent-skills.md) +- [Codex CLI Skills](codex-cli-skills.md) +- [Gemini CLI Skills](gemini-cli-skills.md)