opencode-skills-collection 4.0.4 → 4.0.5

package/bundled-skills/docs/maintainers/audit.md

@@ -39,11 +39,8 @@ This document summarizes the repository coherence audit performed after the `app
   - missing examples and missing limitations sections,
   - overly long `SKILL.md` files that should probably be split into `references/`,
   - plus the existing structural/safety checks (frontmatter, risk, `When to Use`, offensive disclaimer, dangling links).
-- The report also includes a non-blocking `suggested_risk` for skills that are still marked `unknown` or appear to be misclassified, so maintainers can resolve risk classification during PR review without changing the contributor gate.
-- Added `tools/scripts/sync_risk_labels.py` (also exposed as `npm run sync:risk-labels`) for conservative legacy cleanup: it only rewrites `risk: unknown` when the suggestion is high-confidence enough to be safely automated.
-- The sync now covers explicit high-confidence `safe`, `critical`, `offensive`, and `none` patterns. When a skill is promoted to `offensive`, the sync also inserts the canonical `AUTHORIZED USE ONLY` notice so the label and content guardrail stay aligned.
-- The intended maintainer loop is: `audit:skills` to inspect `suggested_risk`, `sync:risk-labels` for the safe automated subset, then manual review for the ambiguous tail that should not be batch-classified.
-- Use `npm run audit:skills` for the maintainer view and `npm run audit:skills -- --json-out ... --markdown-out ...` when you want artifacts for triage or cleanup tracking.
+- Risk inference from isolated words was removed because it produced widespread false positives. The audit validates declared metadata; ambiguous labels require semantic review.
+- Use `npm run audit:skills` for the maintainer view and `npm run audit:skills -- --json-out ... --markdown-out ...` when you want objective structural artifacts for triage or cleanup tracking.
 
 ### 3. Cross references
 
@@ -79,8 +76,6 @@ This document summarizes the repository coherence audit performed after the `app
 npm run validate          # skill validation (soft)
 npm run validate:strict   # hardening / diagnostic pass
 npm run audit:skills      # full skill audit with finding codes and status
-npm run sync:risk-labels  # conservative sync for high-confidence legacy risk labels
-npm run sync:risk-labels -- --dry-run  # preview legacy risk rewrites before touching files
 npm run validate:references  # workflow, bundle, and docs/users/bundles.md references
 npm run security:docs       # documentation command-risk scan (required for security-sensitive guidance)
 npm run build             # chain + catalog
@@ -90,5 +85,5 @@ npm test                  # suite test
 ## Open issues / follow-up
 
 - Gradual cleanup of legacy skills so `npm run validate:strict` can become a hard CI gate in the future.
-- Continue reducing the remaining `risk: unknown` tail with conservative sync passes plus manual maintainer review for ambiguous cases.
+- Continue reducing the remaining `risk: unknown` tail through semantic maintainer review.
 - Keep translated docs aligned in a separate pass after the canonical English docs are stable.

package/bundled-skills/docs/maintainers/legacy-redirect-bridge.md

@@ -0,0 +1,46 @@
+# Legacy Redirect Bridge
+
+The compatibility site at `https://sickn33.github.io/antigravity-awesome-skills/` is published from the separate `sickn33/sickn33.github.io` repository. It preserves old indexed URLs while the canonical site lives at `https://sickn33.github.io/agentic-awesome-skills/`.
+
+## Managed deployment surface
+
+Only these paths belong to the redirect generator:
+
+- `.nojekyll`
+- `redirect-manifest.json`
+- `antigravity-awesome-skills/**`
+
+The target repository's `README.md` and `.github/**` automation are deliberately outside that managed set.
+
+Generate a fresh bridge from the current catalog:
+
+```bash
+npm run pages:redirect-bridge -- --output /new/output/directory
+```
+
+The generator keeps the curated sitemap route count locked while deriving the skill count from `skills_index.json`. It also preserves the legacy Google verification file and the Bing verification meta tag on the legacy root page.
+
+Manifest schema version `3` records source-repository provenance, redirect coverage, and webmaster-verification evidence for automation consumers.
+
+Verify a checked-out target repository byte-for-byte:
+
+```bash
+npm run pages:redirect-verify -- --deployment-root /path/to/sickn33.github.io
+```
+
+Add a bounded live probe after deployment:
+
+```bash
+npm run pages:redirect-verify -- \
+  --deployment-root /path/to/sickn33.github.io \
+  --live-root https://sickn33.github.io/ \
+  --live-mode sample
+```
+
+Use `--live-mode all` for a complete route-pair audit.
+
+## Publication contract
+
+The target repository owns the scheduled synchronization workflow. It checks out this repository at `main`, regenerates only the managed deployment surface, opens a fixed-branch PR when drift exists, dispatches the exact-head verifier, and merges only after the protected check succeeds. The same run explicitly requests and verifies the legacy Pages build so automation is not dependent on GitHub events suppressed for `GITHUB_TOKEN`-authored changes.
+
+Target `main` must remain protected with strict `legacy-bridge-verify`, administrator enforcement, pull requests required, and force pushes/deletions disabled.

package/bundled-skills/docs/maintainers/merge-batch.md

@@ -30,22 +30,18 @@ Use `--dry-run` to exercise local classification without approving a run or merg
 
 `merge:batch` will:
 
-- refresh the PR body when the Quality Bar checklist is missing
-- record the existing workflow-run generation, then close and reopen the PR if stale metadata needs a fresh `pull_request` event
 - fetch the exact base/head objects and classify the complete raw Git diff
 - recompute changed-skill evidence with evaluator code materialized from the trusted `main` commit
 - reject incomplete evidence coverage, deterministic quality/security/provenance regressions, and base/head drift
-- for external PRs, poll for asynchronously-created fork runs and approve only post-reopen runs waiting on `action_required` when every path, mode, object, size, and workflow identity is allowlisted
+- for external PRs, poll for asynchronously-created fork runs and approve only runs waiting on `action_required` when every path, mode, object, size, and workflow identity is allowlisted
 - for same-repository maintainer PRs, allow repository-wide source changes while still enforcing trusted changed-skill evidence, exact-head review, required checks, branch protection, and immutable PR identity
-- wait only for check suites belonging to the post-reopen workflow generation; older runs on the same head SHA cannot satisfy or fail the gate
+- wait for the latest required checks bound to the exact head SHA
 - call GitHub's immediate squash-merge endpoint and continue only when it reports `merged: true`
 - pull the protected `main`; its trusted workflow opens a canonical-sync bot PR for generated artifacts and contributor credits when needed
 
 ## What It Automates
 
-- PR body normalization against the repository template
-- stale PR metadata refresh
-- generation-bound required-check polling for the current PR head
+- exact-head required-check polling
 - handoff of post-merge contributor and artifact drift to the canonical-sync PR lane
 
 ## What It Does Not Automate

package/bundled-skills/docs/maintainers/merging-prs.md

@@ -21,7 +21,7 @@ Resolve conflicts **on the PR branch** so the PR becomes mergeable, then use "Sq
 - `README.md` is mixed ownership: contributor prose edits are allowed, but workflow-managed metadata is canonicalized on `main`.
 - If derived files appear in a PR refresh or merge conflict, prefer **`main`'s side** and remove them from the PR branch instead of hand-maintaining them there.
 - Do not block a PR only because shared generated files would be regenerated differently after other merges. `main` auto-syncs the final state after merge.
-- If a skill PR leaves `risk: unknown`, that is not automatically a blocker. Maintainers can review the suggested classification with `npm run audit:skills`, optionally run `npm run sync:risk-labels` locally after merge, and still keep the contributor PR source-only.
+- If a skill PR leaves `risk: unknown`, that is not automatically a blocker. Review the actual behavior semantically; do not infer risk from isolated words or rewrite it automatically.
 
 ### Steps (maintainer resolves conflicts on the contributor’s branch)
 

package/bundled-skills/docs/maintainers/pr-autonomy.md

@@ -41,11 +41,10 @@ Every new or relocated skill and every canonical skill-content change requires m
 
 ## Fork Review States
 
-The Skill Review workflow separates three outcomes:
+The Skill Review workflow separates two outcomes:
 
 - `review`: a semantic review actually ran using trusted base scripts;
-- `manual-review-required`: repository secrets were unavailable to a fork, so a maintainer must review and attest to the exact head SHA;
-- `missing-review-credentials`: an internal branch expected semantic-review credentials but none were configured, so the check fails closed.
+- `manual-review-required`: Tessl credentials or quota were unavailable, or Tessl did not produce a passing semantic result, so a maintainer must review and attest to the exact head SHA.
 
 A successful `manual-review-required` check means only that the requirement was recorded. It is not a successful semantic review.
 

package/bundled-skills/docs/maintainers/release-process.md

