feat: /goal prompt-crafting skill — docs-conformant goal shape + mechanical length check

[kyle-sexton]

Category: improvement · Source: user experience with /goal invocations.

Problem

Hand-written /goal inputs often don't match the goal shape the official Claude Code docs describe, and /goal has a character limit (user reports 4,000 chars — VERIFY against current official docs during implementation, do not trust this number or training data). LLMs cannot reliably count characters, so conformance needs a mechanical check, not model judgment.

Proposal

A skill that crafts /goal inputs: reads the CURRENT official docs for the goal contract (shape, sections, limits) at authoring time rather than baking them in; drafts the goal from the user's intent; validates length with an actual counter (script — wc/tokenizer, not model estimation) and trims/restructures to fit; outputs the final paste-ready goal.

Notes

• Doc-lookup-at-runtime keeps the skill agnostic to doc drift (limits/shape changing between CC versions).
• Length validation belongs in a bin/ script per the plugin conventions.

[kyle-sexton]

This was generated by AI during triage. · Category: improvement · Priority: priority: high (week directive — pipeline improving itself). Routed status: ready.

/goal prompt-crafting skill — implementation plan

Docs verification. /goal is a confirmed official Claude Code slash command (requires v2.1.139+). The current official docs state the contract explicitly: /goal <condition> sets a session-scoped completion condition; /goal with no argument shows status; /goal clear (aliases stop/off/reset/none/cancel) removes it. Critically, the docs specify "The condition can be up to 4,000 characters" — the issue's ~4,000 figure is verified against the primary source. Source: https://code.claude.com/docs/en/goal

Two verified facts that shape the design:

• The limit is on characters, not tokens. The counter must count characters (e.g. wc -m on the condition string), not tokens — the issue's "wc/tokenizer" phrasing is loose; the correct unit is characters.
• The evaluator only sees the transcript. Per the docs, the small-fast-model evaluator "does not call tools" and judges the condition against "what Claude has already surfaced in the conversation." A well-crafted condition must therefore be transcript-demonstrable, and the docs prescribe an effective-condition shape the skill should target: (a) one measurable end state, (b) a stated check (how Claude proves it, e.g. "npm test exits 0"), (c) constraints that must not change, (d) an optional turn/time bound clause (e.g. "or stop after 20 turns").

Behavioral contract.

• Inputs: the user's natural-language intent for the autonomous run, plus any constraints/bounds they volunteer.
• Doc lookup at runtime: on each invocation the skill reads the current official /goal docs to obtain the character limit and the effective-condition shape. The limit is never hardcoded — it is sourced from the live doc at authoring time. Define graceful degradation: if the fetch fails or the doc structure has shifted, the skill warns and proceeds against the last-known limit rather than silently guessing (recommended), or hard-errors — pick one and state it.
• Draft step: synthesize a candidate condition from intent, structured to the doc-sourced effective-condition shape (measurable end state + stated check + constraints + optional bound clause), and phrased so Claude's own transcript output can demonstrate it.
• Mechanical length check: a deterministic validation script (no model invocation — LLMs cannot reliably count characters) counts the drafted condition's characters and returns pass/fail against the doc-sourced limit. Interface: exit 0 = within limit, non-zero = over, plus the actual count on stdout. Ships with a companion test script per local convention.
• Trim/restructure loop: on fail, tighten/restructure the condition and re-run the counter until pass, preserving the measurable end state, the stated check, and the constraints.
• Output: a paste-ready /goal <condition> string, confirmed under the limit by the actual counter.

Acceptance criteria.

1. The character limit is obtained from the live official docs at runtime; no numeric limit is baked into the skill or its script (grep-clean of 4000/4,000).
2. Length validation is performed by a deterministic script counting characters, not by model estimation; the script exits non-zero when the draft exceeds the doc-sourced limit and is covered by a companion test.
3. The drafted condition conforms to the doc's effective-condition shape and is transcript-demonstrable (does not assume the evaluator runs commands or reads files).
4. On a too-long draft, the skill trims/restructures and re-validates until the counter passes, without dropping the end state, stated check, or constraints.
5. Final output is a paste-ready /goal invocation verified under-limit by the actual counter.
6. Runtime-doc-fetch failure has a defined, non-silent behavior.

Recommended placement. planning. Its interview skill already locks a "task contract (goal, constraints, acceptance criteria)," which is nearly isomorphic to the doc's effective-condition shape — planning produces crafted artifacts from intent, which is exactly this skill's job. Runner-up: session-flow (since /goal is a session-continuation feature, sibling to keep-going/orchestrate); maintainer-vetoable.

Decision defaulted: lives in the planning plugin — veto before merge

---

Convention correction (not a blocker): the issue refers to a bin/ script, but the verified local convention is a mechanical, deterministic validation script under the plugin-root scripts/ directory (not per-skill, not bin/), with exit codes 0=pass / 1=fail / 2=usage-or-env-error, no model invocation, and a companion .test.sh. The "length validation belongs in a dedicated mechanical script" convention is real and well-established across the installed plugins (e.g. skill-quality's check-skill.sh) — only the directory name in the issue is off.

[kyle-sexton]

Design confirmed in interview session (2026-07-19) — decisions binding for implementation

Placement veto resolved: planning confirmed (maintainer-approved this session). The interview task-contract isomorphism argument held.

Skill name decided: draft-goal-condition (2-generator naming round, maintainer-picked). "Condition" is the official docs' term for the artifact — "goal prompt" phrasing belongs in the frontmatter description as a discovery trigger, not in the name. "Draft" signals a reviewable artifact that is authored, not set/run.

Scope addition (maintainer-approved): lever-fit gate as step 0. Before authoring, the skill checks whether /goal is even the right lever, using the official comparison semantics: /goal = next turn starts when previous finishes, stops when evaluator confirms condition; /loop = interval-driven; /schedule (routines) = cloud, sessionless; Monitor tool = event stream a dynamic loop may use internally. Wrong-lever exit routes to the appropriate alternative instead of authoring a goal for interval-shaped work. Source: https://code.claude.com/docs/en/goal (comparison table), https://code.claude.com/docs/en/scheduled-tasks, https://code.claude.com/docs/en/routines

Additional verified doc facts (fetched 2026-07-19, all from https://code.claude.com/docs/en/goal):

• /clear removes any active goal; goals survive --resume/--continue only (turn count/timer/token baseline reset on resume). The skill's output guidance should note this — a goal must be re-set after any /clear.
• Behavior on submitting an over-limit condition is undocumented — no stated error/truncation/rejection semantics. The skill must not assume; the mechanical counter is the only pre-submission guard.
• No official guidance exists on splitting oversized goals; the only documented mitigation is the optional turn/time-bound clause.

Deferred (recorded, not in scope): goal-splitting guidance. Proposing sequential per-phase goals when a brief cannot compress into one provable condition would be our own construction with no official doctrine behind it. Trigger to revisit: the first real brief that cannot fit a single transcript-provable condition under the limit.

Relation to #480: stays a separate skill (loop prompts have no evaluator/char-limit semantics; distinct discovery concerns per docs/PLUGIN-PHILOSOPHY.md split rule). A universal prompt-authoring generalization is deferred until duplication is actually observed across both shipped skills.