From f9add74fa5f43ffb920091de2e8743f18161d90a Mon Sep 17 00:00:00 2001 From: hbrooks Date: Tue, 11 Aug 2026 00:17:10 -0400 Subject: [PATCH] skills: catch the conventions and platform docs up to the file rename `agent asset` became `agent file`, but both skill files still taught the old spelling. That matters more than a stale README: cli-conventions is what a coding agent reads before naming a new command, and the ellipsis skill is what `agent help --interactive` answers from, so each one hands out a command that no longer appears in `--help`. Also documents the rule the rename established, since it was not written down anywhere: a renamed command keeps its old name as a hidden alias. Fixes two smaller staleness bugs found in the same sweep: the ellipsis skill showed `agent review --no-post` with no pull request number, which the server stopped accepting when `pull_request_number` became required, and a comment in types.ts still pointed at `GET /github/members`. --- skills/cli-conventions/SKILL.md | 27 ++++++++++++++++----------- skills/ellipsis/SKILL.md | 9 +++++---- src/lib/types.ts | 5 +++-- 3 files changed, 24 insertions(+), 17 deletions(-) diff --git a/skills/cli-conventions/SKILL.md b/skills/cli-conventions/SKILL.md index c9b0c9a..063dfad 100644 --- a/skills/cli-conventions/SKILL.md +++ b/skills/cli-conventions/SKILL.md @@ -18,40 +18,45 @@ route text. Singular nouns, one verb per action. ``` -agent asset list agent asset delete +agent file list agent file delete agent session start agent config default set ``` -- **The noun is singular, always.** `asset`, not `assets`. `hook`, not +- **The noun is singular, always.** `file`, not `files`. `hook`, not `hooks`. `analytics` is the sole exception: it is a mass noun with no singular form. - **The plural still works, hidden.** Register it with `alsoKnownAs`, which - keeps it callable but strips it from every help surface. `agent assets list` + keeps it callable but strips it from every help surface. `agent files list` runs and prints nothing extra. +- **A renamed command keeps its old name, hidden.** `agent file` was `agent + asset`, so it registers `asset` and `assets` alongside `files`. A caller who + learned the old spelling is never told it is wrong. - **Read-only integration browsers use a bare plural leaf**: `github repos`, `slack channels`, `linear teams`, `sentry orgs`. They have no get/create/delete to disambiguate against, so the extra `list` is noise. - Anything with more than one verb gets ` `: `asset list`, - `asset get`, `asset upload`, `asset delete`. + Anything with more than one verb gets ` `: `file list`, + `file get`, `file upload`, `file delete`. - **`delete` is the shown verb**, with `rm` as a hidden alias. Never the reverse. - **`list` is the shown verb**, with `ls` hidden. ```ts -const asset = alsoKnownAs( - program.command('asset').description('...'), +const file = alsoKnownAs( + program.command('file').description('...'), + 'files', + 'asset', 'assets', ) apiRoutes( - alsoKnownAs(asset.command('delete ').description('...'), 'rm'), - 'DELETE /assets/{id}', + alsoKnownAs(file.command('delete ').description('...'), 'rm'), + 'DELETE /files/{id}', ) ``` ## Arguments -Kebab-case placeholders: ``, ``, ``, +Kebab-case placeholders: ``, ``, ``, ``, ``. Never camelCase, and never a bare `` when the type matters. @@ -93,7 +98,7 @@ Other rules: One line, imperative verb first, no trailing period. - **Say what the caller gets, not which endpoint answers.** `List your stored - assets, newest first` — not `List assets (GET /assets)`. + files, newest first` — not `List files (GET /files)`. - **Routes go in the long help**, last, via `apiRoutes(cmd, 'GET /...')`. When a command also has an `addHelpText('after', ...)` usage note, chain the note *inside* the `apiRoutes()` call so the route line still lands last. diff --git a/skills/ellipsis/SKILL.md b/skills/ellipsis/SKILL.md index 686e130..47a6365 100644 --- a/skills/ellipsis/SKILL.md +++ b/skills/ellipsis/SKILL.md @@ -427,9 +427,10 @@ Review pull requests on demand, without waiting for a push: ```sh agent review 519 # review a pull request by number agent review 519 --full # re-review the whole PR, ignoring earlier reviews -agent review --no-post # print findings instead of posting to GitHub +agent review 519 --no-post # print findings instead of posting to GitHub agent review list --repo api # a repository's reviews, newest first agent review get # one review's findings, scope, and whether it posted +agent review init # scaffold code_review.yaml for this repository ``` Which pipeline runs is not a parameter. An explicit review resolves the same @@ -460,7 +461,7 @@ agent variable list # names and timestamps only agent integration # what is connected, in one table agent github repos # also github members, slack channels, # linear teams, sentry orgs -agent asset upload shot.png # store a PNG, print an org-gated link +agent file upload shot.png # store a PNG, print an org-gated link ``` Sync local Claude Code sessions into the same searchable history, then hand work @@ -646,11 +647,11 @@ If `ELLIPSIS_SANDBOX_ID` is set in the environment, you are the agent in an Ellipsis session. The `agent` CLI is pre-installed and pre-authenticated with a session-scoped token, so you can start child sessions, search the team's session history, read analytics, and upload screenshots as org-gated links -(`agent asset upload shot.png`) with no login. `agent session connect` with no +(`agent file upload shot.png`) with no login. `agent session connect` with no id connects to the current session, via `ELLIPSIS_SESSION_ID`. That token is deliberately narrower than a human's. It can list variable names -but not set or delete them, cannot delete an asset, and cannot repoint an +but not set or delete them, cannot delete a file, and cannot repoint an account or repository default. An agent cannot overwrite the team's credentials or destroy the evidence it posted. diff --git a/src/lib/types.ts b/src/lib/types.ts index da884d0..1ae8209 100644 --- a/src/lib/types.ts +++ b/src/lib/types.ts @@ -413,8 +413,9 @@ export interface ListAgentSessionsQuery { start?: string end?: string limit?: number - // A GitHub account id (GET /github/members); scopes the list to sessions - // attributed to that developer. The CLI resolves it from a --author login. + // A GitHub account id (GET /integrations/github/members); scopes the list to + // sessions attributed to that developer. The CLI resolves it from a --author + // login. author_id?: number }