skills: tell the whole story in the public skill, and fix what went stale

[hbrooks]

Summary

Rewrites skills/ellipsis/SKILL.md. The skill explained the mechanics of the platform without the problem it solves, so a coding agent reading it could operate Ellipsis but not explain why a team would adopt it.

Added the story:

• The problem: agents run on a developer's own credentials, so an agent's blast radius is a person's blast radius; spend is invisible until the invoice; setup lives in one engineer's dotfiles; no transcript outlives the session. Plus the individual-developer half: agents clobber each other, and they die when the laptop closes.
• Why cloud beats laptop: parallelism, shared config, governance, always on.
• Benefits that were missing entirely: usage-based pricing with no seats, any model (Claude/GPT/GLM, BYOK, BYO gateway), structured output as a typed contract, and a new "Sessions you can audit" section covering observability, attribution, retention, and analytics.

Fixed what went stale. Code review had drifted furthest from the product:

• include_default_reviewers no longer exists. A stage list replaces that stage wholesale.
• One filename, code_review.yaml, and its position decides scope: a repo root governs that repo, the .ellipsis repo's copy governs the org. The old agents/code_review.yaml convention is now a config error.
• enabled: false does the opposite of what the skill claimed: it marks the file inactive so the next rung applies, rather than suppressing review.
• Documented the description stage, and that the gatekeeper is opt-in rather than built in.
• Corrected agent session handoff, shown without its required --parent, and softened "every command is singular" since github, slack, budget, and usage have no plural alias.

Two bugs found while verifying, not fixed here

1. agent review init scaffolds an unusable file. It writes to agents/code_review.yaml (src/commands/review.ts:37), a path the backend now rejects via assert_valid_for_location. Its template also still advertises include_default_reviewers and "three reviewer lenses."
2. Bare agent review and --branch send fields the API dropped. buildCreateRequest sends branch/sha/config_id/model/budget; CreateReviewRequest now takes only owner, repo, pull_request_number, scope, and post.

This PR documents only the pull-request review path, so the skill is honest either way.

Test plan

• All 3 deployable YAML examples validate against the live schema, through the real parse_agent_config_yaml and parse_code_review_config_yaml validators (not a YAML-syntax check)
• All 33 documented commands resolve, and every documented flag confirmed against --help
• All 20 docs links return 200
• bun run typecheck clean; 426 tests pass
• No em dashes; no YC or GTM material

Important

Rewrites skills/ellipsis/SKILL.md to explain the problem cloud agents solve, not just the mechanics of the platform.

Added narrative:

• Problem: agents on personal credentials have unbounded blast radius and spend; setup lives in one engineer's dotfiles; no audit trail; individual developers see clobbering and session loss on laptop closure.
• Why cloud beats laptop: parallelism (each session gets isolated sandbox), shared config, governance (budgets and scoped credentials), always on (GitHub/Slack/Sentry events and schedules).
• Missing benefits: usage-based pricing with no seats, multiple model providers (Claude, GPT, GLM, BYOK, gateway proxy), structured output as typed contract.
• New section "Sessions you can audit": covers observability (live feed with lossless resume), attribution (person/key/parent session), retention, and analytics split human vs. bot.

Fixed stale code-review docs:

• include_default_reviewers and agents/code_review.yaml paths are now errors; pipeline file location (repo root or .ellipsis repo root) determines scope, and location entirely replaces the organizational default.
• enabled: false marks file inactive (falls through to org file/built-in), not suppressing review.
• Documented description stage (default Haiku agent) and clarified filter gatekeeper is opt-in, not built-in.
• Declared stages as wholesale replacements, not append; review inherits default, description and filter inherit defaults unless declared.
• Documented "bots are reviewed too" and reviewed findings attach to the commit.

Updated CLI and config:

• Added agent me, agent review --full, clarified --detach, --parent for handoff.
• Corrected credential precedence and ELLIPSIS_API_BASE_URL.
• Clarified sandbox image is cached per repo set/commit, so repeat sessions boot in seconds.
• Added explanation of per-developer caps and structured_output as exit contract.
• Updated links and added Permissions, Conversations, Skills, Which PRs Get Reviewed docs.

^{This description was created by for df96073. It will automatically update as commits are pushed.}

[ellipsis-dev]

Caution

Changes requested ❌ — 2 issues

Reviewed df96073 in 6 minutes, 33 seconds.

• Reviewed 1 commit with 397 lines of code in 1 file
• Ran 1 review agent producing 2 comments where 2 were posted
• This pipeline runs no gatekeeper, so findings are posted as written.
• View full details on ellipsis.dev

^{This review was created by . You can tag @ellipsis in this pull request.}

[ellipsis-dev]

The --no-post example lost its PR number when the working-tree paragraph was deleted, so it now demonstrates the local snapshot path instead of a PR review. Add the number.

This hunk deleted the bare agent review / --branch lines and the paragraph that explained the snapshot behavior, but kept agent review --no-post under the heading "Review pull requests on demand". With no PR number, buildCreateRequest takes the local branch (src/commands/review.ts:481-487): it creates a WIP commit and force-pushes it to ellipsis/review/<branch>, and hardcodes post: false so --no-post is a no-op there (see the comment at review.ts:478-480). A reader following this line to skip posting on PR 519 instead pushes a branch to their remote, and per this PR's own description that path sends fields the API dropped.

Suggested change

	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 --full # re-review the whole PR, ignoring earlier reviews
	agent review 519 --no-post # print findings instead of posting to GitHub

[ellipsis-dev]

"Which pipeline runs is not a parameter" contradicts the shipped CLI: agent review -c/--config <id> selects a pipeline, and the agent review default ladder is read only by explicit reviews.

src/commands/review.ts:65 registers -c, --config <id> ('run a saved agent config instead of the built-in reviewer'), and registerReviewDefaults (review.ts:275-278) documents a two-rung account/per-repo default whose comment states the opposite of this paragraph: 'Only explicit reviews read it: webhook reviews keep matching the pipelines' own pull_requests: filters.' Those endpoints are live in src/lib/api.ts:376-391. An agent using this skill will tell a user they cannot choose a pipeline for an explicit review, and has no way to explain a broken default rung, which fails explicit reviews closed (review.ts:349-352).