@@ -47,7 +47,7 @@ Use this as a diagnostic signal. It is useful for spotting legacy quality debt,
 - Confirm `README.md` reflects the current version and generated counts.
 - Confirm Credits & Sources, contributors, and support links are still correct.
 - If PR or CI workflow behavior changed during the cycle, confirm maintainer and contributor docs mention the active checks (for example the `skill-review` workflow for `SKILL.md` pull requests).
-- If maintainers used `npm run sync:risk-labels` or a comparable cleanup flow during the cycle, make sure the maintainer docs still describe the current audit -> sync -> repo-state loop.
+- If maintainers changed declared risk labels during the cycle, confirm that each change has semantic review evidence rather than lexical inference.
 
 5. Prepare the protected release PR:
 
@@ -65,22 +65,29 @@ This command:
 - creates and pushes `release/vX.Y.Z`
 - opens a release PR containing the scripted canonical release state
 
+Prerelease versions use the same protected flow, for example `15.0.0-rc.1`. They must have their own exact changelog section.
+
 6. Merge the release PR through required checks, update local `main`, then publish the GitHub release:
 
 ```bash
 npm run release:publish -- X.Y.Z
 ```
 
-This command proves local `main` equals protected `origin/main` and the exact squash commit of the merged `release/vX.Y.Z` PR, checks that no canonical-sync PR or release-state drift remains, creates or reuses the matching local/remote tag safely, and creates the GitHub release object from the matching `CHANGELOG.md` section. It never pushes `main` directly and can be retried after a partial tag/release failure.
+This command proves local `main` equals protected `origin/main` and the exact squash commit of the merged `release/vX.Y.Z` PR, checks that no canonical-sync PR or release-state drift remains, creates or reuses the matching local/remote tag safely, and creates the GitHub release object from the matching `CHANGELOG.md` section. SemVer prereleases are marked as GitHub prereleases. It never pushes `main` directly and can be retried after a partial tag/release failure.
 
 7. Publish to npm if needed:
 
 ```bash
-npm publish
+npm publish --tag latest
+```
+
+Normally this still happens via the existing GitHub release workflow after the GitHub release is published. The workflow publishes stable versions explicitly to npm's `latest` dist-tag and prerelease versions explicitly to `next`; it fails closed on an invalid version. Verify both tags after a prerelease so `latest` remains on the last stable release.
+
+```bash
+npm view agentic-awesome-skills dist-tags --json
 ```
 
-Normally this still happens via the existing GitHub release workflow after the GitHub release is published.
-That workflow now reruns `sync:release-state`, installs Python dependencies from `tools/requirements.txt`, refreshes tracked web assets, fails on canonical drift via `git diff --exit-code`, executes tests and docs security checks, runs the web-app coverage gate, enforces `npm audit --audit-level=high`, builds the web app, and dry-runs the npm package before `npm publish`.
+The workflow reruns `sync:release-state`, installs Python dependencies from `tools/requirements.txt`, refreshes tracked web assets, fails on canonical drift via `git diff --exit-code`, executes tests and docs security checks, runs the web-app coverage gate, enforces `npm audit --audit-level=high`, builds the web app, and dry-runs the npm package before publishing.
 
 ## Canonical Sync Bot
 

package/bundled-skills/docs/maintainers/repo-growth-seo.md

@@ -6,21 +6,21 @@ This document keeps the repository's GitHub-facing discovery copy aligned with t
 
 Preferred positioning:
 
-> Installable GitHub library of 1,965+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and other AI coding assistants.
+> AAS Core is the local, deterministic engine that turns an explicit project profile into an explainable skill-stack recommendation and immutable preview plan, backed by 1,967+ cataloged skills.
 
 Key framing:
 
-- installable skill library;
-- GitHub-first discovery;
-- broad multi-tool compatibility;
-- bundles, workflows, and onboarding docs;
-- useful for both breadth and curated evaluation.
+- AAS Core as the primary product;
+- local MCP and CLI as the agent-facing and operator-facing interfaces;
+- `aas-stack.json` and the immutable plan as durable artifacts;
+- GitHub as the canonical source, with the hosted catalog and Workbench as discovery and review surfaces;
+- catalog, plugins, bundles, workflows, and direct installers as supporting content and distribution.
 
 ## GitHub About settings
 
 Preferred description:
 
-> Installable GitHub library of 1,965+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
+> Local, deterministic AAS Core for explainable coding-agent skill stacks, backed by 1,967+ cataloged skills. Includes a read-only MCP, stack CLI, Workbench review, plugins, bundles, workflows, and direct distribution.
 
 Preferred homepage:
 
