diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index aed8e81d..47093861 100644 --- a/.github/MAINTENANCE.md +++ b/.github/MAINTENANCE.md @@ -98,6 +98,14 @@ Before ANY commit that adds/modifies skills, run the chain: ```bash npm run audit:maintainer ``` + When you are reducing legacy `risk: unknown` debt, use this sequence instead of hand-editing large batches: + ```bash + npm run audit:skills + npm run sync:risk-labels -- --dry-run + npm run sync:risk-labels + npm run sync:repo-state + ``` + `sync:risk-labels` is intentionally conservative. It should handle only the obvious subset; the ambiguous tail still needs maintainer review. 4. **COMMIT GENERATED FILES**: ```bash @@ -107,6 +115,7 @@ Before ANY commit that adds/modifies skills, run the chain: > 🔴 **CRITICAL for direct `main` work**: If you skip this on maintainer work that lands directly on `main`, CI will fail with "Detected uncommitted changes". > For contributor PRs, do **not** include derived registry artifacts. CI blocks direct edits to those files and previews drift separately. > See [`docs/maintainers/ci-drift-fix.md`](../docs/maintainers/ci-drift-fix.md) for details. + > `main` may still auto-commit canonical artifacts with `[ci skip]`, but only within the generated-files contract. If the sync leaves unmanaged drift, the workflow must fail instead of pushing a partial fix. ### B. When You Merge a PR (Step-by-Step) diff --git a/CHANGELOG.md b/CHANGELOG.md index 41ef2776..e207ce03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- **Risk maintenance workflow**: expanded the legacy `risk:` cleanup flow so maintainers can sync explicit high-confidence `none`, `safe`, `critical`, and `offensive` labels from audit suggestions, including auto-inserting the required `AUTHORIZED USE ONLY` notice when a legacy skill is promoted to `offensive`. +- **Contributor and maintainer policy docs**: clarified that automated validation is necessary but not sufficient for skill changes, documented the manual logic review requirement, and aligned maintainer guidance around the `audit:skills` -> `sync:risk-labels` -> `sync:repo-state` loop. +- **Web app and CI docs**: aligned public documentation with the current static Pages deploy, local-only maintainer sync flow, browser-local save behavior, web-app coverage checks, and the stricter release/CI contract now used on `main`. + ## [9.1.0] - 2026-03-28 - "SaaS Multi-Tenancy and Three.js r183 Refresh" > Installable skill library update for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and related AI coding assistants. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3ba9048..9b2752fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -246,6 +246,8 @@ Passing `npm run validate` or `skill-review` is not enough on its own for skill - obvious failure modes, unsafe assumptions, and user-facing edge cases, - whether the declared `risk:` level still matches the actual behavior. +Submitting `risk: unknown` is still acceptable for genuinely legacy or not-yet-classified content. Maintainers may later use `npm run audit:skills` and `npm run sync:risk-labels` to reconcile high-confidence legacy labels without asking contributors to regenerate catalog artifacts in their PRs. + For **docs / workflows / infra changes**: ```bash diff --git a/README.md b/README.md index 65d8530e..a39348ab 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,7 @@ Install once; then use Starter Packs in [docs/users/bundles.md](docs/users/bundl # Default: ~/.gemini/antigravity/skills (Antigravity global). Use --path for other locations. npx antigravity-awesome-skills ``` + The npm installer uses a shallow clone by default so first-run installs stay lighter than a full repository history checkout. 2. **Verify**: ```bash @@ -273,6 +274,8 @@ If you want a faster answer than "browse all 1,331+ skills", start with a tool-s These skills are continuously reviewed and hardened, but the collection is not "safe by default". They are instructions and examples that can include risky operations by design. - Runtime hardening now protects the `/api/refresh-skills` mutation flow (method/host checks and optional token gate) before any repo mutation. +- The published GitHub Pages catalog runs in static public-catalog mode, so the maintainer-only `/api/refresh-skills` flow is hidden in production unless you are using the local Vite dev server with the explicit sync flag. +- Skill saves in the web UI are intentionally browser-local today. Optional Supabase configuration is read-only and should not be treated as a shared write path or authoritative leaderboard. - Markdown rendering in the web app avoids raw HTML passthrough (`rehype-raw`) and follows safer defaults for skill content display. - A repo-wide `SKILL.md` security scan checks for high-risk command patterns (for example `curl|bash`, `wget|sh`, `irm|iex`, command-line token examples) with explicit allowlisting for deliberate exceptions. - Pull requests that touch `SKILL.md` files now also run an automated `skill-review` GitHub Actions check, so contributors and maintainers get a second pass focused on skill structure and review quality. @@ -521,6 +524,8 @@ npm run app:dev That will copy the generated skill index into `apps/web-app/public/skills.json`, mirror the current `skills/` tree into `apps/web-app/public/skills/`, and start the Vite development server. +On the hosted GitHub Pages site, the same app runs as a static public catalog: dev-only sync controls stay hidden there, and save/star actions remain local to the browser. + **Hosted online:** The same app is available at [https://sickn33.github.io/antigravity-awesome-skills/](https://sickn33.github.io/antigravity-awesome-skills/) and is deployed automatically on every push to `main`. To enable it once: **Settings → Pages → Build and deployment → Source: GitHub Actions**. ## Contributing @@ -531,6 +536,7 @@ That will copy the generated skill index into `apps/web-app/public/skills.json`, - Validate with `npm run validate` before opening a PR. - Keep community PRs source-only: do not commit generated registry artifacts like `CATALOG.md`, `skills_index.json`, or `data/*.json`. - If your PR changes `SKILL.md`, expect the automated `skill-review` check on GitHub in addition to the usual validation and security scans. +- If your PR changes skills or risky guidance, manual logic review is still required even when the automated checks are green. ## Community diff --git a/apps/web-app/README.md b/apps/web-app/README.md index 7a9da678..a959984e 100644 --- a/apps/web-app/README.md +++ b/apps/web-app/README.md @@ -8,6 +8,7 @@ This app is the static catalog and skill browser for `antigravity-awesome-skills - Renders home, category, bundle, and skill detail routes for the published library. - Adds SEO metadata, sitemap-backed URLs, and static asset resolution for GitHub Pages. - Supports a local-only "refresh skills" developer flow through the Vite dev server plugin. +- Treats save/star interactions as browser-local UX, even when optional read-only Supabase counts are configured. ## Architecture @@ -19,12 +20,18 @@ This app is the static catalog and skill browser for `antigravity-awesome-skills The app intentionally assumes a static hosting model in production. Anything that depends on `/api/*` is development-only unless it is backed by a real serverless or backend implementation. +The hosted Pages build should be understood as a public catalog, not a control plane: + +- `Sync Skills` is a maintainer/development affordance and must stay hidden unless `VITE_ENABLE_SKILLS_SYNC=true`. +- save/star interactions are local-only unless the project gains a real backend write contract with abuse controls and deployment support. + ## Development From the repo root: ```bash npm run app:install +npm run app:test:coverage npm run app:dev ``` @@ -79,6 +86,7 @@ The high-level maintainer flow is: From the repo root: ```bash +npm run app:test:coverage cd apps/web-app && npm run test cd apps/web-app && npm run test:coverage npm run test @@ -86,6 +94,8 @@ npm run test The repo-level test suite also contains workflow and documentation guardrails outside `src/`, so changes to this app can fail tests in `tools/scripts/tests/` even when the React code itself is untouched. +`main`/release CI also runs `npm run app:test:coverage`, so coverage thresholds are part of the real shipping contract for this app rather than an optional local extra. + ## Troubleshooting - If the app shows stale catalog data, run `npm run sync:web-assets` from the repo root and rebuild. diff --git a/docs/contributors/quality-bar.md b/docs/contributors/quality-bar.md index 3505548e..ec91b02c 100644 --- a/docs/contributors/quality-bar.md +++ b/docs/contributors/quality-bar.md @@ -64,6 +64,8 @@ Use `npm run audit:skills` when you need a repo-wide report that goes beyond sch - which skills are missing examples or limitations, - and which skills have the highest concentration of warnings/errors. +Maintainers can pair that report with `npm run sync:risk-labels` for conservative legacy cleanup. That sync only rewrites `risk: unknown` when the suggested label is explicit and high-confidence enough to automate safely, and it preserves the contributor-facing rule that new or uncertain submissions can still start as `unknown`. + --- ## Support Levels @@ -94,6 +96,7 @@ Notes: - `npm run validate` is the operational contributor gate. - `npm run audit:skills` is the maintainer-facing compliance/usability report for the full library. +- `npm run sync:risk-labels` is a maintainer cleanup tool for high-confidence legacy `risk:` fixes. - `npm run security:docs` is required for command-heavy or risky skill content. - PRs that touch `SKILL.md` also get an automated `skill-review` GitHub Actions check. - Skill changes and risky guidance still require a manual logic review before merge, even when the automated gates pass. diff --git a/docs/maintainers/audit.md b/docs/maintainers/audit.md index 574e0926..808ea133 100644 --- a/docs/maintainers/audit.md +++ b/docs/maintainers/audit.md @@ -17,7 +17,9 @@ This document summarizes the repository coherence audit performed after the `app ### 1. Conteggi - `README.md`, `package.json`, and generated artifacts are aligned to the current collection size. -- `npm run sync:all` and `npm run catalog` are the canonical commands for keeping counts and generated files synchronized. +- `npm run sync:repo-state` is the canonical maintainer command for keeping counts, generated files, contributors, and tracked web assets synchronized on local `main`. +- `npm run sync:release-state` is the canonical release-facing variant when you want the same sync without the contributor refresh step. +- `npm run sync:all` remains a legacy alias for the core chain, not the full maintainer sync surface. ### 2. Validazione skill @@ -39,6 +41,8 @@ This document summarizes the repository coherence audit performed after the `app - 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. ### 3. Riferimenti incrociati @@ -76,6 +80,7 @@ npm run validate # validazione skill (soft) npm run validate:strict # hardening / diagnostic pass npm run audit:skills # audit completo per skill con finding codes e 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 @@ -85,4 +90,5 @@ npm test # suite test ## Issue aperte / 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. - Keep translated docs aligned in a separate pass after the canonical English docs are stable. diff --git a/docs/maintainers/ci-drift-fix.md b/docs/maintainers/ci-drift-fix.md index f31da309..8851ca19 100644 --- a/docs/maintainers/ci-drift-fix.md +++ b/docs/maintainers/ci-drift-fix.md @@ -1,6 +1,6 @@ # CI Drift Fix Guide -**Problem**: The failing job is caused by uncommitted changes detected in `README.md`, `skills_index.json`, or catalog files after the update scripts run. +**Problem**: The failing job is caused by tracked drift left behind after the canonical sync steps run on `main`. **Error**: @@ -9,7 +9,16 @@ ``` **Cause**: -Scripts like `tools/scripts/generate_index.py`, `tools/scripts/update_readme.py`, and `tools/scripts/build-catalog.js` modify `README.md`, `skills_index.json`, `data/catalog.json`, `data/bundles.json`, `data/aliases.json`, and `CATALOG.md`. The workflow expects these files to have no changes after the scripts run. Any differences mean the committed repo is out-of-sync with what the generation scripts produce. +The canonical sync contract is broader than just the root registry files. Scripts such as `generate_index.py`, `update_readme.py`, `build-catalog.js`, `setup_web.js`, and plugin sync helpers can legitimately update: + +- `README.md` +- `CATALOG.md` +- `skills_index.json` +- `data/*.json` +- tracked web assets under `apps/web-app/public/` +- generated plugin metadata and plugin-safe copies + +The workflow expects the repository to be clean after those sync steps finish. Any remaining tracked or unmanaged changes mean `main` is out of sync with what the generation pipeline actually produces. ## Pull Requests vs Main @@ -18,32 +27,36 @@ Scripts like `tools/scripts/generate_index.py`, `tools/scripts/update_readme.py` ## How to Fix on `main` -1. Run the **FULL Validation Chain** locally: +1. Run the canonical maintainer sync locally: ```bash - npm run chain - npm run catalog + npm run sync:repo-state ``` -2. Check for changes: +2. Check whether anything is still dirty: ```bash git status git diff ``` -3. Commit and push any updates: +3. If the sync produced only canonical/generated changes, stage and commit them. Prefer the generated-files contract instead of a hand-maintained file list: + ```bash - git add README.md skills_index.json data/skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md - git commit -m "chore: sync generated registry files" + node tools/scripts/generated_files.js --include-mixed + git add $(node tools/scripts/generated_files.js --include-mixed) + git commit -m "chore: sync canonical artifacts" git push ``` +4. If `sync:repo-state` leaves unrelated or unmanaged drift, stop and inspect it. The bot on `main` is only allowed to push the canonical/generated subset; anything else should fail the workflow instead of being silently auto-committed. + ## Maintainer guidance for PRs - Validate the source change, not the absence of committed generated artifacts. - If a contributor PR includes direct edits to `CATALOG.md`, `skills_index.json`, or `data/*.json`, ask them to drop those files from the PR or remove them while refreshing the branch. - If merge conflicts touch generated registry files, keep `main`'s version for those files and let `main` auto-sync the final generated artifact set after merge. +- If CI on `main` later creates a bot commit with `[ci skip]`, that is expected only for the canonical/generated subset. It is not a license to push arbitrary extra drift. **Summary**: Use generator drift as a hard failure only on `main`. On PRs, the contract is simpler: source-only changes are reviewed, generated output is previewed, and `main` produces the final canonical artifact set. diff --git a/docs/maintainers/merging-prs.md b/docs/maintainers/merging-prs.md index 888ade99..16a9e332 100644 --- a/docs/maintainers/merging-prs.md +++ b/docs/maintainers/merging-prs.md @@ -8,6 +8,7 @@ - The PR must show as **Merged**, not Closed. That way the contributor appears in the repo’s contribution graph and the PR is clearly linked to the merge commit. - Do **not** integrate a PR by squashing locally, pushing to `main`, and then closing the PR. That would show "Closed" and the contributor would not get proper credit. - Before merging, require the normal PR checks from [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) to be green. If the PR touches `SKILL.md`, also require the separate [`skill-review` workflow](../../.github/workflows/skill-review.yml) to pass. +- For PRs that touch `SKILL.md` or risky guidance, require a real manual logic review in addition to the automated checks. Confirm the instructions, failure modes, and `risk:` label make sense before merging. ## If the PR has merge conflicts @@ -19,6 +20,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. ### Steps (maintainer resolves conflicts on the contributor’s branch) diff --git a/docs/maintainers/release-process.md b/docs/maintainers/release-process.md index a5e10362..bf3cdbe1 100644 --- a/docs/maintainers/release-process.md +++ b/docs/maintainers/release-process.md @@ -17,7 +17,13 @@ This is the maintainer playbook for cutting a repository release. Historical rel npm run release:preflight ``` -This preflight now runs the deterministic `sync:release-state` flow, refreshes the tracked web assets in `apps/web-app/public`, executes the local test suite, runs the web-app build, and performs `npm pack --dry-run --json` so release tags are validated against the same artifact path used later in CI. +This preflight now runs the deterministic `sync:release-state` flow, refreshes the tracked web assets in `apps/web-app/public`, executes the local test suite, installs the web-app dependencies, runs the web-app build, and performs `npm pack --dry-run --json` so release tags are validated against the same artifact path used later in CI. + +The active CI/release contract also expects: + +- Python dependencies to come from `tools/requirements.txt`, +- the web app coverage job (`npm run app:test:coverage`) to stay green, +- and `npm run security:docs` to pass without relying on non-blocking audit warnings. 2. Mandatory documentation hardening (repo-wide SKILL.md security scan): @@ -41,6 +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. 5. Prepare the release commit and tag locally: @@ -73,7 +80,7 @@ npm publish ``` Normally this still happens via the existing GitHub release workflow after the GitHub release is published. -That workflow now reruns `sync:release-state`, refreshes tracked web assets, fails on canonical drift via `git diff --exit-code`, executes tests and docs security checks, builds the web app, and dry-runs the npm package before `npm publish`. +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`. ## Canonical Sync Bot @@ -81,6 +88,7 @@ That workflow now reruns `sync:release-state`, refreshes tracked web assets, fai - PRs stay source-only. - After merge, the `main` workflow may commit generated canonical files directly to `main` with `[ci skip]`. +- Those bot commits still skip CI, so the sync contract must stay narrow and predictable: only canonical/generated files may be staged, and any unmanaged drift must fail the workflow instead of being silently pushed. - The bot commit is only allowed to stage files resolved from `tools/scripts/generated_files.js --include-mixed`. - If repo-state sync leaves any unmanaged tracked or untracked drift, the workflow fails instead of pushing a partial fix. - The scheduled hygiene workflow follows the same contract and shares the same concurrency group so only one canonical sync writer runs at a time. diff --git a/docs/maintainers/security-findings-triage-2026-03-15.md b/docs/maintainers/security-findings-triage-2026-03-15.md index d3d7d362..c6dd13c6 100644 --- a/docs/maintainers/security-findings-triage-2026-03-15.md +++ b/docs/maintainers/security-findings-triage-2026-03-15.md @@ -1,5 +1,7 @@ # Security Findings Triage (2026-03-15) +Maintainer note: later fixes changed the status of several findings after this baseline snapshot. See [`security-findings-triage-2026-03-29-addendum.md`](security-findings-triage-2026-03-29-addendum.md) before using this file as the current source of truth. + - Baseline: `origin/main@226f10c2a62fc182b4e93458bddea2e60f9b0cb9` - Input CSV was treated as triage input only, not as ground truth. - Status meanings: `still present and exploitable`, `still present but low practical risk`, `obsolete/not reproducible on current HEAD`, `duplicate of another finding`. diff --git a/docs/maintainers/security-findings-triage-2026-03-29-addendum.md b/docs/maintainers/security-findings-triage-2026-03-29-addendum.md new file mode 100644 index 00000000..9f66aba6 --- /dev/null +++ b/docs/maintainers/security-findings-triage-2026-03-29-addendum.md @@ -0,0 +1,45 @@ +# Security Findings Triage Addendum (2026-03-29) + +This addendum updates the 2026-03-15 baseline after the follow-up hardening +work shipped on `main`. + +## Corrected / Updated Findings + +- Finding `1` / `7` (`tools/scripts/sync_microsoft_skills.py`) + The Microsoft sync path now constrains filesystem writes and copied inputs to + safe in-repo targets. The plugin-skill discovery path also skips symlinked + `SKILL.md` files instead of trusting them. Regression coverage lives in + `tools/scripts/tests/test_sync_microsoft_skills_security.py`. + +- Finding `18` / `29` (`tools/scripts/validate_skills.py`, + `tools/scripts/generate_index.py`) + Frontmatter parsing now rejects non-mapping YAML payloads cleanly and handles + empty/frontmatter-edge cases without crashing downstream validation or index + generation. Regression coverage lives in + `tools/scripts/tests/test_frontmatter_parsing_security.py`. + +- Finding `19` + The web app no longer exposes shared frontend writes for skill saves/stars by + default. The current behavior is browser-local save state with optional + read-only remote counts, so the old "anonymous Supabase writes allow skill + star tampering" assessment is no longer the active behavior on current HEAD. + +- Findings `16` / `17` + The `refresh-skills` plugin remains a local development surface, but the + published GitHub Pages app now runs in static public-catalog mode and does not + expose the maintainer sync CTA in production. Treat the residual plugin logic + as local dev hardening scope, not a public production endpoint. + +- Finding `33` + The Office unpack helpers no longer call `extractall()` blindly. They now + validate archive member paths and reject traversal/symlink-style entries + before extraction. Regression coverage lives in + `tools/scripts/tests/test_office_unpack_security.py`. + +## Maintainer Guidance + +- Keep the 2026-03-15 file as the historical baseline snapshot. +- Use this addendum plus the newer regression tests when deciding which + findings are still actionable on current HEAD. +- If a future triage refresh is produced, fold these corrections into the next + full summary instead of re-copying the original counts unchanged. diff --git a/docs/users/faq.md b/docs/users/faq.md index 58ad662c..f057a3aa 100644 --- a/docs/users/faq.md +++ b/docs/users/faq.md @@ -81,6 +81,13 @@ For a concrete example (including pseudo‑code) see: The skill files themselves are stored locally on your computer, but your AI assistant needs an internet connection to function. +### Does the hosted web app write anything back to the repository? + +No. The public site is a static GitHub Pages deploy. + +- The maintainer `Sync Skills` flow is local-development only and is not a public production endpoint. +- Browser save/star interactions are intentionally local-first for now. Until the project has a real backend contract, treat them as browser-local state rather than shared repository writes. + --- ## Security & Trust @@ -123,6 +130,8 @@ If you get a 404 from npm, use: `npx github:sickn33/antigravity-awesome-skills` git clone https://github.com/sickn33/antigravity-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. + **Tool-specific paths:** - Claude Code: `.claude/skills/` @@ -148,6 +157,28 @@ This repository also includes repo-local plugin metadata for Codex: That path exposes the new plugin-safe Codex root plugin plus generated bundle plugins. For the full explanation, read [plugins.md](plugins.md). +### Why do I not see `Sync Skills` on the hosted website? + +Because the public site is a static GitHub Pages catalog, not a maintainer control surface. + +`Sync Skills` is only meant for local maintainer/development runs behind the Vite dev server, and it stays hidden unless the local environment explicitly enables it. + +### What does `Public catalog mode` mean? + +It means you are looking at the published static catalog build. + +In that mode: + +- catalog browsing and skill detail pages work normally +- dev-only `/api/refresh-skills` behavior is not available +- anything that would require a backend or mutable server state is intentionally disabled or reduced to local-only behavior + +### Are saves/stars global or just local? + +Right now they are local to your browser. + +The app may show optional read-only community counts when configured, but clicking save/star does not create a shared server-side vote. Until the project ships a real backend write contract with abuse controls, treat saves as a personal local bookmark signal. + ### What does `plugin-safe` mean? Plugin-safe means the published Claude Code and Codex plugins only include the subset of skills that is ready for marketplace-style distribution. diff --git a/docs/users/getting-started.md b/docs/users/getting-started.md index 9b661cf0..6259fa24 100644 --- a/docs/users/getting-started.md +++ b/docs/users/getting-started.md @@ -33,6 +33,7 @@ npx antigravity-awesome-skills ``` This clones to `~/.gemini/antigravity/skills` by default. Use `--cursor`, `--claude`, `--gemini`, `--codex`, or `--kiro` to install for a specific tool, or `--path ` for a custom location. Run `npx antigravity-awesome-skills --help` for details. +The installer uses a shallow clone by default so you get the current library without paying for the full git history on first install. If you see a 404 error, use: `npx github:sickn33/antigravity-awesome-skills` @@ -116,11 +117,13 @@ Once installed, just talk to your AI naturally. We classify skills so you know what you're running: -- 🟣 **Official**: Maintained by Anthropic/Google/Vendors (High Trust). -- 🔵 **Safe**: Community skills that are non-destructive (Read-only/Planning). -- 🔴 **Risk**: Skills that modify systems or perform security tests (Authorized Use Only). +- ⚪ **unknown**: legacy/unclassified content that still needs maintainer triage. +- 🟢 **none**: pure text/reasoning guidance. +- 🔵 **safe**: read-only or low-risk operational guidance. +- 🟠 **critical**: state-changing or deployment-impacting guidance. +- 🔴 **offensive**: pentest/red-team guidance with an explicit Authorized Use Only warning. -When adding new skills, high-risk guidance is extra-reviewed with repository-wide `security:docs` scanning before release. +Community PRs may still submit `risk: unknown`, but maintainers now audit and progressively reconcile those labels using the repo-wide audit/report tooling. High-risk guidance is extra-reviewed with repository-wide `security:docs` scanning before release. _Check the [Skill Catalog](../../CATALOG.md) for the full list._ diff --git a/walkthrough.md b/walkthrough.md index 6617e071..901dd6a3 100644 --- a/walkthrough.md +++ b/walkthrough.md @@ -1,3 +1,19 @@ +# Maintenance Walkthrough - 2026-03-29 + +- Fixed the remaining production/documentation drift introduced by the web-app and CI hardening work: + - clarified that the hosted GitHub Pages app runs in static public-catalog mode + - documented that `Sync Skills` is development-only unless explicitly enabled in local maintainer runs + - documented that web-app save/star interactions are intentionally browser-local today +- Hardened the maintainer documentation so release and CI expectations now match the live workflows: + - release docs now mention the shared `tools/requirements.txt` install path, the web-app coverage gate, and blocking `npm audit --audit-level=high` on publish + - maintainer docs now document the narrow canonical-artifact auto-sync contract on `main` +- Expanded the documented risk-maintenance workflow after the new automation landed: + - `audit:skills` exposes `suggested_risk` + - `sync:risk-labels` supports conservative high-confidence legacy cleanup + - offensive auto-promotions now also insert the canonical `AUTHORIZED USE ONLY` notice +- Updated user-facing install docs to mention that the npm installer now uses a shallow clone for lighter first-run installs. +- Updated the onboarding/trust docs to reflect the real `risk` taxonomy (`unknown`, `none`, `safe`, `critical`, `offensive`) instead of the older simplified wording. + # Maintenance Walkthrough - 2026-03-25 - Imported 14 skills from [Dimillian/Skills](https://github.com/Dimillian/Skills) into `skills/`: