diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef572f15..f03fa3c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,7 @@ git push origin my-branch Open the PR with the default template and enable **Allow edits from maintainers** so conflicts can be resolved without extra back-and-forth. If your PR adds or edits `SKILL.md`, GitHub will also run the automated `skill-review` workflow on the pull request. +Community PRs should stay **source-only**: do not include generated registry artifacts such as `CATALOG.md`, `skills_index.json`, or `data/*.json`. If you only want to improve docs, editing directly in GitHub is still perfectly fine. @@ -211,9 +212,11 @@ More examples... 1. **Copy it to your AI tool's skills directory:** ```bash - cp -r skills/my-awesome-skill ~/.agent/skills/ + cp -r skills/my-awesome-skill ~/.gemini/antigravity/skills/ ``` + Or copy it into the specific tool path you are testing against, such as `~/.claude/skills/`, `~/.cursor/skills/`, or a custom workspace path like `.agent/skills/`. + 2. **Try using it:** ``` @my-awesome-skill help me with [task] @@ -243,6 +246,8 @@ npm run validate:references npm test ``` +For **any normal community PR**, keep the branch source-only and leave generated registry artifacts out of the diff. `main` canonicalizes those after merge. + Optional maintainer-style preflight: ```bash diff --git a/README.md b/README.md index 2974a7d6..31b40ff3 100644 --- a/README.md +++ b/README.md @@ -414,6 +414,7 @@ That will copy the generated skill index into `apps/web-app/public/skills.json`, - Follow the contributor guide in [`CONTRIBUTING.md`](CONTRIBUTING.md). - Use the template in [`docs/contributors/skill-template.md`](docs/contributors/skill-template.md). - 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. ## Community diff --git a/docs/users/faq.md b/docs/users/faq.md index 1f0e54f9..ad3005d4 100644 --- a/docs/users/faq.md +++ b/docs/users/faq.md @@ -93,9 +93,16 @@ _Always check the Risk label and review the code._ ### Where should I install the skills? -The universal path that works with most tools is `.agent/skills/`. +It depends on how you install: -**Using npx:** `npx antigravity-awesome-skills` (or `npx github:sickn33/antigravity-awesome-skills` if you get a 404). +- **Using the installer CLI (`npx antigravity-awesome-skills`)**: + The default install target is `~/.gemini/antigravity/skills/` for Antigravity's global library. +- **Using a tool-specific flag**: + Use `--claude`, `--cursor`, `--gemini`, `--codex`, `--kiro`, or `--antigravity` to target the matching tool path automatically. +- **Using a manual clone or custom workspace path**: + `.agent/skills/` is still a good universal workspace convention for Antigravity/custom setups. + +If you get a 404 from npm, use: `npx github:sickn33/antigravity-awesome-skills` **Using git clone:** @@ -121,10 +128,10 @@ This repository now includes `.claude-plugin/marketplace.json` and `.claude-plug ### Does this work with Windows? -**Yes.** Use the standard install flow: +**Yes.** Use the same standard install flow as other platforms: ```bash -git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills +npx antigravity-awesome-skills ``` If you have an older clone created around the removed symlink workaround, reinstall into a fresh directory or rerun `npx antigravity-awesome-skills`. @@ -221,8 +228,10 @@ Include: The repository enforces automated quality control. Your skill might be missing: 1. A valid `description`. -2. Usage examples. - Run `npm run validate` locally to check before you push. +2. Clear usage guidance or examples. +3. The expected PR template checklist in the PR body. + +Run `npm run validate` locally before you push, and make sure you opened the PR with the default template so the Quality Bar checklist is present. ### My PR failed "security docs" check. What should I do? @@ -254,6 +263,18 @@ Since v8.0.0, GitHub automatically runs a `skill-review` workflow on any PR that You do not need to close and reopen the PR. Informational or style-only findings do not block merging. +### Do community PRs need generated files like `CATALOG.md` or `skills_index.json`? + +**No.** Community PRs should stay **source-only**. + +Do **not** include generated registry artifacts like: + +- `CATALOG.md` +- `skills_index.json` +- `data/*.json` + +Maintainers regenerate and canonicalize those files on `main` after merge. If you touch docs, workflows, or infra, run `npm run validate:references` and `npm test` locally instead. + ### Can I update an "Official" skill? **No.** Official skills (in `skills/official/`) are mirrored from vendors. Open an issue instead. diff --git a/docs/users/usage.md b/docs/users/usage.md index a62348b6..856489a4 100644 --- a/docs/users/usage.md +++ b/docs/users/usage.md @@ -12,7 +12,7 @@ Great question! Here's what just happened and what to do next: When you ran `npx antigravity-awesome-skills` or cloned the repository, you: -✅ **Downloaded 1,304+ skill files** to your computer (default: `~/.gemini/antigravity/skills/`; or `~/.agent/skills/` if you used `--path`) +✅ **Downloaded 1,304+ skill files** to your computer (default: `~/.gemini/antigravity/skills/`; or a custom path like `~/.agent/skills/` if you used `--path`) ✅ **Made them available** to your AI assistant ❌ **Did NOT enable them all automatically** (they're just sitting there, waiting) @@ -310,7 +310,7 @@ AI: [Creates tests, sets up CI/CD, deploys to Vercel] Yes! Three ways: 1. Browse [CATALOG.md](../../CATALOG.md) (searchable list) -2. Run `ls ~/.agent/skills/` (if installed there) +2. Run `ls ~/.gemini/antigravity/skills/` (or your actual install path) 3. Ask your AI: "What skills do you have for [topic]?" ### "Do I need to restart my IDE after installing?" @@ -344,7 +344,7 @@ Use @skill-creator to help me build a custom skill for [your task] ### "What if a skill doesn't work as expected?" -1. Check the skill's SKILL.md file directly: `~/.agent/skills/[skill-name]/SKILL.md` +1. Check the skill's `SKILL.md` file directly in your installed path, for example: `~/.gemini/antigravity/skills/[skill-name]/SKILL.md` 2. Read the description to ensure you're using it correctly 3. [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) with details diff --git a/docs/users/visual-guide.md b/docs/users/visual-guide.md index 4e6f41ab..aaa2fc59 100644 --- a/docs/users/visual-guide.md +++ b/docs/users/visual-guide.md @@ -70,7 +70,7 @@ antigravity-awesome-skills/ ``` ┌──────────────┐ -│ 1. INSTALL │ Copy skills to .agent/skills/ +│ 1. INSTALL │ Run npx installer or clone to your tool path └──────┬───────┘ │ ↓ @@ -178,31 +178,30 @@ antigravity-awesome-skills/ ## Installation (Visual Steps) -### Step 1: Clone the Repository +### Step 1: Install the Repository ``` ┌─────────────────────────────────────────┐ │ Terminal │ ├─────────────────────────────────────────┤ -│ $ git clone https://github.com/ │ -│ sickn33/antigravity-awesome-skills │ -│ .agent/skills │ +│ $ npx antigravity-awesome-skills │ │ │ -│ ✓ Cloning into '.agent/skills'... │ -│ ✓ Done! │ +│ ✓ Installing to │ +│ ~/.gemini/antigravity/skills/ │ └─────────────────────────────────────────┘ ``` +If you want a workspace-style manual install instead, cloning into `.agent/skills/` is still a valid custom path for Antigravity. + ### Step 2: Verify Installation ``` ┌─────────────────────────────────────────┐ │ File Explorer │ ├─────────────────────────────────────────┤ -│ 📁 .agent/ │ -│ └── 📁 skills/ │ -│ ├── 📁 brainstorming/ │ -│ ├── 📁 stripe-integration/ │ -│ ├── 📁 react-best-practices/ │ -│ └── ... (1,304+ total) │ +│ 📁 ~/.gemini/antigravity/skills/ │ +│ ├── 📁 brainstorming/ │ +│ ├── 📁 stripe-integration/ │ +│ ├── 📁 react-best-practices/ │ +│ └── ... (1,304+ total) │ └─────────────────────────────────────────┘ ``` @@ -311,7 +310,7 @@ Open skills_index.json → Search for keyword → Find skill path │ ↓ ┌──────────────┐ -│ 4. TEST │ Copy to .agent/skills/ +│ 4. TEST │ Copy to your tool's installed skills path └──────┬───────┘ Try: @docker-mastery │ ↓ @@ -435,7 +434,7 @@ START HERE ├─────────────────────────────────────────────────────────────┤ │ │ │ 📥 INSTALL │ -│ git clone [repo] .agent/skills │ +│ npx antigravity-awesome-skills │ │ │ │ 🎯 USE │ │ @skill-name [your request] │ @@ -455,6 +454,7 @@ START HERE │ │ │ 🆘 HELP │ │ • docs/users/getting-started.md │ +│ • docs/users/faq.md │ │ • CONTRIBUTING.md │ │ • docs/contributors/skill-anatomy.md │ │ • GitHub Issues - Ask questions │