rightspec

You are responsible for producing high-quality execution specifications. A specification written with this skill must be executable, stand-alone, and robust to missing context. Any executor — human or agent — should be able to follow it without access to any prior conversation or hidden assumptions.

Specifications are the contract between intent and execution. A vague spec leads to inconsistent results and broken delegation chains.

Purpose

This skill converts vague requests, goals or descriptions into concrete, actionable documents. Use it whenever a user or an upstream agent needs a specification that another executor (human or agent) can follow. The resulting spec enables consistent execution, delegation and evaluation.

Assumptions

• Zero-context tolerance: The executor may have no access to the conversation history or author intent. Do not rely on hidden background knowledge.
• No hallucination: Do not fabricate facts, standards or assumptions. If essential information is missing, state the assumption explicitly and mark it as such.
• Non-specific domain: The skill is generic. It handles research, analysis, process design, software or non-software tasks. Do not hard-code domain specifics unless provided in the prompt.
• Agent and human compatibility: Specifications should use clear language, predictable structure and no ambiguous shorthand. Avoid idioms, colloquial expressions and metaphor — agents parse these poorly and humans interpret them inconsistently.

Key Principles

1. Executability over elegance — Favour clarity and precision over literary style. Eliminate ambiguity even if the wording becomes longer. The executor should never have to guess the author's intent.
2. Explicit assumptions — Whenever the spec depends on context not provided, note the assumption and describe how to revisit it if the assumption proves false. This prevents silent failures downstream.
3. Clear boundaries — Define both what is in scope and what is explicitly not required. A strong spec includes non-goals to prevent scope drift, which is one of the most common failure modes in delegated work.
4. Layer separation — Separate purpose, scope, workflow, outputs and evaluation into distinct sections rather than blending them into narrative prose. This makes specs scannable and auditable.
5. Output contracts — Specify the structure, required fields and quality criteria of deliverables. Define formats (e.g. table, list, narrative), citation requirements and level of detail.
6. Failure and escalation handling — Anticipate missing data, contradictory inputs or tool failures. Also anticipate judgement dilemmas — situations where the executor must make a subjective decision but the spec does not tell them how to decide (e.g., two sections overlap in scope, the output feels too abstract to be useful, or a trade-off has no clear winner). Provide procedures for how the executor should proceed or stop when encountering uncertainty. Specs that only describe the happy path are incomplete.
7. Evaluability — Provide success criteria and an evaluation checklist so that a reviewer can judge whether the spec has been followed.
8. Progressive disclosure — Keep SKILL.md focused on essential guidance. Move detailed templates and rubrics to the templates/ and rubrics/ folders, linking them here. This minimizes token usage when the full detail is not needed.

When to Trigger

Trigger this skill whenever the user requests:

• Drafting or refining a "spec", "specification", "SOP", "execution plan", "workflow contract", "agent prompt spec" or similar.
• Turning a high-level goal or idea into a structured set of instructions for someone else to follow.
• Evaluating or auditing an existing specification for clarity, completeness and executability.

Examples:

• "Write a handoff spec so Agent B can run the analysis without any context from Agent A."
• "Create an SOP for this data pipeline that any agent can follow."
• "Check if this handoff doc is clear and suggest improvements."

Output Modes

Determine which mode to use based on the user's request. When ambiguous, default to Full Spec.

• Full Spec — The user wants a complete, deployable specification. Use the full template and all relevant sections. Trigger phrases: "write a spec", "draft a specification", "create an SOP", "make this executable".
• Skeleton — The user wants a reusable template or framework, not a filled-in document. Deliver the skeleton template with section headers and guidance prompts. Trigger phrases: "give me a framework", "create a template", "just the structure".
• Audit — The user has an existing spec and wants it evaluated. Use the review checklist to assess the document and return structured feedback with concrete improvement suggestions. Trigger phrases: "review this spec", "is this clear enough", "audit this document", "what's missing".
• Change Spec — The user wants to modify one or more existing documents and needs a specification that an executor can follow to apply the changes. Use the change spec template. This mode produces instructions for document modification, not a new document. Trigger phrases: "write a change spec", "spec out these changes", "make a modification plan", "write edit instructions for this doc". Also trigger when the user describes changes to an existing document and wants them formalized for someone else to execute.

Standard Spec Structure

Unless instructed otherwise, organise the spec using the following sections. Omit or merge sections only if truly irrelevant.

1. Title — Name the spec by function, not marketing slogan. Keep it concise.
2. Purpose — One to three sentences defining why the spec exists and the desired outcome.
3. Executor / Intended User — Describe who is expected to follow the spec (e.g., generalist LLM agent, data analyst, human researcher) and any assumed capability level. If the executor is an agent, list available tools explicitly. If the executor is not yet known at the time of writing, mark as TBD and write the spec as if for a generalist executor with no assumed background — this produces the most portable spec. The author or a downstream coordinator can narrow the executor profile later without weakening the spec.
4. Scope — Define the tasks included. Be concrete about what the spec covers.
5. Non-goals — Define adjacent tasks or responsibilities that are explicitly excluded.
6. Definitions and Assumptions — Define terms that could be interpreted differently. List any assumptions about missing information. Provide default behaviours when information is absent.
7. Inputs / Preconditions — List what must be available before starting execution (e.g., specific data, access credentials, constraints, deadlines). If a required input may be missing, describe how the executor should obtain or estimate it.
8. Workflow / Required Process — Describe the standard sequence of activities. For each stage, specify the objective, required actions, intermediate outputs, and minimum quality standards. Avoid writing rigid step-by-step instructions when flexible reasoning is needed, but ensure that essential actions are not skipped. When a stage involves subjective judgement, provide a good example and a bad example with a brief explanation of why the bad example fails. Examples anchor the executor's calibration far more than abstract criteria do.
9. Tool / Resource Policy — If the executor must use tools (e.g., search engines, database connectors, calculators, code execution), specify when to use them, when not to use them, and how to handle tool results. Clarify the priority of evidence from different sources.
10. Output Contract — Define the required deliverable(s) in explicit terms. Specify mandatory sections, ordering, formats, citation requirements, level of detail and distinctions between facts, interpretations and as