@@ -28,8 +28,9 @@ Preferred homepage:
 
 Preferred social preview:
 
-- use a clean preview image that says `1,965+ Agentic Skills`;
-- mention Claude Code, Cursor, Codex CLI, and Gemini CLI;
+- lead with `AAS Core` and the profile → stack → plan flow;
+- present `1,968+ Agentic Skills` as supporting catalog evidence, not a second product;
+- mention Codex and Claude as the current Core agent path, with broader host compatibility as distribution support;
 - avoid dense text and tiny logos that disappear in social cards.
 
 Preferred topics:
@@ -75,11 +76,12 @@ Suggested release template:
 ```md
 ## [VERSION] - YYYY-MM-DD - "User-facing title"
 
-> Installable skill library update for Claude Code, Cursor, Codex CLI, Gemini CLI, and related AI coding assistants.
+> AAS Core and supporting catalog update for local, explainable coding-agent skill stacks.
 
 Start here:
 
-- Install: `npx agentic-awesome-skills`
+- AAS Core guide: `docs/users/aas-core.md`
+- Direct skill distribution: `npx agentic-awesome-skills`
 - Choose your tool: `README.md#choose-your-tool`
 - Specialized plugins: `README.md#recommended-specialized-plugins`
 - Bundles: `docs/users/bundles.md`
@@ -113,9 +115,9 @@ Start here:
 
 Suggested pinned discussion topics:
 
-- `Start here: best skills by tool`
-- `Best bundles for new users`
-- `How to choose between Antigravity and other skill libraries`
+- `Start here: compose a project stack with AAS Core`
+- `Choose between Core recommendation and direct distribution`
+- `How the catalog, plugins, bundles, and workflows support Core`
 
 Discussion posts should:
 

package/bundled-skills/docs/maintainers/skills-update-guide.md

@@ -72,7 +72,7 @@ The update process refreshes:
 - Canonical skills index (`skills_index.json`)
 - Compatibility mirror (`data/skills_index.json`)
 - Web app skills data (`apps\web-app\public\skills.json`)
-- All 1,965+ skills from the skills directory
+- All 1,968+ skills from the skills directory
 
 ## When to Update
 

package/bundled-skills/docs/users/aas-core.md

