[YoungDan]

Summary

Adds a repository skill that teaches coding agents how to run this CLI against the contract on current main: JSON in and out, the published exit codes, auth that does not print secrets, and a change loop that stops before approve, deploy, or --yes unless a human explicitly asks.

.agents/skills/deslicer-cli/SKILL.md   # canonical skill
.cursor/skills/deslicer-cli/SKILL.md   # Cursor discovery copy
.claude/skills/deslicer-cli/SKILL.md   # Claude Code discovery copy
tests/skill_cli_commands.rs            # named commands exist; exit table matches; copies match

The skill covers when to use it, install and deslicer --version, schema / --help, -o json and the error envelope (hint, next_command, retryable), the exit-code table, device login vs CI OIDC vs tools token, the change loop (init, inventory validate, plan, show/status, validate, human approval, deploy, verify, revert), and hard rules with short examples. Placeholders only (example-prod, example_servers, https://observer.example.test).

Linked from the README, the skills index, the quickstart, and docs/exit-codes.md.

Lines that contain the product name carry pragma: allowlist secret, the same marker CHANGELOG.md uses. The commit hook treats that name as the configured Docker Hub username. The marker is not part of the CLI contract.

Draft claims corrected against main

The attached drafts were input, not the contract. Checked against src/, docs/exit-codes.md, and deslicer schema's exit-code rows. Issues #263, #264, #265, #268, #269, #270, #271, #272, and the fix PR #273 are still open, so the skill states the behavior and does not cite the tickets.

• Do not pin v1.6.0 or the workshop cell (dap-102, ops.*.show, all_in_one_servers_ag1). This tree is 1.8.0. Tagged v1.8.0 has -o json and the error envelope. schema exists on main and not on that tag. If schema exits 2, fall back to --help and keep -o json.
• Install is Homebrew, cargo install deslicer-cli, or scripts/install.sh, as in docs/installation.md.
• Dry-run is not universal. schema.requires_yes is only the gated applies (change revert, change retry, and the other --yes commands). change plan, change approve, and change deploy mutate with no --yes. Do not probe approve expecting 403 mfa_required; it may succeed.
• The tester exit list omitted 12, 20, 21, 22, 23, and 130. Retryable codes are 9, 10, 22, 23, and 24. Exit 4 is not retryable except auth.pending after auth login --no-wait.
• whoami does not include the API origin for a device session. auth status does (observer_api_url, session_deslicer_api_url, api_url_drift). A tools token is sent only when both OBSERVER_API_URL and DESLICER_API_TOKEN are set; otherwise the keyring session wins. details.verified: false is not proof. A later 401 is.
• The device session is one OS keyring entry (deslicer-cli / device-session), with a 0600 file fallback. It is not per origin, and changing HOME does not clear it. No session-lifetime number is in this repo; read expires_at. DESLICER_DEV_TOKEN is rejected.
• stdout is not always one JSON document. Plan/show/status can emit a second CI object without schema_version. change status prints JSON even for human output. change validate uses --format, not -o. --report-only on a missing report can exit 15. inventory validate prints ok: false and exits 1.
• init with no --provider on a GitHub remote selects App/OIDC (github) and can exit 1 with template path … is not allowlisted. The tools-token path is --provider github-token. That scaffold can write a null apps: key, which inventory validate rejects (apps must be a list).
• Some --help flag descriptions are still blank. Read schema and do not invent a meaning.
• A non-UUID plan id is exit 2 from change validate (local parser). Other commands can turn a generic HTTP 400 into exit 8.
• change verify starts a compile. It is not a read, and there is no universal "completed plans exit 7" rule in this tree. change revert is a dry-run until --yes, and the inverse plan is not auto-approved.
• Success next_command / next_commands may name approve, deploy, or retry --yes. Those are not permission. Error-envelope next_command is the recovery step.

Evidence

• Before: no skill for the agent-native contract; drafts disagreed with main on pins, hosts, dry-run, and exit codes.
• After: cargo test --test skill_cli_commands — 3 passed (commands in the clap tree, exit table matches PUBLISHED_EXIT_CODES, discovery copies match). cargo clippy --test skill_cli_commands -- -D warnings passed. cargo fmt --all applied.

Review

Please have a Product Expert review this first. After that, Roger or Sai should review. Do not merge from this branch; main is protected.

Merge danger

Door: two-way. Removing the skill does not change CLI behavior.

Blast radius: documentation and one new test. README's global-flag row now documents -o / --output / DESLICER_OUTPUT and marks --log-format deprecated, matching src/cli.rs.