meta(aeo): Improve homepage schema and discovery docs

Add visible FAQ and concepts content, strengthen tool-specific integration
guides, and publish a dedicated skills-vs-MCP explainer.

Extend homepage SEO metadata and JSON-LD so the GitHub Pages catalog
better reflects the repository's real positioning and common user
questions.

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.

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.

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.

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)

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.

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)