@@ -0,0 +1,147 @@
+# AAS Core: Agent-First Skill Stacks
+
+> **Preview status:** AAS Agent-First Preview helps Codex and Claude compose a local, explainable, reproducible skill stack. Full-catalog recommendation quality and transactional apply/recovery safety are not yet certified.
+
+AAS Core is the primary way to turn the repository's skill catalog into a controlled project stack:
+
+> **The agent composes. You control. AAS keeps the stack reproducible.**
+
+The durable artifact is [`aas-stack.json`](#the-stack-manifest), not a prompt, an opaque model decision, or a copy of the entire catalog. The same deterministic, versioned core powers the local MCP server and the `aas` CLI. The hosted Workbench is a review surface; it is not a browser-side installer or hosted control plane.
+
+## How it works
+
+```text
+your project
+  -> Codex or Claude inspects the repository
+  -> local AAS MCP (stdio, read-only)
+  -> deterministic AAS Core + bundled or verified local catalog
+  -> agent explains a recommendation and proposes aas-stack.json
+  -> you review the exact skills, target, policy, and catalog identity
+  -> aas stack validate
+  -> aas stack plan (preview; no skill changes)
+```
+
+The agent may inspect your project using its normal local capabilities, but AAS MCP does not scan the repository. It receives an explicit, allowlisted profile from the agent and returns structured catalog evidence.
+
+## Configure the local MCP
+
+> **Release boundary:** AAS Core landed after release 14.6.0, which is not a valid Core bootstrap. Core-capable packages begin with the 15.x line. In the command template below, replace `X.Y.Z` only with an exact release whose notes explicitly state that it includes AAS Core; do not resolve an unreviewed moving tag.
+
+The package publishes separate `aas` and `aas-mcp` binaries. For a pinned Core release without relying on npm's default-bin selection, invoke `aas` explicitly:
+
+```bash
+npm exec --yes --ignore-scripts --package=agentic-awesome-skills@X.Y.Z -- aas mcp configure \
+  --host codex \
+  --scope user \
+  --config /absolute/path/to/codex/config.toml \
+  --cache-root /absolute/path/to/aas-cache
+```
+
+Use `--host claude` with the appropriate absolute Claude MCP configuration path for Claude. The first command is a preview and returns an approval digest without changing the host configuration. Review it, then repeat the exact command with:
+
+```text
+--approve <approval-digest>
+```
+
+Configuration is explicit and integrity-bound. AAS installs or reuses an exact content-addressed runtime, verifies it, and changes only its managed MCP configuration section. Restart the host if it does not reload MCP configuration automatically.
+
+## Ask the agent to compose the stack
+
+Once the host discovers the AAS MCP tools, give it the outcome and constraints rather than manually choosing from almost 2,000 skills:
+
+```text
+Inspect this repository and use the AAS MCP tools to recommend a small skill stack
+for implementing and testing this project. Explain exclusions and unknowns, then
+propose an aas-stack.json and validate it with inspect_stack before presenting it.
+Do not install or apply anything.
+```
+
+The local MCP exposes exactly these read-only tools:
+
+- `search_skills` — search the verified local catalog;
+- `get_skill` — inspect one skill and its recorded evidence;
+- `recommend_stack` — produce a deterministic recommendation from an explicit profile and policy;
+- `inspect_stack` — validate and explain a proposed manifest;
+- `diff_stack` — compare manifests using verified local catalogs.
+
+It also exposes the `aas://skills/{id}` resource template. MCP calls do not install or remove skills, update catalogs, edit host configuration, or apply a stack. Full skill text is returned only when requested and remains marked as untrusted content.
+
+## The stack manifest
+
+`aas-stack.json` records approved desired state:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "project-stack",
+  "catalog": {
+    "package": "agentic-awesome-skills",
+    "version": "<version>",
+    "integrity": "sha256-..."
+  },
+  "targets": [{ "host": "codex", "scope": "project" }],
+  "intent": { "goals": ["build", "test"] },
+  "policy": {
+    "allowedRisk": ["none", "safe"],
+    "requireKnownSource": true,
+    "allowManualSetup": false
+  },
+  "skills": [
+    { "id": "example-skill" }
+  ]
+}
+```
+
+The manifest pins the catalog identity, target, intent, policy, and exact skill IDs. Repository observations, ranking factors, exclusions, unknowns, and natural-language explanations stay in recommendation or plan output instead of becoming hidden state.
+
+## Validate and preview the plan
+
+Use absolute paths in automation and review the JSON result from each command:
+
+```bash
+aas stack validate --manifest /absolute/path/to/aas-stack.json
+
+aas stack plan \
+  --manifest /absolute/path/to/aas-stack.json \
+  --target codex:project \
+  --target-root /absolute/path/to/project \
+  --cache-root /absolute/path/to/aas-cache \
+  --runtime-integrity '<npm-sri>' \
+  --out /absolute/path/to/plan.json
+```
+
+`stack plan` derives the exact runtime version from the catalog identity in `aas-stack.json`; the verified runtime integrity remains explicit. The CLI rejects a legacy `--runtime-version` override when it disagrees with the manifest, so the documented command does not need a version edit for each release.
+
+`stack validate` is read-only. `stack plan` writes only the requested plan artifact and does not materialize skills or AAS managed state in the target. The immutable plan binds the manifest, runtime, catalog, target identity, current managed state, and exact logical operations.
+
+Stop after reviewing the plan unless you are deliberately participating in controlled preview development. `stack apply` and `stack recover` are disabled by default, require additional experimental flags and exact digest approval, and are **not supported or certified preview safety claims**.
+
+## Privacy, trust, and limits
+
+- MCP is local stdio, process-per-session, read-only, offline-capable, and contains no model credentials or telemetry.
+- Recommendation is deterministic and evidence-based; AAS does not call another model, use embeddings, or perform remote ranking.
+- Missing evidence is reported as `unknown`. AAS may leave goals uncovered instead of presenting a weak match as certainty.
+- Catalog updates and runtime changes are explicit. There is no resident daemon or implicit auto-update.
+- The MCP boundary does not grant skill prose instruction authority and cannot guarantee how an external model interprets untrusted content.
+- Preview qualification does not certify full-catalog recommendation quality, transactional crash/race safety, apply, or recovery.
+
+## Other ways to use the catalog
+
+AAS Core is the recommended path when Codex or Claude can use the local MCP. Existing distribution paths remain available:
+
+- direct skill installs for hosts that load `SKILL.md` files;
+- specialized plugins for a fixed, domain-focused distribution;
+- bundles as human-curated presets;
+- workflows as ordered execution playbooks;
+- the legacy `agentic-awesome-skills` installer for compatible direct installs.
+
+These surfaces provide catalog content and packaging. AAS Core adds project-aware composition, explicit policy, a durable stack manifest, and a reviewable plan.
+
+## Next reads
+
+- [Getting Started](getting-started.md)
+- [Usage](usage.md)
+- [Skills vs MCP Tools](skills-vs-mcp-tools.md)
+- [Plugins for Claude Code and Codex](plugins.md)
+- [Bundles](bundles.md)
+- [FAQ](faq.md)

package/bundled-skills/docs/users/agentic-awesome-skills-vs-awesome-claude-skills.md

@@ -1,27 +1,28 @@
 # Agentic Awesome Skills vs Awesome Claude Skills
 
-If you are comparing **Agentic Awesome Skills** with **Awesome Claude Skills**, the decision usually comes down to breadth vs curation.
+If you are comparing **Agentic Awesome Skills** with **Awesome Claude Skills**, first decide whether you need deterministic project-level composition or an editorial discovery list. Catalog breadth and curation are secondary dimensions.
 
 For clarity: the repository many people still refer to as `awesome-claude-skills` now lives at [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills).
 
 ## TL;DR
 
-- Choose **Agentic Awesome Skills** if you want a large installable library, broad tool coverage, and strong onboarding.
+- Choose **Agentic Awesome Skills** if you want AAS Core to turn an explicit project profile into an explainable, reviewable skill stack, with broad catalog and distribution support around it.
 - Choose **VoltAgent Awesome Agent Skills** if you want a curated list with a strong official-team angle and a tighter scope.
 
 ## At-a-glance comparison
 
 | Criteria | Agentic Awesome Skills | VoltAgent Awesome Agent Skills |
 | --- | --- | --- |
-| Best for | Breadth, installation, multi-tool daily use | Curated discovery and official/community highlights |
-| Catalog shape | Large installable library with bundles, workflows, docs, and generated catalog | Curated awesome-list style collection |
+| Best for | Local deterministic composition, durable desired state, and plan preview | Curated discovery and official/community highlights |
+| Product shape | AAS Core with local MCP, CLI, stack/plan artifacts, Workbench review, and supporting catalog/distribution | Curated awesome-list style collection |
 | Supported tools | Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, Kiro, OpenCode, Copilot, more | Claude Code, Codex, Antigravity, Gemini CLI, Cursor, Copilot, OpenCode, Windsurf, more |
 | Onboarding | Installation docs, bundles, workflows, getting-started guides | Curated README and categorized references |
-| Good fit when | You want one repo to install and work from | You want a smaller list to browse and evaluate |
+| Good fit when | You want an agent to recommend a project stack under explicit policy | You want a smaller list to browse and evaluate manually |
 
 ## Why choose Agentic Awesome Skills
 
-- You want a single GitHub repository that acts as both a skill source and an installable working library.
+- You want Codex or Claude to send an explicit profile to a local, read-only MCP and receive a deterministic recommendation.
+- You want the approved selection recorded as `aas-stack.json` and validated before an immutable plan is produced.
 - You care about onboarding assets like [`bundles.md`](bundles.md), [`workflows.md`](workflows.md), and tool-specific guides.
 - You need coverage across many domains, not just a curated shortlist.
 
@@ -33,11 +34,11 @@ For clarity: the repository many people still refer to as `awesome-claude-skills
 
 ## Honest tradeoffs
 
