opencode-skills-collection 4.0.4 → 4.0.5

package/bundled-skills/docs/users/bundles.md

@@ -825,7 +825,9 @@ _For shipping clean changes in public repositories._
 **Plugin status:** Codex plugin-safe · Claude plugin-safe
 
 - [`commit`](../../skills/commit/): High-quality conventional commits.
+- [`create-branch`](../../skills/create-branch/): Create a safe topic branch before committing.
 - [`create-pr`](../../skills/create-pr/): PR creation with review-ready context.
+- [`pr-writer`](../../skills/pr-writer/): Write and open structured pull requests.
 - [`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.
@@ -1060,4 +1062,4 @@ Found a skill that should be in a bundle? Or want to create a new bundle? [Open
 
 ---
 
-_Last updated: June 2026 | Total Skills: 1,965+ | Total Bundles: 58_
+_Last updated: June 2026 | Total Skills: 1,968+ | Total Bundles: 58_

package/bundled-skills/docs/users/claude-code-skills.md

@@ -1,24 +1,31 @@
-# Claude Code Skills
+# AAS Core with Claude Code
 
-If you are looking for **Claude Code skills** you can install from GitHub, this repository is designed to get you from first clone to first useful prompt quickly.
+For Claude Code, the recommended AAS path is **AAS Core**: a local, agent-first control plane for catalog search, deterministic stack recommendation, manifest inspection, and preview-first planning.
 
-Agentic 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.
+The local AAS MCP is read-only. It can help Claude search and inspect the catalog or propose a minimal `aas-stack.json`, while validation, planning, and any approved changes stay in the AAS CLI lifecycle.
 
-Release `9.0.0` also adds a first-class Claude Code plugin distribution plus bundle plugins. If you want the full explanation of root plugin vs bundle plugin vs full install, read [plugins.md](plugins.md).
+Start with the [AAS Core guide](aas-core.md). The Claude plugin marketplace and direct skill installation remain supported delivery paths after you know which skills you want.
+
+> **Preview status:** Search, recommendation, manifest validation, and planning are the documented preview path. Stop after plan review; apply and recovery are not certified preview safety claims.
 
 ## How to use Agentic 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.
+Configure AAS Core for Claude Code, describe the task and constraints, review the recommended stack, then preview the CLI plan. Core does not install or mutate through MCP. The current documented preview path stops after plan review.
 
 ## Why use this repo for Claude Code
 
-- It includes 1,965+ skills instead of a narrow single-domain starter pack.
+- It lets Claude search the verified local catalog without loading the full library into context.
+- It produces deterministic recommendations with inspectable factors and evidence.
+- It keeps MCP discovery read-only and CLI changes approval-gated.
+- It includes 1,968+ skills instead of a narrow single-domain starter pack.
 - It supports the standard `.claude/skills/` path and the Claude Code plugin marketplace flow.
 - It also ships generated bundle plugins so teams can install focused packs like `Essentials` or `Security Developer` from the marketplace metadata.
 - It includes onboarding docs, bundles, and workflows so new users do not need to guess where to begin.
 - It covers both everyday engineering tasks and specialized work like security reviews, infrastructure, product planning, and documentation.
 
-## Install Claude Code Skills
+## Direct install and plugins
+
+These are alternative delivery paths for users who already know which skill payload they want.
 
 ### Option A: installer CLI
 
@@ -53,6 +60,14 @@ test -d .claude/skills || test -d ~/.claude/skills
 
 ## Example Claude Code prompts
 
+With AAS Core configured:
+
+```text
+Use AAS to recommend a minimal skill stack for this security review. Propose the aas-stack.json and preview the plan without applying it.
+```
+
+After installing or activating a chosen skill, direct invocation still works:
+
 ```text
 Use @brainstorming to design a new billing workflow for my SaaS.
 ```
@@ -67,6 +82,7 @@ Use @create-pr to turn these changes into a clean PR summary and checklist.
 
 ## What to do next
 
+- Start with [`aas-core.md`](aas-core.md) for setup, trust boundaries, and the stack lifecycle.
 - Start with [`bundles.md`](bundles.md) if you want a role-based shortlist.
 - Use [`workflows.md`](workflows.md) if you want step-by-step execution playbooks.
 - Compare options in [`best-claude-code-skills-github.md`](best-claude-code-skills-github.md) if you are still evaluating repositories.

package/bundled-skills/docs/users/codex-cli-skills.md

@@ -1,39 +1,47 @@
-# Codex CLI Skills
+# AAS Core with Codex CLI
 
-If you want **Codex CLI skills** that are easy to install and practical in a local coding loop, this repository is designed for that exact use case.
+For Codex, the recommended AAS path is **AAS Core**: a local, agent-first control plane that lets Codex search the verified catalog, inspect skills, and recommend a minimal stack before anything is installed.
 
-Agentic 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.
+The AAS MCP server is local and read-only. Codex can call `search_skills`, `get_skill`, `recommend_stack`, `inspect_stack`, and `diff_stack`; changes remain in the CLI lifecycle, where `validate` and `plan` are preview operations and `apply` requires explicit approval.
 
-Release `9.0.0` also adds a first-class Codex plugin distribution plus bundle plugins. If you want the full explanation of root plugin vs bundle plugin vs full install, read [plugins.md](plugins.md).
+Start with the [AAS Core guide](aas-core.md). Direct skill installation and Codex plugins remain supported when you already know exactly which payload you want.
+
+> **Preview status:** Search, recommendation, manifest validation, and planning are the documented preview path. Stop after plan review; apply and recovery are not certified preview safety claims.
 
 ## How to use Agentic 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:
+Configure AAS Core for Codex, then describe the real task instead of manually searching a large directory. The normal flow is:
 
-1. install with `npx agentic-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
+1. Codex discovers the local AAS MCP tools.
+2. Codex searches the catalog and requests a deterministic recommendation for your task profile.
+3. Codex proposes a minimal `aas-stack.json` for you to review.
+4. The AAS CLI validates the manifest and previews the exact plan.
+5. Stop after reviewing the plan unless you are deliberately participating in controlled preview development.
 
 ## Why use this repo for Codex CLI
 
-- It supports Codex CLI with a dedicated install flag and a standard skills layout.
+- It gives Codex native, local discovery and recommendation through MCP.
+- It keeps catalog evidence, stack intent, validation, and planning deterministic and inspectable.
+- It separates read-only agent tools from approval-gated CLI mutations.
 - It is strong for local repo work where you want to move from planning to implementation to verification without changing libraries.
 - It includes both general-purpose engineering skills and deeper specialist tracks.
-- It gives you docs and bundles, not just raw skill files.
+- It still supports direct installs and plugin distributions as delivery surfaces.
+
+## Direct install and plugins
 
-## Install Codex CLI Skills
+Use a direct install only when you intentionally want the library copied into Codex's skills path:
 
 ```bash
 npx agentic-awesome-skills --codex
 ```
 
-If you prefer a plugin-style Codex integration, this repository also ships repo-local plugin metadata in `.agents/plugins/marketplace.json` and `plugins/agentic-awesome-skills/.codex-plugin/plugin.json`.
+For plugin-style packaging, this repository also ships repo-local metadata in `.agents/plugins/marketplace.json` and `plugins/agentic-awesome-skills/.codex-plugin/plugin.json`.
 
 It also generates bundle-specific Codex plugins so you can install a curated pack such as `Essentials` or `Web Wizard` as a marketplace plugin instead of loading the full library.
 
 Those Codex plugins are plugin-safe filtered distributions. Skills that still depend on host-specific paths or undeclared setup stay in the repository, but are not published into the Codex plugin until they are hardened.
 
-For the canonical explanation of how Codex plugins relate to the full library and bundle installs, read [plugins.md](plugins.md).
+For the canonical explanation of how Core, Codex plugins, and direct installs relate, read [plugins.md](plugins.md).
 
 ### Verify the install
 
@@ -51,6 +59,14 @@ test -d .codex/skills || test -d ~/.codex/skills
 
 ## Example Codex CLI prompts
 
+With AAS Core configured:
+
+```text
+Use AAS to recommend the smallest skill stack for designing and testing this parser change. Show me the proposed aas-stack.json and preview the plan; do not apply it.
+```
+
+After installing or activating a chosen skill, direct invocation still works:
+
 ```text
 Use @concise-planning to break this feature request into an implementation checklist.
 ```
@@ -65,6 +81,7 @@ Use @create-pr once everything is passing and summarize the user-facing changes.
 
 ## What to do next
 
+- Start with [`aas-core.md`](aas-core.md) for setup, trust boundaries, and the stack lifecycle.
 - Read [`ai-agent-skills.md`](ai-agent-skills.md) if you want a framework for choosing between broad and curated skill libraries.
 - Read [`plugins.md`](plugins.md) if you want the plugin-specific install story for Codex and Claude Code.
 - Use [`workflows.md`](workflows.md) when you want step-by-step execution patterns for common engineering goals.

package/bundled-skills/docs/users/discovery-manifest.md

@@ -1,6 +1,8 @@
-# Stable Skills Manifest v1
+# Stable Skills Manifest v1 for Custom Integrations
 
-This page documents the `skills_index.json` manifest contract used by stable integrations.
+This page documents the legacy-compatible `skills_index.json` contract used by custom host integrations and lazy loaders.
+
+For Codex and Claude Code, use [AAS Core](aas-core.md) instead of wiring a host directly to this repository manifest. Core uses a verified local catalog and exposes bounded, read-only MCP tools for search, inspection, and recommendation. The raw manifest remains useful for integrations that do not have an AAS Core host adapter.
 
 ## Manifest contract (v1)
 
@@ -34,7 +36,7 @@ Stable integrations must not load every skill instruction file up front.
 - Enforce a per-turn maximum so user prompts stay below context limits.
 - Validate each resolved path stays under your configured `SKILLS_ROOT`.
 
-This is the core prevention for context truncation and trajectory conversion errors in larger multi-skill hosts.
+This is the main prevention for context truncation and trajectory conversion errors in custom multi-skill hosts. It is not the AAS Core catalog or stack lifecycle contract.
 
 ## Why the `data/` mirror exists
 
@@ -57,6 +59,7 @@ This is the core prevention for context truncation and trajectory conversion err
 
 ## Related docs
 
+- [`docs/users/aas-core.md`](aas-core.md)
 - [`docs/integrations/jetski-cortex.md`](../integrations/jetski-cortex.md)
 - [`docs/integrations/jetski-gemini-loader/README.md`](../integrations/jetski-gemini-loader/README.md)
 - [`docs/users/windows-truncation-recovery.md`](windows-truncation-recovery.md)

package/bundled-skills/docs/users/faq.md

@@ -6,6 +6,22 @@
 
 ## General Questions
 
+### What is AAS Core?
+
+AAS Core is the deterministic, versioned control plane that turns this repository's catalog into an approved project stack. Codex or Claude can inspect a repository, send an explicit profile to the local read-only AAS MCP, explain the resulting recommendation, and propose an `aas-stack.json`. The `aas` CLI then validates the manifest and previews an immutable plan.
+
+AAS Core is the product; the approved `aas-stack.json` and immutable plan are its durable artifacts. Skills and the catalog provide content and evidence, MCP and CLI are interfaces, Workbench is a review surface, and plugins, bundles, workflows, and installers provide curation or distribution around Core. Start with [AAS Core](aas-core.md).
+
+### Is AAS Core fully certified?
+
+No. The current public claim is **AAS Agent-First Preview**: it helps Codex and Claude compose a local, explainable, reproducible skill stack. Full-catalog recommendation quality and transactional apply/recovery safety are not yet certified.
+
+`stack apply` and `stack recover` are experimental, disabled by default, and are not supported preview safety claims. The recommended public flow stops after reviewing `stack validate` and `stack plan` output.
+
+### Does AAS upload my repository or use another model?
+
+No. The agent may inspect the project using its normal local capabilities, but AAS MCP does not scan the repository. It receives an explicit allowlisted profile and runs deterministic recommendation against a bundled or verified local catalog. MCP is local stdio, read-only, offline-capable, and contains no model credentials or telemetry.
+
 ### 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.
@@ -13,9 +29,9 @@ Skills are specialized instruction files that teach AI assistants how to handle
 
 ### Do I need to install every skill?
 
-**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 focus on the skills that match your role first.
+**No.** With AAS Core, ask the agent to recommend a small stack that matches your project, target, goals, and risk policy. On a broad direct install, all skills may be present locally while the host loads only the skills it invokes.
+
+Use [Starter Packs](bundles.md) as human-curated presets when you want a fixed starting point.
 
 If you want a narrower install surface for **Claude Code** or **Codex**, use the new plugin distributions documented in [plugins.md](plugins.md) instead of the full library install.
 
@@ -31,12 +47,13 @@ Start from:
 - [bundles.md](bundles.md)
 - [workflows.md](workflows.md)
 
-### What is the difference between skills and MCP tools?
+### What is the difference between skills, AAS MCP, and the CLI?
 
 - **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.
+- **AAS MCP** is the local, read-only discovery and composition interface to AAS Core. It searches and inspects the verified catalog, recommends a stack, and checks or compares manifests.
+- **The `aas` CLI** manages explicit lifecycle operations such as catalog status/update, MCP configuration, stack validation, planning, and diagnostics.
 
-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.
+Other MCP servers may grant access to APIs, services, databases, or hosted systems. AAS MCP has a narrower boundary: it does not install, apply, update catalogs, scan repositories, or modify configuration through tool calls.
 
 For the longer explanation, read [skills-vs-mcp-tools.md](skills-vs-mcp-tools.md).
 
@@ -118,6 +135,12 @@ _Always check the Risk label and review the code._
 
 ## Installation & Setup
 
+### How do I start with AAS Core?
+
+Use the pinned `aas` binary from a release whose notes explicitly state that it includes AAS Core to preview and approve local MCP configuration for Codex or Claude. Release 14.6.0 predates Core; Core-capable packages begin with the 15.x line. Restart the host if needed, then ask the agent to recommend and explain a stack without applying it. The command template and trust boundaries are in [AAS Core](aas-core.md).
+
+The package publishes separate `agentic-awesome-skills`, `aas`, and `aas-mcp` binaries. Use the explicit `aas` binary for Core lifecycle commands; the legacy `agentic-awesome-skills` entrypoint remains the direct installer.
+
 ### Where should I install the skills?
 
 It depends on how you install:
@@ -137,7 +160,7 @@ If you get a 404 from npm, use: `npx github:sickn33/agentic-awesome-skills`
 git clone https://github.com/sickn33/agentic-awesome-skills.git .agent/skills
 ```
 
-The installer CLI is the recommended path for most users because it performs a lighter shallow clone of the current library. Manual `git clone` is still the right option when you want the full repository history or plan to contribute from the same checkout.
+For direct skill distribution, the installer CLI performs a lighter shallow clone of the current library. Manual `git clone` remains appropriate when you want the full repository history or plan to contribute from the same checkout. For Codex or Claude users who want project-specific recommendation, start with AAS Core instead of treating a full-library install as the primary product path.
 
 **Tool-specific paths:**
 
@@ -254,7 +277,7 @@ npx agentic-awesome-skills@14.3.0 --path .agents/skills --release 14.3.0 --skill
 
 Remove `--dry-run` only after reviewing the plan.
 
-If you prefer to assemble and review the set visually, use the hosted [Skill Workbench](https://sickn33.github.io/agentic-awesome-skills/workbench). It filters recorded risk, provenance, host compatibility, and setup evidence before generating the same release-pinned commands.
+To review a Core stack manifest or immutable plan visually, use the hosted [Skill Workbench](https://sickn33.github.io/agentic-awesome-skills/workbench). It imports the JSON in browser memory and checks the supported artifact structure; it does not assemble a stack, generate install commands, access the filesystem, or install skills.
 
 The filter rules are:
 
@@ -355,9 +378,13 @@ Examples:
 
 ### How do I know which skill to use?
 
+With AAS Core, describe the project outcome and constraints, then ask the agent to call `recommend_stack`. Review its coverage, evidence, exclusions, discovery candidates, and unknowns before accepting the proposed IDs.
+
+For manual discovery:
+
 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?"
+2. **Search**: `ls skills/ | grep "keyword"`.
+3. **Use a preset**: Start from [Bundles](bundles.md).
 
 ---
 

package/bundled-skills/docs/users/gemini-cli-skills.md

@@ -12,7 +12,7 @@ Install into the Gemini skills path, then ask Gemini to apply one skill at a tim
 
 - It installs directly into the expected Gemini skills path.
 - It includes both core software engineering skills and deeper agent/LLM-oriented skills.
-- It helps new users get started with bundles and workflows rather than forcing a cold start from 1,965+ files.
+- It helps new users get started with bundles and workflows rather than forcing a cold start from 1,968+ files.
 - It is useful whether you want a broad internal skill library or a single repo to test many workflows quickly.
 
 ## Install Gemini CLI Skills

package/bundled-skills/docs/users/getting-started.md

@@ -1,8 +1,21 @@
-# Getting Started with Agentic Awesome Skills (V14.6.0)
+# Getting Started with AAS Core
 
-**New here? This guide will help you supercharge your AI Agent in 5 minutes.**
+**New here? Start with AAS Core and let your agent compose a small, reviewable skill stack for the project.**
 
-> **💡 Confused about what to do after installation?** Check out the [**Complete Usage Guide**](usage.md) for detailed explanations and examples!
+> **Preview status:** AAS Agent-First Preview supports local, explainable stack composition with Codex and Claude. Full-catalog recommendation quality and transactional apply/recovery safety are not yet certified.
+
+## Start with AAS Core
+
+AAS Core is the primary product path. Codex or Claude inspects your project, calls the local read-only AAS MCP, explains a deterministic catalog recommendation, and proposes an `aas-stack.json`. You review the exact policy and skill IDs before using the `aas` CLI to validate the manifest and preview a plan.
+
+```text
+project -> agent -> local AAS MCP -> recommendation -> aas-stack.json
+        -> human review -> validate -> plan preview
+```
+
+Start with the canonical [AAS Core guide](aas-core.md) to configure the MCP and run that flow. The direct installer, plugins, bundles, and manual skill invocation described below remain useful alternatives, especially for hosts without a native AAS MCP adapter.
+
+> **Need more examples after setup?** Continue with the [Complete Usage Guide](usage.md).
 
 ---
 
@@ -15,16 +28,16 @@ AI Agents (like **Claude Code**, **Gemini**, **Cursor**) are smart, but they lac
 
 ---
 
-## Quick Start: The "Starter Packs"
+## Alternative Path: Direct Skill Distribution and Starter Packs
 
 Don't panic about the size of the repository. You don't need everything 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.
+On the direct-install path, you install the library 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.
 
 If you prefer a marketplace-style install for **Claude Code** or **Codex**, use the new plugin distributions described in [plugins.md](plugins.md).
 
-### 1. Install the Repo
+### 1. Install Skills Directly
 
 **Option A — npx (easiest):**
 
@@ -154,7 +167,7 @@ For Claude Code, use:
 For Codex, this repository also ships a root plugin plus bundle plugins through the repo-local metadata described in [plugins.md](plugins.md).
 
 **Q: Do I need to install every skill?**
-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.
+A: No. With AAS Core, ask the agent to recommend a small stack under an explicit policy. On the legacy direct-install path, you can install the broad library while the host reads only invoked or relevant skills. **Starter Packs** in [bundles.md](bundles.md) remain human-curated discovery aids.
 
 **Q: Can I make my own skills?**
 A: Yes! Use the **@skill-creator** skill to build your own.
@@ -186,6 +199,7 @@ Need a tool-specific starting point first?
 - [Codex CLI skills](codex-cli-skills.md)
 - [Gemini CLI skills](gemini-cli-skills.md)
 
-1. [Browse the Bundles](bundles.md)
-2. [See Real-World Examples](../contributors/examples.md)
-3. [Contribute a Skill](../../CONTRIBUTING.md)
+1. [Configure and use AAS Core](aas-core.md)
+2. [Browse the Bundles](bundles.md)
+3. [See Real-World Examples](../contributors/examples.md)
+4. [Contribute a Skill](../../CONTRIBUTING.md)

package/bundled-skills/docs/users/kiro-integration.md

@@ -18,7 +18,7 @@ Kiro is AWS's agentic AI IDE that combines:
 
 Kiro's agentic capabilities are enhanced by skills that provide:
 
-- **Domain expertise** across 1,965+ specialized areas
+- **Domain expertise** across 1,968+ 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

package/bundled-skills/docs/users/plugins.md

@@ -2,7 +2,7 @@
 
 Release `9.0.0` adds first-class plugin distributions for both **Claude Code** and **Codex**.
 
-This page is the canonical explanation of what those plugins are, how they differ from a full library install, and why the repository now ships both a **root plugin** and multiple **specialized plugins**.
+This page explains how plugins fit beneath **AAS Core**, the recommended orchestration layer for Codex and Claude Code. Plugins and direct installs deliver skill payloads; Core helps an agent discover, recommend, inspect, validate, and plan a minimal stack before delivery.
 
 ## What a plugin is in this repo
 
@@ -17,9 +17,13 @@ Plugins are useful when you want:
 
 Plugins are **not** different content formats. They still ship `SKILL.md` playbooks. The difference is the packaging, install surface, and filtering.
 
-## Full library install vs plugin install
+## Core orchestration vs delivery surfaces
+
+For Codex and Claude Code, start with [AAS Core](aas-core.md) when you want the agent to choose from catalog evidence. Core exposes read-only local MCP tools and keeps validation, planning, and approved changes in the CLI.
+
+Once the desired stack is clear, plugins and direct installs are two supported delivery surfaces. They do not replace Core and Core is not another plugin bundle.
 
-You now have two valid ways to use this repository with Claude Code or Codex.
+## Full library install vs plugin install
 
 ### Full library install
 
@@ -132,6 +136,13 @@ Bundle-specific Codex plugins are generated alongside the root plugin so you can
 
 ## Which path should you choose?
 
+Choose **AAS Core first** if:
+
+- you want Codex or Claude Code to search and inspect the local catalog
+- you want a deterministic recommendation instead of manually browsing thousands of skills
+- you want a reviewable `aas-stack.json` and preview plan before any change
+- you want read-only MCP discovery separated from approval-gated CLI operations
+
 Choose the **full library** if:
 
 - you want the biggest catalog
@@ -155,6 +166,7 @@ The hosted [specialized plugin landing page](https://sickn33.github.io/agentic-a
 
 ## Related guides
 
+- [AAS Core](aas-core.md)
 - [Getting Started](getting-started.md)
 - [FAQ](faq.md)
 - [Claude Code skills](claude-code-skills.md)

package/bundled-skills/docs/users/skills-vs-mcp-tools.md

@@ -1,89 +1,108 @@
-# Skills vs MCP Tools
+# Skills, AAS MCP, and Other MCP Tools
 
-If you are trying to understand the difference between **Antigravity skills** and **MCP tools**, the short version is:
+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.
+- **AAS MCP** is the local, read-only interface through which an agent searches the verified AAS catalog, inspects evidence, and composes a proposed stack.
+- **Other MCP tools** connect an assistant to external systems such as APIs, databases, browsers, or hosted services.
+- **The `aas` CLI** validates durable stack intent and previews exact lifecycle operations under human control.
 
-The two are complementary, not competing.
+These surfaces are complementary. AAS Core connects them around the approved `aas-stack.json` manifest.
 
 ## 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
+- 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.
+In practice, a skill improves the assistant's decision-making, structure, and process. It remains content, not an executable capability or a grant of authority.
 
-Example:
+Examples:
 
 - `@brainstorming` helps the model clarify requirements before implementation.
-- `@lint-and-validate` helps the model run the right quality checks before claiming success.
+- `@lint-and-validate` helps the model run appropriate quality checks before claiming success.
 
-## What an MCP tool does
+## What AAS MCP does
 
-An MCP tool gives the model a capability it would not otherwise have, such as:
+AAS MCP is part of this repository's product, not an unrelated external integration. Codex or Claude uses it to call the same deterministic AAS Core that powers the CLI projections.
 
-- reading from a database
-- calling GitHub APIs
-- fetching docs from a service
-- creating calendar events
-- querying an external system
+It exposes exactly:
 
-In practice, an MCP tool expands what the assistant can do in the world.
+- `search_skills`;
+- `get_skill`;
+- `recommend_stack`;
+- `inspect_stack`;
+- `diff_stack`;
+- the `aas://skills/{id}` resource template.
 
-## The easiest mental model
+The agent inspects the project using its normal local capabilities and sends AAS an explicit, allowlisted profile. AAS MCP does not scan the repository itself. It returns structured factors, evidence, coverage, exclusions, discovery candidates, and unknowns from a bundled or verified local catalog.
+
+AAS MCP is local stdio, process-per-session, read-only, offline-capable, and contains no model credentials or telemetry. Its tool calls do not install or remove skills, apply a stack, update catalogs, or edit host configuration.
+
+## What other MCP tools do
 
-Use this rule:
+An external MCP tool may give the model a capability it would not otherwise have, such as:
 
-- **Skills tell the assistant how to work.**
-- **MCP tools tell the assistant what systems it can touch.**
+- reading from a database;
+- calling GitHub APIs;
+- fetching documentation from a service;
+- creating calendar events;
+- querying or changing another system.
 
-If you only install tools, the assistant may have access but still behave inconsistently.
+Those tools expand what the assistant can do in the world. Their permissions, network behavior, and write boundaries depend on each server. They are different from the deliberately narrow AAS MCP catalog/composition boundary.
 
-If you only install skills, the assistant may know the workflow but still lack the capability to reach the external system it needs.
+## What the CLI does
 
-Together, they are much stronger.
+The `aas` CLI is the explicit operational interface for:
 
-## Which one should you start with?
+- catalog status and updates;
+- MCP configuration;
+- stack initialization and deterministic recommendation from an explicit profile;
+- manifest validation;
+- plan creation and read-only diagnostics.
 
-Start with **skills** if:
+The durable artifact is `aas-stack.json`, which pins catalog identity, targets, intent, policy, and exact skill IDs. The agent may propose it; the user reviews it. `stack validate` checks it, and `stack plan` creates an immutable preview bound to the observed managed state and exact operations.
+
+`stack apply` and `stack recover` exist only for controlled preview development. They are experimental, disabled by default, and are not supported or certified preview safety claims.
+
+## The easiest mental model
 
-- 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
+- **Skills provide the operating guidance.**
+- **AAS MCP helps the agent select and explain the right guidance.**
+- **`aas-stack.json` records what the user approved.**
+- **The CLI validates and previews the lifecycle.**
+- **Other MCP servers provide access to outside systems.**
 
-Start with **MCP tools** if:
+## Which path should you start with?
 
-- 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
+Start with **AAS Core** when:
 
-Use **both** when:
+- you use Codex or Claude with local MCP support;
+- you want the agent to compose a small stack from project evidence;
+- you need explicit risk/source/setup policy and a reproducible manifest;
+- you want a reviewable plan before any skill changes.
 
-- you want reliable workflows plus external capabilities
-- you are building agent systems, internal tooling, or multi-step operational flows
+Start with a **direct skill or specialized plugin** when:
 
-## How this repo fits in
+- the host does not yet have a native AAS MCP configuration adapter;
+- you already know the exact skill or fixed domain pack you want;
+- you prefer manual invocation without a managed stack lifecycle.
 
-Agentic Awesome Skills is primarily a **skill library**:
+Add **other MCP tools** when the work needs live access to APIs, services, databases, or hosted platforms. A stack can contain skills that guide those integrations without granting the external permissions itself.
 
-- 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
+## Preview limits
 
-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.
+AAS Agent-First Preview helps Codex and Claude compose a local, explainable, reproducible skill stack. It does not claim certified full-catalog recommendation quality or transactional apply/recovery safety. Missing evidence is reported as `unknown`, and AAS may leave a goal uncovered rather than present a weak recommendation as certainty.
 
 ## Good next reads
 
+- [AAS Core](aas-core.md)
+- [Getting Started](getting-started.md)
 - [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)
+- [Plugins for Claude Code and Codex](plugins.md)