Skip to content
6 changes: 3 additions & 3 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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"
}
Expand Down
4 changes: 2 additions & 2 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
50 changes: 37 additions & 13 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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
Comment thread
jeremy marked this conversation as resolved.
Resolved
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.
87 changes: 73 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
92 changes: 56 additions & 36 deletions install.md
Original file line number Diff line number Diff line change
@@ -1,97 +1,117 @@
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 (`<cli> 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
Comment thread
jeremy marked this conversation as resolved.
Resolved
# 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 (`<cli> 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.**

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
```
Expand All @@ -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.