-- Antigravity can feel bigger and noisier at first because it optimizes for breadth.
+- The AAS catalog is larger and its evidence remains uneven; Core reports unknowns rather than treating breadth as certified quality.
 - VoltAgent can be easier to skim quickly because it optimizes for curation.
-- If you want both, a sensible workflow is to browse curated lists first and install a broader library once you know your use cases.
+- If you want both, use curated lists for editorial discovery and AAS Core when you need a reproducible, policy-controlled project stack.
 
 ## Suggested next step
 
-- If you want to install and start using skills today, go back to [`README.md`](../../README.md) and follow the installation guide.
+- If you want project-specific composition, start with the [AAS Core guide](aas-core.md). If you already know exact skill IDs, use the direct distribution options in [`README.md`](../../README.md).
 - If you are still evaluating tool-specific options, continue with [`best-claude-code-skills-github.md`](best-claude-code-skills-github.md) or [`best-cursor-skills-github.md`](best-cursor-skills-github.md).

package/bundled-skills/docs/users/ai-agent-skills.md

@@ -1,29 +1,32 @@
 # AI Agent Skills
 
-If you are researching **AI agent skills** on GitHub, the biggest decision is usually not "which single skill is best?" but "do I want a broad installable library or a smaller curated collection?"
+If you are researching **AI agent skills** on GitHub, the useful first decision is whether you want deterministic project-level composition or manual selection from a catalog.
 
