docs(repo): Align docs with current maintainer flows
Document the current static web-app behavior, local-only save flow, shallow installer path, and maintainer-only sync controls.\n\nAlign maintainer guides with the active audit-to-risk-sync workflow, canonical artifact bot contract, release/coverage requirements, and updated security triage context so the docs match the repository's real operating model.
This commit is contained in:
sickn33
9
.github/MAINTENANCE.md
vendored
9
.github/MAINTENANCE.md
vendored
@@ -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)
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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 <dir>` 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._
|
||||
|
||||
|
||||
@@ -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/`:
|
||||
|
||||
Reference in New Issue
Block a user