Skip to content

skills: rewrite the public Ellipsis skill against the new docs - #98

Merged
hbrooks merged 1 commit into
mainfrom
skill-rewrite-from-new-docs
Aug 1, 2026
Merged

skills: rewrite the public Ellipsis skill against the new docs#98
hbrooks merged 1 commit into
mainfrom
skill-rewrite-from-new-docs

Conversation

@hbrooks

@hbrooks hbrooks commented Aug 1, 2026

Copy link
Copy Markdown
Member

What

Rewrites skills/ellipsis/SKILL.md from scratch against the docs rewrite in ellipsis-dev/ellipsis#6101. The old skill was written against the Diátaxis tree and had drifted from the product.

Why it needed a rewrite, not an edit

The old skill was wrong in ways a reader would act on:

  • limits: instead of budget:, and plural triggers: instead of trigger:. Both fail validation today.
  • agent hooks, agent integrations, agent analytics reviewers for what are singular commands.
  • Five dead doc URLs, all pointing at the deleted /docs/get-started and /docs/reference trees.
  • Code review was absent, even though it is one of the two products. So was agent review, the whole on-demand review surface.
  • A "Getting started" walkthrough built around a numbered onboarding flow, which read as marketing rather than something an agent needs to act on.

What is in the new one

Structured to match how the docs are now organized: what Ellipsis is, agents as code, triggers, code review, the CLI, writing a config, sandboxes and permissions, skills, in-sandbox behavior.

New coverage the old skill lacked:

  • Code review: the org-wide toggle, the pipeline stages, and the overlay merge rules that actually trip people up. Declaring pull_requests: is authoritative (a non-matching PR gets no review, not the built-in one); unset filter: inherits the gatekeeper while filter: [] disables it.
  • agent review: reviewing a PR by number, and the bare form that snapshots your working tree to an ellipsis/review/<branch> sidecar.
  • Triggers: all six react surfaces, the watch set vs clone set distinction, and the for default of users: true, bots: false.
  • Sandbox lifetimes: which of dockerfile_append / image.setup / hooks is cached and which is not, since that is the difference between a warm start and a 10-minute install every session.
  • The in-sandbox token is narrower than a human's: it cannot write variables, delete assets, or repoint a default.

Verification

Nothing was ported on trust. Against this repo's actual binary:

  • All 36 documented commands resolve (--help on each).
  • Every documented flag exists on the command it is listed under.

Against the backend's real validators:

  • All three config examples parse through AgentConfig.from_yaml / CodeReviewConfig.from_yaml.
  • Confirmed from source, not docs prose: claude-opus-5 default, $250 session default and platform max, $1k/$10k/$40k trailing ceilings, $10 default budget.run, 8-reviewer cap, cpu 0.125-16, memory 512MB-64GB, timeout 60s-1h, 600s image.setup and 300s hook caps, 10 skills / 50 files / 512 KiB / 64 KiB, the six react surfaces, and all six exit statuses named.

House style: no em dashes, none of simply, easily, just, powerful.

Note

agent config validate is deliberately not documented here. It is still uncommitted work in the tree and POST /v1/configs/validate currently 405s, so documenting it would be a promise the CLI cannot keep. Worth adding in the PR that ships it.

The docs rewrite (ellipsis#6101) reorganized everything product by
product, and the old skill had drifted from it: `limits` instead of
`budget`, plural `triggers`, `agent hooks`/`agent integrations` for what
are now singular, and code review missing entirely even though it is one
of the two products.

Rewritten from the 59 new pages, with every command, flag, field, and
number verified against source rather than ported:

- Code review gets its own section: the org-wide toggle, the pipeline
  stages, and the overlay merge rules that actually catch people out
  (declaring `pull_requests:` is authoritative, unset vs `filter: []`).
- `agent review` is documented at all, including the tree review and its
  sidecar branch.
- Triggers cover all six react surfaces, the watch set vs clone set
  distinction, and the `for` default that excludes bots.
- Every config example validates through the real production validators.
@hbrooks
hbrooks merged commit 64086bd into main Aug 1, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant