opencode-skills-collection 4.0.4 → 4.0.6

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 boundary that exposes the complete catalog, validates exact skill IDs selected by the coding agent from an explicit project profile, and produces an immutable preview plan, backed by 1,968+ 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,969+ 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 an agent-selected Core stack 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,969+ skills from the skills directory
 
 ## When to Update
 

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

@@ -0,0 +1,182 @@
+# AAS Core: Agent-Owned Skill Stacks
+
+AAS Core lets Codex and Claude search and read the complete local AAS catalog, preserve their exact skill selection as reproducible desired state, and preview a validated plan before any target change.
+
+> **The agent inspects and chooses. AAS records and validates. You control.**
+
+The primary durable artifact is [`aas-stack.json`](#the-stack-manifest). It records the exact skill IDs chosen by the coding agent; it is not the output of a Core ranking system. An audit-enabled flow can also persist a separate canonical `aas-selection-evidence.json` sidecar. The local MCP is a read-only catalog, composition, and evidence boundary; a client or the `aas` CLI performs persistence, the CLI validates and plans, and Workbench is a browser-local review surface.
+
+## How it works
+
+```text
+your project
+  -> Codex or Claude inspects the repository
+  -> agent searches and reads the complete local AAS catalog
+  -> agent chooses the exact skill IDs
+  -> compose_stack validates and returns the manifest in memory
+  -> client or CLI persists aas-stack.json and optional evidence sidecar
+  -> you review the artifacts
+  -> aas stack validate
+  -> aas stack plan (preview; no skill changes)
+```
+
+AAS MCP does not scan the repository and does not decide which skills are best. Codex or Claude uses its own project understanding and judgment. All 1,968 skills in the current catalog remain individually searchable, readable, selectable, and usable; missing or incomplete metadata never makes a skill ineligible. Core has no semantic policy that favors a small stack, while every stack manifest has an explicit technical maximum of 128 skills.
+
+## Configure the local MCP
+
+> **Release boundary:** AAS Core landed after release 14.6.0. Use an exact Core-capable release rather than an unreviewed moving tag.
+
+```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 choose the stack
+
+Give the agent the desired outcome and constraints, and leave selection judgment with the agent:
+
+```text
+Inspect this repository. Search and read the complete local AAS catalog, then
+enumerate the project's primary capability areas. For each capability, run a
+focused search, paginate or refine until you find plausible candidates, and use
+get_skill to compare multiple candidates when available. Select at least one
+non-redundant valid skill for every covered capability. Explicitly report as a
+catalog gap any capability for which the catalog has no valid match. At minimum,
+evaluate architecture/runtime, languages/frameworks, domain behavior,
+data/storage, external integrations, testing/quality, security/privacy,
+user experience/accessibility when user-facing, deployment/operations, and
+maintenance workflow; mark dimensions not applicable instead of silently
+omitting them. Do not stop at the first few matches or optimize for the smallest
+stack. Core imposes no semantic small-stack policy; the manifest format has a
+technical maximum of 128 selected skills.
+Only then use compose_stack with a project profile to validate the exact IDs and
+return a schema 2 manifest in memory, and use inspect_stack before presenting
+it. Do not install or apply anything.
+```
+
+This capability-coverage contract is delivered to supported clients in the MCP
+`initialize` instructions and reinforced by the tool descriptions. It is an
+agent obligation, not a Core ranking or eligibility policy: Core still accepts
+and preserves any structurally valid set of catalog IDs and never chooses for the
+agent.
+
+The local MCP exposes these read-only tools:
+
+- `search_skills` — retrieve deterministic, paginated matches from every skill in the verified local catalog without scores or ranking;
+- `get_skill` — inspect one skill and optionally read its full content;
+- `compose_stack` — validate the agent-selected IDs and return the stack manifest in memory without writing it;
+- `inspect_stack` — validate and explain a proposed manifest;
+- `diff_stack` — compare manifests using verified local catalogs.
+- `export_selection_evidence` — combine the server-recorded session trace with an agent-declared capability ledger and an already composed and inspected manifest;
+- `inspect_selection_evidence` — validate the sidecar's structure, digests, catalog identity, manifest binding, and factual cross-references without judging skill suitability.
+
+Search results use a stable catalog order and contain no relevance score, recommendation, or preferred ordering. Codex or Claude evaluates the returned candidates semantically and chooses exact IDs. Metadata returned by search or inspection is informational context; Core does not use risk, source, setup, compatibility, review, or evidence metadata to rank, exclude, or disable a skill.
+
+MCP calls do not install or remove skills, update catalogs, edit host configuration, persist a stack, or apply it. Full skill text is returned only when requested and remains marked as untrusted content.
+
+## The stack manifest
+
+`aas-stack.json` records agent-chosen desired state:
+
+```json
+{
+  "schemaVersion": 2,
+  "name": "project-stack",
+  "catalog": {
+    "package": "agentic-awesome-skills",
+    "version": "<version>",
+    "integrity": "sha256-..."
+  },
+  "targets": [{ "host": "codex", "scope": "project" }],
+  "profile": {
+    "goals": ["build", "test"],
+    "projectType": "web application",
+    "languages": ["typescript"],
+    "frameworks": ["react"],
+    "constraints": ["preview only"]
+  },
+  "skills": [
+    { "id": "example-skill" }
+  ]
+}
+```
+
+The manifest pins catalog identity, targets, the project profile, and exact agent-selected skill IDs. It intentionally has no selection policy: Core validates identity and structure but does not overrule the agent's choice because metadata is missing, incomplete, or cautionary.
+
+`compose_stack` produces this manifest only in MCP process memory. Persist it through the client or the CLI. Audit-enabled CLI flows publish `aas-stack.json` together with `aas-selection-evidence.json` in the requested `artifact-dir`, keeping the sidecar separate from the desired-state manifest.
+
+## Selection evidence sidecar
+
+`aas-selection-evidence.json` makes the selection process auditable without moving semantic judgment into Core. It binds a path-safe project fingerprint, catalog identity, manifest digest, the agent-declared ten-dimension capability ledger, capability-to-skill mappings, and the actual `search_skills`, `get_skill`, `compose_stack`, and `inspect_stack` facts recorded by that MCP server session. `export_selection_evidence` takes the ledger but obtains the trace from server-owned session state; the caller cannot supply a replacement historical trace. `inspect_selection_evidence` performs structural and factual validation only.
+
+The trace records effective search query/cursor/limit values and returned IDs, opened skill IDs, exact compose IDs, inspect outcomes, safe error codes, deterministic retry attempts, and canonical input/output byte counts. Monotonic call durations are recorded separately outside the evidence digest. Client name and version come from MCP initialization when valid and available; model identity is omitted unless a trusted protocol surface supplies it.
+
+The sidecar does not prove that a capability is correctly interpreted, that a selected skill is best, or that semantic coverage is sufficient. Repository evidence references are relative and contain no file contents or absolute paths. Search queries are recorded verbatim as factual trace data, so do not put secrets, credentials, private source text, or personal data in `search_skills` queries. Runtime observations that are not deterministic are not part of the canonical evidence digest.
+
+The digest makes later edits detectable but is not a signature or cross-session identity attestation. The non-falsification guarantee is narrower: callers cannot inject or replace historical tool calls through `export_selection_evidence`; a standalone inspector can verify structure and digests, not who produced the file.
+
+To publish the manifest and exported sidecar without exposing a one-file intermediate state, use a new artifact directory:
+
+```bash
+aas stack create \
+  --selection /absolute/path/to/agent-selection.json \
+  --evidence /absolute/path/to/exported-evidence.json \
+  --artifact-dir /absolute/path/to/new-audit-artifact \
+  --require-evidence
+```
+
+The destination must not already exist. The CLI validates both artifacts, writes private staged files named `aas-stack.json` and `aas-selection-evidence.json`, synchronizes them, and publishes the complete directory with one rename. The original `stack create --selection ... --out ...` manifest-only path remains supported.
+
+## 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 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` remain experimental and require explicit opt-in.
+
+## Privacy, trust, and limits
+
+- MCP is local stdio, process-per-session, read-only, offline-capable, and contains no model credentials or telemetry.
+- Codex or Claude owns semantic selection. Different agents or project observations may reasonably produce different stacks.
+- Catalog integrity and manifest validation are deterministic; skill suitability is an agent judgment, not a Core score.
+- Core does not impose a semantic skill-count target. The technical manifest maximum is 128 skills, and every one of the current catalog's 1,968 skills remains individually searchable, readable, selectable, and usable. Metadata remains visible but informational.
+- Evidence exports include raw `search_skills` queries; keep secrets and sensitive project content out of those queries.
+- Catalog updates and runtime changes are explicit. There is no resident daemon or implicit auto-update.
+- Skill prose is untrusted content and does not gain instruction authority by being returned through MCP.
+
+## Other ways to use the catalog
+
+Direct installs, specialized plugins, bundles, workflows, and the legacy installer remain available. These surfaces distribute or curate catalog content; AAS Core adds complete local access, durable agent-owned selection, manifest validation, 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 complete catalog access with agent-owned reproducible selection or an editorial discovery list.
 
 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 | Complete local catalog access, agent-owned selection, 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 inspect a project and choose exact IDs from the full catalog | 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 search and read a complete catalog through a local, read-only MCP and own the selection.
+- 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 agent-selected 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 agent-owned project selection with reproducible state or manual catalog browsing.
 
-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, searches and reads the complete local catalog, chooses exact skill IDs, and uses `compose_stack` to pin them in `aas-stack.json`. The CLI validates that agent-owned state 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?
+- **Agent-owned selection**: can the coding agent search and read every skill before choosing exact IDs?
+- **Reproducibility**: can the chosen IDs be pinned to a catalog identity and replayed without a metadata eligibility gate?
+- **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 the agent to choose a focused stack for a real project.
+- You want complete local search and inspection 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 complete local catalog access, agent-owned selection, reproducible stack composition, and 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 complete catalog access 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 complete catalog access with Claude-owned selection, curated discovery, or official reference material.
 
-## Best overall installable library
+## Best for agent-selected 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 inspect a project, search and read the complete catalog through a local read-only MCP, choose exact IDs, 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.
+- complete local catalog access with Claude-owned selection;
+- 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.