diff --git a/antigravity-awesome-skills/README.md b/antigravity-awesome-skills/README.md index 4ac9b85b..18796523 100644 --- a/antigravity-awesome-skills/README.md +++ b/antigravity-awesome-skills/README.md @@ -486,14 +486,14 @@ We officially thank the following contributors for their help in making this rep ## Star History - Star History Chart + Star History Chart - - - Star History Chart + + + Star History Chart diff --git a/antigravity-awesome-skills/SOURCE.md b/antigravity-awesome-skills/SOURCE.md index e2302a94..b96274f5 100644 --- a/antigravity-awesome-skills/SOURCE.md +++ b/antigravity-awesome-skills/SOURCE.md @@ -1,8 +1,8 @@ # Source - Repo: https://github.com/sickn33/antigravity-awesome-skills -- Ref: d89c349f775bff02124a1bbd345450115c1c8705 +- Ref: afc403de16917b418c301b690970047b2109542f - Remove-Paths: -- Snapshot: 2026-06-07 +- Snapshot: 2026-06-08 - Sync-Mode: copy_skill_dirs - Notes: vendored into playbook branch thirdparty/skill diff --git a/antigravity-awesome-skills/apps/web-app/public/sitemap.xml b/antigravity-awesome-skills/apps/web-app/public/sitemap.xml index 3eef78b4..37b3ec83 100644 --- a/antigravity-awesome-skills/apps/web-app/public/sitemap.xml +++ b/antigravity-awesome-skills/apps/web-app/public/sitemap.xml @@ -2,253 +2,253 @@ http://localhost/ - 2026-06-07 + 2026-06-08 daily 1.0 http://localhost/plugins - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/runapi-cli - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/article-illustrations - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/cv-generator - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/open-dynamic-workflows - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/video-content-extractor - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/2slides-ppt-generator - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/anti-sycophancy - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/event-staffing-compliance - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/event-staffing-ordering - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/examprep-ai - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/permission-manager - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/skill-suggester - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/smart-git-automation - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/antigravity-agent-manager - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/hasdata - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/hasdata-cli - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/linkedin-content-generator - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/accesslint-audit - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/accesslint-diff - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/accesslint-scan - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/composition-patterns - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/debugging-toolkit - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/deploy-to-vercel - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/polis-protocol - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/python-development - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/react-native-skills - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/skill-issue - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/tdd-workflows - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/vercel-cli-with-tokens - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/vercel-optimize - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/vercel-react-view-transitions - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/doc2math - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/moatmri - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/nextjs-seo-indexing - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/schema-markup-generator - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/social-metadata-hardening - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/user-thoughts - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/vibe-code-cleanup - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/vibecode-production-qa-validator - 2026-06-07 + 2026-06-08 weekly 0.7 http://localhost/skill/yield-intelligence - 2026-06-07 + 2026-06-08 weekly 0.7 diff --git a/antigravity-awesome-skills/assets/star-history.png b/antigravity-awesome-skills/assets/star-history.png index d4b9085e..52e56d3f 100644 Binary files a/antigravity-awesome-skills/assets/star-history.png and b/antigravity-awesome-skills/assets/star-history.png differ diff --git a/brooks-lint/AGENTS.md b/brooks-lint/AGENTS.md index c12352fd..8092c999 100644 --- a/brooks-lint/AGENTS.md +++ b/brooks-lint/AGENTS.md @@ -3,7 +3,7 @@ This repository is an AI-powered code quality tool grounded in twelve classic engineering books (e.g., *The Mythical Man-Month*, *Code Complete*, *A Philosophy of Software Design*, *Software Engineering at Google*). ## Core Purpose -**brooks-lint** is a Codex CLI plugin used to diagnose code quality across six "decay risk" dimensions: Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, and Domain Model Distortion. +**brooks-lint** is a portable Agent-Skills code quality tool — it runs on any Agent-Skills-compatible agent (Codex CLI, OpenCode, Cursor, Antigravity, pi, and others that read `AGENTS.md` and load `SKILL.md` skills) to diagnose code quality across six "decay risk" dimensions: Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, and Domain Model Distortion. ## Skill Integration - **Auto-trigger:** You **must** proactively use the appropriate skill whenever discussing code quality, PR reviews, architecture health, test quality, or technical debt. diff --git a/brooks-lint/CHANGELOG.md b/brooks-lint/CHANGELOG.md index 26c6f27f..5363a48a 100644 --- a/brooks-lint/CHANGELOG.md +++ b/brooks-lint/CHANGELOG.md @@ -4,6 +4,43 @@ All notable changes to brooks-lint are documented here. ## [Unreleased] +### Added + +- **One-command multi-platform installer** — `scripts/install.sh ` + copies the six skills + `_shared/` **flat** into the correct folder for + OpenCode, Cursor, Windsurf, Antigravity, pi, Kiro, GitHub Copilot, Claude, or + the vendor-neutral `~/.agents/skills`, so the `../_shared/` relative reads + always resolve (users can't get the layout wrong). Runs from a clone or via + `curl … | bash -s -- `; `--project` targets the current repo. +- **Per-platform setup guides** — `docs/getting-started.md` plus + `docs/{opencode,cursor,windsurf,antigravity,pi,copilot,kiro}-setup.md`, with + install, invocation, gotchas, and source links for each. Modeled on the + `addyosmani/agent-skills` docs layout (compact README + detailed docs). +- **Multi-platform support in both READMEs** — the EN and zh-CN READMEs now + expose seven additional Agent-Skills agents via collapsible per-platform + entries that link to the docs, plus a verification-status note inviting + community end-to-end reports. Resolves the OpenCode compatibility request (#14). + +- **Factory Droid support** — added `droid` to the installer and a + `docs/factory-droid-setup.md` guide. Droid natively loads `SKILL.md` from + `~/.factory/skills` / `.factory/skills` and reads `AGENTS.md`. +- **`install.sh` now covers Gemini and Codex** (`gemini`, `codex` targets) so a + single command installs every documented platform. + +### Fixed + +- **Gemini CLI manual install was broken** — the old `cp -r skills/* + ~/.gemini/skills/brooks-lint/` nested every `SKILL.md` two levels deep, and + Gemini only discovers skills **one level deep**, so none of the six skills were + found. Corrected to a flat `~/.gemini/skills/` install (EN + zh-CN READMEs). + Also flattened the Codex manual install to match the skill-installer layout. + +### Changed + +- **`AGENTS.md`** now describes brooks-lint as a portable Agent-Skills tool + (runs on any `AGENTS.md`/`SKILL.md`-compatible agent) rather than a + Codex-CLI-specific plugin. + --- ## [1.3.0] - 2026-05-24 diff --git a/brooks-lint/README.md b/brooks-lint/README.md index 8542a41d..9d40e114 100644 --- a/brooks-lint/README.md +++ b/brooks-lint/README.md @@ -226,9 +226,10 @@ cp -r skills/* ~/.claude/skills/brooks-lint/ #### Manual Install ```bash -mkdir -p ~/.gemini/skills/brooks-lint -cp -r skills/* ~/.gemini/skills/brooks-lint/ +mkdir -p ~/.gemini/skills +cp -r skills/* ~/.gemini/skills/ # flat — Gemini discovers skills only one level deep ``` +> Or simply: `./scripts/install.sh gemini` ### Codex CLI @@ -246,9 +247,81 @@ python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-githu #### Manual Install ```bash git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint -mkdir -p ~/.codex/skills/brooks-lint -cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/brooks-lint/ +mkdir -p ~/.codex/skills +cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/ # flat — matches the skill-installer layout ``` +> Or simply: `./scripts/install.sh codex` + +### More platforms — OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid + +brooks-lint ships as standard [Agent Skills](https://agentskills.io). **Any agent that loads Agent +Skills runs all six modes with no conversion** — one command installs them: + +```bash +# pick your platform; --project installs into the current repo instead of your global config +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- +# = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · gemini · codex · agents +``` + +The installer copies the skills **flat** into the right folder for your platform, so the shared +framework (`../_shared/`) always resolves — you can't get the layout wrong. Then just ask +("review this PR", "audit the architecture") and the matching skill auto-triggers from its +`description`. New to skills, or using another agent? See **[docs/getting-started.md](docs/getting-started.md)**. + +
OpenCode + +`./scripts/install.sh opencode` → `~/.config/opencode/skills` (also reads `~/.claude/skills` and +`AGENTS.md`). Full guide: [docs/opencode-setup.md](docs/opencode-setup.md). +
+ +
Cursor (2.4+) + +`./scripts/install.sh cursor` → `~/.cursor/skills` (also `.agents/skills`; reads `AGENTS.md`). +Full guide: [docs/cursor-setup.md](docs/cursor-setup.md). +
+ +
Windsurf (Cascade) + +`./scripts/install.sh windsurf` → `~/.codeium/windsurf/skills` (reads `AGENTS.md`). +Full guide: [docs/windsurf-setup.md](docs/windsurf-setup.md). +
+ +
Antigravity (Google) + +`./scripts/install.sh antigravity --project` → `.agent/skills` (reads `AGENTS.md` / `GEMINI.md`). +Full guide: [docs/antigravity-setup.md](docs/antigravity-setup.md). +
+ +
pi (earendil-works) + +`./scripts/install.sh pi` → `~/.pi/agent/skills`, or point pi's `skills` setting at a clone. +Full guide: [docs/pi-setup.md](docs/pi-setup.md). +
+ +
GitHub Copilot + +`./scripts/install.sh copilot --project` → `.github/skills` (also auto-detects `.claude/skills`; reads +`AGENTS.md`). Full guide: [docs/copilot-setup.md](docs/copilot-setup.md). +
+ +
Kiro (AWS) + +`./scripts/install.sh kiro` → `~/.kiro/skills` (auto-registers `/brooks-review`; reads `AGENTS.md`). +Full guide: [docs/kiro-setup.md](docs/kiro-setup.md). +
+ +
Factory Droid + +`./scripts/install.sh droid` → `~/.factory/skills` (registers `/brooks-review`; reads `AGENTS.md`). +Full guide: [docs/factory-droid-setup.md](docs/factory-droid-setup.md). +
+ +> **🧪 Verification status.** Claude Code, Gemini CLI, and Codex CLI are maintainer-verified. The eight +> platforms above are documented from each tool's official skill spec and verified at the file-layout +> level (the installer is tested), but not yet end-to-end run by the maintainer on every platform. Tried +> one — working **or** broken? [Open an issue](https://github.com/hyhmrright/brooks-lint/issues/new) with +> the platform, version, and what you saw. Another Agent-Skills agent? It almost certainly works the same +> way — tell us and we'll add it. ## Slash Commands @@ -287,6 +360,13 @@ cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/brooks-lint/ The skills also trigger automatically when you discuss code quality, architecture, maintainability, or test health. +### OpenCode · Cursor · Antigravity · pi + +These platforms invoke Agent Skills automatically from each skill's `description` — just ask +("review this PR", "audit the architecture", "where's our worst tech debt?") and the matching mode +runs. For explicit invocation, use the platform's skill-command syntax (e.g. pi registers each skill +as `/skill:brooks-review`; Cursor and OpenCode expose `/brooks-review` once the skill is discovered). + ## Usage ### PR Review diff --git a/brooks-lint/README.zh-CN.md b/brooks-lint/README.zh-CN.md index c0b47ec1..e9264561 100644 --- a/brooks-lint/README.zh-CN.md +++ b/brooks-lint/README.zh-CN.md @@ -226,9 +226,10 @@ cp -r skills/* ~/.claude/skills/brooks-lint/ #### 手动安装 ```bash -mkdir -p ~/.gemini/skills/brooks-lint -cp -r skills/* ~/.gemini/skills/brooks-lint/ +mkdir -p ~/.gemini/skills +cp -r skills/* ~/.gemini/skills/ # 扁平——Gemini 只发现一层深的技能 ``` +> 或直接：`./scripts/install.sh gemini` ### Codex CLI @@ -246,9 +247,78 @@ python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-githu #### 手动安装 ```bash git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint -mkdir -p ~/.codex/skills/brooks-lint -cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/brooks-lint/ +mkdir -p ~/.codex/skills +cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/ # 扁平——与技能安装器布局一致 ``` +> 或直接：`./scripts/install.sh codex` + +### 更多平台——OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid + +brooks-lint 以标准 [Agent Skills](https://agentskills.io) 形式分发。**任何加载 Agent Skills 的 agent +都能无需任何转换运行全部六种模式**——一条命令即可安装： + +```bash +# 选择你的平台；加 --project 装进当前仓库而非全局配置 +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <平台> +# <平台> = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · gemini · codex · agents +``` + +安装器会把技能**扁平**拷进该平台对应的文件夹，让共享框架（`../_shared/`）始终正确解析——你不可能装错布局。 +装好后直接提问（"审查这个 PR"、"审查架构"），对应技能就会依据 `description` 自动触发。 +不熟悉 skills、或用的是别的 agent？见 **[docs/getting-started.md](docs/getting-started.md)**。 + +
OpenCode + +`./scripts/install.sh opencode` → `~/.config/opencode/skills`（同时读取 `~/.claude/skills` 与 +`AGENTS.md`）。完整指南：[docs/opencode-setup.md](docs/opencode-setup.md)。 +
+ +
Cursor（2.4+） + +`./scripts/install.sh cursor` → `~/.cursor/skills`（也读 `.agents/skills`；读取 `AGENTS.md`）。 +完整指南：[docs/cursor-setup.md](docs/cursor-setup.md)。 +
+ +
Windsurf（Cascade） + +`./scripts/install.sh windsurf` → `~/.codeium/windsurf/skills`（读取 `AGENTS.md`）。 +完整指南：[docs/windsurf-setup.md](docs/windsurf-setup.md)。 +
+ +
Antigravity（Google） + +`./scripts/install.sh antigravity --project` → `.agent/skills`（读取 `AGENTS.md` / `GEMINI.md`）。 +完整指南：[docs/antigravity-setup.md](docs/antigravity-setup.md)。 +
+ +
pi（earendil-works） + +`./scripts/install.sh pi` → `~/.pi/agent/skills`，或让 pi 的 `skills` 设置指向一个克隆。 +完整指南：[docs/pi-setup.md](docs/pi-setup.md)。 +
+ +
GitHub Copilot + +`./scripts/install.sh copilot --project` → `.github/skills`（也自动识别 `.claude/skills`；读取 +`AGENTS.md`）。完整指南：[docs/copilot-setup.md](docs/copilot-setup.md)。 +
+ +
Kiro（AWS） + +`./scripts/install.sh kiro` → `~/.kiro/skills`（自动注册 `/brooks-review`；读取 `AGENTS.md`）。 +完整指南：[docs/kiro-setup.md](docs/kiro-setup.md)。 +
+ +
Factory Droid + +`./scripts/install.sh droid` → `~/.factory/skills`（注册 `/brooks-review`；读取 `AGENTS.md`）。 +完整指南：[docs/factory-droid-setup.md](docs/factory-droid-setup.md)。 +
+ +> **🧪 验证状态。** Claude Code、Gemini CLI、Codex CLI 已由维护者验证。上面八个平台依据各工具官方技能规范编写， +> 并已在文件布局层面验证（安装器经过测试），但维护者尚未在每个平台端到端实跑。在某平台试过了——无论成功**还是**失败？ +> 请[提一个 issue](https://github.com/hyhmrright/brooks-lint/issues/new)，附上平台、版本和你看到的结果。 +> 用的是其它兼容 Agent Skills 的 agent？它几乎肯定以同样方式工作——告诉我们，我们会补上。 ## 斜杠命令 @@ -287,6 +357,12 @@ cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/brooks-lint/ 当你讨论代码质量、架构、可维护性或测试健康时，这些技能也会自动触发。 +### OpenCode · Cursor · Antigravity · pi + +这些平台依据每个技能的 `description` 自动调用 Agent Skills——直接提问（"审查这个 PR"、"审查架构"、 +"我们最糟的技术债在哪"）就会运行对应模式。需要显式调用时，使用各平台的技能命令语法（例如 pi 把每个技能注册为 +`/skill:brooks-review`；Cursor 与 OpenCode 在技能被发现后暴露 `/brooks-review`）。 + ## 使用 ### PR 审查 diff --git a/brooks-lint/SOURCE.md b/brooks-lint/SOURCE.md index a9f0d7cb..aa65e797 100644 --- a/brooks-lint/SOURCE.md +++ b/brooks-lint/SOURCE.md @@ -1,8 +1,8 @@ # Source - Repo: https://github.com/hyhmrright/brooks-lint -- Ref: 85e4ddbe4b06036b0d0f08e88193a864077261a9 +- Ref: 0e92503911f28ff091b14c017d4345f7a2dd8817 - Remove-Paths: -- Snapshot: 2026-06-02 +- Snapshot: 2026-06-08 - Sync-Mode: copy_skill_dirs - Notes: vendored into playbook branch thirdparty/skill diff --git a/brooks-lint/docs/antigravity-setup.md b/brooks-lint/docs/antigravity-setup.md new file mode 100644 index 00000000..afa98711 --- /dev/null +++ b/brooks-lint/docs/antigravity-setup.md @@ -0,0 +1,40 @@ +# Antigravity Setup + +Google's [Antigravity](https://antigravity.google) uses Claude-compatible +[Agent Skills](https://agentskills.io) and reads `AGENTS.md` / `GEMINI.md`, so all six brooks-lint +modes run with no conversion. + +## Install + +```bash +# project-scoped is the official convention (recommended) +./scripts/install.sh antigravity --project # this repo: ./.agent/skills + +# global +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- antigravity +./scripts/install.sh antigravity # global: ~/.gemini/skills +``` + +Manual equivalent (project): + +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p .agent/skills +cp -r /tmp/brooks-lint/skills/* .agent/skills/ # flat — brooks-* and _shared/ as siblings +``` + +## Invoke + +Ask naturally ("review this PR", "audit the architecture") — the agent selects the matching skill from +its `description`. `AGENTS.md` / `GEMINI.md` carry the Iron Law and Health Score rules. + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): `../_shared/` only resolves when + `_shared/` is a sibling of the `brooks-*` folders. +- The project convention `.agent/skills/` is well documented; the **global** skills path + (`~/.gemini/skills` vs a product subfolder) varies between sources — if the global install isn't + discovered, use the project install. Please report what worked. +- 🧪 Documented per the official [skills](https://antigravity.google/docs/skills) and + [rules & workflows](https://antigravity.google/docs/rules-workflows) docs; community end-to-end + verification welcome — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/docs/copilot-setup.md b/brooks-lint/docs/copilot-setup.md new file mode 100644 index 00000000..6ef1861d --- /dev/null +++ b/brooks-lint/docs/copilot-setup.md @@ -0,0 +1,43 @@ +# GitHub Copilot Setup + +GitHub Copilot has supported [Agent Skills](https://agentskills.io) since December 2025 (coding agent, +Copilot CLI, and VS Code agent mode). It reads `AGENTS.md` and **auto-detects existing `.claude/skills` +folders**, so all six brooks-lint modes run with no conversion. + +## Install + +```bash +# personal (all repos) — one command +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- copilot + +# from a clone +./scripts/install.sh copilot # personal: ~/.copilot/skills +./scripts/install.sh copilot --project # this repo: ./.github/skills +``` + +Manual equivalent (commit to a repo so the cloud agent and reviewers share it): + +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p .github/skills +cp -r /tmp/brooks-lint/skills/* .github/skills/ # flat — brooks-* and _shared/ as siblings +``` + +Copilot discovers skills from `.github/skills`, `.claude/skills`, `.agents/skills` (project) and +`~/.copilot/skills`, `~/.agents/skills` (personal). `./scripts/install.sh agents` (→ `~/.agents/skills`) +is shared with Cursor and pi. + +## Invoke + +Ask naturally in Copilot Chat / CLI ("review this PR", "audit the architecture") — Copilot loads the +matching skill on demand from its `description`. `AGENTS.md` (or `.github/copilot-instructions.md`) +carries the Iron Law and Health Score rules. + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): `../_shared/` only resolves when + `_shared/` is a sibling of the `brooks-*` folders. +- Org/enterprise-level skills were "coming soon" at launch; repo-level `.github/skills` works today. +- 🧪 Documented per the [Agent Skills announcement](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/) + and [docs](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills); community + end-to-end verification welcome — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/docs/cursor-setup.md b/brooks-lint/docs/cursor-setup.md new file mode 100644 index 00000000..8f741764 --- /dev/null +++ b/brooks-lint/docs/cursor-setup.md @@ -0,0 +1,38 @@ +# Cursor Setup + +[Cursor](https://cursor.com) added native [Agent Skills](https://agentskills.io) support in 2.4. It +loads `SKILL.md` skills and reads `AGENTS.md`, so all six brooks-lint modes run with no conversion. + +## Install + +```bash +# simplest — one command (global) +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- cursor + +# from a clone +./scripts/install.sh cursor # global: ~/.cursor/skills +./scripts/install.sh cursor --project # this repo: ./.cursor/skills +``` + +Manual equivalent: + +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p ~/.cursor/skills +cp -r /tmp/brooks-lint/skills/* ~/.cursor/skills/ # flat — brooks-* and _shared/ as siblings +``` + +Cursor also loads `.agents/skills/` / `~/.agents/skills/` and existing Claude/Codex skill folders, so +`./scripts/install.sh agents` works too and is shared with Copilot and pi. + +## Invoke + +Ask naturally ("review this PR", "audit the architecture") and Cursor selects the matching skill from +its `description`, or use the `/brooks-review` slash form once the skill is discovered. + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): `../_shared/` only resolves when + `_shared/` is a sibling of the `brooks-*` folders. +- 🧪 Documented per the official [skills docs](https://cursor.com/docs/skills); community end-to-end + verification welcome — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/docs/factory-droid-setup.md b/brooks-lint/docs/factory-droid-setup.md new file mode 100644 index 00000000..3e4869ac --- /dev/null +++ b/brooks-lint/docs/factory-droid-setup.md @@ -0,0 +1,43 @@ +# Factory Droid Setup + +Factory's [Droid](https://factory.ai) (`droid` CLI) natively loads +[Agent Skills](https://agentskills.io) and reads `AGENTS.md`, so all six brooks-lint modes run with no +conversion. + +## Install + +```bash +# simplest — one command +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- droid + +# from a clone +./scripts/install.sh droid # personal: ~/.factory/skills +./scripts/install.sh droid --project # this repo: ./.factory/skills +``` + +Manual equivalent: + +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p ~/.factory/skills +cp -r /tmp/brooks-lint/skills/* ~/.factory/skills/ # flat — brooks-* and _shared/ as siblings +``` + +Droid discovers skills from `~/.factory/skills` (personal), `.factory/skills` (project), and the legacy +`.agent/skills`, each a single level deep. + +## Invoke + +Ask naturally ("review this PR", "audit the architecture") — Droid auto-loads the matching skill from +its `description` — or use the slash form `/brooks-review` (Droid registers each skill as a command). +`AGENTS.md` carries the Iron Law and Health Score rules. + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): `../_shared/` only resolves when + `_shared/` is a sibling of the `brooks-*` folders, and Droid discovers skills only one level deep. +- Droid ignores Claude-only frontmatter fields (e.g. `allowed-tools`); `name` + `description` + body + are all it needs, so the skills load unchanged. +- 🧪 Documented per the official [skills docs](https://docs.factory.ai/cli/configuration/skills) and + [AGENTS.md docs](https://docs.factory.ai/cli/configuration/agents-md); community end-to-end + verification welcome — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/docs/getting-started.md b/brooks-lint/docs/getting-started.md new file mode 100644 index 00000000..c71f87f5 --- /dev/null +++ b/brooks-lint/docs/getting-started.md @@ -0,0 +1,74 @@ +# Getting Started — brooks-lint on any agent + +brooks-lint is six [Agent Skills](https://agentskills.io) (`SKILL.md` + Markdown guides) plus a +shared `_shared/` framework folder. **Any coding agent that loads Agent Skills can run all six modes +with no conversion** — you just place the `skills/` directory where that agent looks for skills. + +## The one thing that matters: flat layout + +Every skill reads the shared framework via the relative path `../_shared/common.md`. That only +resolves when `_shared/` is a **sibling** of the `brooks-*` folders: + +``` +/ +├── brooks-review/SKILL.md ← reads ../_shared/common.md +├── brooks-audit/SKILL.md +├── … +└── _shared/ ← sibling, no SKILL.md (ignored as a skill, read as files) +``` + +So always copy `skills/*` **flat** — never nest everything under one `brooks-lint/` folder for the +platforms that discover skills with a single-level glob (`skills//SKILL.md`). + +## Simplest install — one command + +The installer copies the skills flat into the correct folder for your platform, so you can't get the +layout wrong: + +```bash +# from a clone +./scripts/install.sh + +# or without cloning +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- +``` + +`` ∈ `opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · gemini · +codex · claude · agents`. Add `--project` to install into the current repo instead of your global +config. `agents` targets the vendor-neutral `~/.agents/skills` folder that Cursor, Copilot, pi, Gemini, +and Codex all read. + +## Per-platform guides + +| Platform | Guide | Discovers `SKILL.md` from | Reads `AGENTS.md` | +|----------|-------|---------------------------|:-----------------:| +| OpenCode | [opencode-setup.md](opencode-setup.md) | `~/.config/opencode/skills`, `.opencode/skills`, `~/.claude/skills` | ✅ | +| Cursor | [cursor-setup.md](cursor-setup.md) | `~/.cursor/skills`, `.cursor/skills`, `.agents/skills` | ✅ | +| Windsurf | [windsurf-setup.md](windsurf-setup.md) | `~/.codeium/windsurf/skills`, `.windsurf/skills` | ✅ | +| Antigravity | [antigravity-setup.md](antigravity-setup.md) | `.agent/skills`, `~/.gemini/skills` | ✅ | +| pi | [pi-setup.md](pi-setup.md) | `~/.pi/agent/skills`, `.pi/skills`, settings array | ✅ | +| GitHub Copilot | [copilot-setup.md](copilot-setup.md) | `.github/skills`, `.claude/skills`, `~/.copilot/skills` | ✅ | +| Kiro | [kiro-setup.md](kiro-setup.md) | `.kiro/skills`, `~/.kiro/skills` | ✅ | +| Factory Droid | [factory-droid-setup.md](factory-droid-setup.md) | `~/.factory/skills`, `.factory/skills`, `.agent/skills` | ✅ | + +For Claude Code, Gemini CLI, and Codex CLI, see the [README install section](../README.md#installation). +`./scripts/install.sh gemini` and `./scripts/install.sh codex` also work and use the flat layout these +two require (Gemini discovers skills only one level deep). + +## Any other agent + +If your agent accepts a skills folder or an instruction file, brooks-lint works: + +- **Loads `SKILL.md`?** Point it at a flat `skills/` folder (use `install.sh agents` for the neutral + `~/.agents/skills`). +- **Only reads an instructions file** (`AGENTS.md` / `CLAUDE.md` / a system prompt)? Add the repo's + `AGENTS.md` so the agent learns the Iron Law and scoring, then have it read the relevant + `skills//SKILL.md` on demand. + +## Verification status + +The marketplace-installed platforms (Claude Code, Gemini CLI, Codex CLI) are maintainer-verified. The +seven Agent-Skills platforms above are documented from each tool's official skill spec and verified at +the file-layout level (the installer is tested), but not yet end-to-end run by the maintainer on every +platform. **Tried one? Tell us** — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new) +with the platform, version, and what you saw, working or broken. diff --git a/brooks-lint/docs/kiro-setup.md b/brooks-lint/docs/kiro-setup.md new file mode 100644 index 00000000..1061c384 --- /dev/null +++ b/brooks-lint/docs/kiro-setup.md @@ -0,0 +1,41 @@ +# Kiro Setup + +AWS [Kiro](https://kiro.dev) (IDE & CLI) natively loads Claude-compatible +[Agent Skills](https://agentskills.io), reads `AGENTS.md`, and **auto-registers each skill as a slash +command**, so all six brooks-lint modes run with no conversion. + +## Install + +```bash +# simplest — one command (global) +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- kiro + +# from a clone +./scripts/install.sh kiro # global: ~/.kiro/skills +./scripts/install.sh kiro --project # this repo: ./.kiro/skills +``` + +Manual equivalent: + +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p ~/.kiro/skills +cp -r /tmp/brooks-lint/skills/* ~/.kiro/skills/ # flat — brooks-* and _shared/ as siblings +``` + +Or use the IDE: **Agent Steering & Skills** panel → **+** → **Import a skill** → paste a GitHub URL or +pick a local folder (Kiro copies it into your skills folder). + +## Invoke + +Ask naturally ("review this PR", "audit the architecture"), or use the auto-registered slash command +`/brooks-review`. `AGENTS.md` is always-included and carries the Iron Law and Health Score rules. + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): `../_shared/` only resolves when + `_shared/` is a sibling of the `brooks-*` folders. +- Kiro requires the folder name to equal the skill's `name` (✅ already true here), `name` ≤ 64 chars, + and `description` ≤ 1024 chars (brooks-lint's longest is ~920). +- 🧪 Documented per the official [skills docs](https://kiro.dev/docs/skills/); community end-to-end + verification welcome — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/docs/opencode-setup.md b/brooks-lint/docs/opencode-setup.md new file mode 100644 index 00000000..b9cd9644 --- /dev/null +++ b/brooks-lint/docs/opencode-setup.md @@ -0,0 +1,45 @@ +# OpenCode Setup + +[OpenCode](https://opencode.ai) natively loads [Agent Skills](https://agentskills.io) and reads +`AGENTS.md`, so all six brooks-lint modes run with no conversion. + +## Install + +```bash +# simplest — one command (global) +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- opencode + +# from a clone +./scripts/install.sh opencode # global: ~/.config/opencode/skills +./scripts/install.sh opencode --project # this repo: ./.opencode/skills +``` + +Manual equivalent: + +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p ~/.config/opencode/skills +cp -r /tmp/brooks-lint/skills/* ~/.config/opencode/skills/ # flat — brooks-* and _shared/ as siblings +``` + +OpenCode also discovers Claude-compatible `~/.claude/skills/*/SKILL.md`, so an existing Claude install +(if flat) is picked up automatically. + +## Invoke + +Just ask — OpenCode auto-selects skills from each `description`: + +- "review this PR" → `brooks-review` +- "audit the architecture" → `brooks-audit` +- "where's our worst tech debt?" → `brooks-debt` + +For explicit invocation, `/brooks-review` etc. are available once the skill is discovered. The repo's +`AGENTS.md` carries the Iron Law (Symptom → Source → Consequence → Remedy) and the Health Score rules. + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): skills read `../_shared/`, which only + resolves when `_shared/` sits beside the `brooks-*` folders. +- 🧪 Documented per the official [skills](https://opencode.ai/docs/skills/) and + [rules](https://opencode.ai/docs/rules/) docs; community end-to-end verification welcome — + [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/docs/pi-setup.md b/brooks-lint/docs/pi-setup.md new file mode 100644 index 00000000..bc8e7bfd --- /dev/null +++ b/brooks-lint/docs/pi-setup.md @@ -0,0 +1,39 @@ +# pi Setup + +[pi](https://github.com/earendil-works/pi) (the earendil-works coding agent) natively loads +[Agent Skills](https://agentskills.io) and reads `AGENTS.md` / `CLAUDE.md`, so all six brooks-lint +modes run with no conversion. + +## Install + +```bash +# simplest — one command (global) +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- pi + +# from a clone +./scripts/install.sh pi # global: ~/.pi/agent/skills +./scripts/install.sh pi --project # this repo: ./.pi/skills +``` + +Or **don't copy at all** — point pi at a clone via settings (`~/.pi/settings.json`, or project +`.pi/settings.json`): + +```json +{ "skills": ["/path/to/brooks-lint/skills"] } +``` + +pi can also reuse other tools' skill folders the same way, e.g. `{ "skills": ["~/.claude/skills"] }` +(only if that folder is flat). + +## Invoke + +Ask naturally ("review this PR", "audit the architecture"), or use the auto-registered command form +`/skill:brooks-review`. `AGENTS.md` carries the Iron Law and Health Score rules. + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): `../_shared/` only resolves when + `_shared/` is a sibling of the `brooks-*` folders. +- pi caps `description` at 1024 chars; brooks-lint's longest is ~920, so all six skills load cleanly. +- 🧪 Documented per the official [skills docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md); + community end-to-end verification welcome — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/docs/windsurf-setup.md b/brooks-lint/docs/windsurf-setup.md new file mode 100644 index 00000000..27b7066b --- /dev/null +++ b/brooks-lint/docs/windsurf-setup.md @@ -0,0 +1,36 @@ +# Windsurf Setup + +[Windsurf](https://windsurf.com) (Cascade) natively loads [Agent Skills](https://agentskills.io) and +reads `AGENTS.md`, so all six brooks-lint modes run with no conversion. + +## Install + +```bash +# simplest — one command (global) +curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- windsurf + +# from a clone +./scripts/install.sh windsurf # global: ~/.codeium/windsurf/skills +./scripts/install.sh windsurf --project # this repo: ./.windsurf/skills +``` + +Manual equivalent: + +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p ~/.codeium/windsurf/skills +cp -r /tmp/brooks-lint/skills/* ~/.codeium/windsurf/skills/ # flat — brooks-* and _shared/ as siblings +``` + +## Invoke + +Ask naturally ("review this PR", "audit the architecture") — Cascade selects the matching skill from +its `description`. The repo's `AGENTS.md` is read by Windsurf's rules engine and carries the Iron Law +and Health Score rules. (`@skill-name` also references a discovered skill.) + +## Notes + +- **Flat layout** is mandatory (the installer guarantees it): `../_shared/` only resolves when + `_shared/` is a sibling of the `brooks-*` folders. +- 🧪 Documented per the official [Cascade skills docs](https://docs.windsurf.com/windsurf/cascade/skills); + community end-to-end verification welcome — [open an issue](https://github.com/hyhmrright/brooks-lint/issues/new). diff --git a/brooks-lint/scripts/install.sh b/brooks-lint/scripts/install.sh new file mode 100755 index 00000000..b2e2d9eb --- /dev/null +++ b/brooks-lint/scripts/install.sh @@ -0,0 +1,135 @@ +#!/usr/bin/env bash +# +# brooks-lint universal skill installer. +# +# brooks-lint ships as standard Agent Skills (SKILL.md). Most modern coding +# agents discover skills from a per-platform folder with a single-level glob +# (skills//SKILL.md) and read shared files via the relative path +# ../_shared/. This script copies the six skills + _shared/ FLAT into the right +# folder for your platform, so the relative reads always resolve — you can't get +# the layout wrong. +# +# Usage: +# ./scripts/install.sh [--project] +# curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- +# +# Platforms: opencode cursor windsurf antigravity pi kiro copilot droid gemini codex claude agents +# agents = the vendor-neutral ~/.agents/skills folder (read by Cursor, Copilot, pi, Gemini, Codex) +# +# Flags: +# --project install into the current repo (././skills) instead of the global folder +# --dir PATH install into an explicit folder (overrides platform mapping) +# --list print supported platforms and exit +# +set -euo pipefail + +REPO_URL="https://github.com/hyhmrright/brooks-lint.git" +PLATFORMS="opencode cursor windsurf antigravity pi kiro copilot droid gemini codex claude agents" + +err() { printf '\033[31merror:\033[0m %s\n' "$*" >&2; } +info() { printf '\033[36m›\033[0m %s\n' "$*"; } +ok() { printf '\033[32m✓\033[0m %s\n' "$*"; } + +# --- resolve the skills/ source (adjacent to this script, or clone) ---------- +resolve_src() { + local script_dir + script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd || true)" + if [ -n "$script_dir" ] && [ -d "$script_dir/../skills" ]; then + local root + root="$( cd "$script_dir/.." && pwd )" + printf '%s' "$root/skills" + return + fi + # Running via curl | bash — clone a shallow copy. + local tmp + tmp="$(mktemp -d)" + info "Cloning brooks-lint into $tmp …" >&2 + git clone --depth 1 "$REPO_URL" "$tmp/brooks-lint" >/dev/null 2>&1 + printf '%s' "$tmp/brooks-lint/skills" +} + +# --- map a platform to its skills folder ------------------------------------- +global_dir() { + case "$1" in + opencode) printf '%s' "$HOME/.config/opencode/skills" ;; + cursor) printf '%s' "$HOME/.cursor/skills" ;; + windsurf) printf '%s' "$HOME/.codeium/windsurf/skills" ;; + antigravity) printf '%s' "$HOME/.gemini/skills" ;; + pi) printf '%s' "$HOME/.pi/agent/skills" ;; + kiro) printf '%s' "$HOME/.kiro/skills" ;; + copilot) printf '%s' "$HOME/.copilot/skills" ;; + droid) printf '%s' "$HOME/.factory/skills" ;; + gemini) printf '%s' "$HOME/.gemini/skills" ;; + codex) printf '%s' "$HOME/.codex/skills" ;; + claude) printf '%s' "$HOME/.claude/skills" ;; + agents) printf '%s' "$HOME/.agents/skills" ;; + *) return 1 ;; + esac +} + +project_dir() { + case "$1" in + opencode) printf '%s' "$PWD/.opencode/skills" ;; + cursor) printf '%s' "$PWD/.cursor/skills" ;; + windsurf) printf '%s' "$PWD/.windsurf/skills" ;; + antigravity) printf '%s' "$PWD/.agent/skills" ;; + pi) printf '%s' "$PWD/.pi/skills" ;; + kiro) printf '%s' "$PWD/.kiro/skills" ;; + copilot) printf '%s' "$PWD/.github/skills" ;; + droid) printf '%s' "$PWD/.factory/skills" ;; + gemini) printf '%s' "$PWD/.gemini/skills" ;; + codex) printf '%s' "$PWD/.codex/skills" ;; + claude) printf '%s' "$PWD/.claude/skills" ;; + agents) printf '%s' "$PWD/.agents/skills" ;; + *) return 1 ;; + esac +} + +# --- arg parsing ------------------------------------------------------------- +PLATFORM="" +SCOPE="global" +EXPLICIT_DIR="" +while [ $# -gt 0 ]; do + case "$1" in + --project|--here) SCOPE="project" ;; + --dir) shift; EXPLICIT_DIR="${1:-}" ;; + --list) printf 'Supported platforms: %s\n' "$PLATFORMS"; exit 0 ;; + -h|--help) sed -n '2,28p' "${BASH_SOURCE[0]:-$0}" | sed 's/^# \{0,1\}//'; exit 0 ;; + -*) err "unknown flag: $1"; exit 2 ;; + *) PLATFORM="$1" ;; + esac + shift +done + +if [ -z "$PLATFORM" ] && [ -z "$EXPLICIT_DIR" ]; then + err "no platform given." + printf 'Supported platforms: %s\n' "$PLATFORMS" >&2 + printf 'Example: ./scripts/install.sh opencode\n' >&2 + exit 2 +fi + +# --- resolve destination ----------------------------------------------------- +if [ -n "$EXPLICIT_DIR" ]; then + DEST="$EXPLICIT_DIR" +elif [ "$SCOPE" = "project" ]; then + DEST="$(project_dir "$PLATFORM")" || { err "unknown platform: $PLATFORM"; exit 2; } +else + DEST="$(global_dir "$PLATFORM")" || { err "unknown platform: $PLATFORM"; exit 2; } +fi + +SRC="$(resolve_src)" +[ -d "$SRC" ] || { err "could not locate skills/ source at: $SRC"; exit 1; } + +# --- copy flat --------------------------------------------------------------- +info "Installing brooks-lint skills" +info " from: $SRC" +info " to: $DEST" +mkdir -p "$DEST" +cp -R "$SRC"/* "$DEST"/ + +count="$(find "$DEST" -maxdepth 2 -name SKILL.md | wc -l | tr -d ' ')" +ok "Installed $count skills (+ _shared/) into $DEST" +info "Flat layout verified: brooks-* and _shared/ are siblings, so ../_shared/ resolves." +echo +info "Next: open your agent and ask \"review this PR\" / \"audit the architecture\"," +info "or invoke a skill directly (e.g. /brooks-review). See docs/-setup.md."