From 8e2df4d3e3bc7e8217c5a4e133cfa66c2216ec82 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 29 Aug 2026 18:13:19 +0000 Subject: [PATCH] Expand agent skill stack with tiered install and selective S-tier additions - Add CORE/EXTENDED/OPTIONAL tiers via BERD_SKILLS_TIER - Pin skills CLI version from skills-lock.json (skillsCli: 1.5.23) - Add hallmark, deep-research, last30days to EXTENDED tier - Add Context7 MCP to .cursor/mcp.json - Document conflict warnings, optional tools (OpenSpec, Graphify, Impeccable) Co-authored-by: Prax Lannister --- .agents/skills/README.md | 67 ++++++++++++++- .cursor/mcp.json | 8 ++ AGENTS.md | 13 ++- scripts/install-agent-skills.sh | 139 +++++++++++++++++++++++--------- skills-lock.json | 1 + 5 files changed, 188 insertions(+), 40 deletions(-) create mode 100644 .cursor/mcp.json diff --git a/.agents/skills/README.md b/.agents/skills/README.md index adb3a5465..2a5e1b236 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -39,15 +39,51 @@ discover → interrogate/spec → plan → implement → review → security → Also installed: **Anthropic dev subset** (MCP builder, frontend-design, webapp-testing, etc.) and **awesome-copilot** (417-skill toolbox). +## Install tiers + +The install script supports three tiers via `BERD_SKILLS_TIER`: + +| Tier | Env value | What installs | +| --- | --- | --- | +| **CORE** (default) | `core` | Layered pipeline packs (~740 skills) | +| **EXTENDED** | `extended` | CORE + selective S-tier additions below | +| **ALL** | `all` | EXTENDED + optional hooks (no bulk verticals) | + +```bash +./scripts/install-agent-skills.sh # CORE (default) +BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh +``` + +The script pins `npx skills` to the version in `skills-lock.json` (`skillsCli` field). Override with `SKILLS_CLI_VERSION=latest` if needed. + +## Extended tier additions + +| Skill | Source | Role | +| --- | --- | --- | +| **hallmark** | [nutlope/hallmark](https://github.com/nutlope/hallmark) | UI taste gate — anti-AI-slop design for greenfield pages and redesigns | +| **deep-research** | [24601/agent-deep-research](https://github.com/24601/agent-deep-research) | Async deep research (one skill, not four parallel systems) | +| **last30days** | [mvanhorn/last30days-skill](https://github.com/mvanhorn/last30days-skill) | Recency radar — what people say about a topic in the last 30 days | + +## Conflict warnings + +Do **not** run multiple full methodologies on the same task — pick one primary workflow: + +| Task type | Pick one | Avoid stacking | +| --- | --- | --- | +| Planning | pstack `/poteto-mode` **or** superpowers `/writing-plans` **or** gstack `/plan-ceo-review` | All three in one session | +| Code review | Berd `code-review` **or** compound `ce-code-review` **or** mattpocock `/code-review` | Redundant review passes | +| UI design | hallmark **or** shadcn `/improve` design sections | Duplicate design audits | +| Research | `deep-research` **or** `last30days` **or** compound research agents | Four parallel research systems | + ## Install or refresh ```bash ./scripts/install-agent-skills.sh ``` -The script uses [`npx skills@latest`](https://github.com/vercel-labs/skills) with `-a cursor -y --copy` (Cursor only, project-local). It restores Berd-owned skills after upstream packs are copied and removes junk agent directories. +The script uses [`npx skills`](https://github.com/vercel-labs/skills) (pinned via `skills-lock.json`) with `-a cursor -y --copy` (Cursor only, project-local). It restores Berd-owned skills after upstream packs are copied and removes junk agent directories. -Run twice to verify idempotence. Expect ~740 skills after a full install. +Run twice to verify idempotence. Expect ~740 skills after CORE; ~743 after EXTENDED. ## One-time repo setup @@ -156,13 +192,40 @@ Install manually when relevant: npx skills@latest add supabase/agent-skills --skill '*' -a cursor -y --copy npx skills@latest add cloudflare/skills --skill '*' -a cursor -y --copy npx skills@latest add aws/agent-toolkit-for-aws/skills --skill '*' -a cursor -y --copy +# Remotion vertical (12 skills — install one, not all): +npx skills@latest add remotion-dev/skills --skill remotion-best-practices -a cursor -y --copy +# NVIDIA (343 skills — pick individual skills only): +npx skills@latest add nvidia/skills --list +npx skills@latest add nvidia/skills --skill -a cursor -y --copy ``` +## MCP servers + +Project MCP config: `.cursor/mcp.json` + +| Server | Command | Purpose | +| --- | --- | --- | +| **Context7** | `npx -y @upstash/context7-mcp` | Up-to-date library documentation lookup | + +## Optional runtime tools (manual) + +These are **not** run by the install script. Install when needed: + +| Tool | Install | Notes | +| --- | --- | --- | +| **OpenSpec** | `npm install -g @fission-ai/openspec@latest` then `openspec init` | Creates `openspec/` structure for spec-driven workflows | +| **Graphify** | `uv tool install graphifyy` then `graphify cursor install --project` | Requires `uv` on PATH; visualizes codebase graphs | +| **Impeccable** | `npx impeccable skills install` (project) then `/impeccable init` in Agent chat | Design-system skill; installs to `.cursor/` and `.agents/` | +| **agent-browser CLI** | `npm install -g agent-browser` | Required for browser QA layer (see above) | + ## Searchable armory (do NOT bulk-install) | Pack | Source | Notes | | --- | --- | --- | | **Microsoft skills** | [microsoft/skills](https://github.com/microsoft/skills) | Large repo — context rot risk. Use `npx skills add microsoft/skills --list` and install individual skills only. | +| **wshobson/agents** | [wshobson/agents](https://github.com/wshobson/agents) | 94 plugins — do NOT bulk install | +| **NVIDIA skills** | [nvidia/skills](https://github.com/nvidia/skills) | 343 GPU/AI-Q skills — install individual skills only | +| **everything-claude-code** | various | Redundant with gstack + superpowers + pstack + compound — skip | | Vercel skills CLI | [vercel-labs/skills](https://github.com/vercel-labs/skills) | Package manager for all skills | | Anthropic skills | [anthropics/skills](https://github.com/anthropics/skills) | Dev subset installed; browse for more | | Supabase | [supabase/agent-skills](https://github.com/supabase/agent-skills) | Postgres/Supabase workflows | diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 000000000..d8981ab2f --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} diff --git a/AGENTS.md b/AGENTS.md index bba2d64e8..ef94d5334 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,7 +126,18 @@ local override. ## Agent skills -Project skills live in `.agents/skills/`. Install or refresh with `./scripts/install-agent-skills.sh`. **gstack** (`/plan-ceo-review`, `/ship`, `/qa`, …) also needs its runtime: `./scripts/install-gstack-runtime.sh` (runs automatically at the end of the skill install script). See `.agents/skills/README.md`. +Project skills live in `.agents/skills/`. Install or refresh: + +```bash +./scripts/install-agent-skills.sh # CORE tier (default) +BERD_SKILLS_TIER=extended ./scripts/install-agent-skills.sh # + hallmark, deep-research, last30days +``` + +**gstack** (`/plan-ceo-review`, `/ship`, `/qa`, …) also needs its runtime: `./scripts/install-gstack-runtime.sh` (runs automatically at the end of the skill install script). + +- Stack tiers, conflict warnings, and optional tools: `.agents/skills/README.md` +- MCP servers (Context7): `.cursor/mcp.json` +- Skills CLI version pin: `skills-lock.json` → `skillsCli` ### Issue tracker diff --git a/scripts/install-agent-skills.sh b/scripts/install-agent-skills.sh index 55fd20d90..6730019c2 100755 --- a/scripts/install-agent-skills.sh +++ b/scripts/install-agent-skills.sh @@ -4,6 +4,28 @@ set -euo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" cd "$repo_root" +# Tier: core (default) | extended | all +# core — layered pipeline packs (default Berd stack) +# extended — core + selective S-tier additions (hallmark, deep-research, last30days) +# all — extended + optional verticals (none bulk-installed by default) +readonly BERD_SKILLS_TIER="${BERD_SKILLS_TIER:-core}" + +# Pin skills CLI when skills-lock.json records a version (falls back to latest). +skills_cli_version() { + if [[ -f "$repo_root/skills-lock.json" ]] && command -v jq >/dev/null 2>&1; then + local pinned + pinned="$(jq -r '.skillsCli // empty' "$repo_root/skills-lock.json" 2>/dev/null || true)" + if [[ -n "$pinned" ]]; then + echo "$pinned" + return + fi + fi + echo "latest" +} + +readonly SKILLS_CLI="$(skills_cli_version)" +readonly SKILLS_NPX=(npx --yes "skills@${SKILLS_CLI}") + # Berd-owned skills that must not be overwritten by upstream packs. readonly -a PROTECTED_SKILLS=( assistive-ux @@ -48,14 +70,82 @@ remove_gstack_fixtures() { install_pack() { local spec="$1" shift - npx --yes skills@latest add "$spec" --skill '*' -a cursor -y --copy "$@" + "${SKILLS_NPX[@]}" add "$spec" --skill '*' -a cursor -y --copy "$@" } # Install one or more named skills from a pack. install_skills() { local spec="$1" shift - npx --yes skills@latest add "$spec" -a cursor -y --copy "$@" + "${SKILLS_NPX[@]}" add "$spec" -a cursor -y --copy "$@" +} + +tier_at_least() { + local want="$1" + case "$BERD_SKILLS_TIER" in + core) [[ "$want" == "core" ]] ;; + extended) [[ "$want" == "core" || "$want" == "extended" ]] ;; + all) true ;; + *) + echo "error: unknown BERD_SKILLS_TIER=$BERD_SKILLS_TIER (use core|extended|all)" >&2 + exit 1 + ;; + esac +} + +# ── CORE tier ──────────────────────────────────────────────────────────────── +# Layer: discover → interrogate/spec → plan → implement → review → security → browser QA → ship → learn +install_core_tier() { + echo "Installing CORE tier (skills@${SKILLS_CLI}) …" + + install_pack shadcn/improve + install_pack obra/superpowers + install_pack mattpocock/skills --full-depth + install_pack garrytan/gstack + install_pack cursor/plugins --full-depth + install_pack vercel-labs/agent-skills + + install_pack trailofbits/skills + + install_skills vercel-labs/skills --skill find-skills + install_skills vercel-labs/agent-browser --skill agent-browser + + install_skills anthropics/skills \ + --skill claude-api \ + --skill doc-coauthoring \ + --skill frontend-design \ + --skill mcp-builder \ + --skill skill-creator \ + --skill web-artifacts-builder \ + --skill webapp-testing + + install_pack github/awesome-copilot + + if ! install_pack EveryInc/compound-engineering-plugin 2>/dev/null; then + echo "Note: EveryInc/compound-engineering-plugin install failed; use /add-plugin compound-engineering in Cursor." + fi +} + +# ── EXTENDED tier ──────────────────────────────────────────────────────────── +# Selective S-tier additions — one skill per pack, project-local only. +install_extended_tier() { + echo "Installing EXTENDED tier …" + + install_skills nutlope/hallmark --skill hallmark + install_skills 24601/agent-deep-research --skill deep-research + install_skills mvanhorn/last30days-skill --skill last30days +} + +# ── OPTIONAL tier ──────────────────────────────────────────────────────────── +# Documented verticals — install individually, never bulk (context rot). +# Uncomment or run manually when relevant: +# +# install_skills remotion-dev/skills --skill remotion-best-practices +# install_skills nvidia/skills --skill # 343 skills — pick one +# npx skills add microsoft/skills --list # armory only +# npx skills add wshobson/agents --list # 94 plugins — do NOT bulk install +install_optional_tier() { + echo "OPTIONAL tier: no bulk installs (see .agents/skills/README.md)." } # Optional packs — install manually when relevant (not part of default stack): @@ -66,43 +156,18 @@ install_skills() { # npx skills@latest add microsoft/skills --list # npx skills@latest add microsoft/skills --skill -a cursor -y --copy -echo "Installing agent skill packs into .agents/skills/ …" +echo "BERD_SKILLS_TIER=$BERD_SKILLS_TIER" -# Layer: discover → interrogate/spec → plan → implement → review → security → browser QA → ship → learn +if tier_at_least core; then + install_core_tier +fi + +if tier_at_least extended; then + install_extended_tier +fi -# Core workflow packs -install_pack shadcn/improve -install_pack obra/superpowers -install_pack mattpocock/skills --full-depth -install_pack garrytan/gstack -install_pack cursor/plugins --full-depth -install_pack vercel-labs/agent-skills - -# Security layer -install_pack trailofbits/skills - -# Discovery -install_skills vercel-labs/skills --skill find-skills - -# Browser QA -install_skills vercel-labs/agent-browser --skill agent-browser - -# Anthropic dev/engineering subset (skip pure creative/doc examples) -install_skills anthropics/skills \ - --skill claude-api \ - --skill doc-coauthoring \ - --skill frontend-design \ - --skill mcp-builder \ - --skill skill-creator \ - --skill web-artifacts-builder \ - --skill webapp-testing - -# Toolbox -install_pack github/awesome-copilot - -# Compound engineering (learn layer) — plugin install fallback documented in README -if ! install_pack EveryInc/compound-engineering-plugin 2>/dev/null; then - echo "Note: EveryInc/compound-engineering-plugin install failed; use /add-plugin compound-engineering in Cursor." +if tier_at_least all; then + install_optional_tier fi restore_protected_skills diff --git a/skills-lock.json b/skills-lock.json index a311f72e7..dab9665ff 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -1,5 +1,6 @@ { "version": 1, + "skillsCli": "1.5.23", "skills": { "Make Bot UI": { "source": "cursor/plugins",