feat: add packaged skill command and agent guidance

[ThomasK33]

Summary

• add a top-level agent-terminal skill command that prints the packaged skills/agent-terminal/SKILL.md
• add --json support for that command using the standard success envelope
• make coding-agent guidance prominent in top-level help, including the preloaded-skill vs fallback-command wording
• document the new on-demand skill loading flow in the README
• add unit, contract, and integration coverage for raw output, JSON output, and help discoverability

Why

Coding agents need an obvious, machine-friendly way to load the packaged agent-terminal skill before they start driving session commands. This change keeps the skill as a single source of truth, makes it available directly from the installed CLI, and makes the help output explicitly steer agents toward the preloaded-skill-or-fallback-command workflow.

User-facing behavior

• agent-terminal skill now prints the packaged skill markdown verbatim.
• agent-terminal skill --json now returns the packaged skill content in the normal command envelope.
• agent-terminal --help now tells coding agents to use the preloaded agent-terminal skill when available, and otherwise call agent-terminal skill before other session commands.

Validation

• ~/.local/bin/mise exec -- node ./node_modules/vitest/vitest.mjs run test/integration/cli.test.ts
• ~/.local/bin/mise run ci

Proof / dogfood artifacts

• skill command proof bundle: /tmp/agent-terminal-skill-proof-iaWdon
• help prominence proof bundle: /tmp/agent-terminal-help-proof-BbEZjF
• screenshot examples: /tmp/agent-terminal-skill-proof-iaWdon/skill-command.png, /tmp/agent-terminal-help-proof-BbEZjF/help-prominence.png
• recordings: /tmp/agent-terminal-skill-proof-iaWdon/skill-command.webm, /tmp/agent-terminal-help-proof-BbEZjF/help.webm

Follow-up

• issue Feature request: keep run completion markers out of rendered terminal output #21 tracks the future cleanup to keep internal run completion markers out of rendered terminal output

---

📋 Implementation Plan

Plan: add a packaged-skill CLI command and advertise it in help

Decision and constraints

• Chosen approach: read the packaged skills/agent-terminal/SKILL.md at runtime; defer compile-time embedding/codegen.
• Keep one source of truth: do not duplicate the skill contents inside TypeScript.
• Primary UX goal: agent-terminal skill should be usable by coding agents as a just-in-time skill loader.
• Repo fit: stay consistent with the existing CLI JSON envelope and fail-fast assertion style.

Verified repo facts that shape this plan

• skills/agent-terminal/SKILL.md already exists and the published package already includes skills/ via the package.json files list.
• src/cli/main.ts does not currently register a skill command.
• The codebase already resolves packaged files relative to import.meta.url (for example in src/cli/commands/version.ts and src/renderer/bundledFont.ts), so the same pattern can load the skill from both source-tree runs and installed-package runs.
• A relative URL of ../../../skills/agent-terminal/SKILL.md from src/cli/commands/skill.ts should resolve correctly in both dev (src/...) and built (dist/...) layouts.

Workstream 1 — implement the packaged-file loader and command contract

Files / symbols

• src/cli/commands/skill.ts (new)
• src/util/assert.ts (reuse existing helpers only; no new abstraction unless needed)
• src/protocol/messages.ts and/or src/protocol/schemas.ts if the new JSON result belongs in the machine-facing protocol layer rather than command-local types

Steps

1. Add a small loader helper in src/cli/commands/skill.ts that reads:
   • new URL('../../../skills/agent-terminal/SKILL.md', import.meta.url)
   • using readFile(..., 'utf8')
2. Validate aggressively:
   • assert the read result is a string,
   • assert it is non-empty,
   • map unreadable/missing-file cases to the existing CLI/storage error path instead of silently degrading.
3. Define the user-facing command contract:
   • agent-terminal skill prints the raw skill markdown to stdout with no banner/prefix so agents can ingest it directly.
   • agent-terminal skill --json emits the normal success envelope and includes the exact skill content in the result.
4. Keep the JSON result minimal and explicit, e.g. name, content, and optionally a simple source marker such as source: 'packaged-file' if that proves useful during implementation.

Quality gate after Workstream 1

• Add/adjust a focused unit test that proves the loader returns non-empty content and converts read failures into the expected CLI error shape.
• Confirm the command preserves exact file contents, including trailing newline behavior if the checked-in skill file has one.

Workstream 2 — wire the command into the CLI and advertise it in help

Files / symbols

• src/cli/main.ts
• src/cli/output.ts (reuse existing output helpers if possible; avoid new output plumbing unless necessary)
• README.md only if the existing skill-install guidance becomes misleading after the new command lands

Steps

1. Register a new top-level skill command in src/cli/main.ts.
2. Follow existing informational-command patterns (version, doctor) for action wiring and --json handling.
3. Add a concise top-level help note advertising the command for coding agents, while keeping the help output scannable. Preferred message shape:
   • mention agent-terminal skill,
   • say it is recommended for coding agents,
   • avoid long prose or repeating the full skill inline in help.
4. If needed, update the README skill section so agent-terminal skill becomes the preferred retrieval path while the existing packaged-file copy flow remains documented as a fallback.

Quality gate after Workstream 2

• Integration coverage proves:
  • agent-terminal skill exits successfully and stdout exactly matches skills/agent-terminal/SKILL.md.
  • agent-terminal skill --json returns a valid command envelope containing the same content.
  • top-level --help output includes the new skill guidance.
• No existing informational commands regress.

Workstream 3 — validation, dogfooding, and review artifacts

Automated validation

Run the narrowest relevant checks first, then the broader repo gates:

1. Targeted tests for the new behavior (unit + integration).
2. mise run format-check
3. mise run lint
4. mise run typecheck
5. If the change stays small and runtime permits, finish with mise run ci (fallback: npm run verify if mise is unavailable).

Dogfooding setup

• Use an isolated absolute AGENT_TERMINAL_HOME for all manual CLI runs.
• Prefer direct CLI invocation during development, e.g. npx tsx src/cli/main.ts ....
• Capture the exact commands used so they can be replayed by reviewers.

Dogfooding scenarios

1. Raw skill output
   • Run agent-terminal skill (or the repo-local equivalent during development).
   • Verify the emitted stdout matches the packaged SKILL.md byte-for-byte.
2. Machine-readable output
   • Run agent-terminal skill --json and verify the envelope plus embedded content.
3. Discoverability
   • Run agent-terminal --help and confirm the new guidance is easy to find without dominating the help text.

Review artifacts / proof bundle

Create reviewer-friendly proof for the CLI change, ideally under a new dogfood/ bundle if maintainers want the evidence checked in:

• commands.sh with the exact dogfooding commands,
• one screenshot showing the updated top-level help,
• one terminal recording (asciicast and/or WebM) showing agent-terminal skill and agent-terminal skill --json,
• any captured stdout samples needed for review.

If a checked-in dogfood bundle is unnecessary for this small change, still collect the screenshot and recording during verification so the reviewer can inspect what was exercised.

Acceptance criteria

• agent-terminal skill exists as a top-level command.
• Default mode prints the packaged skill markdown exactly, with no extra wrapper text.
• --json uses the standard CLI success envelope and includes the exact same skill content.
• The implementation reads the packaged file via import.meta.url; there is no handwritten duplicated copy of the skill in source.
• Top-level help explicitly points coding agents to agent-terminal skill.
• Relevant tests and validation pass.

---

Generated with mux • Model: openai:gpt-5.4 • Thinking: xhigh