mirror of https://github.com/stablyai/orca.git synced 2026-09-21 16:02:20 +00:00

Files

T

Jinwoo Hong fb322046e8 skills: rewrite and trim the seven non-orchestration guides (#19128 )

* skills: rewrite the seven non-orchestration guides to one outcome-first standard

Every guide leads with Result / Done / Safe failure, states conditions instead of case lists, keeps one done bar and one autonomy envelope, and loads references at the point of use via `skills get <topic> --full`. orca-cli drops from 424 to 260 always-loaded lines with three references; orca-per-workspace-env from 794 to 397 with five.

Defects fixed in shipped guides: `emulator camera` (no such command), iOS `permissions` (backend refuses it), Android pane described as in development, `relayGracePeriodSeconds: 0` documented as immediate teardown (it is unbounded), doctor `ok: true` hiding `warn`, an SSH exemplar setting both `jumpHost` and `proxyCommand`, a provisioned-root fetch from `origin`, and the Linear unconfirmed-write rule keyed on four verbs when ten emit it.

The resolver ladder, placeholder rule, and older-binary fallback shared by every installable SKILL.md now come from one skill-stubs/_shared/cli-resolution.md fragment composed by the generator, which also bundles per-guide references into --full. New guards: every ORCA invocation and flag resolves against COMMAND_SPECS, descriptions carry no angle-bracket tokens, reference routing is checked both ways, and an always-loaded size ratchet (300 lines) that guides may leave but never join.

* skills: address review on the SSH recipe and the parity guard

- ssh-host create script: route the bootstrap ssh through the chosen jump host or proxy command, refuse both at once, use StrictHostKeyChecking=accept-new instead of a blind ssh-keyscan append, and pass gh_token/project_root/repo_url/repo_ref to the remote bash via printf %q so a quote in a value cannot break out of the command.
- per-workspace-env envelope: the step-10 workspace test the user asked for is no longer forbidden by the same paragraph.
- linear guides: name the full verb, ORCA linear list-issues.
- parity guard: a prefix reference such as ORCA linear --help or ORCA emulator --webcam now has its flags checked against every command under that prefix; only an exact path or an explicit ... was checked before.

* skills: tighten prose in the seven rewritten guides

Shorter outcome spines, one idea per sentence, no restated rationale after a rule. No rule, command, or pinned phrase changes; 47 net lines fewer across the guides and references.

* skills: route orca-cli and per-workspace-env gates through --reference

Both guides told agents to load --full at a gate because the per-reference
selector did not exist when they were written. Now that main serves
`skills get <topic> --reference references/<file>.md`, load only the
named file and keep --full as the fallback for an older CLI, matching the
orchestration kernel.

* skills: drop outcome-spine boilerplate from the CLI-wrapper guides

The Result/Done/Safe-failure preambles and Next Action closers restated
rules the body already carries. Agents stop fine without them, and for
a CLI wrapper the command surface is the guide. Keeps the one substantive
rule computer-use's Done block added (never report unverified as success)
inside Action Rules. orchestration and per-workspace-env keep theirs:
those are multi-step workflows where the done bar is load-bearing.

(cherry picked from commit 44a74baf73)

* skills: trim the guides and stubs to what agents actually need

- Drop the Result/Done/Safe-failure preambles and Next Action closers from
  the six CLI-wrapper guides; the one substantive rule (never report an
  unverified computer-use action as success) moves into Action Rules.
- Drop the 'guide may be stale, trust --help' lines: the guide is served by
  the binary that runs the commands, so it cannot be stale relative to it.
- Drop the status --json / open --json preflight from every guide; the stub
  no-guessing paragraph now says to start Orca only when a command reports
  it is not running.
- Cut the ORCA placeholder paragraph in each guide to one line that points
  back at the stub's resolution.
- Trim the orchestration, orca-cli, and computer-use descriptions to trigger
  phrases plus one line of scope.
- Remove the older-binary fallback section from every stub (and its two
  shared blocks); a binary without skills get gets one sentence.
- Remove the guide size ratchet test.

* skills: apply independent review cleanup

* skills: clarify guide loading and Linear command discovery

* skills: harden environment recipe examples

* test: complete branch rename journal doubles

* skills: clarify custom Codex launch and refresh model example

* test: deduplicate journal fix now present on main

2026-09-07 00:03:48 -04:00

3.4 KiB

Raw Permalink Blame History

Artifact and skill publishing commands

The publish gate and its recovery are in the guide body. This is the command surface behind it.

Artifacts

ORCA artifacts share <file> --json
ORCA artifacts update <file> --json
ORCA artifacts unshare <file> --json
ORCA artifacts list [--cursor <cursor>] --json
ORCA artifacts delete <id> --json

share, update, and unshare accept .html, .htm, .md, and .markdown files.
share saves the returned edit token in the active Orca profile and never includes it in CLI output. update and unshare look up that record by the resolved local file path, so use the same path and Orca profile that originally shared the file.
list returns one page of artifacts owned by the signed-in account. If JSON output has nextCursor, pass it back with --cursor <cursor>. delete <id> deletes an account-owned artifact by the id returned from list; it does not need the original local file or its edit-token record.
Relative HTML assets are not uploaded. Share a self-contained HTML file or use absolute asset URLs.
If an upload exceeds the CLI transport limit, use the browser upload page as directed by the error.
For local or staging development, --api-url <url> overrides the artifact service; ORCA_ARTIFACTS_API_URL provides the same override for the session.
ORCA_CLOUD_AUTH_TOKEN is a development-only authentication override. Prefer the active Orca profile's normal PropelAuth session and never expose the token in logs or agent output.

Agents can publish one or more installed skills behind one unlisted link through the signed-in Orca account. The user must first grant the separate, default-off permission in Settings → Share Skills ("Allow agents and the Orca CLI to publish skill links"). There is no CLI or RPC way to grant it. Manual publishing from the reviewed desktop flow remains available without this agent permission.

ORCA skills installed --json
ORCA skills share --skill <selector> [--skill <selector> ...] --bundle-name <name> --json

skills installed returns safe discovery IDs and names. It does not expose local skill paths in CLI output. Sharing then verifies that each SKILL.md declares a portable lowercase name containing only letters, numbers, and hyphens.
Each --skill must be an exact discovery ID or an unambiguous installed-skill name. Use IDs when names collide.
Multiple --skill flags create one bundle and one link. --all and arbitrary paths are intentionally unsupported; name every skill the user asked to publish.
Skill folders can contain scripts, configuration, or credentials. The permission is authority, not intent: publish only the skills the user named and never widen the set.
A denied command fails with agent_skill_sharing_disabled. Do not retry; ask the user to enable the switch in the desktop app if they want this action.
Orca stages one agent-published bundle at a time per host. If another publish is active, wait for it to finish before retrying agent_skill_sharing_busy.
Run the command in an Orca terminal on the machine that stores the skills. Forwarded WSL, SSH, and paired-runtime invocations fail before discovery so Orca cannot read from the wrong filesystem.
The JSON result contains the unlisted URL and public share/package/version IDs. It never includes cloud authentication tokens.

3.4 KiB Raw Permalink Blame History

Artifact and skill publishing commands

Artifacts

Skill sharing

3.4 KiB

Raw Permalink Blame History