Skill & Agent Authoring
Relevant source files
The following files were used as context for generating this wiki page:
Roughly is a Claude Code plugin that implements gated development pipelines through a coordination-of-subagents model. Authoring within this system involves creating two primary types of Markdown-based artifacts: Skills and Agents. Skills serve as the orchestrators or procedural drivers (e.g., build, fix), while Agents are specialized sub-processes dispatched for isolated tasks (e.g., discovery, code-reviewer).
The core philosophy of authoring in Roughly is centered on "subagent-per-task" execution, ensuring that each implementation step remains isolated with a clean context. This architecture prevents context overflow and enforces high-quality output through mandatory human gates and automated two-stage reviews.
Sources: CLAUDE.md:12, README.md:104-120
Skill Authoring
Skills are Markdown files located at skills/<name>/SKILL.md. They define the sequence of stages, logic, and human gates required to complete a complex workflow.
Skill Metadata and Constraints
Every skill must begin with YAML frontmatter defining its identity and behavioral flags. A critical constraint for coordinator skills (like build, fix, review-plan) is the disable-model-invocation: true flag, which prevents Claude from answering conversationally instead of following the skill's programmatically defined stages.
| Field | Requirement | Description |
|---|---|---|
name | Mandatory | The unique identifier for the skill. |
description | Mandatory | A brief summary of the skill's purpose. |
disable-model-invocation | Required for coordinators | Prevents conversational drift; forces stage execution. |
| Line Limit | ≤ 300 lines | Enforced by internal drift checks to maintain focus. |
Sources: CLAUDE.md:40-52, CONTRIBUTING.md:195-200
Logic and Dispatch Conventions
Skills use specific prose patterns to control the flow of execution. Authors must distinguish between mutually exclusive choices and sequential steps.
- Multi-branch Case Dispatch: When a skill partitions behavior, authors must use explicit language: "evaluate top-to-bottom; execute only the first matching case." This prevents "fall-through" where multiple blocks might execute cumulatively.
- Sequential Structure: For linear steps, authors must use an invariant clause (e.g., "collect ALL decisions BEFORE any disk mutations") to commit to run-in-order semantics.
- Skill Flags: User-facing behavioral changes must be implemented as flags (e.g.,
--ci), not environment variables.
Sources: CONTRIBUTING.md:58-85, CLAUDE.md:68-69
Shared Procedural References (ADR-012)
To prevent duplication between major pipelines (like build and fix), common procedural logic (e.g., Stage 8 wrap-up or Abort handling) is extracted to skills/shared/. Skills reference these at runtime using a single-line directive: Read `skills/shared/<file>.md`.
Sources: CONTRIBUTING.md:104-115, CLAUDE.md:32-35
Agent Authoring
Agents are specialized sub-processes defined in agents/<name>.md. They are designed for isolated, high-focus tasks within a skill's pipeline.
Agent Metadata and word limits
Agents must contain YAML frontmatter specifying their tools and the underlying model (typically sonnet, though opus is reserved for complex tasks like epic-reviewer). Agents are strictly limited to 650 words to ensure context remains lean.
---
name: discovery
description: "Research and scope features before planning."
tools: Glob, Grep, Read, Bash
model: sonnet
---
Sources: CLAUDE.md:40-52, CONTRIBUTING.md:200-202, agents/discovery.md:1-7
The Agent Preamble
Because Claude Code plugins lack an automatic "include" mechanism, all agents must manually inline a canonical sync reference known as the Agent Preamble. This ensures all agents start with identical project context by reading CLAUDE.md and .roughly/known-pitfalls.md.
Sources: agents/agent-preamble.md:1-20, CLAUDE.md:21-25
Architectural Flow
The relationship between the Skill Orchestrator and Agent Subagents is strictly hierarchical. The orchestrator manages the state and gates, while subagents perform discrete units of work.
This diagram illustrates the standard Roughy pipeline flow where the orchestrator dispatches specific agents and manages human approval gates.
Sources: README.md:104-120, skills/fix/SKILL.md:60-100
Verification and Safety Gates
Authoring skills requires implementing safety checks and "pre-flight" migrations. Every major skill must include a byte-identical pre-flight block to detect legacy states from older versions of the plugin.
Plan Review Requirements
Skills that generate implementation plans (like build and fix) must dispatch the review-plan subagent. This agent enforces strict authoring conventions for plans:
- Edit Site Enumeration: Every intended modification must be explicitly numbered.
- Runtime Signals: Any conditional logic in a plan must name its observable signal source (e.g., a specific command or file path).
- Quoted-Wording Markers: Literal text must be marked as
verbatim:orform:to prevent implementation ambiguity.
Sources: skills/review-plan/SKILL.md:36-80, CONTRIBUTING.md:120-145
Two-Stage Review Logic
Orchestrators must perform a two-stage review after an implementation agent returns:
- Spec Compliance: Verified by the orchestrator (inline) to ensure the agent modified only the requested files and followed instructions.
- Quality Check: Running project-specific type checks, linting, and tests.
Sources: README.md:113-116, skills/fix/SKILL.md:180-210
Summary
Skill and Agent authoring in Roughly is a structured process that prioritizes context isolation and human-in-the-loop safety. By adhering to strict line/word limits, mandatory preambles, and explicit dispatch language, authors ensure that the complex multi-stage pipelines remain reliable and technically accurate across various project maturities.
Sources: CLAUDE.md:40-54, README.md:195-205