diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b49779b..8ea5aec 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -2,8 +2,8 @@ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "basecamp-skills", "metadata": { - "description": "Basecamp skills for Claude Code", - "version": "0.1.0" + "description": "Agent skills for 37signals products: Basecamp, HEY, and Fizzy", + "version": "0.2.0" }, "owner": { "name": "37signals", @@ -12,7 +12,7 @@ "plugins": [ { "name": "basecamp-skills", - "description": "Basecamp skills for Claude Code — project management, todos, cards, messages, and more.", + "description": "Agent skills for 37signals products, each driving its product's CLI. Bundles the Basecamp skills today; HEY and Fizzy join as their CLIs publish here (see the README).", "source": "./", "category": "productivity" } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ed84bc6..cb465fa 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "basecamp-skills", - "version": "0.1.0", - "description": "Basecamp skills for Claude Code — project management, todos, cards, messages, and more.", + "version": "0.2.0", + "description": "Agent skills for 37signals products, each driving its product's CLI. Bundles the Basecamp skills today; HEY and Fizzy join as their CLIs publish here (see the README).", "author": { "name": "37signals", "email": "support@37signals.com" diff --git a/AGENTS.md b/AGENTS.md index b898ebf..456a609 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,25 +1,49 @@ -# Basecamp Skills Repo +# 37signals Skills Repo -Distribution repo for Basecamp skills for Claude Code. Skills are auto-synced -from [basecamp/basecamp-cli](https://github.com/basecamp/basecamp-cli) on each -release by `scripts/sync-skills.sh`. +Publish target for the agent skills of 37signals products: Basecamp, HEY, and +Fizzy. Each product's CLI mirrors its `skills/` tree into `skills/` here on +release, via that CLI's `scripts/sync-skills.sh`. Nothing under `skills/` is +written by hand. For installation, see [install.md](install.md). +## Sources + +| Source | Skills | Publishes here | +|--------|--------|----------------| +| [basecamp-cli](https://github.com/basecamp/basecamp-cli/tree/main/skills) | `basecamp`, `basecamp-doctor` | On each stable release | +| [hey-cli](https://github.com/basecamp/hey-cli/tree/main/skills) | `hey` | On each stable release. Absent right now: see [#5](https://github.com/basecamp/skills/issues/5) | +| [fizzy-cli](https://github.com/basecamp/fizzy-cli/tree/master/skills) | `fizzy` | Not yet; a release sync is proposed in [fizzy-cli#214](https://github.com/basecamp/fizzy-cli/pull/214) | + ## Key constraints -- **Do not edit skills here.** Edit in `basecamp-cli/skills/` and let the sync - publish them. Manual edits will be overwritten on the next release. -- `.managed-skills` tracks which skill directories are owned by the sync script. - Don't edit it manually. -- Non-skill files (README, AGENTS.md, install.md, .claude-plugin/) are safe to - edit directly — the sync only touches `skills/` and `.managed-skills`. +- **Do not edit skills here.** Edit them in the CLI repo that owns them + (`basecamp-cli/skills/`, `hey-cli/skills/`, `fizzy-cli/skills/`) and let the + next release publish them. Manual edits here are overwritten by that release. +- **Manifests are per source, and owned by the sync scripts.** + `.managed-skills.basecamp-cli` and `.managed-skills.hey-cli` (and + `.managed-skills.fizzy-cli` once Fizzy publishes) each list the skill + directories that source's sync owns. A sync only ever deletes directories + listed in its own file, so one product's release cannot remove another's + skills. The legacy shared `.managed-skills` is kept as a comment-only + tombstone so a CLI still running the old script deletes nothing. Don't edit + any of these manually. +- **Safe to edit directly:** `README.md`, `AGENTS.md`, `install.md`, and + `.claude-plugin/`. The sync only touches `skills/` and its own manifest. ## Repo structure ``` -.claude-plugin/ # Plugin manifest for marketplace install +.claude-plugin/ # Plugin manifest for marketplace install skills/ - basecamp/SKILL.md # Synced from basecamp-cli -.managed-skills # Auto-generated manifest + basecamp/SKILL.md # Synced from basecamp-cli + basecamp-doctor/SKILL.md # Synced from basecamp-cli + hey/SKILL.md # Synced from hey-cli (absent until its next release, see #5) +.managed-skills.basecamp-cli # Skill directories owned by basecamp-cli's sync +.managed-skills.hey-cli # Skill directories owned by hey-cli's sync +.managed-skills # Legacy shared manifest, comment-only tombstone ``` + +The per-source manifests and the tombstone appear with the first release of +each CLI after its sync fix ships; until then the legacy `.managed-skills` is +the only manifest present. diff --git a/README.md b/README.md index e0096a6..3d852f5 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,86 @@ -# Agent Skills for Basecamp +# Agent Skills for 37signals products -[Agent skills](https://agentskills.io) for Basecamp project management — -todos, cards, messages, schedule, campfire, and more. +[Agent skills](https://agentskills.io) for Basecamp, HEY, and Fizzy. Each skill +teaches a coding agent to work in one product through that product's CLI. ``` npx skills add basecamp/skills ``` -See [install.md](install.md) for full setup instructions including CLI authentication. +That installs every skill in `skills/`. See [install.md](install.md) for the +full setup, including installing and authenticating each CLI. -## Available skills +## Skills -| Skill | Description | -|-------|-------------| -| [basecamp](skills/basecamp/SKILL.md) | Full Basecamp CLI integration — todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, and campfire. | +| Skill | Product | Published from | Description | +|-------|---------|----------------|-------------| +| [basecamp](skills/basecamp/SKILL.md) | Basecamp | [basecamp-cli](https://github.com/basecamp/basecamp-cli/tree/main/skills/basecamp) | Interact with Basecamp via the Basecamp CLI. Full API coverage: projects, todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, chat, pings, gauges, assignments, notifications, bookmarks, bubble-up, drafts, notes, calendars, and accounts. | +| [basecamp-doctor](skills/basecamp-doctor/SKILL.md) | Basecamp | [basecamp-cli](https://github.com/basecamp/basecamp-cli/tree/main/skills/basecamp-doctor) | Diagnose Basecamp CLI, authentication, and agent-plugin health. | +| hey | HEY | [hey-cli](https://github.com/basecamp/hey-cli/tree/main/skills/hey) | Interact with HEY via the HEY CLI. Read and send email; manage contacts, boxes, labels, collections, calendars, todos, habits, time tracking, and journal entries. **Missing from `skills/` right now** (see below). | +| fizzy | Fizzy | [fizzy-cli](https://github.com/basecamp/fizzy-cli/tree/master/skills/fizzy) | Interact with Fizzy via the Fizzy CLI. Manage boards, cards, columns, comments, steps, reactions, tags, users, notifications, pins, webhooks, and account settings. **Not published here yet** (see below). | -## Requires +**hey** is absent because of a sync bug +([#5](https://github.com/basecamp/skills/issues/5)): the basecamp-cli and +hey-cli release syncs shared one `.managed-skills` manifest, so each product's +release deleted the other product's skills. Fixes are in flight in both CLIs. +The skill returns automatically on the first hey-cli release after that fix +ships. Until then, get it from +[hey-cli/skills/hey](https://github.com/basecamp/hey-cli/tree/main/skills/hey), +or run `hey skill install`, which installs it from the CLI itself. -- [Basecamp CLI](https://github.com/basecamp/basecamp-cli) (see [install instructions](https://github.com/basecamp/basecamp-cli#installation)) -- An authenticated Basecamp account (`basecamp auth login`) +**fizzy** is not published here yet: fizzy-cli's release has no skills sync. +One is proposed in +[fizzy-cli#214](https://github.com/basecamp/fizzy-cli/pull/214); once it ships, +the skill arrives with the next fizzy-cli release. +Get it from +[fizzy-cli/skills/fizzy](https://github.com/basecamp/fizzy-cli/tree/master/skills/fizzy), +or run `fizzy skill install`. + +## Requirements + +Each skill drives its product's CLI, so install and authenticate the CLI for +the products you use. One is enough; the skills for the others sit idle. + +**Basecamp** — [basecamp-cli](https://github.com/basecamp/basecamp-cli) +([install guide](https://github.com/basecamp/basecamp-cli/blob/main/install.md)) + +```bash +curl -fsSL https://basecamp.com/install-cli | bash # or: brew install --cask basecamp/tap/basecamp-cli +basecamp auth login +``` + +**HEY** — [hey-cli](https://github.com/basecamp/hey-cli) +([install guide](https://github.com/basecamp/hey-cli/blob/main/docs/install.md)) + +```bash +curl -fsSL https://hey.com/install-cli | bash # or: brew install --cask basecamp/tap/hey +hey auth login +``` + +**Fizzy** — [fizzy-cli](https://github.com/basecamp/fizzy-cli) +([install guide](https://github.com/basecamp/fizzy-cli#quick-start)) + +```bash +curl -fsSL https://raw.githubusercontent.com/basecamp/fizzy-cli/master/scripts/install.sh | bash # or: brew install --cask basecamp/tap/fizzy +fizzy setup # personal access token, account, default board +``` + +## Contributing + +Skills are never edited in this repo; a change made here is overwritten by the +next release of the CLI that owns it. Open issues and pull requests against the +skill's source instead: + +- Basecamp: [basecamp-cli/skills](https://github.com/basecamp/basecamp-cli/tree/main/skills) +- HEY: [hey-cli/skills](https://github.com/basecamp/hey-cli/tree/main/skills) +- Fizzy: [fizzy-cli/skills](https://github.com/basecamp/fizzy-cli/tree/master/skills) + +Issues about this repo itself (the README, install.md, the plugin manifest, or +the publishing) belong here. ## About -These skills are automatically published from -[basecamp/basecamp-cli](https://github.com/basecamp/basecamp-cli) on each -release. To contribute, open issues or PRs there. +This repo is a publish target. On each release, a CLI's `scripts/sync-skills.sh` +copies its `skills/` tree into `skills/` here, records the directories it owns +in a manifest, and commits straight to `main`. Only the README, install.md, +AGENTS.md, and `.claude-plugin/` are written by hand. diff --git a/install.md b/install.md index e63c96b..43f9c5d 100644 --- a/install.md +++ b/install.md @@ -1,87 +1,107 @@ -I want you to install Agent Skills for Basecamp for me. Execute all steps autonomously. +I want you to install Agent Skills for 37signals products for me. Execute all steps autonomously. -OBJECTIVE: Install Basecamp agent skills so your agent can manage projects, todos, cards, messages, schedule, campfire, and more via the Basecamp CLI. +OBJECTIVE: Install the agent skills for the 37signals products you use — Basecamp, HEY, Fizzy, any or all — plus the CLI behind each, so your agent can work in those products. -DONE WHEN: `basecamp --version && basecamp auth status` both succeed and the basecamp skill is installed in your agent. +DONE WHEN: every product you chose in the TODO reports signed in (` auth status --json | grep -q '"authenticated": true'` succeeds for each of `basecamp`, `hey`, `fizzy` that you chose — at least one, and only those; a CLI on this machine for a product you did not choose is left alone) and `npx skills list` shows the skills from this repo. ## TODO -- [ ] Install Basecamp CLI -- [ ] Authenticate with Basecamp +- [ ] Install Basecamp CLI (only if you use Basecamp) +- [ ] Authenticate with Basecamp (only if you use Basecamp) +- [ ] Install and sign in to HEY CLI (only if you use HEY) +- [ ] Install and sign in to Fizzy CLI (only if you use Fizzy) - [ ] Install skills ## Step 0: Install Basecamp CLI -Check if the Basecamp CLI is already installed: +Only if you use Basecamp; otherwise mark this TODO done and continue. The basecamp skills need the Basecamp CLI. Skip the install if `basecamp --version` already succeeds. See the [Basecamp CLI install guide](https://github.com/basecamp/basecamp-cli/blob/main/install.md) for other install methods. ```bash -basecamp --version +curl -fsSL https://basecamp.com/install-cli | bash ``` -If `basecamp` is not installed, install it. See the [Basecamp CLI install guide](https://github.com/basecamp/basecamp-cli/blob/main/INSTALL.md) for full options, or use Homebrew: - +**Verify:** ```bash -brew install --cask basecamp/tap/basecamp +basecamp --version +# Expected: basecamp version X.Y.Z ``` -If `basecamp: command not found` after install, add to PATH: +## Step 1: Authenticate with Basecamp + +Only if you use Basecamp; otherwise mark this TODO done and continue. Skip if `basecamp auth status` already reports authenticated (the installer runs setup on an interactive terminal). Otherwise this opens a browser for OAuth; grant access when prompted. Credentials are stored in the system keychain. ```bash -export PATH="$HOME/.local/bin:$PATH" +basecamp auth login ``` **Verify:** ```bash -basecamp --version -# Expected: basecamp version X.Y.Z +basecamp auth status --json | grep -q '"authenticated": true' && echo OK +# Expected: OK. The status command exits 0 even when signed out, so test the flag. ``` -## Step 1: Authenticate with Basecamp +## Step 2: Install and sign in to HEY CLI + +Only if you use HEY; otherwise mark this TODO done and continue. Run all three lines: the first installs the CLI only when `hey` is not already on PATH (see the [HEY CLI install guide](https://github.com/basecamp/hey-cli/blob/main/docs/install.md) for other install methods), the second signs in only when not already signed in (it opens a browser), and the third installs the hey skill from the CLI itself, since it is temporarily missing from this repo (see the [README](README.md)) — it runs even when the CLI was already installed. ```bash -basecamp auth login +command -v hey >/dev/null || curl -fsSL https://hey.com/install-cli | bash +hey auth status --json | grep -q '"authenticated": true' || hey auth login +hey skill install ``` -This opens a browser for OAuth. Grant access when prompted. The CLI stores credentials securely in the system keychain. - **Verify:** ```bash -basecamp auth status -# Expected: Authenticated (scope: read) +hey version && hey auth status --json | grep -q '"authenticated": true' && echo OK +# Expected: a version line, then OK ``` -## Step 2: Install skills +## Step 3: Install and sign in to Fizzy CLI + +Only if you use Fizzy; otherwise mark this TODO done and continue. Run all three lines: the first installs the CLI only when `fizzy` is not already on PATH (see the [Fizzy CLI README](https://github.com/basecamp/fizzy-cli#quick-start) for other install methods), the second runs `fizzy setup` — which asks for a personal access token and an account — only when not already signed in, and the third installs the fizzy skill from the CLI itself, since it is not published in this repo yet (see the [README](README.md)) — it runs even when the CLI was already installed. ```bash -npx skills add basecamp/skills +command -v fizzy >/dev/null || curl -fsSL https://raw.githubusercontent.com/basecamp/fizzy-cli/master/scripts/install.sh | bash +fizzy auth status --json | grep -q '"authenticated": true' || fizzy setup +fizzy skill install ``` -This installs skills from this repo into your agent using the [Agent Skills](https://agentskills.io) open standard. The installer auto-detects your agent and places skills in the correct directory. It supports Claude Code, Cursor, Codex, VS Code, Gemini CLI, Goose, Amp, OpenCode, and others. - -To install for a specific agent: - +**Verify:** ```bash -npx skills add basecamp/skills -a claude-code +fizzy --version && fizzy auth status --json | grep -q '"authenticated": true' && echo OK +# Expected: fizzy version X.Y.Z, then OK ``` -To install globally (available across all projects): +## Step 4: Install skills + +Run this whichever products you use. Installs every skill in this repo into your agent using the [Agent Skills](https://agentskills.io) open standard. The installer auto-detects your agent (Claude Code, Cursor, Codex, VS Code, Gemini CLI, Goose, Amp, OpenCode, and others) and places skills in the right directory. Add `-a claude-code` to target one agent, or `-g` to install globally. ```bash -npx skills add basecamp/skills -g +npx skills add basecamp/skills ``` **Verify:** ```bash npx skills list -# Expected: basecamp skill listed +# Expected: basecamp and basecamp-doctor listed (hey too, once it is published here) ``` -Restart your agent session to pick up the new skills. The basecamp skill provides full CLI coverage: projects, todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, and campfire. +Restart your agent session to pick up the new skills. -EXECUTE NOW: Start with Step 0. Mark TODO items complete as you go. Stop when `basecamp --version && basecamp auth status` both succeed and the basecamp skill is installed. +EXECUTE NOW: Start with Step 0. Mark TODO items complete as you go. Stop when every product you chose in the TODO reports signed in (` auth status --json | grep -q '"authenticated": true'` succeeds for each of `basecamp`, `hey`, `fizzy` that you chose — at least one, and only those; a CLI on this machine for a product you did not choose is left alone) and `npx skills list` shows the skills from this repo. --- +## Optional: Homebrew installs + +**Do not execute this section unless explicitly requested.** + +```bash +brew install --cask basecamp/tap/basecamp-cli +brew install --cask basecamp/tap/hey +brew install --cask basecamp/tap/fizzy +``` + ## Optional: Manual installation **Do not execute this section unless explicitly requested.** @@ -89,9 +109,9 @@ EXECUTE NOW: Start with Step 0. Mark TODO items complete as you go. Stop when `b Clone this repo and symlink skills into your agent's skill directory manually: ```bash -git clone https://github.com/basecamp/skills ~/.basecamp-skills +git clone https://github.com/basecamp/skills ~/.37signals-skills mkdir -p ~/.claude/skills -for skill in ~/.basecamp-skills/skills/*/; do +for skill in ~/.37signals-skills/skills/*/; do ln -sfn "$skill" ~/.claude/skills/"$(basename "$skill")" done ``` @@ -100,7 +120,7 @@ For per-project installation: ```bash mkdir -p .claude/skills -ln -sfn ~/.basecamp-skills/skills/basecamp .claude/skills/basecamp +ln -sfn ~/.37signals-skills/skills/basecamp .claude/skills/basecamp ``` -Update with `cd ~/.basecamp-skills && git pull`. Symlinks pick up changes immediately. +Update with `cd ~/.37signals-skills && git pull`. Symlinks pick up changes immediately.