Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions skills/cli-conventions/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,40 +18,45 @@ route text.
Singular nouns, one verb per action.

```
agent asset list agent asset delete <asset-id>
agent file list agent file delete <file-id>
agent session start agent config default set <config-id>
```

- **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 `<noun> <verb>`: `asset list`,
`asset get`, `asset upload`, `asset delete`.
Anything with more than one verb gets `<noun> <verb>`: `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 <asset-id>').description('...'), 'rm'),
'DELETE /assets/{id}',
alsoKnownAs(file.command('delete <file-id>').description('...'), 'rm'),
'DELETE /files/{id}',
)
```

## Arguments

Kebab-case placeholders: `<session-id>`, `<config-id>`, `<asset-id>`,
Kebab-case placeholders: `<session-id>`, `<config-id>`, `<file-id>`,
`<api-url>`, `<owner/name>`. Never camelCase, and never a bare `<id>` when the
type matters.

Expand Down Expand Up @@ -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.
Expand Down
9 changes: 5 additions & 4 deletions skills/ellipsis/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <review-id> # 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down
5 changes: 3 additions & 2 deletions src/lib/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand Down