coily dispatch: emit reference docs from the CLI, shrink the skill to a trigger shim #11

New issue

Open

opened 2026-05-23 20:53:57 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-05-23 20:53:57 +00:00

Owner

Originally filed by @coilysiren on 2026-05-21T13:23:09Z - https://github.com/coilysiren/coily/issues/311

Problem - The coily-dispatch skill body documents how coily dispatch behaves (headless vs interactive, detach mechanics, refusal conditions, out-of-scope). coily dispatch is a hard-triggered, agent-only command. Humans do not invoke it directly. So that half of the skill body is never read by a human and never fuzzy-matched. It is pure agent-facing reference text.

A skill earns its keep on the trigger surface: the description, the synonyms, the dictation-miss tolerance. That part of coily-dispatch is real and should stay (the voice-collision table, owner/repo fuzzy resolution, when-to-fire). The reference half is not skill-shaped. It is --help output that happens to be written for an agent.

Proposal

Split the current coily-dispatch SKILL.md along the seam:
- Stays in the skill: frontmatter triggers, dictation-collision table, fuzzy owner/repo resolution, when-to-fire / when-not-to-fire.
- Moves into the CLI: how headless vs interactive is picked, the detach-and-watch mechanics, refusal conditions, what coily dispatch owns vs what the skill owns.
Add coily dispatch help (or coily dispatch --explain) that emits the reference text. Gate it behind the subcommand so a normal coily dispatch headless ... invocation stays cheap. The agent reads the wall only when it needs to.
Skill body ends with: "for command behavior, run coily dispatch help."

Why this is better than a skill body

Single source of truth. CLI-emitted docs colocate with coily.yaml and the dispatch code. They version together. A skill markdown drifts from the actual command.
Portable. coily dispatch help is readable by any agent harness (Codex, Cursor, a bare claude -p), not just Claude Code's skill loader.
Honest about the interface. The skill stops pretending the reference half is human-facing.

Origin: design discussion with Kai about agent-only CLIs and what actually belongs in a skill vs the CLI itself.

_Originally filed by @coilysiren on 2026-05-21T13:23:09Z - [https://github.com/coilysiren/coily/issues/311](https://github.com/coilysiren/coily/issues/311)_ **Problem** - The `coily-dispatch` skill body documents how `coily dispatch` behaves (headless vs interactive, detach mechanics, refusal conditions, out-of-scope). `coily dispatch` is a hard-triggered, agent-only command. Humans do not invoke it directly. So that half of the skill body is never read by a human and never fuzzy-matched. It is pure agent-facing reference text. A skill earns its keep on the trigger surface: the description, the synonyms, the dictation-miss tolerance. That part of `coily-dispatch` is real and should stay (the voice-collision table, owner/repo fuzzy resolution, when-to-fire). The reference half is not skill-shaped. It is `--help` output that happens to be written for an agent. **Proposal** 1. Split the current `coily-dispatch` SKILL.md along the seam: - Stays in the skill: frontmatter triggers, dictation-collision table, fuzzy owner/repo resolution, when-to-fire / when-not-to-fire. - Moves into the CLI: how headless vs interactive is picked, the detach-and-watch mechanics, refusal conditions, what `coily dispatch` owns vs what the skill owns. 2. Add `coily dispatch help` (or `coily dispatch --explain`) that emits the reference text. Gate it behind the subcommand so a normal `coily dispatch headless ...` invocation stays cheap. The agent reads the wall only when it needs to. 3. Skill body ends with: "for command behavior, run `coily dispatch help`." **Why this is better than a skill body** - Single source of truth. CLI-emitted docs colocate with `coily.yaml` and the dispatch code. They version together. A skill markdown drifts from the actual command. - Portable. `coily dispatch help` is readable by any agent harness (Codex, Cursor, a bare `claude -p`), not just Claude Code's skill loader. - Honest about the interface. The skill stops pretending the reference half is human-facing. Origin: design discussion with Kai about agent-only CLIs and what actually belongs in a skill vs the CLI itself.

coilysiren referenced this issue

2026-05-23 20:54:04 +00:00

coily-action: GitHub Action wrapper for lockdown-audited Claude Code runs #61

coilysiren added the

label

2026-05-31 01:52:53 +00:00

coilysiren added

and removed

labels

2026-05-31 06:59:56 +00:00