-Agentic Awesome Skills is built for the first path: broad coverage, multiple supported tools, installation help, onboarding docs, bundles, workflows, and a catalog that supports both beginner and advanced users.
+Agentic Awesome Skills is built around **AAS Core**: Codex or Claude inspects the project, sends an explicit profile to the local AAS MCP, and receives an explainable recommendation from the verified catalog. The agent proposes `aas-stack.json`; the CLI validates it and produces an immutable preview plan before any target change.
 
-## What to look for in an AI agent skills library
+The catalog, plugins, bundles, workflows, and direct installer remain supporting content and distribution surfaces. AAS does not scan the repository, call a remote model, or write project files through MCP.
 
-- **Installability**: can you put the skills where your tool expects them without manual copying?
-- **Supported tools**: does the repo work with Claude Code, Cursor, Codex CLI, Gemini CLI, and related environments?
-- **Breadth vs curation**: do you want many options or a smaller shortlist of high-signal entries?
-- **Onboarding quality**: are there docs, bundles, workflows, and examples, or only raw files?
-- **Trust model**: does the repo identify official sources, security posture, and community review expectations?
+## What to look for in an AI agent skill system
+
+- **Explicit input boundary**: is project analysis performed by the coding agent and passed as a reviewable profile?
+- **Deterministic recommendation**: can the same profile, policy, runtime, and catalog identity reproduce the same result?
+- **Explainability**: do recommendations include evidence, exclusions, uncovered goals, and unknowns?
+- **Durable desired state**: can the approved selection be recorded independently of the agent conversation?
+- **Preview before change**: can the system validate the manifest and produce an exact plan without changing the target?
+- **Source and compatibility evidence**: are provenance, risk, host support, and distribution boundaries explicit?
 
 ## When Agentic Awesome Skills is a good fit
 
-- You want one library that spans planning, coding, debugging, testing, security, infra, product, and marketing.
-- You care about installation paths and practical onboarding, not only catalog size.
-- You want bundles and workflows to reduce choice overload.
-- You need compatibility across more than one AI coding assistant.
+- You use Codex or Claude and want a small, policy-controlled stack for a real project.
+- You want local search and recommendation without repository scanning or remote-model calls by AAS.
+- You need a reviewable `aas-stack.json` and CLI validation and planning before target changes.
+- You also value a broad catalog and multiple distribution options around the Core workflow.
 
 ## When a smaller curated repo may be better
 
-- You only want a narrow shortlist of highly curated or vendor-focused skills.
-- You prefer reviewing fewer files even if coverage is lower.
-- You are evaluating alternatives for a single tool and want a quick comparison first.
+- You only want a fixed, vendor-maintained shortlist and do not need project-aware composition.
+- You prefer selecting and invoking individual skills manually.
+- Your host does not yet have an AAS Core adapter and direct distribution is sufficient.
 
 ## Start with a tool-specific guide
 
@@ -32,7 +35,7 @@ Agentic Awesome Skills is built for the first path: broad coverage, multiple sup
 - [`codex-cli-skills.md`](codex-cli-skills.md)
 - [`gemini-cli-skills.md`](gemini-cli-skills.md)
 
-## Compare broad vs curated libraries
+## Compare catalogs and distribution models
 
 - [`agentic-awesome-skills-vs-awesome-claude-skills.md`](agentic-awesome-skills-vs-awesome-claude-skills.md)
 - [`best-claude-code-skills-github.md`](best-claude-code-skills-github.md)
@@ -40,6 +43,6 @@ Agentic Awesome Skills is built for the first path: broad coverage, multiple sup
 
 ## Quick recommendation
 
-- Choose **Agentic Awesome Skills** if you want a large, installable, multi-tool library with onboarding help.
-- Choose a smaller curated repo if you want fewer choices and more editorial filtering.
-- If you are unsure, install this repo first, start with [`bundles.md`](bundles.md), and then compare alternatives once you know your preferred workflow.
+- Choose **AAS Core** if you want local, deterministic, explainable skill-stack composition from an explicit project profile to a preview plan.
+- Choose direct distribution if you already know the exact skills you want or your host does not support the Core path.
+- Choose a smaller curated repository if a fixed editorial shortlist matters more than project-specific recommendation and durable desired state.

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

