docs(skill): document agent-deck try (scratch sessions) in SKILL.md

[tarekrached]

What problem does this solve?

agent-deck try is absent from the main skill, so every time a user asks their agent for a scratch playground the agent rediscovers the command from --help — including the question that actually matters on locked-down machines: whether the experiments directory is configurable (it is: [experiments] directory). Worse, the one place the skill does show try — references/sandbox.md — shows it taking a prompt string (agent-deck try "refactor the auth module"), but the argument is an experiment name (try_cmd.go: fuzzy-matched against existing experiment folders), so the example teaches agents the wrong mental model.

Why this change

Docs-only:

1. New "Scratch Sessions (agent-deck try)" section in skills/agent-deck/SKILL.md: find-or-create semantics, fuzzy matching, --list / --no-session / -c / --sandbox, the [experiments] config block (directory / date_prefix / default_tool), and the "plain folder, not a git repo" note.
2. One row in Essential Commands.
3. Fix the misleading sandbox.md example to use an experiment name and point at the new section.

All claims verified against cmd/agent-deck/try_cmd.go and internal/experiments/experiments.go on main (see Evidence).

User impact

Agents answer "spin up a scratch session" correctly on the first try, including redirecting the experiments dir on machines that only trust specific workspace roots. No behavior change; no code touched.

Evidence

Verified against the implementation on main:

• cmd/agent-deck/try_cmd.go — usage says "Experiment name (fuzzy matched against existing experiments)"; flags --list/-l, --no-session, --sandbox, -c/--cmd; config help prints the [experiments] block.
• internal/session/userconfig.go GetExperimentsSettings() — default directory ~/src/tries, [experiments].directory honored with ExpandPath.
• internal/experiments/experiments.go — folder creation is os.MkdirAll only (no git init), supporting the "plain folder" note.
• The corrected sandbox example: agent-deck try auth-refactor --sandbox matches the real flag set (--sandbox is a try flag).

Real-usage provenance: in my own Claude Code transcripts (2026-07-22), an agent driving agent-deck was instructed to "skip agent-deck try if its path isn't configurable" — a question the skill couldn't answer, so the agent worked around the command instead of configuring it.

Docs-only diff — no test changes; revert-check not applicable.

AI disclosure

• AI-authored (a model wrote most of it)

Model(s), if AI helped: claude-fable-5

Prompt / session log (optional): —

What actually bothered you

My human asked: "I'm surprised how much is being rediscovered every time agent-deck gets invoked by an agent."

Checklist

• Targeted diff: one problem, no unrelated changes
• Tests added or updated for new behavior — docs-only change, no behavior to test
• Test suite passes sandboxed: HOME=$(mktemp -d) XDG_CONFIG_HOME= XDG_DATA_HOME= XDG_CACHE_HOME= go test ./... — not run: docs-only diff, no Go changes (self-check: go-checks skipped)
• If this touches a hot path (list, status, session output, startup, tmux layer): before/after timing evidence included
• CHANGELOG.md untouched (entries are added at landing)
• AI-assisted? Disclosed above, with validation evidence, and I can answer questions about the code
• "Allow edits from maintainers" is enabled

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (2)

• skills/agent-deck/SKILL.md is excluded by !**/*.md
• skills/agent-deck/references/sandbox.md is excluded by !**/*.md

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fa8e01fb-fb74-4e29-893e-873648ee227f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

👋 Thanks for the contribution — intake looks complete.

Your PR body carries everything the maintainer's validation pipeline reads first: the problem, the reasoning, the human intent behind it, and an AI-disclosure. It will be applied, built, and tested against main, and you'll get a structured result within about a day. Merges are always human.

_{gate marker read: ai=authored model=claude-fable-5 intent=yes}