@@ -1,18 +1,18 @@
 # Best Claude Code Skills on GitHub
 
-If you are looking for the **best Claude Code skills on GitHub**, there is no single perfect repository for every user. The right choice depends on whether you want breadth, curation, or official reference material.
+If you are looking for the **best Claude Code skills on GitHub**, there is no single perfect repository for every user. The right choice depends on whether you want deterministic project-level composition, curated discovery, or official reference material.
 
-## Best overall installable library
+## Best for deterministic project stacks
 
 ### 1. [sickn33/agentic-awesome-skills](https://github.com/sickn33/agentic-awesome-skills)
 
-Best for teams and individual developers who want one large installable library with onboarding docs, bundles, workflows, and support for more than just Claude Code.
+Best for teams and individual developers who want Claude to send an explicit project profile to a local, read-only MCP, receive an explainable recommendation, and produce a reviewable `aas-stack.json` before CLI validation and planning.
 
 Choose this if you want:
 
-- a broad library you can install and use immediately;
-- bundles and workflows to reduce choice overload;
-- compatibility beyond Claude Code alone.
+- local deterministic recommendation with explicit policy and evidence;
+- durable desired state plus immutable plan preview;
+- a broad catalog, plugins, bundles, workflows, and direct distribution around Core.
 
 ## Best curated shortlist
 
@@ -52,11 +52,11 @@ Choose this if you want:
 
 ## How to choose quickly
 
-- Choose **Agentic Awesome Skills** if you want the most practical install-and-use path.
+- Choose **Agentic Awesome Skills** if you want project-specific composition and a reviewable lifecycle before any target change.
 - Choose **VoltAgent Awesome Agent Skills** if you want the strongest curated shortlist.
 - Choose **anthropics/skills** if official vendor reference matters most.
 - Choose **karanb192/awesome-claude-skills** if you want a smaller community-first Claude library.
 
 ## Recommended next step
 
-If you want to get productive quickly, install [Agentic Awesome Skills](https://github.com/sickn33/agentic-awesome-skills) and start with [`claude-code-skills.md`](claude-code-skills.md) plus [`bundles.md`](bundles.md).
+If you want a project-specific stack, start with the [AAS Core guide](aas-core.md) and [`claude-code-skills.md`](claude-code-skills.md). Use direct distribution only when you already know the exact skills or fixed plugin you want.

package/bundled-skills/docs/users/best-cursor-skills-github.md

@@ -1,12 +1,12 @@
 # Best Cursor Skills on GitHub
 
-If you are searching for the **best Cursor skills on GitHub**, the best option depends on whether you want a broad installable library, a curated discovery list, or a smaller community collection.
+If you are searching for the **best Cursor skills on GitHub**, the best option depends on whether you want an agent-composed project stack, a broad direct distribution, a curated discovery list, or a smaller community collection. Cursor does not yet have a native AAS Core adapter, so its current AAS path is direct distribution rather than the Codex/Claude Core workflow.
 
-## Best overall installable library
+## Broadest AAS direct distribution for Cursor
 
 ### 1. [sickn33/agentic-awesome-skills](https://github.com/sickn33/agentic-awesome-skills)
 
-Best for developers who want one repository they can install into Cursor and keep using across frontend, backend, testing, infra, product, and growth work.
+Best for developers who want the AAS catalog delivered into Cursor across frontend, backend, testing, infra, product, and growth work while treating AAS Core as the repository's primary product for supported agent clients.
 
 Choose this if you want:
 
@@ -52,11 +52,11 @@ Choose this if you want:
 
 ## How to choose quickly
 
-- Choose **Agentic Awesome Skills** if you want the strongest install-and-use path for real day-to-day Cursor work.
+- Choose **Agentic Awesome Skills** if you want its broad supporting catalog and direct Cursor distribution today, with a clear boundary that this is not yet the native AAS Core path.
 - Choose **VoltAgent Awesome Agent Skills** if you want curation first and installation later.
 - Choose **Ai-Agent-Skills** if you want a smaller installable library.
 - Choose **cursor-skills** if you want the most Cursor-specific starting point.
 
 ## Recommended next step
 
-If your goal is to start working in Cursor today, install [Agentic Awesome Skills](https://github.com/sickn33/agentic-awesome-skills) and continue with [`cursor-skills.md`](cursor-skills.md).
+If your goal is to start working in Cursor today, use the direct distribution guidance in [`cursor-skills.md`](cursor-skills.md). For the primary product model and current Codex/Claude path, read the [AAS Core guide](aas-core.md).