
analysis-skills
Collection of analysis skills including code review and iterative answer self-review with blind sub-agent verification
- GitHub stars
- 21
Install
/plugin install analysis-skills@buyoung-agent-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add buYoung/skills.
Contents
Discovered from sourceSkills 25
AGENTS.md Generation Capability
This skill enables the agent to generate AGENTS.md files that serve as contributor guides for AI agents working on a codebase.
Core Capability
- Function: Analyze repository boundaries and generate or update a standardized
AGENTS.mddocument - Output Format: Markdown file with structured sections
- Writing Goal: Reader-centered guidance informed by ISO 24495-1:2023 plain language principles: contributors can find the relevant guidance, understand the verified contract, and use it for their next change
- Character Limit: Dynamic, based on repository LOC (Lines of Code)
- Monorepo Support: Automatically detects monorepo structures and generates hierarchical documentation (Root + Packages)
- Update Support: Refreshes only standard sections in a marked, managed
AGENTS.md, preserving user-defined custom sections. Unmarked files require a concrete change preview and one-time adoption confirmation; files without matching standard headings require an explicit full-regeneration request
Output Sections
Single Repo / Package Document (4-5 Sections)
For single repositories or individual packages in a monorepo:
- Overview: 1-2 sentence project description (abstract, no tool/framework lists)
- Ownership Map: Optional, evidence-backed map split into stable ownership boundaries and active change routes — entry points, state owners, behavior decision points, external surfaces, contracts/side effects, verification anchors, and recent history-informed routes. Omit this section when the repository does not expose stable boundaries or active routes worth documenting; never invent ownership just to fill the template.
- Core Behaviors & Patterns: Cross-cutting patterns traced through full flows — error propagation chains, state lifecycle transitions, cross-boundary wiring mechanisms, resilience/recovery strategies, shared resource management. Discovered via multi-phase analysis: surface idiom detection, then deep tracing across layers.
- Conventions: Naming, code style, API/interface design conventions (callback naming, return value shapes, method responsibility splitting), configuration/registration structure, boundary conventions (error flattening, schema drift absorption, containment rules), component composition patterns.
- Working Agreements: Rules for agent behavior and communication
Monorepo Root Document (2-3 Sections)
For the root of a monorepo structure:
- Overview: 1-2 sentences describing the monorepo's purpose
- Ownership Map: Optional map split into stable package-level responsibility boundaries and active cross-package change routes. At monorepo roots, package names plus manifests, public exports, README text, dependency direction, and recent confirmed change clusters can establish enough evidence; omit the section when the root exposes only an uninformative package list.
- Working Agreements: Common working agreements applicable to all packages
Operation Modes
Generate vs Update
- Generate: Creates a new
AGENTS.mdfrom scratch (default when noAGENTS.mdexists) - Update: Refreshes standard sections in an existing managed
AGENTS.mdwhile preserving custom sections. A valid management marker establishes enrollment in this workflow; matching headings identify replacement candidates, not authorship. Unmarked files need one-time adoption confirmation after a concrete preview; zero matching headings require an explicit full-regeneration request. See ./references/update_strategy.md for the marker contract and adoption workflow.
The agent automatically selects the appropriate mode based on whether an AGENTS.md file already exists at the target location.
Generation Modes (Monorepo)
Supports three modes: All (root + all packages, default), Root Only, and Single Package. See ./references/monorepo_strategy.md for detailed strategy and mode selection criteria.
Execution Workflow
Run these steps in order. Each step has a fixed output that the next step depends on; skipping ahead produces wrong character budgets, unmatched update sections, or missed monorepo packages. The bundled scripts under ./scripts/ make the deterministic steps reproducible — invoke them rather than re-deriving the logic each run.
Step 1 — Decide Mode
-
Check whether
AGENTS.mdexists at the target location. Present → Update candidate (subject to the management check below). Absent → Generate. -
Run monorepo detection at the repo root:
python ./scripts/detect_monorepo.py <repo_root>Output:
{is_monorepo, markers}. Atrueresult is provisional: discover the actual packages per ./references/monorepo_detection.md. If fewer than 2 packages are found, treat the repo as a single document despite the marker. Otherwise choose All / Root Only / Single Package per ./references/monorepo_strategy.md. Ifis_monorepois false, treat the repo as a single document. -
Before LOC measurement or deep analysis, run
python ./scripts/parse_sections.py <path/to/AGENTS.md> --doc-type <single_repo|monorepo_root>for each existing target.management_statusismanaged,unmarked, orinvalid;generated_doc_typerecords the valid marker's original document type or is null. Invalid markers stop automatic updating. Resolve the original type in the next item before applying the heading-count gate: unmarked files with matching standard headings may proceed to preparation of an adoption preview, but not writing; zero matched headings under the original type require an explicit full-regeneration request. A matching heading alone never authorizes a write. -
Compare a valid
generated_doc_typewith the current target type. When they differ, rerun the parser with the original type to identify the original managed and custom sections before preparing full regeneration. For an unmarked file, infer its original type from distinctive standard headings (## 3. Working Agreementsversus## 3. Core Behaviors & Patterns/## 5. Working Agreements); ask which original type to use if these conflict or are insufficient. Preserve original custom sections and obtain confirmation of the concrete type-transition preview before overwriting. -
For package documents, check whether the repository-root
AGENTS.mdexists. If it does, reference its actual relative path. If it does not, include the common working agreements directly in the package document plus any discovered package-local verification command. Do not create a root file for a Single Package request. In All mode, recheck after the root has been handled.
Step 2 — Measure LOC and Allocate Budget
For each target document (single repo, or root + each package), run:
python ./scripts/loc_to_limit.py <target_directory>
Output: {loc, scale, character_limit}. If the script reports tokei is missing, surface its install message and stop — do not estimate LOC by hand. Use the proportions in ./references/loc_measurement.md as initial section allocations, then redistribute capacity according to verified content. Only the combined preamble and managed sections have a hard character limit; the section proportions are not independent ceilings.
Step 3 — Build Stack Context
Before pattern/convention analysis, read the package manifests at the document's scope (root or per package) per ./references/read_only_commands.md > Dependency Discovery. Skip lock files. Use this stack context to focus Step 4 on relevant frameworks rather than searching blindly.
Step 4 — Analyze the Repository
Read ./references/content_quality.md before analysis. Keep a compact internal record of decision-relevant facts, their current source evidence, and their intended destination. In Generate mode, discover these facts from source. In Update mode, also extract important facts from the old analysis-derived managed sections as inspection leads, reconfirm them against current source, and discover what the old document missed. The old document is not evidence of current behavior, and the working record is not a new output section.
For selected important behaviors, inspect direct implementing helpers until applicable choices, guard/bypass paths, recovery outcomes, state lifetime, ownership/cleanup conditions, and actual recipients are established. Save that compact relationship record in a temporary scratch file outside the target repository before drafting. A feature or helper name by itself does not close source tracing. Recent history affects active-route classification, not whether a currently verified safety contract is retained.
Before history-driven prioritization, build the coverage table from documented capabilities and authoritative registrations/public surfaces. In Update mode, also account for every old managed Stable boundary, Active route, and core flow. Confirm each row's current owner/consumer and selection or evidence-based exclusion. Trace selected rows from open to closed using actual implementing files and symbols, including each behavior-changing stage of a pipeline. A history window with no changes cannot exclude a live hook, migration, or safety condition.
For Update mode, use git history as an ownership-discovery signal before deep source tracing:
-
Prefer changes since the last skill-generated
AGENTS.mdupdate for the target document. If no reliable update anchor exists, default to roughly the last 3 months and adjust by repository activity. -
Run the bundled high-churn signal helper before manually expanding git history:
python ./scripts/git_ownership_signals.py <target_directory>If a reliable update anchor exists, pass it with
--anchor <commit-ish>. The script emits compact Markdown-KV to minimize context use. -
Start with commit metadata and changed paths only. Do not read broad diffs by default.
-
Look for changed-path clusters, repeated co-change patterns, renames/moves, deleted paths, and high-churn boundary files.
-
Use history to decide where to inspect next, not what to document. Add an
Ownership Mapboundary only when current code or documented contracts confirm it. -
Do not persist timeline summaries such as "earlier focus" or "current focus" in
AGENTS.md. Report them only in the user-facing summary unless the transition is currently represented in code as a live migration or compatibility boundary.
See ./references/read_only_commands.md#git-history-signals-update-mode for token-safe git commands and expansion rules.
Run the multi-phase analysis defined in ./references/agents_md_template.md:
- Phase 1 — Stack & Surface Discovery (recurring idioms in 3+ files, project-specific abstractions).
- Phase 2 — Deep Tracing across layers (error propagation, wiring, state lifecycle, failure paths, centralized delegation).
- Phase 3 — Validation (prefer patterns present in 3+ locations, accounting for cross-layer flows; also retain a single verified critical boundary that governs safe work).
If Serena MCP is available, prefer its read-only symbol tools (find_symbol, find_referencing_symbols, get_symbols_overview, etc.) over rg / grep / find — symbolic queries are more accurate for caller tracing and cross-layer flows. See ./references/read_only_commands.md#symbol-level-analysis-optional-requires-serena-mcp.
Run this analysis in the current context only. Do not delegate to subagents — Phase 3 cross-pattern validation and section-level budget tracking require a unified view (see Scope Boundaries > Single-Context Execution).
Document only patterns/conventions actually observed. Preserve necessary entry points, behavior-changing alternatives, exception/fallback conditions, lifecycle obligations, and compatibility effects. If a section needs more than its initial allocation, redistribute unused capacity within the total limit rather than deleting these facts. Apply the compression order in the content-quality reference.
If optional ## 2. Ownership Map has no evidence-backed content, omit the section and keep later section numbers unchanged. Section numbers are update-mode identifiers; never renumber Core Behaviors & Patterns, Conventions, or Working Agreements to close the gap. When evidence exists, split Ownership Map content into Stable Ownership Boundaries for the durable safety boundaries the previous single-list Ownership Map would have documented, and Active Change Routes for recent history-informed routes confirmed against current code. Treat Active Change Routes as additive update-mode context, not as a replacement or filter for stable boundaries. Stable bullets are full change-routing rules; Active bullets are parent-linked or cross-boundary delta routes. Do not restate the parent Stable boundary's broad owner, contract, or verification in Active. If no meaningful delta remains after removing inherited Stable details, omit the Active route. Do not impose a bullet-count limit beyond the section character budget.
Step 5 — Assemble (Generate) or Splice (Update)
Read ./references/plain_language.md before drafting. Write generated section bodies for a contributor who knows the project's programming language but does not yet know its local owners, terms, or contracts. Apply the same writing guidance to fresh managed bodies in Update mode; preserve custom sections and existing preamble bytes under the update contract. This is an output-writing pass, not a new section or a new standing rule for future agent responses.
Draft the closed, decision-relevant contracts into Ownership Map/Core Behaviors first, without duplicating them across sections. Use remaining capacity for repository-specific conventions; do not fill generic naming, role, logging, or resource lists at the expense of a covered contract. Keep every coverage row accounted for when removing an Active label or consolidating sections.
-
Generate: Emit the document using the structure in ./references/agents_md_template.md (4-5 sections for single repo / package, 2-3 for monorepo root, depending on whether
Ownership Maphas evidence-backed content). Add exactly one standalone<!-- agents-md-generator: v1; doc-type: single_repo -->line to the preamble, before the first##heading; usemonorepo_rootfor a monorepo root. Use ./references/working_agreements.md for the Working Agreements section and its root-absence fallback. -
Update: Run the section parser on the existing file:
python ./scripts/parse_sections.py <path/to/AGENTS.md> --doc-type single_repo(Use
--doc-type monorepo_rootfor a monorepo root, or the original type from Step 1 when preparing a transition.) The output marks each##heading asis_standard(a replacement candidate subject to the management gate) or not (preserved), flags evidence-gated headings inoptional_standard, and marks matched optional sections withis_optional_standard. Legacy## 2. Folder Structuresections reportcanonical_title: "## 2. Ownership Map"so approved updates can migrate them. Replace only the standard sections' bodies; keep custom sections, the file title, and the preamble unchanged except for approved marker insertion or type-transition replacement. Insert missing required headings at their numbered position, and missing optional headings only when fresh analysis produced evidence-backed content. Full reassembly rules: ./references/update_strategy.md.Management gate: use the Step 1 management result, not
is_standardalone. For an unmarked file, finish a concrete preview of replacements, insertions, deletions, and marker insertion, then obtain one-time adoption confirmation. On approval, write the adoption and marker together; on refusal, leave the original file unchanged. A general update request is not adoption confirmation. Preserve all non-standard content and the existing preamble except the expressly approved marker insertion. Invalid markers must be reported rather than silently repaired. See the update strategy for details.If the existing document type no longer matches the repo (e.g., a single repo became a monorepo), force full regeneration instead of update: carry every custom section over verbatim into the regenerated document (original order preserved) and get the user's confirmation before overwriting.
Step 6 — Verify and Write
Before writing, confirm:
- The combined length of the preamble and the standard (managed) sections is within
character_limit. Section allocations may be exceeded after rebalancing; preserve section responsibilities and do not add filler. Custom sections are excluded from the budget and must never be trimmed to satisfy it. - The document has exactly one valid management marker in its preamble and its document type matches the output. The marker counts toward the preamble budget. Preserve the preamble apart from approved marker insertion or type-transition replacement. An unmarked file is written only after approval of its concrete adoption preview.
- None of the Anti-Patterns appear (no Common Commands, run/test/build/deploy instructions, IDE/tooling settings, etc.). Exception: the discovered type-check command in Working Agreements is required content, not a build/run instruction.
- For Update mode: every standard section body was rebuilt from its managed source, not reused because the old wording appeared acceptable.
- For both modes: after final compression, compare the assembled document with the working fact record per ./references/content_quality.md. Every important verified fact must be conveyed, corrected to current behavior, or excluded with an evidence-based reason. Unexplained loss or distortion fails verification even if structure and length pass. Reconfirmed identifiers and meaning may recur in freshly written sections; freshness does not require erasing useful facts. If important facts cannot fit after reallocation and compression, finish a reviewable candidate and ask about scope or total limit before writing.
- Review the generated prose with the reader-task check in ./references/plain_language.md after compression. A contributor must be able to locate a change, identify its owner and applicable conditions, and use the stated contract and verification surface without decoding shorthand. Revise unclear managed prose while retaining verified meaning; this review does not authorize changes to custom sections, the preserved preamble, canonical headings, or character limits.
- Read the temporary record and final output together: point each important fact to its actual final sentence and check its applicable relationship fields. Reverse-check broad claims about recovery, migration, restoration, reuse, guards, and resource ownership against their implementing helpers. If both record and prose omit a condition, reopen the helper; their agreement is not a pass. Keep this audit outside
AGENTS.mdand report only material corrections or limitations to the user. - Check coverage as well as depth: all old managed boundaries/routes/flows and documented or registered capability candidates have a current disposition, and no selected row remains
open. Empty history, generic "lower value", or space pressure is not an exclusion reason for a current safety contract. Generic pipeline stage names do not establish the stages' actual choices or recovery conditions. - For Update mode: scan only managed standard sections for stale standing work-agreement wording. Fail verification if managed content still contains
Keep edits minimal,Minimal changes,preserve public APIs,existing plugin behavior, oravoid unnecessary abstraction; custom sections may keep any user-owned wording. - For Update mode: every preserved custom section is byte-for-byte identical to the original.
- For Update mode: report to the user any wording being removed from managed standard sections — user additions inside managed sections are not preserved, so list what is dropped before overwriting and suggest moving anything user-owned into a custom section.
- For Update mode: if an existing managed
Ownership Mapor legacyFolder Structuresection will be omitted because no current evidence supports it, report that whole-section removal and get confirmation before overwriting. - For single-repo documents: the managed
Working Agreementssection does not contain monorepo-only wording such as package-levelAGENTS.mdguidance. - For package documents: a root reference resolves to an existing file; otherwise the package contains common working agreements directly and no missing-root reference. If a root document now exists where a previous update used the fallback, switch to inheritance through the usual managed-section replacement and dropped-wording report.
Then write with the Edit/Write tool. For Monorepo with mode = All, repeat Steps 2–6 per target package after handling the root, re-running the Step 1 Generate/Update decision, management check, and root-existence check for each package — a package without AGENTS.md is Generate even when the root was Update.
Tools
This skill uses the following read-only tools for repository analysis. See ./references/read_only_commands.md for detailed usage patterns.
- Serena MCP symbol tools (preferred when available):
find_symbol,find_referencing_symbols,find_referencing_code_snippets,get_symbols_overview,search_for_pattern,list_dir,find_file,read_file. Prefer these overrg/grep/findfor symbol lookups, caller tracing, and structural analysis. Use only the read-only tools listed; do NOT invoke write/edit symbol tools orexecute_shell_command. See ./references/read_only_commands.md#symbol-level-analysis-optional-requires-serena-mcp. tokei: LOC measurement (required)rg(ripgrep): Content search (fallback when Serena MCP is unavailable)grep/Select-String: Content search (fallback per OS, when neither Serena norrgis available)sed -n/Get-Content \| Select-Object: Paginated file reading per OStree: Directory structure visualizationfind: File and directory discovery (Linux / macOS, fallback when Serenafind_fileis unavailable)ls,pwd: Basic directory navigationgit log,git show --stat,git show --name-only: Update-mode ownership discovery signals; use the bundled script first, then metadata and changed paths, never broad diffs by default
Bundled Scripts
Deterministic steps are bundled as scripts under ./scripts/ so they run identically across invocations and platforms. Prefer these over re-deriving the logic in natural language.
scripts/loc_to_limit.py: Runstokeiwith the prescribed exclusions, parses theTotalrow, and returns{loc, scale, character_limit}. Surfaces the install message and exits non-zero iftokeiis missing.scripts/detect_monorepo.py: Checks marker files (pnpm-workspace.yaml,lerna.json,nx.json,turbo.json,rush.json,.moon/workspace.yml,go.work,Cargo.toml [workspace] members,package.jsonworkspaces, Gradlesettings.gradle*, Mavenpom.xml <modules>, Bazel, Buck2, Pants, Hatch/uv/rye). Gradle matching reads complete literal include declarations, including multiline forms, ignores comments/string examples, and deduplicates project paths; it does not evaluate dynamic Gradle expressions. Returns{is_monorepo, markers}; atrueresult is provisional until package discovery finds 2+ packages (Step 1).scripts/parse_sections.py: For Update mode. Returns a section map with standard-heading candidates, custom sections, and missing headings, plusmanagement_statusandgenerated_doc_type. Existing JSON fields and--doc-typematching remain unchanged; consumers must use the management gate before writing. Headings and markers inside fenced code blocks are ignored. The parser reports line ranges rather than rewriting content; splice preserved ranges from the original bytes, retaining line endings and trailing whitespace.scripts/git_ownership_signals.py: For Update mode. Runs token-safe git history aggregation over the target directory and prints compact Markdown-KV high-churn path signals. The output is a discovery signal only and must be confirmed against current code before documentingOwnership Mapboundaries.
Domain Knowledge
- LOC Measurement: Capability to measure repository size and determine character limits. See ./references/loc_measurement.md
- Repository Analysis: Capability to inspect and understand codebase structure. See ./references/read_only_commands.md
- Output Template: Standardized AGENTS.md structure specification. See ./references/agents_md_template.md
- Content Quality: Decision-relevant fact discovery, evidence-based retention/correction, compression order, and final semantic comparison. See ./references/content_quality.md
- Plain Language: Reader needs, findable labels, clear technical prose, and a final reader-task review informed by ISO 24495-1:2023. See ./references/plain_language.md
- Working Agreements: Agent behavior rules for generated documents. See ./references/working_agreements.md
- Monorepo Detection: Capability to identify monorepo structures. See ./references/monorepo_detection.md
- Monorepo Strategy: Strategy for generating documentation in monorepos. See ./references/monorepo_strategy.md
- Update Strategy: Strategy for updating existing AGENTS.md files with selective section refresh. See ./references/update_strategy.md
Scope Boundaries
- Read-Only Analysis: Supports non-destructive commands for repository inspection
- Output Scope: Produces documentation content only; excludes run/test/build/deploy instructions. Optional sections are omitted when repository analysis finds no concrete, stable content for them.
- Excluded Inputs: Lock files (
pnpm-lock.yaml,package-lock.json,yarn.lock, etc.) are outside analysis scope - Single-Context Execution (No Subagents): This skill must NOT spawn subagents (e.g., the
Agent/Tasktool,Explore,general-purpose, or any delegated agent) at any step. AGENTS.md generation requires a unified view of the repository: accumulated stack context (Step 3), per-section character budgets (Step 2), Phase 3 validation across 3+ locations, and Update-mode byte-for-byte preservation of custom sections all depend on a single context. Splitting work across subagents loses this state and produces inconsistent or budget-violating output. A parent agent invoking this skill is fine — the skill's internal execution must stay in one context.
Biz Opportunity Scout
Capability to identify, analyze, and validate business opportunities through quantitative frameworks.
Analysis Scope
| Scope Type | Description |
|---|---|
| Idea Validation | Early-stage concept viability assessment |
| Idea Pivot/Extension | Existing idea modification or expansion |
| Business Expansion | Established business growth opportunity |
Core Analysis Frameworks
| Framework | Reference | Purpose |
|---|---|---|
| Market Sizing | market_sizing.md | TAM/SAM/SOM calculation methodology |
| Unit Economics | unit_economics.md | LTV, CAC, Contribution Margin, Payback Period |
| Competitive Analysis | competitive_analysis.md | Market positioning and competitor mapping |
| PMF Indicators | pmf_indicators.md | Product-Market Fit measurement criteria |
Data Collection
| Method | Description |
|---|---|
| Web Search | Real-time market data, competitor info, industry trends via web search |
| External Research | Industry reports, public data sources, academic papers |
| User Input | Business-specific assumptions and known metrics |
Note: Use web search actively to gather up-to-date market data, pricing information, and competitor intelligence. Search queries should target specific data points needed for each framework.
Output Specification
| Component | Description |
|---|---|
| Numeric Report | Quantitative analysis with calculated metrics |
| Investment Pitch | Key figures formatted for investor presentation |
| Go/No-Go Decision | Binary recommendation with supporting rationale |
| Opportunity Scorecard | Composite score/grade across all dimensions |
See report_template.md for HTML output structure and file naming conventions.
Report File Naming
| Option | Pattern | Example |
|---|---|---|
| Default | report/scout-report_[service-name]_[date].html | report/scout-report_coffee-subscription_2024-01-14.html |
| Custom | User-specified folder and filename | User input |
Clear Writing
ISO 24495-1:2023 defines plain language by its outcome: wording, structure, and design so clear that the intended readers can easily find what they need, understand what they find, and use that information. Everything in this skill serves that outcome.
Two things about the standard shape how you should work:
- It focuses on how well readers can use a document, not on mechanical measures such as readability formulas. So the job is not "shorten sentences and swap hard words." Most of the work is deciding what these readers need and arranging it so they can act on it. Word choice is a small part: the International Plain Language Federation (IPLF) reports that only about 7% of the standard's roughly 485 ideas concern word choice.
- It applies to most written languages, and the IPLF describes it as language-neutral. Apply its guidelines through the conventions of the language you are writing in.
The four principles
The standard treats the principles as interdependent, not as a sequence: a text is usable when its content is relevant, findable, and understandable, and only evaluation shows whether it really is. The steps below follow the principles in working order; go back to an earlier step whenever a later one shows a problem.
| Principle | Reader outcome | Guidelines (clause) |
|---|---|---|
| 1 Relevant | Readers get what they need | 5.1.2 Identify the readers · 5.1.3 Identify the readers' purpose · 5.1.4 Identify the context in which readers will read the document · 5.1.5 Select the document type or types · 5.1.6 Select content that readers need |
| 2 Findable | Readers can easily find what they need | 5.2.2 Structure the document for readers · 5.2.3 Use information design techniques that enable readers to find information · 5.2.4 Use headings to help readers predict what comes next · 5.2.5 Keep supplementary information separate |
| 3 Understandable | Readers can easily understand what they find | 5.3.2 Choose familiar words · 5.3.3 Write clear sentences · 5.3.4 Write concise sentences · 5.3.5 Write clear and concise paragraphs · 5.3.6 Consider including images and multimedia · 5.3.7 Project a respectful tone · 5.3.8 Ensure that the document is cohesive |
| 4 Usable | Readers can easily use the information | 5.4.2 Evaluate the document continually as it is developed · 5.4.3 Evaluate the document further with readers · 5.4.4 Continue to evaluate readers' use of the document |
references/guidelines.md explains what each guideline asks and how to apply and check it. Read it once at the start of the task, and go back to the relevant section when a specific question comes up (for example, where warnings belong relative to steps). It also marks which statements summarize the standard, which come from IPLF commentary, and which are practical guidance written for this skill — keep that distinction when you cite the standard.
Choose the mode
- Write: the user gives notes, facts, or a request and wants new text.
- Rewrite: the user gives existing text and wants it plainer. If they ask to "check and fix," it is a rewrite.
- Review: the user wants to know whether and where a text falls short, without a rewrite. Use Steps 2 to 5 and the Check questions in
references/guidelines.mdas your criteria, and report in the review format under Output instead of rewriting.
All three modes start with readers, purpose, and situation, because plainness only exists relative to particular readers. A sentence that is plain for nurses can be opaque to patients.
Step 1: Confirm readers, purpose, and situation before writing
You need three things before drafting or reviewing:
- Readers: who will read it, and how much they already know about the topic.
- Purpose: what readers need to do, decide, or know after reading.
- Situation (the context in 5.1.4): where and how they will meet the text (text message, printed letter, notice board, web page), and any pressure on them that would change the text (urgency, worry, bad news).
Treat each as known only when the user states it, or the provided material states it outright (for example, an addressee line plus an explicit request to the reader). A stated channel, such as "문자로 보낼 안내" or a printed letter, confirms the situation. If any of the three would have to be guessed, ask before drafting or reviewing. A wrong guess produces a polished text for the wrong person, which costs more than one short exchange.
Ask in a single message that is quick to answer, covering only what is still missing. Offer two or three likely options drawn from the context so the user can pick rather than compose. Add these to the same message when they apply:
- Only when it would change the text: the document type if the request leaves it open, required wording, format, or length, and facts the text needs that are missing (dates, amounts, contacts, conditions).
- If several audiences will read the document, ask which one is primary. When needs conflict, the standard gives the primary audience priority.
- In a rewrite, list any source passages whose meaning you cannot pin down. Guessing there can change someone's obligations or rights.
- If the described readers have serious difficulty reading (for example, a cognitive disability or very limited command of the language), note briefly that ISO 24495-1 separates plain language from easy language, and ask whether to continue with plain language. If they want easy language instead, say that this skill does not apply easy-language rules.
After the answers, proceed. Do not start a second round of questions unless an answer reveals a gap that would make the text wrong. If the user has explicitly told you not to ask, write for the most likely readers, purpose, and situation the context supports.
Step 2: Decide the content (Principle 1)
- List the questions the readers will bring: what is this, does it affect me, what must I do, by when, how, what happens if I don't, whom do I contact. Answer the ones these readers need; leave out what they don't.
- Keep content the author is required to include (legal notices, compliance text), but place it so it does not block the main message (5.2.5).
- Select content ethically: accurate, not misleading, and nothing the reader needs to know hidden or buried. Simplifying never means dropping a condition, fee, deadline, risk, or exception that affects the reader.
- Do not invent facts. Resolve missing facts needed for a correct, usable text through Step 1. Omit an unknown detail only when the remaining text still serves the reader's purpose accurately.
- Choose a document type that fits the readers, purpose, and situation. In a rewrite, keep the user's document type and channel unless they ask to change it.
Step 3: Structure and design (Principle 2)
- Readers should be able to tell at a glance what the text is about and whether it concerns them. Give it a title or subject line that says so when the document type has one.
- Lead with what most readers need most, usually the main message or the action required.
- Order the rest by the reader's logic: steps in time order; warnings about what not to do before the steps they protect; information most readers need before information only some need; new information built on what readers already know.
- Use headings that let readers predict what follows. A heading that states the point or asks the reader's question ("언제까지 신청해야 하나요?", "What happens if I miss the deadline?") does more than a bare label ("신청 기간", "Deadline").
- Make the structure visible with what the destination supports: numbered steps, short lists, tables for comparisons and values, emphasis for the one or two things that must not be missed, space between groups. Format elements with the same function the same way, including the grammatical form of items in one list. Use formatting only where it shows structure or priority: keep connected explanation in sentences, do not give every list item a bold lead-in unless readers scan for those labels, and leave out decorative emoji unless the user asks for them or the channel's conventions expect them.
- Move background, legal detail, and edge cases after the main content or into a clearly labeled section. Warnings, deadlines, and conditions that readers need before they act stay with the step or decision they affect, not in a closing notes section.
- Scale structure to length. A two-sentence text message needs no headings; a multi-page guide needs headings and often a short summary at the top.
Step 4: Wording (Principle 3)
- Choose words and expressions that are familiar, precise, and natural for these readers, including a plain verb over an inflated one that says the same thing. Replace unfamiliar jargon with a clearer equivalent when it preserves the intended meaning. Use necessary technical or legal terms consistently, and explain them at first use when these readers need help with them. Expand or avoid unfamiliar abbreviations; retain familiar ones when they are clearer.
- When readers must match, copy, search for, or enter an existing string (such as a button label, path, command, identifier, or error message), reproduce it exactly. Improve the surrounding explanation as needed. This protection does not freeze labels or messages that the user asks you to author or revise.
- Make each sentence show who does what. Prefer a concrete actor and a verb over abstract nouns. Address readers directly when it fits the document and the language.
- Keep the main point of each sentence easy to spot rather than buried behind long preambles or stacked conditions. Split sentences that carry several ideas, and cut words that add nothing, such as a wrapper that announces a point instead of making it ("Please note that..."). Keep words that carry obligation, permission, or possibility ("must", "may", "can", or "~할 수 있습니다" when it grants an option), because dropping or rewording them can change what readers are required or allowed to do.
- Give each paragraph one topic and state it early.
- Keep a respectful tone: no blaming, threatening, or talking down. Treat readers as capable adults and use inclusive language.
- Make the text cohesive: consistent terms, references whose target is obvious, transitions that show how parts connect, and consistent formatting.
- Use tables and worked examples in the text when they help readers understand better than prose. When the requested deliverable includes an image or diagram, provide the finished visual in a format the destination supports.
ISO 24495-1 favors reader success over mechanical measures such as readability formulas, so do not impose fixed targets of your own, such as a maximum sentence length. The IPLF notes that countries can add language-specific practices, such as sentence length, when they adapt the standard. Judge each choice by whether these readers can follow it. If the user's organization or language has its own conventions (a style guide, house terms, mandated wording), follow them.
Language adaptation
Apply each guideline through the natural patterns of the target language instead of importing English habits. The examples below are local practice, not ISO rules.
A Korean sentence often gets clearer when:
- a chain of Sino-Korean nouns becomes verbs ("서류 제출 시 본인 확인 절차 진행 후 처리" → "서류를 내시면 본인인지 확인한 뒤 처리합니다").
- a light verb such as "진행하다" or "실시하다" gives way to the verb it hides, at the same level of politeness ("신청 절차를 진행해 주시기 바랍니다" → "신청해 주시기 바랍니다").
- translationese goes: "~에 의해", "~되어지다", a plural "~들" that adds nothing, and "또한" or "아울러" opening sentence after sentence.
- the subject and predicate sit close together.
- the actor is named only where leaving it out makes it unclear who acts, such as whether the reader or the organization sends a form. Korean normally drops subjects, so adding them everywhere reads as translated.
In English, the usual moves are active voice where the actor matters, "you" for the reader, and everyday words over formal ones.
Step 5: Evaluate as you go (Principle 4)
The standard says following Principles 1 to 3 makes a usable text likely, but only evaluation confirms it. You cannot test with real readers, so do the evaluation you can do (5.4.2) before you deliver:
- Re-read the draft as the primary reader in their situation, for example skimming on a phone if that is how they will read it.
- For each reader question from Step 2, check that the reader can find the answer quickly, understand it on the first read, and act on it without having to contact anyone.
- Remove wording and formatting that do not help these readers find, understand, or use the information, judged by Steps 2 to 4 and their exceptions.
- In a rewrite, compare the full source with the draft. Preserve the meaning and accuracy of information readers need and content the author must include. Check that omissions remove only irrelevant or redundant material, and that required exact strings still match. Change wording, order, and structure whenever that serves the reader.
- Fix what fails, then check again.
Do not claim that a text "conforms to" or is "certified under" ISO 24495-1. Part 1 offers guidance, and the IPLF states that it is not for certification. Your own check covers only 5.4.2; confirming that readers can use the document also takes evaluation with readers (5.4.3) and of their continued use (5.4.4), which you cannot do here. If the user asks about compliance or testing, explain this and suggest reader-testing methods from references/guidelines.md.
Output
Choose the output language or languages to suit the user's request and intended readers, using the task context when no language is specified.
Write and rewrite modes: deliver only the finished reader-facing text. Include only content that belongs in that document: no preface, summary of changes, checklist, drafting or design notes, placeholders, or other commentary attached to the text. If the user later asks why something changed or wants a check, answer then.
- Format for the destination. Markdown headings and tables suit documents and web pages. For text messages, chat, or plain-text email, use plain-text structure (line breaks, numbered lines) instead of Markdown syntax.
Review mode: the review is the deliverable. Translate the labels below into the chosen output language, with this structure:
Readers, purpose, and situation: <one line, as confirmed>
Findings (most harmful to readers first)
1. [Principle N, clause and guideline name] Where: <short quote or location>
Problem: <what goes wrong for the reader>
Fix: <concrete suggestion, with a short example rewrite when it helps>
2. ...
What already works: <one to three points, only if useful>
Needs checking with real readers: <points that reading alone cannot settle>
Report only problems that affect readers, not cosmetic preferences. Do not rewrite the whole text in review mode unless the user asks. When you name a guideline, cite its clause number and title; do not attribute specific rules such as "always use active voice" to the standard.
Scope
- ISO 24495-2 (legal communication) and ISO 24495-3 (science writing) add domain guidance on top of Part 1. This skill applies Part 1 only. For legal or science texts, apply Part 1 and keep legally required wording intact.
- Plain language serves a general audience. Easy language (easy-read) is a separate practice for readers with reading difficulties.
- Part 1 covers printed or digital information that is mainly text. It does not replace accessibility guidance such as WCAG.
Code Review Workflow
Review changes without modifying code or publishing an external review. Respond in the user's language. A clear target authorizes immediate review; ask only when ambiguity materially changes scope or intent.
1. Resolve the target and version
Read Git operations before retrieving a diff. Record the requested scope, resolved commit IDs or index/worktree state, comparison base, and any path restriction.
- No target: include staged, unstaged, and untracked changes. If none exist, ask what to review; do not substitute HEAD.
- Explicit staged review: use index contents for both changes and surrounding callers, including unchanged files.
- Commit or range: use the selected revisions for context and consumers, never current worktree files as evidence of that revision's behavior.
- File paths narrow findings to those paths; follow necessary consumers outside that boundary for context and disclose the boundary.
- Distinguish endpoint comparison, merge-base comparison, and the legacy inclusive
start~endnotation. Do not silently change the base to make a command succeed.
Inspect status for unresolved conflicts and handle roots and merges explicitly. Preserve the user's index and working tree.
2. Inventory the change and explain intended behavior
Read requirements, relevant contracts, and before/after code in the selected versions. Establish what inputs should produce what observable results. A commit message is context, not proof of correctness.
Track each changed file as reviewed, mechanically checked with a reason, or unreviewed. Prioritize by behavioral impact without sampling source solely by file count. Inspect generated artifacts, lockfiles, vendored code, and bundles according to their actual deployment or dependency effects; a filename is not proof that content is irrelevant. Check generators and outputs together where necessary. Disclose skipped areas if the review cannot be completed.
3. Trace behavior through consumers
Read impact detection. Trace callers → intermediate layers/shared abstractions → final consumers. Follow arguments, defaults, configuration, return values, errors, and cancellation signals through transformations and precedence rules. Confirm changed values actually affect runtime behavior.
Check public exports, adapters, serialized data, dynamic registration, and external consumers where accessible. Search results identify candidate paths; inspect those paths before drawing conclusions. Use version-aware search or an isolated snapshot for historical/index review.
4. Apply relevant practical checks
Read review checks and select checks supported by the change surface. Examine edge conditions, authorization, state transitions, concurrency, resource lifetime, retries/idempotency, compatibility, costs, and test assertions where relevant. Do not turn the reference into a compulsory checklist in the report.
Assess maintainability separately: identify present complexity, duplicated policy, or coupling and explain the concrete benefit of a local improvement. Exclude personal style preferences and speculative abstractions by default.
5. Challenge every suspected defect
Before reporting, establish a reachable trigger, the execution path, expected versus actual behavior, code evidence, and impact. Look for counterevidence: caller validation, compatibility layers, intentional requirements, cleanup/fallback logic, or runtime guarantees.
Compare the base version: omit pre-existing problems not introduced or made worse by this change. Merge reports sharing one root cause, even when several files or consumers expose it. Static evidence can establish a defect without an executed reproduction; say which kind of evidence supports it. If a missing fact could invalidate the claim, state a verification question under limitations instead of presenting it as a confirmed defect.
6. Classify and report
Read output format. Determine defect severity from actual impact and trigger conditions: Critical for severe security/data/availability consequences, Major for material incorrect behavior, Minor for bounded low-impact defects. Keep uncertainty separate; do not calculate confidence scores or promote severity because tests are missing or consumers are numerous.
Default order: target, defects by importance, maintainability observations, verification and limitations. Explicitly state when no confirmed defects were found. Omit empty optional sections and ceremonial praise. Only if the user asks for a verdict, apply the qualitative decision rules in the output reference; never use finding counts or weighted scores.
Tools and boundaries
Use Git and available repository navigation tools, preferring codemap-search when available and appropriate. Search relevant paths and file types. Navigation indexes of the current worktree are not evidence for historical or staged content; use Git blobs/search or an isolated matching snapshot instead. Use existing verification commands when authorized and relevant; report the exact command, execution location, and result. A review request alone does not authorize source changes, new tests, or external posting.
Archived literal examples
These preserved blocks are historical examples, not steps to execute. Use the current workflow above. Single-commit show examples require the root/merge handling above; inclusive range commands require a valid parent. Merge-base commands apply only to an explicitly requested common-ancestor comparison, never as fallback. Worktree rg examples must not supply historical or index context.
git --no-pager show --stat <commit_hash>
# or for staged changes:
git --no-pager diff --cached --stat
# Single commit
git --no-pager show <commit_hash>
# Staged changes
git --no-pager diff --cached
# Commit range
git --no-pager diff <start_hash>^..<end_hash>
# File-scoped
git --no-pager show <commit_hash> -- <file_path>
# Find direct callers
rg -F "symbolName(" .
# Find broader references
rg "symbolName" .
Code Security Audit Capabilities
OWASP 4-source integrated code security audit system for universal codebase analysis.
Knowledge Sources
- OWASP ASVS 5.0.0: 345 verification requirements across 17 security domains (L1/L2/L3)
- OWASP API Security Top 10 2023: 10 API-specific risk categories with code-level indicators
- OWASP CheatSheet Series: 109 practical secure coding cheat sheets for remediation guidance
- OWASP WSTG (Web Security Testing Guide): 12 testing categories with 120+ test scenarios
Source Roles
| Source | Role | Usage |
|---|---|---|
| ASVS 5.0.0 | Verification requirements baseline | Defines what to check — structured requirements per domain |
| API Security Top 10 2023 | Risk taxonomy | Defines what to look for — API-specific threat patterns |
| CheatSheet Series | Implementation guidance | Defines how to fix — secure coding patterns and practices |
| WSTG | Test methodology | Defines how to verify — concrete test scenarios per vulnerability |
Domains
- Input Handling (V1, V2, V5): Encoding, sanitization, injection prevention, validation, file handling
- Authentication & Session (V6, V7, V9, V10): Auth mechanisms, session management, token handling, OAuth/OIDC
- Authorization (V8): Object-level, function-level, property-level access control
- Cryptography (V11, V12): Storage encryption, key management, TLS configuration
- API Security (V4, V17): REST/GraphQL/WebSocket/WebRTC security, rate limiting, resource consumption
- Data Protection (V14): Sensitive data exposure, privacy controls, client-side data
- Configuration (V13, V16): Security headers, CORS, error handling, logging, deployment hardening
- Secure Coding (V3, V15): Web frontend security, architecture patterns, defensive coding, concurrency safety
Input Contract
| Field | Required | Description |
|---|---|---|
| Codebase path | Yes | The current workspace or repository the agent is operating in. Defaults to the active codebase; users may narrow scope to specific directories or files (e.g., src/auth/, api/controllers/) |
| Audit level | No | ASVS verification level (default: L2). See level definitions below |
| Focus areas | No | Security domains to prioritize. See focus area catalog below |
| Tech context | No | Language, framework, or architecture notes for targeted analysis |
Audit Levels (OWASP ASVS 5.0.0)
| Level | Target Application | Requirements | Description |
|---|---|---|---|
| L1 | All applications | ~86 | Essential baseline — covers critical vulnerabilities that are typically exploitable and must be addressed in every application (e.g., SQL injection, OS command injection, basic auth checks) |
| L2 | Applications handling sensitive data (PII, financial, health) | ~230 | Standard security — includes L1 plus defense-in-depth controls such as SSRF protection, template injection prevention, secure session management, and proper cryptographic usage |
| L3 | Mission-critical systems (banking, healthcare, military, infrastructure) | ~345 | Comprehensive defense — includes L1+L2 plus advanced controls such as formula injection prevention, full input canonicalization, and exhaustive cryptographic verification |
Focus Area Catalog
| Focus Area | Domains | Example Checks |
|---|---|---|
| authentication | V6, V7, V9, V10 | Password storage, MFA, OAuth/OIDC flow, credential rotation |
| authorization | V8 | Object-level (BOLA), function-level, property-level access control |
| injection | V1, V2 | SQLi, XSS, command injection, LDAP/XPath injection, template injection, XXE |
| cryptography | V11, V12 | Weak algorithms, key management, TLS configuration, secret storage |
| api-security | V4, V17 | Rate limiting, resource consumption, REST/GraphQL/WebSocket security |
| session | V7, V9, V10 | Token handling, session fixation, cookie attributes, JWT validation, CSRF |
| file-handling | V5 | Path traversal, unrestricted upload, file type validation, storage security |
| data-protection | V14 | Sensitive data exposure, privacy controls, client-side data leakage |
| configuration | V13, V16 | Security headers, CORS, error handling, logging, deployment hardening |
| secure-coding | V3, V15 | Frontend security, concurrency safety, architecture patterns, defensive coding |
Preconditions
- Codebase is accessible and readable
- Agent has file search and read capabilities
- If codebase structure cannot be determined, the agent reports limitations in the audit output
Core Capabilities
- Codebase Reconnaissance: Identifies technology stack, frameworks, entry points, and security-relevant file areas
- Domain-Scoped Analysis: Systematically audits code across all 8 security domains
- ASVS Requirement Verification: Checks code against applicable ASVS 5.0.0 requirements at the specified level
- Vulnerability Pattern Detection: Identifies known vulnerable code patterns from the integrated knowledge base
- Cross-Source Correlation: Maps findings to ASVS requirements, API Top 10 risks, CheatSheet guidance, and WSTG test IDs
- Severity Classification: Rates findings as Critical/High/Medium/Low with evidence and confidence
- Remediation Guidance: Provides concrete fix patterns sourced from CheatSheet Series
- Structured Report Generation: Produces a comprehensive Markdown audit report
Audit Workflow
1. Reconnaissance → Identify stack, structure, entry points
2. Scope Definition → Select applicable ASVS domains and level
3. Domain Analysis → Audit each security domain systematically
4. Finding Synthesis → Deduplicate, correlate across sources, assign severity
5. Remediation Map → Attach fix patterns per finding
6. Report Generation → Produce structured Markdown report
Output Contract
The audit produces a Markdown report containing:
- Executive Summary: Overall risk posture, critical findings count, audit scope
- Findings Table: Each finding with severity, ASVS ID, CWE, evidence, and remediation
- Domain Reports: Per-domain detailed analysis with code references
- Remediation Roadmap: Prioritized fix recommendations
- Audit Metadata: Scope, level, limitations, methodology notes
Severity Levels
| Level | Criteria |
|---|---|
| Critical | Exploitable vulnerability with direct security impact (RCE, SQLi, auth bypass, data breach) |
| High | Significant security weakness requiring prompt remediation (broken access control, weak crypto, SSRF) |
| Medium | Security concern with conditional exploitability (missing headers, verbose errors, weak validation) |
| Low | Defense-in-depth improvement or best practice deviation (logging gaps, minor config issues) |
| Info | Observation or recommendation with no direct security impact |
Technical References
- audit_process.md: Complete step-by-step audit methodology and reconnaissance procedures
- security_domains.md: All 17 ASVS domains with code-audit-relevant requirements and cross-source mappings
- vulnerability_patterns.md: Concrete code-level vulnerability patterns organized by category
- remediation_patterns.md: Secure coding fix patterns from CheatSheet Series
- report_format.md: Detailed Markdown report structure and finding schema
Delegated Review Loop
A quality loop built for users who want to describe what they need and get a result that has already survived scrutiny — without reading schemas, configuring panels, or supervising rounds. The main agent acts purely as an orchestrator: it delegates context-gathering to a scout, the work to a worker sub-agent, fans out an automatically-selected reviewer panel, routes findings back to the worker, and repeats until the panel passes.
Why the main agent never holds the pen: an author reviewing its own work in the same context inherits its own blind spots. Separating the worker (full task context, makes decisions) from the reviewers (clean context, see only the request and the artifact) keeps the critique honest, and keeping the main agent out of authorship keeps the orchestration judgment unbiased.
When to use
Only when the user explicitly invokes this skill or explicitly asks for sub-agents to build and iteratively review/improve something. Never auto-trigger on ordinary implementation requests or on task completion.
If the user already has a finished artifact and only wants it verified — not rebuilt or improved by sub-agents — iterative-self-review is the right tool, not this one.
Roles
| Role | Holds | Never does |
|---|---|---|
| Main agent (orchestrator) | Session lifecycle, task classification, panel selection, finding merge, loop control, final summary | Write or edit the artifact; review it itself; inline document content into sub-agent prompts |
| Scout sub-agent (optional) | Read-only context gathering before the build | Edit anything; make implementation decisions |
| Worker sub-agent | Full task context; produces and improves the artifact | Grade its own work; talk to the user |
| Reviewer sub-agents | Clean context: task request + current artifact only | Edit anything; see the scout's notes, other reviewers' findings, or the worker's reasoning |
Session directory and path-passing rule
All inter-agent content travels as documents inside one per-session directory under .agents/agents-community/<session-id>/, created by the main agent at the start and cleaned up by it at the end. The orchestration rule is strict and is what keeps the main agent's context lean:
- The main agent hands sub-agents file paths only — it never pastes document content into a prompt.
- Each sub-agent reads its inputs from the files itself and writes its output as a new document in the session directory, returning only the path.
- Which paths the main agent hands to whom is the isolation contract. A reviewer that receives the scout's notes or the worker's report path is no longer blind. The full layout and read-access matrix live in session_protocol.md — follow it exactly.
The deliverable itself (code, the actual document) lives at its real repository path; the session directory holds coordination documents only.
Workflow
Step 1 — Frame the task and open the session
Extract the substantive task request from the user's own words. If the invocation message itself is contentless (e.g., just the skill name), reconstruct the request from the user's earlier utterances — verbatim quotes only. Create the session directory per session_protocol.md and write the request to task_request.md. This file is immutable for the rest of the loop and is the one document every agent may read.
Step 2 — Select the reviewer panel
Classify the deliverable (code / document / design or plan / mixed) and pick 2–4 review lenses from the roster in reviewer_panel.md. Correctness and requirements-fit are always in; the rest depend on what the task actually risks. Don't pad the panel — every extra reviewer costs a full read of the artifact, so add a lens only when the task plausibly fails along it.
Then, as a required action of this step — not a formality: print the chosen panel to the user in one line (e.g., "리뷰어 패널: 정확성, 요구사항 충족, 단순성") before spawning any sub-agent (scout included). This line is one of only three things the user sees while the loop runs; skipping it leaves them watching an opaque, slow process with no idea what is happening. Selecting the panel silently and only revealing it in the final summary defeats the line's purpose. No further configuration dialog — defaults carry the rest.
Step 3 — Scout gathers context, and the simplicity gate
If the task depends on context the worker would otherwise have to rediscover — an unfamiliar codebase area, related existing implementations, external constraints — spawn a read-only scout sub-agent first using the prompt in worker_prompt.md. It writes its findings to research/context.md and returns the path. Skip the scout for self-contained tasks; a one-file fix does not need a survey.
The scout's notes go to the worker only. Reviewers never receive this path — they verify reality with their own read-only tools, and feeding them the scout's framing would bias them toward the worker's assumptions.
Simplicity gate. A worker plus a multi-reviewer panel is heavy machinery, and spending it on a trivial task wastes the user's time and tokens. The complexity judgment happens at this step, on whichever path applies:
- Scout ran → its report ends with a complexity verdict (
simpleorsubstantial), judged per the criteria in its prompt. - Scout skipped → the orchestrator judges directly, using the same criteria: the task is
simplewhen it is a small, localized change with no new behavior, no trust-boundary contact, and no realistic way for a reviewer panel to find something a careful single pass would not.
When the verdict is simple, pause and ask the user with the question tool before spawning anything further — one question, plain language: this task looks simple; run the full build-review loop anyway, or handle it normally without the loop? If the user declines, stop the skill: delete the session directory and carry out the task as an ordinary request outside this skill. If the user approves, continue to Step 4 without asking anything again. substantial tasks never ask — they proceed directly.
Step 4 — Worker builds
Spawn the worker sub-agent with the prompt in worker_prompt.md, handing it the paths to task_request.md and (if produced) research/context.md. The worker has normal tool access and full freedom in how it builds. It writes its report to worker_report_0.md and returns the path.
Step 5 — Panel reviews in parallel
Spawn all reviewers in the same turn, one per selected lens, using the reviewer prompt in reviewer_panel.md. Each reviewer receives exactly two paths — task_request.md and the artifact's real location — plus read-only tool access to inspect reality. No scout notes, no worker report, no other reviewers' output, no prior-round findings. Each writes its report to reviews/<lens>_<round>.md and returns the path.
Step 6 — Merge and route
Read the panel's reports and merge them per loop_rules.md: deduplicate overlapping findings, resolve contradictions, drop findings without evidence, classify each as blocker / major / minor. Write the merged result to merged_findings_<round>.md.
- Any blocker or major remains → continue to Step 7.
- Only minors remain (or nothing) → the panel passes; go to Step 8.
Step 7 — Worker improves, panel re-checks
Hand the merged_findings_<round>.md path back to the same worker (continue it with SendMessage so it keeps its build context; if the original worker is unavailable, spawn a fresh one and additionally hand it the previous worker_report_<n>.md path so it inherits the prior decisions). The worker fixes or, with stated reasons, rebuts, and writes worker_report_<n+1>.md.
Then re-review in focused mode: each reviewer receives the path to its own previous review file and re-checks only its previously-flagged items plus a quick scan for newly-introduced breakage — not a full re-read. This keeps round 2+ cheap.
Loop back to Step 6. Maximum 3 improvement rounds; on hitting the cap, stop and report residuals honestly rather than spinning.
Step 8 — Summary and session cleanup
Close with the short summary format in loop_rules.md: what was built, what the panel caught and the worker fixed, what minor items remain, and how many rounds it took. Written for someone who will not read transcripts — no internal vocabulary, no schemas, in the user's language.
Then settle the session directory per session_protocol.md: delete it on a clean pass; preserve it and print its path in the summary on any other termination, so the user can trace what got stuck.
Defaults that keep this vibe-coder friendly
- Zero configuration: panel composition, scout activation, round cap, and severity handling are all automatic.
- The user sees at most three things: the one-line panel announcement up front, the simplicity-gate question (only when the task looks trivial), and the final summary.
- Minor findings never trigger another round — they ride along in the summary as "알아두면 좋은 것" items.
- If the worker and a reviewer disagree and the worker's rebuttal is reasonable, the orchestrator decides; it escalates to the user only when the disagreement changes what the user would receive.
- The session plumbing stays invisible: its path surfaces only when something went wrong and the trail is worth keeping.
Reference files
| File | When to read |
|---|---|
| session_protocol.md | Step 1 and Step 8 — directory layout, read-access matrix, session naming, cleanup rules |
| reviewer_panel.md | Step 2 and Step 5 — lens roster, selection rules, reviewer prompt template |
| worker_prompt.md | Step 3, Step 4, Step 7 — scout prompt, worker build prompt, improvement-round prompt |
| loop_rules.md | Step 6 to Step 8 — merge rules, severity definitions, termination, summary format |
Document Writing
Create documents that help a specific reader understand, act, decide, comply, recover, or reconstruct what happened. The skill routes first and writes second: a polished document built from the wrong document contract is still wrong.
Document structure, writing style, and review methods are defined in this package. Use SKILL.md and its package-local references as the complete working instructions; do not fetch external writing guides or methodological articles to apply the skill. Research needed to verify facts about the requested document's subject follows the source-grounding workflow.
Scope
This skill supports eleven target document types:
- Explanatory overview
- Action guide
- Reference or specification
- Proposal
- Analysis report
- Policy or rules
- Troubleshooting runbook
- Record or meeting notes
- Feature Design Doc (FDD)
- Design System Document
- Software project documentation (README and usage profiles)
The document type describes the artifact being created or assessed. Words appearing only as the subject do not select a type. For example, "write a guide to authoring FDDs" targets a guide, while "write an FDD for saved filters" targets an FDD.
Workflow
1. Identify the requested operation
Identify each separately requested document deliverable and determine whether the user wants to create, update, rewrite, review, fact-check, or normalize it. When an existing document is involved, inspect it before deciding how to proceed. Apply the workflow independently to each deliverable, preserving dependencies and shared source facts; a report and a proposal requested together keep separate document contracts. Do not split one document merely because it contains supporting explanation, recommendations, or steps.
Review is an operation, not a proposal type. A request such as "review this policy" routes to the policy type with the review operation.
Review and fact-check are non-mutating unless the user separately requests an update. They may inspect and research, but must not create, rename, or edit document files. Create, update, rewrite, and normalize are mutating operations within the requested document scope.
2. Identify the target artifact
Use evidence in this order:
- The artifact the user explicitly asks to create or change
- Existing document metadata, path, title, and headings
- The reader's primary outcome
- The content shape implied by the request
If an explicit label conflicts with the requested outcome and the choice materially changes the structure, ask one concise clarification question. Put that question directly in the user-facing response and phrase it so the user can answer the single unresolved choice; a decision note inside an artifact is not a substitute for the question.
3. Select exactly one document type per deliverable
| Type | Select when the primary reader outcome is | Do not select when | Start with |
|---|---|---|---|
| Explanatory overview | Understand a concept, context, or meaning from a readable narrative | The reader needs exact lookup, ordered action, or a design decision source | explanation-overview.md |
| Action guide | Complete a known task from a normal starting state | The starting state is an incident or unknown failure | guide-overview.md |
| Reference or specification | Look up exact definitions, fields, states, options, or contracts non-linearly | The reader needs a conceptual introduction or whole-feature design | reference-specification-overview.md |
| Proposal | Choose, approve, fund, or commit to a future action | The document only reports findings or defines an approved feature's design | proposal-overview.md |
| Analysis report | Understand evidence, findings, implications, and limitations | The primary value is chronology or an explicit approval request | analysis-report-overview.md |
| Policy or rules | Follow durable obligations, permissions, prohibitions, and exceptions | The document is a one-time procedure or a single feature's full design source | policy-rules-overview.md |
| Troubleshooting runbook | Diagnose and recover from an abnormal state | The reader is following a normal installation or usage path | troubleshooting-runbook-overview.md |
| Record or meeting notes | Reconstruct past events, statements, agreements, and chronology | The document interprets evidence as a report or defines current product design | record-minutes-overview.md |
| Feature Design Doc | Use one product feature's behavior, flows, policies, scope, and alternatives as a design decision source for implementation | The artifact is a feature introduction, guide, interface specification, performance report, or build-approval proposal | feature-design-doc-overview.md |
| Design System Document | Use a durable source for product UI foundations, tokens, components, and patterns, or for any digital storefront's visual asset rules | The user wants UI code, a mockup, generated images or assets, or a system or architecture design | design-system-overview.md |
| Software project documentation | Assess an actual software project, install or access it, achieve first use, or find its recurring tasks and configuration | The filename merely wraps another document contract, or the artifact is a standalone API specification, single-task guide, or design decision source | software-project-overview.md |
For software project documentation, the overview owns README/usage profile selection, combined roles, and package-level destinations. Filenames alone do not change the document contract: a design-system index named README.md retains its set's contract, and a guide about writing READMEs remains an action guide.
4. Apply the Design System Document gate and select prebuilts per output set
Select Design System Document only when a requested artifact governs reusable visual or interaction decisions across product UI or any digital storefront's listing assets. A request whose only deliverable is UI, a mockup, images, video, or other produced assets is a production task, not this document type.
For each output set, choose exactly one prebuilt from semantic intent:
| Prebuilt ID | Select when the document governs | Default output root |
|---|---|---|
default | Product UI foundations, tokens, components, content, accessibility, and patterns | docs/design-system |
app-store-page | A digital storefront listing's visual assets, using whatever asset vocabulary and media types its operator defines | docs/design-system-visual-assets |
The requested output path never changes a prebuilt. Resolve each root in this order: a user-specified directory for that set, the location of the existing document set being changed or reviewed, then the selected prebuilt's default output root. A user-specified directory replaces only the prebuilt root; it does not collapse a multi-file set into README.md or another single file. Read only the prebuilt reference for that output set.
Read the selected type's overview and follow its operation-specific references. The ordered decision table in design-direction-workflow.md owns when to ask, write, stop, or report a partial result. Apply it independently to each set; it distinguishes new or direction-changing work, focused revisions, read-only review, and unresolved conditional branches.
Inspect available evidence before asking. For an existing set, inventory the entire tree—not only writable files—and follow its index and approval/change/decision owners before saying that an approved value is unavailable.
If the user explicitly requests both product UI and storefront visual asset systems, split the request into two coordinated Design System Document output sets and apply default and app-store-page independently. Use their separate default roots unless the user supplies one directory for each; ask once before writing if one custom root does not establish the two destinations.
Two sets for the same product and brand may share an approved upper-level direction when authoritative evidence supports it, but validate and document each set's contextual adaptations independently.
For app-store-page, follow storefront-research.md for each actually included target. It owns inclusion and identity resolution, official research, operation-specific writes, and capability-limited fallback, including the whole-set stop when neither online research nor sufficient identity evidence is available.
When a request combines a document with actual UI, image, or video production, keep the document portion under this skill and route the production portion to the appropriate capability as a separate deliverable. Do not let either portion suppress or silently replace the other. In the completion report, label document outputs and production outputs separately and attribute each to its owning workflow; do not imply that document authoring itself produced a binary asset.
For product UI, the selected prebuilt defines component-level design contracts and the workflow to include in the document for presenting new UI previews. Document-only work records that workflow; an authorized mixed request also delivers the actual preview through its production capability.
Before reporting a new saved set as complete, follow the structural verification instructions in design-system-authoring.md. A structural pass does not establish direction approval or semantic quality.
5. Apply the FDD gate
Select FDD only when all of these are true:
- The subject is one product feature.
- The artifact defines what the feature is and why, including material behavior, flow, policy, scope, or alternative decisions.
- Implementers or code agents should treat the artifact as the current design decision source.
The word "feature" or "FDD" appearing as background is not enough. If the artifact teaches how to write an FDD, route to a guide. If it lists an API contract for a feature, route to reference or specification.
6. Resolve generic boundary cases
When no explicit target type settles the choice, use the reader's final action:
- Learn or understand: explanatory overview
- Complete a normal task: action guide
- Retrieve an exact fact or contract: reference or specification
- Approve or choose: proposal
- Interpret evidence: analysis report
- Comply with durable rules: policy or rules
- Recover from failure: troubleshooting runbook
- Reconstruct the past: record or meeting notes
- Govern reusable product UI or digital storefront visual asset decisions: Design System Document
- Evaluate and begin using a software project, or find tasks in its usage manual: software project documentation
Recommendations do not automatically make a report a proposal. Steps do not automatically make a policy a guide. Choose the type that controls why the document exists.
7. Load references progressively
After routing:
- Read only the selected type's overview reference.
- Follow that overview's operation-specific links.
- Do not load the whole type directory.
- Load another type's references only for a separately requested deliverable or a justified reroute, not merely for inspiration.
- If clear evidence shows the route is wrong, discard the previous type contract, return here, and route again.
For all substantial creation, rewrite, or review work, read human-readable-writing.md. Apply its four reader outcomes—relevant, findable, understandable, and usable information—within the selected type and requested operation. Read source-grounding.md only when factual claims require sources or verification. Read existing-document-edits.md only when modifying or reviewing an existing document.
For substantial authoring or review, read drafting-and-revision.md to connect preparation, content review, prose editing, and completion. For focused updates, normalization, or fact-checking, apply only its relevant steps to the requested scope; a mechanical correction does not require the full workflow. Read the selected type's review or validation reference for its applicable quality and completion criteria, without loading unrelated references. Type-specific structures, operation boundaries, and validation sequences take precedence over this shared method.
8. Gather context before drafting
Establish the audience, the reader's starting situation and knowledge, the intended outcome, authoritative inputs, constraints, and output destination. Infer what is safely recoverable from supplied material or the repository. Ask only when an unresolved choice would materially change the document's scope, behavior, or tradeoffs. This includes the primary reader: when the request, supplied material, existing document, and selected type do not establish who will read the document, what they already know, or the situation in which they will use it, and plausible answers would change its type, depth, or structure, ask before drafting. Combine this with any other unresolved choice and offer two or three likely readers drawn from the context. Where the selected type's workflow defines its own questions, follow it instead of adding a reader question. When no live user can answer, write for the most likely reader the context supports and report that assumption.
Before drafting, identify the requested coverage, applicable type-specific completion conditions, and how material unknowns must be handled. Accept notes, fragments, questions, and supplied conversation records as starting material. When a new draft or substantial rewrite needs an outline, optionally organize reader questions and existing evidence using the shared drafting reference; reuse an established outline or decision note when it already serves that purpose.
Do not invent missing decisions or facts. Mark unresolved content explicitly when no live user can answer.
9. Draft and verify
Follow the selected references. Use their structure as a reader-centered default, not as filler. Generic document types may omit sections that do not help the reader. FDD follows its stricter profile and validator contract.
Review content before polishing prose: check both whether readers can find, understand, and use the answers they need and whether material requirements and source facts survived accurately. Resolve content issues within the operation's scope, then edit wording. If editing changes meaning, certainty, conditions, or obligations, recheck the affected passages and their dependencies. Review and fact-check report findings rather than applying corrections. Keep any type-specific structural and semantic checks in their required order.
Before delivery, confirm:
- The opening states the purpose, conclusion, outcome, or request appropriate to the type.
- Headings expose the document's logic when scanned.
- Each paragraph has one main idea.
- Facts, interpretation, decisions, and recommendations are distinguishable.
- Examples and expected results are concrete where useful.
- Independently readable summaries, headings, tables, and steps retain the material conditions, exceptions, and uncertainty that govern their claims or instructions.
- No empty, duplicated, or ceremonial sections remain.
- The result still matches the selected document type.
- For software project documentation, apply its reader-path review and common evidence and consistency contracts to the requested scope.
- For a multi-file Design System Document, every substantive supplied decision is in the owning prebuilt file, every required owner is linked from
index.md, and the actual changed paths match the files the completion will claim. - For a Design System Document, the operation-specific decision table was followed, the approved direction and decision classes are clear, and representative verification covers the scope required by that operation or is recorded as pending.
- For a Design System Document, major patterns explain when to use or avoid them and why; product UI components have findable visual, sizing, and composition contracts, including inherited rules and necessary unknowns. New-UI preview requirements and any claimed preview delivery follow the selected prebuilt and the actual request scope.
- No Design System Document file was created or modified in a branch where the decision table requires a stop; partial work is reported as partial.
- No supplied or verified value has been replaced by convention; no fact, such as a policy, platform behavior, or storefront requirement, has been added without a source; and no design value has been recorded as canonical without supply, verification, user approval, explicit delegation, or a labeled provisional status with a verifiable source.
- Any unresolved choice that requires the user is asked once as a direct question in the user-facing response, not left only as an internal decision note.
File output and collision rules
- Resolve a type-specific output destination in this order: a user-specified path, the existing target's location, then the selected type or prebuilt's default location.
- A Design System Document prebuilt writes a multi-file set, so its root must be a directory. For a new set, ask once if the user provides a
.mdpath instead of a directory. For an existing file inside a set, resolve and preserve its established set root. - Inspect an existing target before writing.
- Update the established artifact only when the request is an update or the selected reference defines in-place lifecycle behavior.
- Do not silently overwrite a different document.
- Do not invent -v2, -final, or date-suffixed duplicates to avoid deciding what the canonical file is.
- Preserve existing platform, storefront, and custom files outside the requested change scope; "not requested" does not mean "delete" or "invalidate".
- If the user asks only for a draft in conversation, return complete Markdown without creating an unsolicited file.
- Follow type-specific location rules when the selected reference defines them; FDD is one such type.
Preservation and safety
When editing, preserve fenced code blocks, paths, identifiers, exact logs, quotations, and user-owned custom sections unless the user explicitly asks to change them. Preserve caller options and established document contracts. Warn before any instruction that can destroy data or materially disrupt a system.
Completion
Use the completion conditions established before drafting. Necessary uncertainty handled under the selected type's rules is not automatically unfinished authoring: a record can faithfully preserve an open decision, and a report can conclude that evidence is insufficient. Conversely, marking a gap does not satisfy a type's blocking requirement. Once the requested scope and required checks are satisfied, stop when only optional embellishment remains; do not narrow requested coverage or omit necessary evidence to finish sooner.
Before reporting completion, compare the resolved output contract and promised paths with the actual final artifact tree. Fix missing owners, links, or files first; if they cannot be produced, report the work as incomplete instead of claiming completion. Report the selected document type, the artifact produced or reviewed, validation performed, and any limitation that remains unverified. Never claim an unrun check passed.
For a Design System Document, also report the maturity state; the authority for the approved direction; which decisions were delegated, recorded as provisional defaults, or left awaiting approval; the representative situations actually checked or still pending; and any unresolved decision. Distinguish completion of a focused revision from whole-set validation; apply the decision table's completion limits to new, direction-changing, and partial work.
Iterative Self-Review
A controlled loop where the main agent owns the answer and, when the user explicitly asks for verification or review, a clean-context sub-agent performs blind verification before the response is surfaced to the user. The sub-agent never edits the artifact, never writes the final response, and never receives anything beyond the applicable user input and the current main-agent response.
The loop guards against two failure modes:
- The main agent over-trusting its first draft.
- The verifier being biased by hidden hints, prior findings, or the main agent's reasoning.
When to use
Use this skill only when the user explicitly asks for verification, review, re-checking, proof, cross-checking, or another second-pass quality gate. Do not run this skill automatically for ordinary conversation or routine task completion.
When invoked, treat all of the following as current_response artifacts:
- Code work and file-change reports.
- Documents, design proposals, specifications, and plans.
- Ordinary prose answers, summaries, recommendations, and explanations.
- Claims that work was done, files contain something, or a conclusion follows from inspected material.
If the user explicitly narrows verification to one part (for example, "이 파일만 검증해줘", "요약 부분만 봐줘", "3번 항목만 확인해줘"), construct {{USER_INPUT}} from only the user utterances needed to define that requested scope and pass only the corresponding part of {{MAIN_RESPONSE}}. Do not let unrelated conversation context broaden the review.
Core principles
- Independent context contract. The sub-agent receives exactly two textual inputs: the applicable user requirements and the current response. Blocked: prior findings, the main agent's reasoning, planning, routing intent, evaluation-criteria summaries. Not blocked: reality — read-only access to cited artifacts is required so response claims can be verified. "No other context" means no main-agent context, not "no tools".
- Immutable base block. Within one verification session, the applicable user requirements, verification criteria, tool policy, and output schema remain byte-identical across rounds. Only the current response changes. If the user adds a new requirement, update the base block once and treat that as the new baseline.
- Sub-agent tool scope. Allowed: read-only inspection tools only. Forbidden: edits, writes, shell file utilities, state-mutating commands, user dialog, asking for more context, calling other agents, WebSearch, arbitrary browsing. Scope is bounded by claim-linkage: trace dependencies as far as needed to verify a specific claim, stop the moment the trace no longer maps to a claim. Full wrapper-vs-reality and cross-platform tool rules live in
sub_agent_prompt_template.md. - Inspection manifest is mandatory. Every cited artifact must have an
artifact_inspectionsrecord. Intentionally skipped artifacts should be listed inskipped_artifacts. Acleanverdict without complete manifest coverage is invalid. Schema and enforcement live inreport_format.md. - No numeric confidence. LLM-rated confidence scores, similarity ratios, and thresholds are unreliable. Use qualitative signals and deterministic counts only.
- Evidence-mandatory findings. Every issue, missing item, and unverified assertion must include a direct quote. Findings without evidence are downgraded.
- User clarification is a main-agent decision. The sub-agent flags ambiguity; the main agent decides whether to ask.
- Sub-agent reports to the main agent only. It never speaks to the user, never composes the final answer, never asks for additional context.
Role split
| Role | Responsibilities | Forbidden |
|---|---|---|
| Main agent | Draft answer, call sub-agent, parse report, route findings, revise, decide termination, ask user when needed, write final response with metadata | Pass prior findings, reasoning, or criteria summaries to the sub-agent |
| Sub-agent | Blind review, emit YAML report, quote evidence, classify unverified assertions | Edit the answer, write the final response, ask the user, request more context, invent context |
Workflow
Step 1 — Initial draft
Write the best current response. This is iteration 0's current_response. The response may be code-related, document-related, a plan, a summary, a file-change report, or ordinary prose.
Step 2 — Blind sub-agent call
Invoke the sub-agent with the prompt body from sub_agent_prompt_template.md. The template takes exactly two variables: {{USER_INPUT}} and {{MAIN_RESPONSE}}. Add nothing else.
{{USER_INPUT}} is not "the user's last message" — it is the applicable substantive task request that serves as the reference point for verification. When the user explicitly narrows verification, include only the user utterances that define that scope. When the most recent user message is a meta-trigger (skill re-invocation, "한번 더", "again", greetings, plain acknowledgements, or any message with no task information), reconstruct the slot by chronologically excerpting only the user's own utterances from earlier in the conversation. The reconstructed block must consist solely of verbatim user quotes — no main-agent summaries or interpretations. The canonical definition of the reconstruction rules and procedure lives in the Call-site notes of sub_agent_prompt_template.md.
The seven review axes are inlined in the prompt. Their intent and scope guards live in verification_criteria.md.
Step 3 — Parse the report
The sub-agent emits the YAML schema in report_format.md. Validate per that file's enforcement rules; re-call the sub-agent when the report is invalid. After two consecutive invalid reports the verifier_invalid_report defensive trigger fires (see termination_triggers.md).
Step 4 — Route findings
Route each item per routing_rules.md. Key branches:
- Regular issues and missing items: accept or reject. Always log the reason for rejection — required for stable-findings and oscillation detection.
scope_creepissues: do not silently apply or remove them. Defer them to the user-decision phase unless they also contain ablockerormajorcorrectness problem.unverified_assertions:user_input_ambiguity+affects_direction=true→ ask user only after any accepted non-minor fixes have been re-verified.unverifiable_fact→ main verifies directly or hedges. Never ask the user.minor_defaultoraffects_direction=false→ use a reasonable default, state the assumption.
Step 5 — Two-phase loop
Phase A — Auto-fix and re-verify
- If any accepted
blockerormajorissue, missing requirement, or direction-affecting unverified assertion can be resolved by the main agent, revise the response. - When this iteration accepted at least one fix, do not surface user-decision items yet. Spawn the next verification round immediately with the immutable base block and the updated
{{MAIN_RESPONSE}}. - Phase A exits only after a round produces zero accepted non-minor fixes.
Phase B — User-decision items
- Surface
minoritems as residual information when useful. - Surface
scope_creepas a keep/remove decision. - Surface unresolved
user_input_ambiguityitems that affect direction as direct questions. - If the user's answer causes any response or artifact change, return to Phase A and re-verify before finalizing.
Step 5.5 — Routing-completion gate
Per the canonical definition in routing_rules.md. Positive triggers cannot fire while routed items remain unresolved.
Step 6 — Evaluate termination
At the end of every iteration, evaluate the termination triggers in the priority order defined in termination_triggers.md. The first trigger that fires ends the loop.
For trigger #5 (Stable findings), invoke the equivalence-judge sub-agent as defined in termination_triggers.md — a separate single-shot sub-agent that takes only the two issue sets and answers yes/no. This is distinct from the verification sub-agent and exists to keep equivalence judgments independent of the main agent's self-bias.
User clarification is not a termination trigger — it is a Phase B routing branch (pause → ask → resume from Step 1 without resetting the iteration counter).
Step 7 — Continue or finalize
If no trigger fires, loop to Step 2. Otherwise, go to Step 8.
Step 8 — Final response with termination metadata
Append the termination block defined in termination_triggers.md:
termination:
trigger: clean_pass | severity_floor | regression | verifier_invalid_report | sub_agent_failure | oscillation | stable_findings | no_progress | no_op
iterations: <count>
residual_issues:
- severity: minor
problem: <one-line description>
rejected_findings:
- problem: <one-line description>
reason: scope_creep | redundant | factually_wrong | weak_evidence
user_decisions:
- question: <asked>
answer: <user's answer>
failure_log:
- type: transient | permanent
cause: <one-line description>
attempt: <number>
Only clean_pass and severity_floor represent successful termination. Surface every other trigger to the user — do not hide them behind a normal-looking response.
Design checklist
- Sub-agent prompt contains only
{{USER_INPUT}}and{{MAIN_RESPONSE}}— no other variables. - When the user explicitly narrowed verification,
{{USER_INPUT}}and{{MAIN_RESPONSE}}include only the requested scope. - On rounds 2+, the user-input, verification-criteria, tool-policy, and output-schema blocks are byte-identical to the first round unless the user added a requirement.
-
{{USER_INPUT}}is not filled with only a meta-trigger one-liner (e.g., "한번 더", "/iterative-self-review"); it contains the substantive request reconstructed from the user's own utterances. - The reconstructed
{{USER_INPUT}}consists solely of verbatim user-utterance quotes — no main-agent summaries or interpretations. - No prior iteration data passed to the sub-agent.
- Sub-agent has read-only tool access only and is bound by claim-linkage scope.
- Sub-agent report includes
artifact_inspectionsfor every cited artifact, or an explicit failed inspection record. - Sub-agent report includes skipped artifacts or areas when it intentionally did not inspect them.
- Every issue/missing has an
evidencedirect quote (otherwise downgraded). - Every
unverified_assertionsitem hassource_of_uncertaintyandaffects_direction. - No confidence scores, thresholds, or similarity ratios used anywhere.
- Stable-findings equivalence uses the dedicated yes/no equivalence-judge sub-agent — never a numeric score.
- Termination triggers evaluated in the documented priority order.
- Step 5.5 routing-completion gate passed before any Positive trigger is allowed to fire.
-
user_input_ambiguity+affects_direction=trueroutes to a user question only after accepted non-minor fixes have been re-verified. - Final response includes the termination metadata block.
Reference files
| File | When to read |
|---|---|
| sub_agent_prompt_template.md | Step 2 — exact prompt body to paste into the sub-agent call (canonical wrapper-vs-reality rules) |
| verification_criteria.md | Step 2 — seven review axes and their scope guards |
| report_format.md | Step 3 — YAML schema, evidence/uncertainty enforcement, manifest enforcement (canonical) |
| routing_rules.md | Step 4 / Step 5.5 — accept/reject routing, unverified_assertions routing, routing-completion gate (canonical) |
| termination_triggers.md | Step 6 — nine triggers, priority order, equivalence-judge call, metadata schema |
JetBrains IDE Plugin Development (IntelliJ Platform SDK)
This skill carries the IntelliJ Platform SDK domain knowledge needed to write, debug, and modify
JetBrains IDE plugins using only APIs supported for external plugins. The source baseline is
IntelliJ Community tag idea/2026.2.2, commit 1c7e601c0423e544917046c23763b15d0282e2a3.
Guidance for 2024.1+ remains version-conditioned; this source baseline does not raise a
plugin's minimum supported IDE version automatically.
How to use this skill
- Establish the target IDE product/build, minimum supported version, IntelliJ Platform Gradle Plugin version, and Java/Kotlin toolchain from the project. Read the Public API boundary and mental model below before selecting APIs.
- Pick the reference file from the Capability index that matches the task and read it before editing.
- For end-to-end shapes — how the registrations, classes, and
plugin.xmlof a feature line up — open the matching folder underexamples/. - Before declaring any plugin-modifying task done, walk the Pre-flight checklist.
Do not invent extension point names, attribute names, or API signatures. The Platform is highly
specific about strings (language="JAVA" vs "java", EP IDs, attribute spellings); a wrong
character is enough to silently disable a feature. When unsure, surface the question to the user
with the relevant reference cited — and verify the spelling in the IDE's plugin.xml editor,
which auto-completes valid EP names from the loaded plugin set and underlines unknown ones.
Public API boundary
This rule applies to every reference, example, API call, base type, implementation, and EP
registration in this package. Use only APIs supported for external plugins. Java/Kotlin
public visibility alone does not establish that support.
- Reject
private,@ApiStatus.Internal,@IntellijInternalApi, internal EPs, and implementation classes not intended for external use. Inspect the exact member, containing types, supertypes, package annotations, module visibility, documentation, and EP declaration metadata in the target version. RespectNonExtendableandOverrideOnlycontracts as well. - Never bypass this boundary with reflection, accessibility overrides, internal casts, copied internal implementations, or suppressed inspections. Risk acceptance is not an exception.
- Internal source is evidence for understanding behavior only. If no supported API can implement the requested feature, explain the limitation and offer the nearest public API alternative; do not fabricate an equivalent capability.
- Evaluate external availability and stability separately. An
ExperimentalAPI is eligible only after external use is confirmed; state its applicable versions and instability and prefer a stable public alternative. Neither a missing annotation nor successful compilation proves that an API is supported or stable. - For changed API guidance, record the source tag, commit, source links, public-status evidence, and applicable versions. Check the minimum version separately from the baseline. If status remains unverified, keep that candidate out of recommended examples.
Read 00_public_api_baseline.md for the pinned evidence and version boundaries. IDE completion and Plugin Verifier supplement this review; neither grants permission to use an internal API.
Mental model — five invariants you must hold
These five invariants explain almost every "why doesn't this work?" question.
plugin.xmlis the contract. A class is invisible to the IDE until it is registered.@Service,@Service(cs)annotations and a fewMETA-INF/filename conventions are the only exceptions; everything else (extensions, listeners, actions, EPs you define, dependencies) must appear inplugin.xml(or aconfig-fileof an<depends optional>block).- Extensions are stateless; services hold state. EP implementations are constructed once
per scope and shared across all calls and threads. Storing mutable state on an extension
leaks across projects, threads, and dynamic reloads. Put state in a service
(
@Service/@Service(Service.Level.PROJECT)), and have extensions look it up on demand. - Threading is non-negotiable. Reading platform model state (PSI, VFS, Document, project model)
needs the API's documented read access. Writing needs the documented write context;
dispatcher and suspending write behavior depend on the target version (see
04_threading_model.md). Long work belongs on a background thread with progress and cancellation. EDT freezes are user-visible; lock violations are immediate exceptions or data corruption. New code on 2024.1+ uses Kotlin coroutines (cs.launch { },readAction { }, and the target-version dispatcher and write API). Disposeris how lifecycle works. Resources tie into aDisposableparent and the platform callsdispose()post-order when the parent goes away. Services are usually the right parent. Never useApplicationorProjectdirectly as a parent — that traps resources past plugin unload and leaks the classloader.CoroutineScopeinjection on a@Serviceis the modern alternative toDisposable.- Dynamic plugin reload imposes hard constraints. The default since 2020.1 is
require-restart="false". To stay reloadable: every EP your plugin contributes to and defines must be dynamic, no static caches of plugin classes, noobjectsingletons holding state, no listeners parented toApplication/Project, nooverrides="true"services.
Capability index
Use this section as a router. Do not bulk-read every reference. Start with the single most specific reference below, then add companion references only when the task crosses that boundary.
Reference filenames are prefixed by category for fast scanning: 01_core, 02_runtime,
03_lifecycle, 04_threading, 05_file_model, 06_code_insight, 07_language,
08_ui, 09_project, 10_execution, and 11_distribution.
- 01_core_gradle_project.md: Project setup, IntelliJ Platform Gradle Plugin 2.x, sandbox IDE, generated helper tasks, multi-module project shape.
- 01_core_plugin_xml.md:
plugin.xml, required descriptor elements, file naming conventions, and descriptor blocks for listeners/actions. - 01_core_dependencies.md:
<depends>, optional dependency config files,sinceBuild,untilBuild, and platform branch targeting. - 01_core_extensions.md: Using, ordering, iterating, defining, or discovering extension points.
- 01_core_extension_diagnostics.md: Plugin loading lifecycle and diagnosing extensions that are registered but ignored.
- 01_core_split_mode_remote_development.md: Split Mode, Remote Development, frontend/backend/shared modules, RPC boundaries, and split sandbox runs.
- 02_runtime_services.md: Light services, constructor rules, state holders, service-scoped
CoroutineScope, and persistent-state handoff. - 02_runtime_listeners_message_bus.md: Declarative listeners,
MessageBus,Topic, manual subscriptions, and listener lifetime. - 02_runtime_actions.md:
AnAction,update,ActionUpdateThread, action groups, keymaps, and action skeletons. - 02_runtime_typed_handlers_editor_actions.md:
TypedHandlerDelegate,EditorActionHandler, typing interception, autopopup routing, and multi-caret editor actions. - 02_runtime_legacy_component_migration.md: Migrating
ApplicationComponent,ProjectComponent, orModuleComponentto services, extensions, listeners, and startup activities. - 02_runtime_deprecated_api_migrations.md: Deprecated listener, coroutine-scope, action, and Plugin DevKit migration checks.
- 03_lifecycle_disposer.md:
Disposabletrees, safe parent selection, cleanup patterns,Alarm, and disposal triggers. - 03_lifecycle_leak_diagnostics.md: Disposer leak debugging, sandbox and heap checks, and leak-prone patterns without internal test APIs.
- 04_threading_model.md: EDT/BGT mental model, lock rules, dumb mode overview, and threading invariants.
- 04_threading_read_write_actions.md: Classic read/write actions,
ReadAction.nonBlocking,WriteCommandAction,invokeLater, modality, and annotations. - 04_threading_background_work_progress.md:
Task.Backgroundable, progress indicators, cancellation, synchronous progress, and fire-and-forget work. - 04_threading_coroutines_2024.md: 2024.1+ coroutine APIs,
Dispatchers.EDT, suspending read/write actions, progress, andrunBlockingCancellable. - 04_threading_thread_to_coroutine_migration.md: Replacing
Thread,ExecutorService, andTask.Backgroundablewith coroutine-based code. - 04_threading_diagnostics.md: Threading symptoms, common mistakes, best practices, and import map for suspending APIs.
- 05_file_model_vfs.md:
VirtualFile, file lookup, refresh, listeners, VFS lifecycle, and identity. - 05_file_model_documents.md:
Document, document lookup, reads, writes, synchronization with PSI, listeners, and guarded ranges. - 05_file_model_psi_basics.md:
PsiElement, PSI lookup, tree walking, modifications, whitespace, and formatting. - 05_file_model_psi_references_caching.md:
SmartPsiElementPointer,PsiReference, named elements, multi-language files, andCachedValue. - 05_file_model_uast.md: UAST for cross-JVM-language analysis (one inspection/line marker covering Java, Kotlin, Scala, Groovy),
UElement/UMethod/UCallExpression,sourcePsivsjavaPsi,AbstractBaseUastLocalInspectionTool, andUastHintedVisitorAdapter. - 05_file_model_indexing_stubs.md: Dumb Mode, smart mode,
FileBasedIndex, stub indexes, andAstLoadingFilter. - 05_file_model_psi_diagnostics.md: Common VFS, Document, PSI, index, and cache failure modes.
- 06_code_insight_editor_model.md:
Editor, caret, selection, multi-caret behavior, and editor coordinate systems. - 06_code_insight_editor_markup_lifecycle.md:
RangeMarker,MarkupModel,RangeHighlighter, scrolling, editor lifecycle, console filters, and guarded blocks. - 06_code_insight_file_editor_provider.md:
FileEditorProvider, custom editor tabs, preview editors, fake files, and editor disposal. - 06_code_insight_line_markers.md:
LineMarkerProvider, gutter icons, leaf-element rules, slow markers, and Dumb Mode behavior. - 06_code_insight_folding.md:
FoldingBuilder, descriptors, callbacks, custom folding settings, non-owned languages, and missing-fold diagnostics. - 06_code_insight_formatter_commenter.md:
FormattingModelBuilder+Block(indent/wrap/SpacingBuilder/getChildAttributes) forCtrl+Alt+L, andCommenterforCtrl+/line/block comment toggles. - 06_code_insight_inspections_intentions_quick_fixes.md:
LocalInspectionTool, inspections, intentions, and quick fixes. - 06_code_insight_inspection_options_suppression.md: Declarative inspection options, legacy options panels, description files, and suppression guardrails.
- 06_code_insight_refactoring_documentation_structure.md:
RefactoringSupportProviderand Rename/Safe Delete/Inline preconditions tied toPsiNamedElement.setName, Find Usages, andPsiReference.isReferenceTo. - 06_code_insight_documentation_target_api.md:
DocumentationTarget, PSI/symbol documentation providers, hover documentation, pointers, and legacy migration. - 06_code_insight_parameter_info_and_navigation.md:
ParameterInfoHandler, structure view, breadcrumbs, choose-by-name, and spellchecking. - 06_code_insight_surround_with.md:
SurroundDescriptor,Surrounder, selection-based code wrapping, and caret/formatting rules. - 06_code_insight_diagnostics.md: Generic "why does my code-insight provider do nothing?" debug flow (EP/language match, construction, threading, Dumb Mode, ordering, prod-only missing dependencies) plus cross-cutting
LineMarkerProvider/FoldingBuilder/Annotator/IntentionActionpitfalls. - 07_language_pipeline.md: End-to-end pipeline for adding a new language/DSL (FileType → Lexer → Parser → ParserDefinition → PSI → highlighter/annotator/completion/references/code insights), LSP-backed alternatives, and the order to implement them.
- 07_language_file_type.md:
Languagesingleton,LanguageFileType, case-sensitive Language ID, and<fileType>registration with mandatoryfieldName="INSTANCE". - 07_language_lexer_jflex.md: JFlex
.flexfiles,FlexLexer/FlexAdapter,%unicoderequirement,--charatGradle flag, andTokenType.WHITE_SPACE/BAD_CHARACTERconventions. - 07_language_grammar_kit_bnf.md: Grammar-Kit BNF — generated parser/PSI/element-type holder,
psiClassPrefix/psiPackage/elementTypeHolderClasssettings,mixinclasses for custom logic (never edit generated*Impl), and hand-rolledPsiParserskeleton. - 07_language_parser_definition_psi_file.md:
ParserDefinitionwiring (lexer/parser/IFileElementType/comment & whitespace token sets/element factory),PsiFileBaseroot file, and<lang.parserDefinition>registration. - 07_language_syntax_highlighting.md: Lexer-based syntax highlighting (
SyntaxHighlighterBase,TextAttributesKeywithDefaultLanguageHighlighterColorsfallbacks),<lang.syntaxHighlighterFactory>registration, andColorSettingsPagefor user-themable colors. - 07_language_annotator.md:
Annotatorfor PSI-based semantic warnings/errors,AnnotationHolderbuilder API (.create()is mandatory), Annotator vsLocalInspectionTooldecision, and stateless/cheap/cached-resolution rules. - 07_language_highlighting_filters.md:
HighlightInfoFilter, syntax/error highlighting suppression, external annotator filters, and false-positive control. - 07_language_completion.md:
CompletionContributor,CompletionType(BASIC/SMART/CLASS_NAME),CompletionParameters/CompletionResultSet,LookupElementBuilder, prefix matchers,runRemainingContributors, and<completion.contributor>registration. - 07_language_inline_completion.md:
InlineCompletionProvider, gray inline suggestions, provider registration, debounce, direct calls, and update behavior. - 07_language_next_edit_suggestions.md: Next Edit Suggestions, internal awaiter boundaries, direct-call routing, and public API guardrails.
- 07_language_postfix_templates.md:
PostfixTemplateProvider, postfix completion registration, description resources, and applicability diagnostics. - 07_language_references_resolution.md:
PsiReference,PsiReferenceContributor, multi-resolve, and search support. - 07_language_find_usages_provider.md:
FindUsagesProvider,WordsScanner, usage presentation, result grouping, Rename, and Safe Delete prerequisites. - 07_language_element_patterns.md:
PlatformPatterns/StandardPatterns/PsiJavaPatternsmatcher DSL — gating completion and reference contributors via.withParent/.withSuperParent/.afterLeaf/.afterSibling/customPatternCondition. - 07_language_injection.md:
MultiHostInjectorfor injecting another language into string literals (regex inside Java strings, SQL inside Kotlin templates) so the inner language gets full PSI/completion/inspection. - 07_language_code_vision_inlay_hints_polysymbols.md: Inline editor hints —
DeclarativeInlayHintsProvider(2023.2+) and legacy<inlayHintsProvider>for parameter/type hints,<codeVision.provider>for usages/refs counts, and Polysymbols for polyglot web files. - 07_language_custom_language_diagnostics.md: Custom-language pitfalls —
language=casing ("JAVA"vs"java"), reused statefulLexer, BNF mixin work in generated*Impl, uncached annotator resolution, no-opsetName, missingBAD_CHARACTERand<colorSettingsPage>. - 08_ui_surface_selection.md: Choosing between Kotlin UI DSL, JB Swing components, actions, or standard Swing fallback.
- 08_ui_settings_persistent_state.md:
PersistentStateComponent,BaseState, immutable state,@State,@Storage, andPasswordSafe. - 08_ui_settings_configurable.md:
Configurablesettings pages. - 08_ui_kotlin_ui_dsl.md: Kotlin UI DSL v2 panels and bindings.
- 08_ui_dialogs.md:
DialogWrapperand modal dialogs. - 08_ui_tool_windows.md:
ToolWindowFactoryand tool-window content. - 08_ui_jcef_embedded_browser.md:
JBCefBrowser, support checks, browser/client disposal, handlers, and JavaScript bridge safety. - 08_ui_layout_helpers.md:
JBSplitter,JBTabs, and layout helpers. - 08_ui_choosers.md: File, class, and reference choosers.
- 08_ui_tables.md:
JBTable,TableView, andListTableModel. - 08_ui_status_bar_widgets.md: Status bar widgets and editor-based popup widgets.
- 08_ui_drag_and_drop.md:
DnDSupport. - 08_ui_notifications.md:
NotificationandEditorNotificationProvider. - 08_ui_icons.md: Standard platform icon constants (
IconLoader.getIcon(...)), SVG resources underresources/icons/, dark-theme_dark.svgpairing, size conventions, andAllIcons.*catalog. - 08_ui_theme_metadata_named_colors.md:
JBColor, named colors,themeMetadataProvider, custom theme keys, and theme-change-safe color lookup. - 08_ui_data_context.md:
UiDataProviderandDataContext. - 08_ui_diagnostics.md: UI/settings/notification pitfalls —
BaseStatevarfields, missing@JvmFieldonSerializablePersistentStateComponent,roamingTyperules,Configurable.applynot flushing, leakedConfigurablepanels holdingEditor/Project, non-DumbAwareToolWindowFactory, missing<notificationGroup>. - 09_project_basics.md:
Projectlookup and lifecycle (e.project, service injection,ProjectManager.getInstance(),defaultProjectcaveats),messageBus, andisDisposed/isOpen. - 09_project_modules_roots_file_index.md:
Module, roots, content entries, order entries, andProjectFileIndex. - 09_project_libraries_sdks_facets.md:
LibraryTablesRegistrarand modifying libraries via Write Action,AdditionalLibraryRootsProvider/SyntheticLibrary,ProjectJdkTableand customSdkType/ProjectSdkSetupValidator, andFacetManager/FacetTypefor per-module tech config. - 09_project_workspace_model.md: Modern entity-based project structure —
ImmutableEntityStorage/MutableEntityStorage,WorkspaceEntitysubclasses (ModuleEntity,ContentRootEntity,LibraryEntity), suspendWorkspaceModel.update, changeFlow<VersionedStorageChange>, andSymbolicEntityId/ExternalMappingKeyfor external-system tracking. - 09_project_view.md: Public Project View customization with
TreeStructureProvider,ProjectViewNodeDecorator, and the supportedAbstractProjectViewPaneextension contract, plus limits on internal selection-helper and extractor methods. - 09_project_lifecycle.md: Project lifecycle hooks —
ProjectActivity(suspend) andStartupActivity.DumbAwarevia<postStartupActivity>,ProjectManagerListener,ModuleListener,ModuleRootListener. - 09_project_model_diagnostics.md: Project-model pitfalls —
defaultProjectmisuse, holdingProjectreferences on application-level state, root-model edits outside Write Action, missingmodel.commit()/dispose(), EDT iteration ofProjectFileIndex, ignoringisExcluded, non-DumbAwareStartupActivity. - 10_execution_run_debug_configurations.md: Run/debug configurations, factories,
RunProfileState, runners, run line markers, and before-run tasks. - 10_execution_process_console_terminal.md:
ProcessHandler,ConsoleView, filters, and embedded terminal. - 10_execution_external_system_integration.md: External System API for Gradle/Maven-style project importers.
- 10_execution_xml_dom_api.md: DOM API for typed XML configs (Spring beans, custom XML DSLs) —
DomElementinterfaces with@Attribute/@Required/GenericAttributeValue,DomFileDescription,Converter/ResolvingConverterfor reference resolution, and<dom.fileDescription>/<dom.extender>. - 10_execution_ide_infrastructure_apis.md: Error reporting, lifecycle listeners, paths, browser launcher, HTTP helpers, power-save mode, and web help.
- 10_execution_search_everywhere_api.md: Search Everywhere result providers, Remote Development-compatible APIs, serializable presentations, and migration from legacy contributors.
- 10_execution_diagnostics.md: Run/debug & integration pitfalls —
RunProfileState.executerunning on EDT, missingProcessTerminatedListener.attach(no exit-code line), globalOkHttpClienton a service blocking unload, DOMisMyFilenamespace bugs, EDT-boundErrorReportSubmitter/HttpRequests. - 11_distribution_dynamic_plugins_classloaders.md: Dynamic plugin requirements, reload verification, and classloader rules.
- 11_distribution_i18n_resource_bundles.md: Resource bundles, localized strings,
@Nls, and language-pack contributions. - 11_distribution_file_live_templates.md:
<internalFileTemplate>for New-File templates (Velocity.ftfiles underresources/fileTemplates/internal/, name must match) and<defaultLiveTemplates>XML atresources/liveTemplates/. - 11_distribution_vcs_extensions.md: VCS plugin EPs —
AbstractVcs,ChangeProvider,VcsDirtyScopeManager,ContentRevision/FilePath/VcsRevisionNumber,VcsRoot/VcsRootChecker, diff/merge tools, and when to extend the existing Git plugin via<depends optional config-file>instead of a newAbstractVcs. - 11_distribution_plugin_verifier.md:
verifyPluginGradle task (2.x replacement forrunPluginVerifier), binary compatibility and API-status reports, and limits distinct from sandbox behavior and unload verification. - 11_distribution_plugin_signing_marketplace.md: Plugin signing and Marketplace publishing.
- 11_distribution_deployment_checklist.md: Pre-release checklist, deployment mistakes, and release-related references.
Common task playbooks
These are decision sketches — they tell you which references to combine, not the full answer.
"Add a new feature triggered by a menu item or shortcut"
- Define an
AnActionsubclass — see02_runtime_actions.md. - Register it under
<actions>inplugin.xml— see01_core_plugin_xml.md. - Make
update()cheap; declaregetActionUpdateThread()— see02_runtime_actions.md. - Long work goes through
04_threading_background_work_progress.mdor04_threading_coroutines_2024.md.
"Add support for a new language"
- Start with
07_language_pipeline.md, then walk the step-specific language references in order:07_language_file_type.md,07_language_lexer_jflex.md,07_language_grammar_kit_bnf.md,07_language_parser_definition_psi_file.md,07_language_syntax_highlighting.md,07_language_annotator.md,07_language_completion.md, and07_language_references_resolution.md. - For search/refactoring/docs, add
07_language_find_usages_provider.md,06_code_insight_documentation_target_api.md, or06_code_insight_refactoring_documentation_structure.md. - For navigation/insights, add the matching editor reference:
06_code_insight_line_markers.md,06_code_insight_folding.md,06_code_insight_formatter_commenter.md,06_code_insight_inspections_intentions_quick_fixes.md,07_language_postfix_templates.md, or06_code_insight_surround_with.md. - Compare the implementation against
examples/simple_language_plugin/.
"Add a tool window with a settings page"
- Tool window surface:
08_ui_tool_windows.md. - State persistence:
02_runtime_services.mdand08_ui_settings_persistent_state.md. - Settings page:
08_ui_settings_configurable.md. - Panel construction:
08_ui_kotlin_ui_dsl.md.
"Migrate threading from Thread/ExecutorService/Task.Backgroundable to coroutines"
Read 04_threading_thread_to_coroutine_migration.md first. Add 04_threading_coroutines_2024.md for API details, 02_runtime_services.md for injected CoroutineScope, and 04_threading_background_work_progress.md when replacing progress indicators.
"Migrate a legacy ApplicationComponent/ProjectComponent to a modern shape"
Read 02_runtime_legacy_component_migration.md first. Add 02_runtime_services.md, 02_runtime_listeners_message_bus.md, 09_project_lifecycle.md, and 02_runtime_deprecated_api_migrations.md as needed.
"Picking a UI surface for a new feature"
Read 08_ui_surface_selection.md first. Then route to 08_ui_kotlin_ui_dsl.md, 08_ui_tool_windows.md, 08_ui_dialogs.md, 08_ui_tables.md, 08_ui_choosers.md, 08_ui_status_bar_widgets.md, 08_ui_notifications.md, or 08_ui_data_context.md based on the chosen surface.
"A registered extension does nothing in the running IDE"
Read 01_core_extension_diagnostics.md. Add 01_core_plugin_xml.md, 01_core_dependencies.md, or 01_core_extensions.md if the diagnosis points to descriptor, dependency, or EP spelling issues.
"A code-insight feature does nothing in production"
Read the provider-specific reference first — for example 06_code_insight_folding.md, 06_code_insight_line_markers.md, 07_language_annotator.md, 07_language_completion.md, 07_language_inline_completion.md, or 06_code_insight_inspections_intentions_quick_fixes.md. Then read 06_code_insight_diagnostics.md for cross-cutting pipeline checks.
"React to typing, Enter, Backspace, or editor actions"
Read 02_runtime_typed_handlers_editor_actions.md first. Add 06_code_insight_editor_model.md, 05_file_model_documents.md, and 04_threading_read_write_actions.md if the handler changes text or caret state.
"Add gray inline suggestions or an inline completion provider"
Read 07_language_inline_completion.md first. Add 06_code_insight_editor_model.md, 05_file_model_documents.md, and 04_threading_coroutines_2024.md if the provider needs editor state, document reads, debouncing, or cancellable background work.
"Work on Next Edit Suggestions"
Read 07_language_next_edit_suggestions.md first. Do not invent a Next Edit provider EP; if the user wants a third-party implementable suggestion source, route the implementation through 07_language_inline_completion.md.
"Make a plugin Remote Development-ready"
Read 01_core_split_mode_remote_development.md first. Add 08_ui_tool_windows.md, 08_ui_dialogs.md, 02_runtime_typed_handlers_editor_actions.md, or 06_code_insight_file_editor_provider.md when the feature has frontend UI or latency-sensitive editing behavior.
"Add a custom editor, preview, or embedded browser"
Read 06_code_insight_file_editor_provider.md first for editor tabs. Add 08_ui_jcef_embedded_browser.md only when the custom editor or tool window genuinely needs browser rendering.
Pre-flight checklist before declaring work done
Run through this whenever you touch plugin code or plugin.xml. Most regressions show up here.
-
plugin.xmlparses (open in IDE, no red underlines; XML DTD validation enabled). -
<depends>com.intellij.modules.platform</depends>is present. - Every API use, inheritance/implementation, and EP registration satisfies the public API boundary above on each supported branch, with source/status evidence recorded.
- Every new EP usage cites a real EP — verified against the IDE's
plugin.xmlcompletion (which only offers EPs from the plugins your<depends>resolved). Language IDs spelled correctly (case-sensitive). - Every new extension implementation is
final/class(notobject), parameterless constructor (or onlyProject/Module/CoroutineScope), no static initializers, no work in the constructor. - Every service is a light service (
@Service) unless there is a real reason not to. Constructors only take 0–2 of:Project,Module,CoroutineScope. No other services injected via constructor. - Every new
Disposableregisters under a plugin-controlled parent, notApplication/Project. - Long-running work runs off the EDT, calls
ProgressManager.checkCanceled()or uses coroutine suspension points, and re-throwsProcessCanceledException/CancellationExceptionrather than swallowing them. - PSI/Document writes are inside a
WriteCommandAction(orwriteCommandAction { }), so they participate in undo. - Dispatchers and read/write APIs match the target version and preserve modality,
cancellation, lifetime, and undo behavior; see the
04_threading_*references. No unownedGlobalScope, blocking UI waits, or raw thread-pool migration shortcuts. - Run Plugin DevKit inspections: "Non-default constructors for service and extension class", "Cancellation check in loops", "Plugin XML errors". They catch most violations automatically.
-
runIdeboots, the changed feature works in the sandbox, and the IDE log (idea.login the sandbox config dir) has no new exceptions related to the plugin. - If targeting multiple IDE versions: the
verifyPluginGradle task (2.x; older guides may call itrunPluginVerifier) passes against the declaredsinceBuildand a recent build. - If altering existing functionality: exercise dynamic install/update/uninstall in the
sandbox without IDE restart. Rebuild changed classes/resources before checking
autoReload; the setting does not compile source or prove unload safety.
Report each check as passed, failed, or not run with the actual command, target build, and observed result. Plugin Verifier is static compatibility analysis, not feature execution. These examples are partial integration skeletons; do not claim compilation or IDE execution without an independently buildable host project and an actual run.
Conventions used across this skill
- "EDT" = Event Dispatch Thread (Swing UI thread). "BGT" = any non-EDT thread.
- "PCE" =
com.intellij.openapi.progress.ProcessCanceledException. - "EP" = extension point. "Light service" = service declared via
@Service(noplugin.xml). - API availability and stability are separate: apply the public API boundary above before
considering
Experimental; follow the documented replacement forObsoleteAPIs. - Code samples are Kotlin where the platform offers a Kotlin-friendly API (which is most of 2024.1+); Java appears when an API has no Kotlin form or when describing legacy code.
Where to look inside this skill
The skill is self-contained — references explain the why, examples show the how:
references/— capability-indexed deep dives. Read the one that matches your task before editing.examples/simple_language_plugin/— full custom-language skeleton.examples/action_basics/—AnAction+ dynamicActionGroup+ keymap registration.examples/settings_persistence/—@Service+SimplePersistentStateComponent+ Kotlin UI DSL v2Configurable.examples/inline_completion_provider/— minimalInlineCompletionProviderplusplugin.xmlregistration.examples/folding_builder/— minimalFoldingBuilderExplusplugin.xmlregistration for a known host language.
When the user reports a behaviour you can't explain from these alone, stop and ask rather
than fabricate API names or attribute spellings. The IDE's plugin.xml editor (with
auto-complete and validation against the resolved plugin set) is the authoritative live
verification surface.
JetBrains IDE VM Options
Analyze the running IDE first, then propose the smallest defensible .vmoptions delta. Do not create or edit the user's files. Treat a flag being accepted by a JVM as compatibility evidence, not as proof of a performance improvement.
Workflow
1. Establish the runtime and baseline
Read prerequisite-check.md. Identify the IDE product/build, actual boot runtime vendor/version/build/path, bundled-versus-custom status, OS, architecture, current effective command line and flags, current custom options, and the process showing the problem.
The IDE build number is context only. It does not prove which runtime is active. The project SDK/JDK is not the IDE boot runtime.
If the exact runtime is unavailable, give collection instructions and limit the answer to diagnostics or runtime-independent changes. Do not infer an unconfirmed JBR major from an IDE version.
2. Confirm the process boundary
Determine whether the symptom belongs to the local IDE process, a remote IDE backend, Gradle daemon, build process, test JVM, language server, terminal process, or another child process. IDE .vmoptions affect only the IDE process to which the file is applied.
Redirect out-of-scope process tuning to that process's own configuration. Never claim that an IDE heap or GC change fixes a Gradle or test JVM problem.
3. Diagnose before selecting an option
Classify the observed evidence rather than mapping a symptom directly to GC:
| Evidence | First investigation | Relevant reference |
|---|---|---|
| IDE freeze or UI stall | Thread dump or IDE CPU profile; correlate with GC/safepoint data | common-options.md |
| High CPU or slow editing | Repeatable IDE CPU profile | performance-validation.md |
| OOM, low-memory warning, or heap saturation | Heap trend, post-GC occupancy, allocation rate | memory-options.md |
| Long or frequent GC pauses | GC log or JFR recorded on the IDE process | gc-options.md |
| Slow startup or indexing | Separate startup/indexing profile under controlled cache conditions | performance-validation.md |
If evidence is missing, explain how to collect it. A freeze alone is not evidence that the collector is the cause.
4. Ground every version-sensitive claim
For each proposed option, record the exact runtime family and build it applies to and distinguish:
- source declaration: a value or availability declared by a specific JBR/OpenJDK source revision;
- runtime-selected value: the ergonomic or initialized value reported by the user's running JVM;
- IDE bundle value: an option supplied by the product's shipped or custom
.vmoptionsfile.
Prefer the running IDE's jcmd VM.command_line and VM.flags -all output for effective values. Link source claims to the matching JBR version, revision, and file. Do not present a source initializer as the final value when runtime ergonomics can change it.
5. Propose a minimal delta
Read only the references relevant to the diagnosed cause:
| File | Use for |
|---|---|
| gc-options.md | Collector compatibility, selection conflicts, measured GC latency |
| memory-options.md | Heap, code cache, metaspace, references, native-memory trade-offs |
| common-options.md | Compiler, strings, threads, diagnostics, process boundaries |
| performance-validation.md | Application checks and controlled A/B comparison |
Default to an add/change/remove list against the confirmed current settings. Preserve unrelated IDE-supplied options and user properties. Remove duplicates by semantic key (for example, multiple -Xmx forms or collector selectors), and explain which effective value wins or conflicts.
Recommend one change purpose at a time. Do not use fixed large heaps, -Xms = -Xmx, lower compilation tiers, or forced compiler/GC thread counts as generic optimizations. State the observed condition that justifies them and their costs.
6. Include application, verification, and rollback
Tell the user to use the product's Help | Edit Custom VM Options action or the exact override source already confirmed. Do not advise editing the installation's default file.
After restart, verify the same IDE process with jcmd <pid> VM.command_line and jcmd <pid> VM.flags -all. Confirm the requested values, selected collector, and any ignored, obsolete, inactive, or overridden flags. JVM startup success alone is insufficient.
Give a rollback that restores the captured baseline or removes only the proposed delta. For performance claims, follow performance-validation.md.
Output contract
Unless the user explicitly requests a full file, return:
- Confirmed environment — IDE, actual boot runtime/build/path, bundled or custom status, OS/architecture, target process, and unknowns.
- Evidence and diagnosis — observations, likely cause, alternatives, and the provenance of version-sensitive facts.
- Proposed delta — options to add, change, or remove, with reason, applicability, and trade-off. Say “no VM option change yet” when evidence does not support one.
- Apply and verify — exact settings location, restart requirement, and effective-value checks.
- Rollback — how to restore the captured baseline.
- Before/after comparison — target metric and controlled A/B procedure, or a link to the relevant steps.
When a full configuration is requested, require the current effective/original options first, preserve required IDE options, annotate only the intended changes, and still provide the delta separately.
Compatibility and evidence boundaries
- Cover JBR 17, 21, and 25 only after confirming the actual runtime major and build.
- Treat unconfirmed or other runtime versions as unknown; do not approximate them with the nearest supported version.
- Verify platform- and build-dependent flags against the exact runtime binary before recommending them.
- Distinguish option recognition, option activation, and measured improvement.
- Report when a collector or diagnostic facility is absent from a particular JBR build.
- State when only JBR 25.0.4 source/default inspection is available and other builds or performance outcomes remain unverified.
Scope
This skill provides analysis, proposed text, verification commands, and measurement procedures for the JetBrains IDE process. It does not change IDE settings, run benchmarks, tune unrelated JVM processes, or guarantee performance gains.
Kysely Query Workflow
Translate query intent into Kysely code using the project's schema types, dialect, and installed API. Source SQL is optional. Keep SQL semantics and the application's result contract visible throughout the task.
1. Classify the request
- Convert SQL: identify input parameters, clauses, and expected output columns before mapping methods.
- Write a query: derive tables, relationships, filtering, cardinality, ordering, and desired result shape from requirements; ask for missing schema or business rules that determine the query.
- Modify or refactor: identify the intended behavior change, or preserve behavior for a refactor. Read the existing builder, helpers, execution site, and result consumer.
- Diagnose types: obtain the exact error, failing expression, relevant table types, and expected result. Follow the diagnostic order below rather than guessing a replacement type.
2. Establish project context and version
Inspect the relevant project package manifest, installed Kysely package metadata when available, lockfile resolution, TypeScript version, database dialect/server version, driver, schema types, and nearby query code. A dependency range is not an exact installed version. Account for workspace-specific resolutions and plugins that transform queries or results.
Use the user's requested version together with installation and lock information. If they conflict, ask which version to target before choosing APIs. If no version can be confirmed, explicitly state “Assuming Kysely 0.29.5” and proceed with that baseline; do not present it as the installed version. Missing dialect, schema, or return requirements still need clarification when they affect correctness.
For 0.29.x, read the version reference before selecting APIs. For another version, verify relevant APIs against that version's official release notes and tagged source/declarations. Do not apply the 0.29 reference as proof of compatibility with older or later versions, or silently upgrade the project.
3. Select references
Read only the topics required by the request, alongside the applicable version reference.
| Need | Reference |
|---|---|
| Selection, aliases, joins, subqueries, CTEs, aggregation, pagination, conditional selection | SELECT |
| Schema read/write types, inserted values, conflict handling, insertion results | INSERT |
| Assignments, update joins, affected rows, update results | UPDATE |
| Delete predicates, USING/JOIN, deletion results | DELETE |
| Boolean grouping, NULL, BETWEEN, values versus references, raw predicates | Operators |
| Ranking, value/aggregate windows, frames, top-N-per-group | Window functions |
| Runtime requirements, changed/removed APIs, patch differences | Kysely 0.29 |
For type errors, start with the shared type contract, then read SELECT for scope/result inference and the reference for the failing operation.
4. Convert, write, modify, or diagnose
Preserve query meaning
For SQL conversion, map clauses without changing boolean parentheses, NULL/three-valued logic, join kind or predicate placement (ON versus WHERE), duplicate rows, grouping, ordering, pagination, selected columns, or aliases. Preserve UNION versus UNION ALL and COUNT(*) versus COUNT(column). Do not add DISTINCT, filters, limits, or an arbitrary ordering to conceal uncertain semantics. Explain nondeterministic source pagination or representative-row selection.
For a new query, settle those same choices from the requirements. Prefer expression-builder callbacks for scoped references and dedicated methods for supported syntax. Bind data values; use a sql fragment when the target API cannot express the required syntax. Check database support separately from Kysely method availability.
When modifying code, follow the query through helpers to execution and result use. Retain the intended result shape (array, first row, optional row, or mutation metadata), transaction instance, plugins, and execution options unless the requested change requires otherwise. A builder-returning helper should remain a builder-returning helper when the request only changes its query.
Diagnose type errors in order
- Schema types: compare table/column names and read/insert/update types, including
Generated,ColumnType,Insertable, andUpdateable. Check driver-returned numeric, date, and JSON values separately. - Reference scope: check tables and aliases visible at the failing callback, correlated subqueries, CTE outputs, and outer-join nullability. Prefer callback-local
eb.fnwhen function arguments need the current query scope. - Expression types: distinguish values from references; check scalar subquery cardinality, operators, CASE branches, aggregate nullability, and explicitly typed raw fragments.
- Result types: check selected aliases,
$ifoptional fields,returning, execution method, helper annotations, and the final consumer. For excessive type instantiation, consult the official recipe and version fixes before suggesting$assertTypewith a structurally equal result type.
Ask for missing evidence instead of claiming an inferred schema or driver type is verified. Do not suppress the cause with any, a cast, or sql<T>. Type annotations do not convert runtime values; see the official type explanation.
5. Explain the result and verification
Provide the requested code or diagnosis, material assumptions (especially version/dialect/schema), the reason for meaningful changes, and what was actually verified. Match the amount of explanation to the request.
Distinguish query construction, SQL compilation, and database execution: a builder constructs a query; .compile() produces SQL and parameters; .execute*() or db.executeQuery() uses the configured driver. Compilation is not proof of server acceptance or correct returned data. See building and execution.
When verification is performed, compare SQL structure and parameter binding as well as result types/shape against the request. Report documentation review, type checking, compilation, and real execution separately; do not imply unperformed checks passed.
Maintaining version references
Keep the six topic references reusable. Add a separate references/kysely-<major>.<minor>.md for a subsequently supported minor release, then link it from this entry point. For patches in the same series, update that file's reviewed patch, date, sources, and relevant differences. Preserve the initial review baseline and distinguish changes that apply only after a particular patch. Do not create historical version files retroactively; consult official evidence for one-off older-version requests.
Linear Issue Creator
Create issues in Linear using the Linear MCP with a 1 main issue + N sub-issues structure.
Core Principles
| Aspect | Main Issue | Sub-Issue |
|---|---|---|
| Perspective | Business / user perspective | Developer / engineer perspective |
| Unit | One feature or problem | One PR-completable task |
| Key question | "What changes for the user?" | "What code do we change?" |
| Labels | None | Exactly 2 (1 area + 1 type) |
| Status mgmt | Auto-completes when all sub-issues are done | Transitions individually |
Workflow Selection
Before gathering requirements, determine the workflow type:
| Workflow | When to use | Description |
|---|---|---|
| Generic | Code tasks: feature, bug, refactor, etc. | Use existing flow as-is |
| PRD Pipeline | Issues requiring a PRD (product requirements doc) or feature spec | Apply content skill principles for high-quality descriptions |
- Generic → proceed to Issue Creation Workflow section below
- PRD Pipeline → proceed to PRD Pipeline Workflow section below
If the user doesn't specify, infer from the work description. Ask if unclear.
Mandatory Rules (Never Skip)
1. Project Linking
Every issue (main + sub) must be linked to a project via the project parameter.
2. Title Prefix
Every issue title must start with [ProjectName].
Examples:
[corral] Implement global hotkey system[corral] Configure Tauri global hotkey plugin
3. Labeling (Sub-Issues Only)
Each sub-issue must have exactly 2 labels. The main issue has no labels.
Area label (pick exactly 1):
Back-endFront-end
Type label (pick exactly 1):
Bug— Bug fixChore— Build, config, dependency maintenanceDocs— DocumentationPerf— Performance improvementRefactor— Code refactoring (no behavior change)Feature— New feature or feature update
4. Team
Always use "private" as the team when creating issues.
Issue Creation Workflow
Step 1: Gather Requirements
Confirm the following with the user:
- Project: Which project (coin-agent, home-page, corral, intellij-jsoninja, etc.)
- Work description: What to build, fix, or change
- Area: Back-end / Front-end
- Type: Bug / Chore / Docs / Perf / Refactor / Feature
If the user has already provided sufficient information, proceed directly. Otherwise, ask.
Step 2: Create the Main Issue
Call Linear:save_issue to create the main issue.
Parameters:
title: "[ProjectName] Main title"
team: "private"
project: "project-name"
description: (use template below)
priority: appropriate priority (1=Urgent, 2=High, 3=Normal, 4=Low)
Use the main issue description template from references/templates.md.
Do NOT assign any labels to the main issue.
Step 3: Create Sub-Issues
Use the main issue's ID as parentId for each sub-issue.
Parameters:
title: "[ProjectName] Sub-task title"
team: "private"
project: "project-name"
parentId: "main issue ID or identifier"
labels: ["area-label", "type-label"] ← always exactly 2
description: (use template below)
priority: appropriate priority
Use the sub-issue description template from references/templates.md.
Step 4: Link Dependencies
If sub-issues depend on each other, connect them with blockedBy.
Linear:save_issue (update)
id: "dependent issue identifier"
blockedBy: ["prerequisite issue identifier"]
Step 5: Report Results
Summarize all created issues for the user:
- Main issue identifier + title + URL
- Sub-issue list (identifier, title, 2 labels, dependencies)
For a full flow example, see references/templates.md.
PRD Pipeline Workflow
Workflow for producing PRD-quality (product requirements document) issue descriptions. Applies principles from four content skills (content-strategy, content-production, content-humanizer, copy-editing) during the description writing process.
Fixed context:
- Target audience: Fullstack developers
- Language: Korean
- Tone: Professional (explaining to a peer developer — professional without being overly formal)
PRD Step 1: Gather Requirements + Select Pattern
Collect the same information as Generic Step 1 (Project, Work description, Area, Type). Additionally confirm:
- PRD topic: What the PRD is about
- Current state: Topic only, draft exists, or nearly complete
- Auto-select pattern:
| Pattern | Starting state | Content skill stages to apply |
|---|---|---|
| A. Blank → Complete | Topic only | content-strategy → content-production → content-humanizer → copy-editing |
| B. Draft → Complete | Draft exists | content-humanizer → copy-editing |
| C. Polish only | Nearly complete | copy-editing |
PRD Step 2: Write Descriptions (Per-Pattern Process)
Apply the applicable stages in order to write issue descriptions.
See references/prd-pipeline.md for the detailed guide.
Pattern A (Blank → Complete) — All 4 stages:
-
content-strategy principles: Plan the PRD structure
- Derive required sections from the target audience's perspective (feature overview, technical requirements, API specs, data models, non-functional requirements, etc.)
- Determine technical depth and scope for each section
- Establish sub-issue decomposition strategy
-
content-production principles: Draft the descriptions
- Write technical requirements at an implementation-ready level of specificity
- Make Acceptance Criteria measurable
- Define per-sub-issue Done Criteria at code level
- Use concrete numbers/specs instead of vague terms ("improve," "optimize")
-
content-humanizer principles: Remove AI patterns
- Eliminate repetitive phrasing (e.g., same sentence structure repeated)
- Remove unnecessary qualifiers ("very important," "essential," "critical")
- Replace with expressions developers actually use
- Deliberately vary sentence length
-
copy-editing principles: Run PRD-relevant Seven Sweeps checks
- Clarity: No ambiguous requirements
- Specificity: Concrete numbers, endpoints, data types specified
- So What: Each requirement explains "why it's needed"
- Prove It: Technical claims have backing (benchmarks, references, etc.)
Pattern B (Draft → Complete): Apply stages 3-4 only Pattern C (Polish only): Apply stage 4 only
PRD Step 3: Create Main Issue
Same as Generic Step 2 — call Linear:save_issue.
Use the PRD Main Issue Description Template from references/templates.md.
PRD Step 4: Create Sub-Issues
Same as Generic Step 3 — create sub-issues.
Use the PRD Sub-Issue Description Template from references/templates.md.
PRD Step 5: Link Dependencies + Report Results
Same as Generic Steps 4-5.
Pre-Creation Checklist
Verify before creating any issue:
Common:
- Is the project specified?
- Do all issue titles start with
[ProjectName]? - Does the main issue have no labels?
- Does every sub-issue have exactly 2 labels (1 area + 1 type)?
- Does each sub-issue's
parentIdpoint to the main issue? - Are all issues linked to the project via
project? - Are inter-sub-issue dependencies defined?
PRD Pipeline additional checks (when PRD workflow is selected):
- Is the pattern (A/B/C) determined?
- Has the description passed through all content skill stages for the selected pattern?
- Is it written in Korean?
- Is the Professional tone maintained?
- Are concrete specs included with no vague expressions?
- Are AI patterns (repetitive phrasing, excessive qualifiers) removed?
Linear Issue Reviewer
Review sub-issues completed by linear-issue-worker and decide whether to approve, request changes, or ask for clarification.
Position in Pipeline
| Stage | Skill | Role |
|---|---|---|
| 1 | linear-issue-creator | Creates main issue + sub-issues with structured templates |
| 2 | linear-issue-worker | Picks up sub-issues, performs code work, transitions to Done |
| 3 | linear-issue-reviewer | Validates Done sub-issues, approves or rejects |
The creator writes Done Criteria and Acceptance Criteria that serve as the contract for this entire pipeline. The worker fulfills that contract; the reviewer verifies it was fulfilled.
Comment Identifier Convention
Each skill uses a distinct comment prefix so comments can be attributed to the correct stage:
| Skill | Comment Identifiers |
|---|---|
linear-issue-worker | ## 🚀 Work Started, ## ✅ Work Complete |
linear-issue-reviewer | ## 리뷰 결과: |
Workflow
Step 1 — Receive Main Issue and Collect Sub-Issues
The user provides a main issue identifier (e.g., PRI-42).
- Call
Linear:get_issuewithincludeRelations: trueto fetch the main issue - Parse and store the Acceptance Criteria from the main issue description (used in final verification)
- Call
Linear:list_issueswithparentIdset to the main issue ID - For each sub-issue, call
Linear:get_issuewithincludeRelations: trueto get full details and comments
Step 2 — Identify Review Targets
Filter sub-issues to find those needing review.
Review target conditions:
- Status is
Done - A
## ✅ Work Completecomment exists (worker's completion report) - No
## 리뷰 결과:comment exists yet (not reviewed)
Re-review detection:
- If a
## 리뷰 결과: 🔄 Changes Requestedcomment exists AND a newer## ✅ Work Completecomment follows it → the worker has re-done the work → this is a re-review target
Status-based handling:
| Sub-Issue Status | Completion Comment | Review Comment | Decision |
|---|---|---|---|
| Done | Present | Absent | Review target |
| Done | Present | Approved | Already reviewed, skip |
| In Progress | Present | Changes Requested | Worker fixing, skip |
| Done | Present | Changes Requested → then new Work Complete | Re-review target |
| Done | Absent | Absent | Exception (see Step 3 exceptions) |
| Todo / In Progress | — | — | Skip |
Present the review plan and wait for user confirmation:
Review Targets (PRI-42):
1. PRI-43 — [project] Sub-issue title (first review)
2. PRI-45 — [project] Sub-issue title (re-review)
Skipped:
- PRI-44 — Already Approved
- PRI-46 — Still In Progress
Proceed?
Step 3 — Per Sub-Issue Review Cycle
For each review target, execute the following verification cycle.
Sub-Issue Review Cycle
3a. Collect Three Sources
Gather the three sources needed for cross-validation:
| Source | Origin | How to Collect |
|---|---|---|
| Done Criteria | Creator wrote in sub-issue description | Parse ## Done Criteria section from description |
| Completion Comment | Worker's change summary | Find comment containing ## ✅ Work Complete |
| Actual Code | Changed files | Extract file paths from the Changes section of completion comment → read files |
Also collect:
- Target Location: Parse
## Target Locationsection from sub-issue description - Technical Details: Parse
## Technical Detailssection from sub-issue description
3b. Verify Done Criteria
Check each Done Criteria item against both the completion comment and actual code:
- Find evidence in the completion comment for this criterion
- Verify in actual code that the condition is implemented
- Cross-validate: does the comment's claim match the code?
| Evidence in Comment | Confirmed in Code | Verdict |
|---|---|---|
| Yes | Yes | Fulfilled |
| Yes | No | Not fulfilled (comment-code mismatch) |
| No | Yes | Fulfilled (flag: comment should be updated) |
| No | No | Not fulfilled |
3c. Compare Target Location
- Check the file list specified in the sub-issue's Target Location section
- Check the file list in the completion comment's Changes section
- Compare:
- Specified file not changed → flag as possible omission
- Unspecified file changed → flag as possible scope creep
- Reasonable scope extensions (e.g., adding imports, test files) → allow but note
3d. Verify Technical Details Compliance
Cross-check against the Technical Details section:
- Libraries / patterns: Were the specified libraries used? Were the prescribed patterns followed?
- API spec: Do request/response shapes match the spec?
- Logic / data flow: Is the implementation consistent with the described flow?
3e. Code Quality Check
Review for general code quality regardless of what the issue specifies:
- Error handling is appropriate
- No hardcoded values (magic numbers, hardcoded URLs, etc.)
- Follows project conventions and code style
- No leftover debug code (
console.log,debugger, commented-out code, etc.) - Type safety is maintained (if TypeScript)
3f. Determine Verdict
Based on steps 3b–3e, choose one of three verdicts:
| Verdict | Condition | Status Change |
|---|---|---|
| Approved | All Done Criteria fulfilled, no critical quality issues | Keep Done |
| Changes Requested | Any Done Criteria not fulfilled, or critical quality issues found | Done → In Progress ("started") |
| Clarification Needed | Implementation choices need explanation, judgment reserved | Keep Done |
3g. Post Review Comment
Write a review comment based on the verdict. Use the templates from references/comment-templates.md.
Review Comment Quality Guide (Content Skill Principles):
Apply these principles when writing review comments to improve quality. Target audience: Fullstack developers | Language: Korean | Tone: Professional
- content-strategy: Structure review comments clearly (verdict summary → per-item verification → specific feedback → next steps).
- content-production: Include specific evidence and code references.
- "There's a problem" → "
notifications.service.ts:42queries notifications without userId validation. Other users' notifications could be exposed." - "Needs fixing" → "PATCH /notifications/:id/read returns empty body on 404. Should return
{ error: 'NOT_FOUND', message: '...' }format."
- "There's a problem" → "
- content-humanizer: Remove AI patterns and write in the tone of giving feedback to a peer developer.
- "Improvement is needed" → "This part would be better as ~"
- Remove unnecessary formality ("I would like to inform you of the review results")
- Make positive feedback specific too: "Good job" → "The cursor-based pagination implementation is clean"
- copy-editing: Focus on Clarity, Prove It, and Specificity.
- Verify review findings are not vague
- Verify change requests include specific resolution direction
- Include file paths and line numbers wherever possible
For Changes Requested, also transition the status:
Linear:save_issue
id: "<sub-issue-id>"
state: "started"
3h. Move to Next Sub-Issue
Proceed to the next review target and repeat from 3a.
Main Issue Final Verification
Execute this only when all sub-issues have been Approved.
Pre-condition Check
- Confirm every sub-issue has a
## 리뷰 결과: ✅ Approvedcomment - If any sub-issue still has
🔄 Changes Requestedor❓ Clarification Neededas its latest review, do NOT proceed with final verification — inform the user which sub-issues are pending
Acceptance Criteria Cross-Check
- Retrieve each Acceptance Criteria item from the main issue
- Map each item to the sub-issue(s) that satisfy it
- If all items are covered → post final review comment
- If gaps exist → identify which criteria are unmet and suggest next steps
Post the final review comment on the main issue using the templates from references/comment-templates.md (Final Review sections).
Apply the same Review Comment Quality Guide above to the final review comment as well.
For exception handling (missing comments, scope creep, conflicts, ambiguous criteria, re-review), see references/exceptions.md.
For Linear API details (state values, description parsing, comment identification, tool calls, retry policy), see references/linear-api.md.
Linear Issue Worker
Execute code tasks from Linear issues produced by the linear-issue-creator skill.
Read structured sub-issues, resolve dependency order, perform the actual file changes,
and keep Linear in sync throughout.
Contract with linear-issue-creator
The creator produces a 1 main issue + N sub-issues structure. Each sub-issue contains everything needed for one unit of code work: Task Description, Target Location, Technical Details, Done Criteria, and Dependencies. This skill consumes that structure and turns it into real code changes.
Workflow
Step 1 — Receive the Main Issue
The user provides a main issue identifier (e.g., PRI-42).
- Call
Linear:get_issuewithincludeRelations: true - Parse the main issue description to extract:
- Purpose / Background — why this work exists
- Goal — desired end state
- Acceptance Criteria — final validation checklist (used at the very end)
- Scope — boundaries of the work
- Impact Area — affected parts of the codebase
- Keep this context in mind — it guides all sub-issue work, but you do NOT code against the main issue directly
Step 2 — List and Sort Sub-Issues
- Call
Linear:list_issueswithparentIdset to the main issue identifier - For each sub-issue, call
Linear:get_issuewithincludeRelations: trueto retrieveblockedBydata- If
get_issuefails for a sub-issue, retry once. If it still fails, use the data already available fromlist_issuesand check theblocksfield of other sub-issues to infer the dependency graph
- If
- Filter out sub-issues with status
DoneorCanceled - Build a dependency-respecting execution order:
- A sub-issue is ready when it has no
blockedByentries, or all its blockers areDone - Sort ready issues by priority (Urgent first), then creation order
- If circular dependencies are detected, report to the user and stop
- A sub-issue is ready when it has no
Present the execution plan and wait for user confirmation:
📋 Execution Plan for PRI-42:
1. PRI-43 — [project] Configure hotkey plugin (no dependencies)
2. PRI-44 — [project] Build settings UI (blocked by PRI-43)
Proceed?
Step 3 — Process Each Sub-Issue
For each sub-issue in order, run the full execution cycle below. After completing one sub-issue, re-evaluate the remaining list — previously blocked issues may now be ready.
Sub-Issue Execution Cycle
3a. Read and Parse
Parse each section of the sub-issue description:
| Section | How to use it |
|---|---|
| Task Description | Understand what to build / change / fix |
| Target Location | Open these files to understand current code structure |
| Technical Details | Plan the implementation — patterns, libraries, API specs |
| Done Criteria | Exit conditions — every item must be satisfiable |
| Dependencies | Verify prerequisite sub-issues are already Done |
Check the sub-issue's labels to determine approach:
| Label | Approach |
|---|---|
Front-end | Work in frontend codebase, verify from browser/UI perspective |
Back-end | Work in server codebase, verify from API/DB perspective |
Feature | Design-first, build the new thing |
Bug | Root-cause analysis first, then fix |
Refactor | Preserve behavior, improve structure |
Chore | Config / build / dependency changes |
Perf | Measure before and after |
Docs | Documentation changes only |
3b. Transition to In Progress + Start Comment
Update the issue status:
Linear:save_issue
id: "<sub-issue-id>"
state: "started"
Post a start comment (write in Korean, Professional tone, no AI patterns — natural and direct):
Linear:save_comment
issueId: "<sub-issue-id>"
body: |
## 🚀 Work Started
### Approach
- [Implementation approach summary — include specific technical decisions]
- [Key files to modify or create]
- [Notable decisions or trade-offs]
3c. Perform Code Work
- Explore — Read files listed in Target Location to understand current state
- Plan — Based on Technical Details, decide exactly what to change
- Implement — Create or modify files
- Verify — Check each Done Criteria item against the changes
Guidelines:
- Respect existing code style and conventions
- If Target Location files don't exist, search nearby directories for the most logical placement and note the deviation in a comment
- If Technical Details reference a library not in the project, check
package.json/requirements.txtor equivalent first. Install if reasonable, or note the gap - Keep changes scoped to what the sub-issue describes — don't refactor unrelated code
3d. Self-Validate Against Done Criteria
Before marking complete, go through each Done Criteria checkbox:
- Confirm the condition is met by the changes
- If a criterion requires runtime verification (e.g., "API returns 422"), explain what was implemented and why it satisfies the criterion
3e. Post Completion Comment
Linear:save_comment
issueId: "<sub-issue-id>"
body: |
## ✅ Work Complete
### Changes
- `path/to/file1.ts` — [what changed]
- `path/to/file2.ts` — [new file, what it does]
### Done Criteria
- [x] Criterion 1 — [brief evidence]
- [x] Criterion 2 — [brief evidence]
### Notes
- [Any deviations, edge cases discovered, etc.]
Comment Quality Guide (Content Skill Principles):
Apply these principles when writing completion comments to improve quality. Target audience: Fullstack developers | Language: Korean | Tone: Professional
- content-strategy: Structure comments clearly (maintain Changes → Done Criteria → Notes order. Each section delivers the information the reader needs without gaps).
- content-production: Write specific, verifiable content.
- "Fixed it" → "Added inventory validation logic to POST /api/orders endpoint, returns 409 when out of stock"
- "Tests done" → "Added 3 unit tests (normal order, out-of-stock, invalid product ID)"
- content-humanizer: Remove AI patterns and write in natural Korean.
- Avoid repeating the same sentence structure — vary verb endings and phrasing
- Remove unnecessary qualifiers ("effectively," "successfully")
- Maintain the tone of explaining to a peer developer
- copy-editing: Focus on Clarity and Specificity.
- Verify file paths and change descriptions are concrete with no vague expressions
- Verify Done Criteria evidence is code-level verifiable
3f. Transition to Done
Linear:save_issue
id: "<sub-issue-id>"
state: "Done"
3g. Move to Next
Re-evaluate the remaining sub-issues. Issues that were blocked by the just-completed one may now be ready. Pick the next ready sub-issue and repeat from 3a.
For exception handling (missing files, unavailable dependencies, ambiguous criteria, blockers, deadlocks), see references/exceptions.md.
Completion
When all sub-issues are processed:
- Review the main issue's Acceptance Criteria
- Post a summary comment on the main issue (write in Korean, Professional tone. Apply content skill principles — specific, no AI patterns, clear):
Linear:save_comment
issueId: "<main-issue-id>"
body: |
## 📋 Overall Completion Report
### Completed Sub-Issues
- [x] SUB-01 — Title
- [x] SUB-02 — Title
### Incomplete Sub-Issues (if any)
- [ ] SUB-03 — Title (reason: ...)
### Acceptance Criteria Review
- [x] Criterion from main issue — satisfied by SUB-01, SUB-02
- [ ] Criterion from main issue — not yet met (reason: ...)
### Summary
[Concretely summarize all changes and current state]
- If all acceptance criteria are met and all sub-issues are Done, inform the user that the work is complete
- If some criteria are unmet, explain what remains and suggest next steps
For Linear API details (state values, description parsing, tool calls, retry policy), see references/linear-api.md.
Orchestration
A manager pattern for large tasks that break into a sequence of different kinds of work. The main agent stays a pure orchestrator: it decomposes the task, picks the topology that fits (a linear pipeline, a parallel fan-out, a dependency DAG, or an iterative loop), assigns each phase a tier, and runs phases as isolated sub-agents that exchange only file paths. It proves any expensive step cheaply before committing to it, validates each phase's output, surfaces progress as it goes, and stops at up to two points to let the user judge. It never does the phase work itself, and it never decides those points on the user's behalf.
Why the main agent never does phase work: a manager that also produces, runs, or scores inherits the producer's blind spots and loses the lean context it needs to sequence the whole run. Separating the orchestrator (decomposes, sequences, gates, reports) from the phase agents (each owns one phase in a clean context) keeps both honest — and keeps the orchestrator's context small enough to run a long task without drowning.
Why at most two user-judged stops, never more: the value is a long autonomous run the user can trust, not a babysat one. Most phases run on their own, and a run with no expensive step and no review halts zero times. But when those two judgments do arise — whether a cheap proof is good enough to commit the expensive step, and whether review findings are real — they are not the orchestrator's to make. Halting at every phase destroys the autonomy; folding either of these two into the orchestration makes it grade its own homework.
When to use
Only when the user explicitly invokes this skill or explicitly asks to run a task as a manager-driven sequence of sub-agent phases. Never auto-trigger on ordinary implementation requests or on task completion.
Use this when the task decomposes into heterogeneous phases — different kinds of work (investigate, produce, run, evaluate, report), in whatever topology fits. If the task is a single artifact that needs to be built and then reviewed, delegated-review-loop is the right tool. If it is a single answer that needs blind verification, iterative-self-review is the right tool. This skill is the backbone for everything larger and more heterogeneous than those.
Roles
| Role | Holds | Never does |
|---|---|---|
| Main agent (orchestrator) | Run id and session lifecycle, decomposition, topology choice, tier assignment, sequencing, cheap-proof framing, review-material routing, progress and reports, re-versioning on change | Perform phase work (investigate / produce / run / evaluate / analyze); decide a review finding's accept/reject for the user; inline phase content into a sub-agent prompt |
| Phase sub-agent (one per phase or per fanned-out item) | One phase's full working context and its own tools; writes its output as documents and returns paths | Run a different phase; talk to the user; inherit another phase's working context |
| Reviewer sub-agents (constructive and adversarial, optional) | The material to critique, received as paths; one lens each | Decide accept/reject (that is the user's judgment); edit the work; act on their own findings |
Run directory and path-passing
All inter-phase content travels as documents inside one per-run directory, .agents/orchestration/<run-id>/, created by the orchestrator at the start. The isolation contract keeps the orchestrator's context lean and keeps phases from contaminating each other:
- The orchestrator hands sub-agents file paths only — it never pastes phase content into a prompt.
- Each phase reads its inputs from files itself and writes its output as new documents in the run directory, returning only the path.
- Which paths the orchestrator hands to whom is the isolation contract. A phase that receives another phase's working notes is no longer isolated. The full layout, lifecycle, resume, validation, and run-id/superseded rules live in phase_protocol.md — follow it exactly.
Deliverables (code, artifacts, reports the user keeps) live at their real paths; the run directory holds coordination documents only.
Choosing a topology
The topology is the shape of the dependency structure between phases, and it decides how Step 5 executes and whether Step 4 applies. Pick the one that fits — do not default to fan-out:
- Linear pipeline — each phase feeds the next (investigate → draft → edit → publish). No fan-out.
- Parallel fan-out + reduce — split into independent items, run them concurrently, synthesize the results.
- Dependency DAG — phases with a partial order; some parallel, some sequential (a migration touching dependent modules).
- Iterative loop (nested only) — produce → critique → refine until a criterion holds, as one phase inside a larger run. A whole-task build-review-improve loop is
delegated-review-loop, not this skill. - Recursive decomposition — a phase discovers sub-phases and the orchestrator spawns them.
A run may nest these (a fan-out whose items are each a small pipeline). The per-topology rules for isolation, tiering, the cheap-proof gate, execution order, and aggregation are in orchestration_shapes.md.
Workflow
Step 1 — Frame, decompose, open the run
Extract the substantive task from the user's own words (reconstruct from earlier utterances with verbatim quotes if the invocation is contentless). Decompose it into phases — each phase is one kind of work with a clear completion condition. Decomposition heuristics: a phase should be one kind of work, one completion condition, and one tier; split a phase that spans two tiers or has independent failure modes; merge phases that always succeed or fail together. Create the run directory and a run-id per phase_protocol.md. Write the task and phase plan to run_plan.md. The plan is a working hypothesis, not a fixed conveyor — phases may be added, split, or re-versioned as the run learns (Step 8).
Step 2 — Pick the topology and assign tiers
Pick the topology (above; details in orchestration_shapes.md) that matches the phases' dependency structure. Then assign each phase a tier by the assignment rules in tiering.md — judgment-heavy work (design, evaluation, adversarial review, synthesis) to the high tier; mechanical work (investigation, command execution, transformation, aggregation) to the standard tier.
Step 3 — Investigate (optional, cheap)
If the decomposition depends on facts you do not yet have — how many items a fan-out covers, what the dependency graph is, what scope each phase faces — spawn one low-cost investigation phase first. It surveys and returns a topology/phase recommendation; it does not produce deliverables. Skip this when the shape is already known.
Step 4 — Cheap proof before an expensive commitment · HALT (go / no-go) · conditional
This applies only when the run has an expensive step to commit to — a wide fan-out, a long DAG, many loop iterations. Run the cheapest representative slice exactly as the full step would (one item per branch, or one phase end-to-end on a single input), then evaluate it for harness failures distinct from work failures (defined in phase_protocol.md).
This is halt type 1. Present the slice result and a go/no-go recommendation; do not commit the expensive step until the user approves. A slice that surfaces harness bugs is the gate working — fix the rig and re-slice rather than spending the full step on a broken one. If the topology has no expensive step (a short linear pipeline), skip this halt and say so in the plan.
Step 5 — Execute per topology
Run the phases in the topology's order — concurrently for independent fan-out items, sequentially for a linear pipeline, in dependency order for a DAG, repeat-until-criterion for a loop (per orchestration_shapes.md). For each phase:
- Run it in a fresh isolated sub-agent, paths only, writing outputs as documents and returning paths.
- Validate the output against its contract. On a contract violation (malformed, missing required fields, empty where output was required), retry up to the cap, then escalate — rules in phase_protocol.md.
- Be resume-aware: skip phases already completed under this run-id; continue from the first incomplete phase (phase_protocol.md).
- Close on completion and account every spawn with a close; leave no orphaned agents.
Step 6 — Review checkpoint · HALT (user judges) · optional
When the output warrants scrutiny, spawn reviewer sub-agents to generate material — at minimum a constructive lens (what to improve) and an adversarial lens (what is wrong or invalid), as distinct agents so one does not soften the other. They produce evidence-bearing findings and return paths (review_gate.md).
This is halt type 2. The orchestration generates review material but does not act on it: present the findings and let the user decide accept/reject. The orchestrator may merge, deduplicate, and rank for readability, but never auto-accepts a finding or proceeds on its own verdict. Accept/reject is the user's. If you judge review unwarranted for this run, say so and why rather than skipping it silently.
Step 7 — Aggregate and report
Aggregate the phase outputs per the topology — concatenate independent results, or synthesize them with a JUDGE-tier reduce phase when they must become one conclusion (orchestration_shapes.md). Report: outcome, per-phase or per-item results, and artifacts by path. Label every load-bearing claim confirmed (backed by an artifact/log/path) or inferred (plausible, needs more). Surface progress throughout the run, not only here — see Progress and cost. Close with the termination block below.
Step 8 — Feedback, re-versioning, resume
Apply user feedback. If feedback changes any run condition — inputs, item set, topology, tier assignment, allowed tools, evaluation criteria, prompts — open a new run-id, mark the prior run superseded, record the change in change_log.md, and re-run the affected scope under the new conditions (details in phase_protocol.md). If the run was interrupted mid-flight, treat the interruption as feedback: re-version if it changed a condition, otherwise resume from the last completed phase.
Progress and cost
- Progress (surfaced): keep a live plan — the phase list with each phase's status — and emit a short checkpoint when each phase completes (what finished, what is next). A long autonomous run must be legible without reading transcripts.
- Cost (observed, never a governor): surface an estimate — expected phase/agent count and JUDGE-tier calls — at the plan and again before any expensive commitment. Cost informs the user; it does not add a halt, cap the run, or change tier/topology choices. The orchestration proceeds on correctness, not on cost.
Halt conditions
At most two phases halt for the user — possibly zero. Everything else runs autonomously.
- Go/no-go (Step 4) — before committing an expensive step. Skipped when the topology has no expensive step.
- Review accept/reject (Step 6) — the user judges review findings; the orchestration never decides them itself. Optional per run, but a skip is stated with its reason, never silent — deciding not to review is adjacent to the judgment that belongs to the user.
Do not add halts at other phases — extra halts destroy the long-autonomous-run value. Do not turn these two into autonomous decisions — that makes the orchestration its own judge.
Output contract
Every run ends with a termination: block. It reuses the block convention and the shared field names (trigger, user_decisions, residual_issues, failure_log) from the ecosystem's review skills, extended with the fields a multi-phase run needs:
termination:
trigger: completed | halted_for_user | aborted
run_id: <id>
resumed_from: <prior run-id or null>
topology: linear | fan_out | dag | loop | recursive | nested
phases_run: <count>
user_decisions: # the two halts surface here
- gate: go_no_go | review_accept_reject
question: <what was asked>
answer: <what the user decided>
superseded_runs: # prior runs this run retroactively replaced
- run_id: <prior id>
reason: <one line>
residual_issues:
- severity: minor
problem: <one line>
failure_log: # harness vs work failures encountered
- type: harness | work
cause: <one line>
phase: <which phase or item>
artifacts:
- <path>
Only completed is a clean finish. Surface halted_for_user and aborted plainly — never behind a normal-looking report. A run never declares itself superseded; it becomes superseded later, retroactively, when a successor run replaces it (Step 8).
Scope and guardrails
- Explicit-invocation only. Never auto-trigger.
- Not a single-artifact build-review-improve loop (
delegated-review-loop) and not single-answer verification (iterative-self-review). - One backbone, topology as a parameter. The workflow, isolation contract, tier rules, two halts, and re-versioning do not change with the shape; the topology only changes Step 5's execution order and whether Step 4 applies. Do not fork into separate procedures per shape.
- Portable by construction. This skill is instructions an agent follows, not orchestration code. Keep core logic free of any specific runtime's primitives or model names; concrete spawn mechanisms, tier bindings, and tool-permission defaults live as examples in the reference files.
- Cost never governs, and the orchestrator does no phase work and decides neither halt for the user.
Reference files
| File | When to read |
|---|---|
| orchestration_shapes.md | Step 2 and Step 5 — the topologies, how each maps isolation, tiering, the cheap-proof gate, execution order, and aggregation |
| tiering.md | Step 2 — capability-by-deliberation tiers, the assignment rules, platform binding examples, and why the cheap-proof gate re-validates the binding |
| phase_protocol.md | Steps 1, 4, 5, 8 — run directory layout, per-phase isolation, lifecycle and orphan accounting, output-contract validation and retry, resume protocol, harness-vs-work failure split, recovery policy, run-id/superseded discipline |
| review_gate.md | Step 6 — constructive and adversarial generation, the user-judged halt, what to present, and the self-marking rationale |
| orchestration_template.md | Steps 3, 5, 6 — the role-boundary phase-prompt template, tool-permission defaults, and platform-primitive notes |
Pi Package Creator
Build a directory that Pi can discover, load, and distribute as one package. A Pi package contains any combination of extensions, skills, prompt templates, and themes; it does not need all four.
Each of the five steps below names the reference to read before you act. Every contract, example, starter file, and check you need is in this bundle, and its relative links point to included files. Do not send the user to external documentation, the original analysis, or another skill. An installed Pi and Node.js runtime and the package's declared dependencies are prerequisites for running the package and its checks, not documents to read.
Compatibility
- This bundle targets Pi
v1.4.0, tag commit4a080252f06caf63a525d7873c5d94d3c23887e0. Development builds with the same version string can differ. - Node.js must satisfy Pi's
>=22.19.0requirement. - Record the user's actual Pi version and, when available, its commit. A matching version string alone does not prove that every behavior described here is present.
- Run the bundled checks against the installed Pi. If an API or behavior differs, report the concrete mismatch. Do not invent a newer contract, and do not make reading external documents a completion step.
- Do not mix legacy
@mariozechner/*examples with current@earendil-works/*imports without saying so.
Evidence and compatibility records the supported Pi revision, observed differences, and limits.
1. Decide the package shape
From the request and existing files, determine the package purpose, destination, namespace, intended resources, runtime access, and delivery source (local, npm, or git). Resolve ordinary layout choices yourself. Ask the user only when a missing decision changes the requested behavior, for example whether to replace a built-in tool, contact a remote service, persist shared data, or publish under an account whose identity is unknown.
Choose the smallest set of resources that delivers the feature, and read the matching reference before implementing it:
| Need | Resource | Read before implementing |
|---|---|---|
| Executable tools, commands, flags, events, providers, MCP, UI | Extension | extensions; also advanced extensions for events, state, UI, providers, and MCP |
| Instructions and supporting files the model loads on demand | Skill | resources, skills section |
| A slash command that expands text with arguments | Prompt template | resources, prompts section |
| Terminal colors and HTML export colors | Theme | resources, themes section |
| Distribution, dependencies, paths, filtering | Package manifest | packaging, for every package |
| Post-creation checks, behavioral tests, artifact verification | Validation | validation, for every package before delivery |
| Install, update, trust, troubleshooting | Delivery | operations, for every package before delivery |
New package: copy only the requested parts of the starter. Its four resource types show independent options, not a minimum shape. In the parts you keep, rename @example/pi-workspace-kit, the acme prefix, filenames, frontmatter names, tool/command/flag names, and the theme name. Replace the demonstration behavior with the user's feature. Do not add resources only to match the starter or its tests.
Existing package: keep its public resource names and source identity unless the requested change requires a migration.
2. Set discovery and dependency boundaries
Discovery rules and host-provided dependencies decide whether an installed package loads at all. The full manifest and filter matrix in packaging is essential reading for this step.
Manifest
For npm delivery, include package.json with a real name and version. A local package can instead use conventional directories without package.json, and a package.json without a pi field also uses conventional discovery. An explicit manifest makes the resource surface reviewable. This is a complete extensions-only example:
{
"name": "@example/pi-workspace-kit",
"version": "0.1.0",
"type": "module",
"keywords": ["pi-package"],
"files": ["extensions", "lib"],
"pi": {
"extensions": ["./extensions/index.ts"],
"skills": [],
"prompts": [],
"themes": []
},
"peerDependencies": {
"@earendil-works/pi-coding-agent": "*",
"typebox": "*"
}
}
"type": "module"is an authoring recommendation, and"pi-package"is a gallery-discovery keyword. Neither is required for local loading.- Use
[]to mark resource types the package does not provide. Omitting a type is also valid when settings filters cannot expose unintended conventional resources. - A manifest
[]is not a complete boundary: a settings filter can still expose files in an unused conventional directory. Remove unused resource directories and theirfilesentries. - An empty
"pi": {}is not equivalent to having nopimanifest.
Extension entry points
- Declare extensions through
pi.extensionsor anextensions/directory. A lone rootindex.tsloads only from a local path; npm and git installs of the same files load nothing. - Declare only real entry points, and keep helper modules outside scanned
extensions/roots, as the starter does withextensions/index.tspluslib/. Otherwise Pi can treat a helper or.d.tsfile as an extension and fail startup.
Dependencies
Declare each imported host package in peerDependencies with "*", and keep it out of bundles:
@earendil-works/pi-ai@earendil-works/pi-agent-core@earendil-works/pi-coding-agent@earendil-works/pi-tuitypebox
Put other runtime libraries in dependencies and development-only tooling in devDependencies. Remove unused host peers from a package without extensions. Pi does not install dependencies for local sources; the author installs them. Git installs omit development dependencies, so ship directly loadable TypeScript or prebuilt JavaScript and every required asset.
3. Implement the resources
Extensions
- Export a default factory that accepts
ExtensionAPI, and register tools, commands, flags, and handlers there. Put work that needs a session in handlers or on first use. Factories also run for package-management commands and help output: an uncaught factory error stops CLI startup, and unbounded initialization can hang it. - Import from public package entry points, normally the package root.
- A tool runs as
execute(toolCallId, params, signal, onUpdate, ctx)and returnscontentanddetails. Report failure by throwing or by returning top-levelisError: true. Preserve cancellation in downstream work by passing the signal through. Readctx.cwd,ctx.mode, andctx.hasUIfrom the current handler's context. - Give public names a package prefix to avoid collisions.
- Bound model-facing text that grows with repository contents, subprocess output, or service responses before returning it; a timeout alone does not limit result size. Use the complete bounded-output helper and the integration example in extensions.
- When adding persistent resources, implement cleanup and session-state restoration. After
await ctx.reload(), return immediately. pi.refreshTools()does not exist;registerTool()refreshes runtime tools itself.
Extensions has complete tool and command contracts, failure handling, and lifecycle patterns. Advanced extensions covers event results, session state, UI, and dynamic resources, and integrations covers providers, classifier calls, and MCP.
Skills, prompts, and themes
- Skills: use
<name>/SKILL.mdwith valid YAML frontmatter starting on the first line and a nonempty description that says what the skill does and when to use it. Ship supporting files inside the package and reference them relative to the skill directory. - Prompts: use a unique
.mdbasename that is not a built-in interactive command, plus a description, a quoted argument hint, and Pi's substitution syntax. A prompt is text, not a shell program. - Themes: start from the complete theme asset. Keep all 51 required tokens and use only supported keys and colors. Do not name the theme
system,dark, orlight; the built-in themes hide those names.
Resources gives exact name rules, argument behavior, optional theme tokens, discovery depth, and collision order.
4. Verify the package you will ship
Read validation, then choose checks from the requested resources, the implemented features, and the delivery source. Extensions-only, skills-only, prompts-only, themes-only, and mixed packages are all valid, and an extension can provide only commands or events without tools. Validate what the package promises: absent optional resources and unused capabilities are not_applicable, not errors or incomplete work.
- Write an inventory of the intended resource paths, public names, helpers, and supporting files. Start from the extensions-only example or the four-resource example and adapt names and paths. An explicit
[]asserts that nothing of that kind is intended; an omitted key is not checked. A load that is empty or free of diagnostics does not prove the package is complete. - Run the package validator, validate-package.mjs, with
--expectand--runtime. Add--packfor npm delivery or a requested tarball; a local-only package needs no npm packing. The validator is a structural checker, not a compiler, so also review relevant imports and build output. - If the package provides tools, adapt the tool cases and run the tool runner, test-tools.mjs. Choose the success, input-rejection, operational-failure, cancellation, and output-size cases that apply to those tools. Do not invent tools, long-running work, or failure paths to fill a generic checklist.
- Exercise the commands, prompts, skills, themes, UI, state, providers, and MCP integrations the package actually provides. Check reload and each supported mode where the package's behavior depends on them. The tool runner uses no model and does not prove these behaviors.
- Check what you deliver. For npm, install needed production dependencies in the extracted copy and repeat the applicable checks. For git, use a clean checkout of the intended ref. For local delivery, check the actual local directory. Do not use development-only files to make a distribution check pass.
Record each applicable check with its command, target Pi version, and evidence, using these statuses:
| Status | Use when |
|---|---|
pass | The check ran and met its expectation |
fail | A contract or expectation was violated |
skipped | A needed check could not run; never count it as a pass |
not_applicable | The resource or feature is outside the package's scope |
warning | A nonblocking recommendation was not followed |
Repair relevant failures and rerun the affected checks. An optional resource does not become a requirement because this skill has a test recipe for it.
5. Deliver the package and its verification commands
Deliver the requested resources, required runtime files, package.json when the chosen shape needs it, and a README that covers the items that apply:
- Supported Pi version or commit, and runtime prerequisites.
- Exact local, npm, or git install command and the intended scope.
- Public tool, command, flag, skill, prompt, and theme names and their usage.
- Required credentials, subprocesses, network access, and state location.
- Resource selection, reload, update, pin migration, and removal commands.
- A verification section the user can run: the actual working directory, prerequisites, copyable commands, expected results, and report locations.
Put the verification commands in both your final response and the package README; saying that checks passed does not replace them. Follow the command handoff recipe:
- Use the actual package paths, resource names, and delivered scripts and fixtures.
- Give native Pi CLI checks and the applicable automated checks. Omit tool tests for a package without tools, and npm packing for local-only delivery.
- Separate shell commands from input typed inside Pi, and mark checks that need a model or a service account.
In the final response, state what you actually verified and any remaining environment limits, and separate commands you ran from commands the user should run. Creating a package and publishing it are separate outcomes: deliver a usable local artifact, and publish only when the user asked for publication.
Before calling the task complete, confirm:
- There are no accidental host runtime copies, undeclared imports, startup collisions, missing packed assets, install-time-only builds, or state written into a managed git checkout.
- Every verification command references delivered files and runs from the stated directory.
React Guide
Establish the installed react/react-dom versions, supported consumers, and rendering path: client rendering, server rendering, or hydration. Inspect package/lockfile and entry-point evidence when available. If versions or inputs are missing, continue investigation and version-independent explanation; defer only choices that depend on the missing facts. Do not assume every React 19 minor exposes the same APIs.
Treat existing defects, incomplete cleanup, and failed checks as diagnosis and repair work. Ask for a decision only when an unresolved product or compatibility choice changes the solution. Migration evidence can come from current source and diagnostics; a prior-stage report is not required.
Route
Start with the closest reference, then read related references directly as the task crosses topics. Use their inputs and checks selectively for the requested explanation, implementation, or review.
- Structure, composition, exports: structure and public API
- Hooks, Effects, subscriptions: Hooks and Effects
- Local/shared/URL/server state: state and data
- Rerenders, profiling, memoization: render performance
- Suspense, loading, errors, retry: async UI
- Server APIs, streaming, initial data, hydration mismatches: SSR and hydration
- Semantics, keyboard, focus, announcements: accessibility
- React 18 runtime or Compiler compatibility: React 18 compatibility
- React 18 departure audit: React 18 to 19 migration
- React 19 arrival validation: React 19 migration
- React 19 ref/provider or 19.2 APIs: React 19 component APIs
- React 19 Actions, forms,
use: React 19 async APIs - React Compiler config or diagnostics: React 19 Compiler
Boundary
This skill explains React rendering and state semantics. A build-tool guide owns module loading, client/server artifacts, plugin adapters, and deployment configuration. For a task spanning both, use both guides and connect their evidence; for Vite, pair this guide with vite-guide. An artificial handoff or caller identity is unnecessary. Respect actual ownership restrictions supplied by the task.
Keep framework-specific routing/data APIs, RSC/Server Functions implementation, and construction of a custom server runtime outside this guide. Ordinary React SSR within an existing host is supported.
Adapt the response to the request: explain the decision and evidence, report changes or findings, and distinguish performed checks from remaining runtime risks. Claim a performance improvement only with comparable before/after measurements. Do not report blocked, failed, or unrun verification as passed.
release-it Release Automation
release-it is a generic, pluggable CLI tool that automates versioning and package publishing. It handles version bumping, Git committing/tagging/pushing, npm publishing, and GitHub/GitLab release creation -- all in a single configurable workflow. Language-agnostic with a powerful plugin system for extending behavior.
Choose the Applying Workflow
Start with the requested operation and the project's existing release entry point. A config repair, CI job, publishing workflow, or plugin does not by itself require a new interactive wrapper. Preserve the chosen execution mode and enabled capabilities when fixing it.
- Configuration, CLI, or CI: use configuration.md and cli-and-workflow.md; load publishing references when applicable.
- Programmatic wrapper: inspect the API, prompt/log ownership, and installed version using cli-and-workflow.md. Use the interactive contract below when generating the service-app command, not as an override for every API caller.
- Version source or custom plugin: use plugins.md and custom-plugin-development.md. Tooling manifests do not determine the application's version source.
- Dirty state, cancellation, or recovery: use git-integration.md to distinguish write paths, staging scope, the shared index, and recoverable state.
The concrete adapter and source-level behavior in this skill are checked against release-it 21.0.1. Match configuration schemas, runtime requirements, and plugin interfaces to the applying project's version; an example's dependency pin is not an instruction to upgrade it.
Default Interactive Contract
For a new interactive service-app release command, generate pnpm release using the project entry script and @inquirer/prompts adapter in
interactive-workflow.md. All release questions use
Inquirer; release-it performs the version update and Git operations.
- Single project:
pnpm release → choose version → confirm commit / commit → confirm tag / tag → confirm push / push. - Monorepo:
pnpm release → choose one service app → choose version → confirm commit / commit → confirm tag / tag → confirm push / push.
The first question in a non-monorepo is the version selection. Do not add an app picker or a separate start confirmation. In a monorepo, offer only the verified service apps with a single-select picker, even when there is only one eligible app. Resolve an unclear service app boundary during setup, then use that app's version source, changelog, and tag policy.
Display the current version and concrete next versions. Always wait for the user's selection; recommended increments, existing settings, and CI environment variables cannot replace it. Pass the selected exact version and target configuration to release-it's API.
Ask each Git confirmation at its release-it execution point and await that action before
asking the next. A negative answer or cancellation stops that action and the entire remaining
flow. Use Inquirer's native y/n confirmation with default: true for commit, tag, and push,
so Enter approves the displayed action, including push;
Ctrl+C cancels the active question. Report the actual remaining files, index, commit, tag,
and push status according to the chosen recovery policy. The packaged example preserves
interrupted work; automatic restoration needs explicit scope and baseline handling.
Check for an interactive terminal before any release work. Do not use
--ci, --only-version, canned answers, or a direct push hook in this default path.
CI automation, npm publishing, and hosted releases remain supported as explicitly requested extensions with their own configuration. Do not infer them from a Git remote or add them to the default service-app flow. Read the adapter compatibility notes before applying it to a different release-it version; its injection surface is confirmed in source, not a stable CLI option.
Quick Start
# After generating the entry script, adapter, and target config:
pnpm release
For first-time setup with project-aware configuration, follow initial-setup.md.
Capability Index
Read the reference file that matches your task:
| Reference | When to Read |
|---|---|
| initial-setup.md | First-time setup. Analyze project → propose config → ask user for decisions → generate tailored config |
| interactive-workflow.md | Default Inquirer flow, executable entry/adapter examples, explicit version selection, cancellation and compatibility |
| monorepo.md | Select one service app and bind its cwd, version, changelog, and tags |
| configuration.md | Setting up or modifying .release-it.* config in any format, config extends/merging, CLI overrides |
| hooks-and-lifecycle.md | Adding pre/post release commands, understanding execution order, template variables |
| cli-and-workflow.md | CLI flags, increment types, pre-release flow, dry-run, CI mode, programmatic API |
| git-integration.md | Working state, staging and recovery scope, tag naming/matching, branch restrictions, push config |
| npm-publishing.md | npm auth, scoped packages, dist-tags, OTP/2FA, OIDC Trusted Publishing, monorepo, private registry |
| github-gitlab-releases.md | GitHub/GitLab release creation, tokens, assets, release notes, comments, draft/pre-release |
| plugins.md | Setting up official/community plugins (conventional-changelog, bumper, keep-a-changelog, etc.) |
| custom-plugin-development.md | Building a custom release-it plugin from scratch, Plugin class API reference |
| troubleshooting.md | Debugging release failures, auth errors, CI issues, common error messages |
Config Formats Overview
release-it supports 6 config file formats. Pick one:
| Format | File | Notes |
|---|---|---|
| JSON | .release-it.json | Most common. Supports $schema for IDE autocomplete |
| TypeScript | .release-it.ts | Type hints via satisfies Config |
| JS/CJS | .release-it.js / .release-it.cjs | Dynamic config, functions for releaseNotes |
| YAML | .release-it.yaml / .release-it.yml | Compact syntax |
| TOML | .release-it.toml | Table-based config |
| package.json | "release-it": {} property | Zero extra files |
Example schema for the checked version: "$schema": "https://unpkg.com/release-it@21.0.1/schema/release-it.json".
Use the applying project's release-it version when generating its configuration.
Only override options that differ from defaults. See configuration.md for all defaults and the extends mechanism.
Common Workflows
Initial setup: initial-setup.md — analyzes project, proposes config, asks for decisions
Add changelog generation: plugins.md → conventional-changelog or keep-a-changelog section
CI/CD pipeline (GitHub Actions): cli-and-workflow.md → CI mode + npm-publishing.md → authentication
Pre-release (alpha/beta/rc): cli-and-workflow.md → pre-release workflow
Custom release steps: hooks-and-lifecycle.md → hook configuration
Monorepo service app: monorepo.md + interactive-workflow.md
Explicit multi-package publishing: npm-publishing.md → monorepo section + plugins.md → workspaces/bumper
Something broke: troubleshooting.md
Build a plugin: custom-plugin-development.md
Key Concepts
- Increment types (UX order, most-used first):
patch→minor→prepatch(alpha) →preminor(beta) →prerelease(rc counter) →major→premajor. semver bumps plus pre-release variants, ordered by typical usage frequency - Dry-run (
--dry-run): Skips writes routed through release-it's shell layer.$= read-only (runs),!= write (skipped). Plugins must guard direct filesystem/network effects themselves - CI mode (
--ci): Non-interactive, auto-detected in CI environments. No prompts, uses spinners instead - npm dist-tags:
latest(default),next,beta,alpha-- controls whatnpm installresolves to - Plugin lifecycle:
init→getName→getLatestVersion→beforeBump→bump→beforeRelease→release→afterRelease - Hooks: Shell commands run at lifecycle points (
before:init,after:bump,after:release, etc.) - Template variables:
${version},${latestVersion},${tagName},${changelog},${name}-- available in config strings - Config precedence: CLI args > config file >
extendsbase > built-in defaults
Rust Guide
Explain Rust's characteristics and established practical patterns by topic. Connect how the language and libraries work to recommended usage, applicable conditions, costs, pitfalls, and exceptions. Use examples that make these relationships concrete.
Explain the Topic
Start with the concept needed to answer the question, then connect it to practice. For a substantial topic, cover mechanism → practical pattern → applicable conditions → pitfalls and exceptions → example. This is a way to develop the explanation, not a required response template. A narrow question may need only a paragraph or a small example.
- Explain why a pattern works: ownership and resource lifetime, type guarantees, execution and synchronization, memory representation, or compilation behavior.
- Develop the suitable std/core approach where it is useful. Explain what a dependency adds and what maintaining an equivalent implementation would cost; fewer dependencies alone do not justify writing a scheduler or unsafe allocator.
- Treat
clone,dyn Trait,Arc<Mutex<T>>, allocation, and abstractions according to their semantics and costs. A useful default has conditions and exceptions. - Use comparisons when the question involves alternatives. Classify their roles before comparing names, and use the library selection policy for new dependency recommendations.
- Relate examples to observable behavior: who owns a buffer, which failure a caller can handle, when a task ends, or which configuration reaches a target.
Match depth to the reader's question. Explain the underlying constraint when discussing a diagnostic; connect an established pattern to the supplied code when application is requested. Keep small examples focused, and explain any omitted runtime, device setup, dependency features, or failure handling that matters to their use.
Account for the Environment
Bring in environmental facts when they change the explanation: core/alloc/std, host and target, OS threads or interrupts, runtime, MSRV and edition, dependency features, public API, and deployment CPU baseline. A general language question needs no repository inspection. Use supplied code and manifests for project-specific questions, and state assumptions where relevant facts are unavailable.
Distinguish workload costs such as I/O waiting, computation, contention, retained memory, startup, and build time. Explain the likely mechanism before suggesting a measurement; a performance hypothesis becomes a speedup claim only with comparable results.
Route by the Question
Read the relevant section of the closest reference first. Long references have contents tables; expand to neighboring sections only when their concepts are needed. Follow cross-topic links for relationships such as ownership and allocation, async and cancellation, or workspace features and no_std.
| Task signal | Read |
|---|---|
| Ownership, borrowing, lifetimes, resource release | Ownership and borrowing, then parameter and return types |
| Newtype, typestate, enum/generic/dyn, shared ownership | Type patterns, dispatch, or shared ownership |
| Lookup, ordering, queues, hashing, collection capacity | Collection semantics and representation, then the relevant operation |
| Allocation, buffer reuse, arena/pool, allocator, retained memory | Memory and allocation |
| Errors, std-only implementations, thiserror/anyhow, recovery/reporting | The error model, manual implementation, or reporting |
| Function/module/crate separation, visibility, core and adapters | Modules and crate boundaries |
| Public API, traits, conversions, SemVer, documentation | API and crate design |
| Workspace, monorepo, feature unification, shared versions/releases | Workspaces and monorepos |
| Crate comparisons, std versus dependencies, adoption/maintenance | Library selection |
| Future/task/thread, Tokio/smol, Rayon/Crossbeam, blocking and limits | Execution model and patterns |
| Async borrowing, Send, 'static, Pin/Unpin | Task ownership, pinning |
| Cancellation, timeouts, shutdown | Cancellation, shutdown |
| Threads, locks, channels, atomics, Send/Sync, contention | Concurrency; use its contents for the specific primitive |
| Profiling, algorithms, layout, runtime and build-time bottlenecks | Performance |
| Auto-vectorization, SIMD intrinsics, CPU detection, fallback | SIMD |
| Browser/WASI, JS boundary, Wasm memory, workers and size | WebAssembly |
| Firmware, no_std, no heap, interrupts, HAL, DMA, embedded async | Embedded and no_std |
| Cargo profiles, LTO, symbols, panic, PGO, compiler flags | Build configuration |
| Raw pointers, layout, aliasing, initialization, FFI | Safety contracts, then the relevant FFI or memory section |
| Compiler errors, Clippy diagnostics, lint configuration | Compiler diagnostics and lints |
| Edition 2024 migration | Edition migration |
| Toolchain upgrade and release compatibility | Versions index, then the relevant release files |
Compatibility
- Use the relevant topic's explanation, conditions, and examples to answer the question. Distinguish language/API guarantees, conditional practices, and measured outcomes.
- Match APIs and dependencies to the project's features, MSRV, target, and runtime. Explain relevant nightly alternatives separately from the stable approach.
- Release references cover Rust 1.80 onward. Each example has its own API requirements; edition 2024 requires Rust 1.85 even when its APIs are older. An older MSRV needs a supported edition and compatible APIs.
- Apply the library catalog's role and suitability conditions. Popularity narrows candidates; it does not establish correctness or a performance benefit.
- State assumptions and unresolved version or target constraints where they affect the answer. Describe compilation, target execution, and measured behavior only to the extent actually established.
Skill Creator
A skill for creating new skills and iteratively improving them.
At a high level, the process of creating a skill goes like this:
- Decide what you want the skill to do and roughly how it should do it
- Write a draft of the skill
- Refine that complete draft once through independent candidates before the evaluation loop
- Create a few test prompts and run claude-with-access-to-the-skill on them
- Help the user evaluate the results both qualitatively and quantitatively
- While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
- Use the
eval-viewer/generate_review.pyscript to show the user the results for them to look at, and also let them look at the quantitative metrics
- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
- Repeat until you're satisfied
- Expand the test set and try again at larger scale
Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.
On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.
Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.
Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.
Cool? Cool.
Communicating with the user
The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
- "evaluation" and "benchmark" are borderline, but OK
- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them
It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.
Creating a skill
Capture Intent
Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.
- What should this skill enable Claude to do?
- When should this skill trigger? (what user phrases/contexts)
- What's the expected output format?
- Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
Interview and Research
Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.
Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.
Write the SKILL.md
Based on the user interview, fill in these components:
- name: Skill identifier
- description: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
- compatibility: Required tools, dependencies (optional, rarely needed)
- the rest of the skill :)
Skill Writing Guide
Anatomy of a Skill
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description required)
│ └── Markdown instructions
└── Bundled Resources (optional)
├── scripts/ - Executable code for deterministic/repetitive tasks
├── references/ - Docs loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts)
Progressive Disclosure
Skills use a three-level loading system:
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md body - In context whenever skill triggers (<500 lines ideal)
- Bundled resources - As needed (unlimited, scripts can execute without loading)
These word counts are approximate and you can feel free to go longer if needed.
Key patterns:
- Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
- Reference files clearly from SKILL.md with guidance on when to read them
- For large reference files (>300 lines), include a table of contents
Domain organization: When a skill supports multiple domains/frameworks, organize by variant:
cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
├── aws.md
├── gcp.md
└── azure.md
Claude reads only the relevant reference file.
Principle of Lack of Surprise
This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.
Writing Patterns
Prefer using the imperative form in instructions.
Defining output formats - You can do it like this:
## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations
Examples pattern - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
Writing Style
Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.
Post-Draft Refinement (once)
Once a complete draft package exists, follow references/post-draft-refinement.md before creating or running test cases. A supplied complete draft can enter here after its goal and constraints are understood; do not recreate it first. The coordinator runs this pass once, using five independent candidates by default, unless the user skips it or requests a different count. Candidate authors follow only the bounded assignment in that reference.
Continue the existing workflow with the integrated package. Later evaluation-driven edits do not restart this pass unless the user requests another round. Honor a user-requested stop after creation or refinement without starting evaluations or description optimization.
Test Cases
After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.
Save test cases to evals/evals.json. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "User's task prompt",
"expected_output": "Description of expected result",
"files": []
}
]
}
See references/schemas.md for the full schema (including the assertions field, which you'll add later).
Running and evaluating test cases
This section is one continuous sequence — don't stop partway through. Do NOT use /skill-test or any other testing skill.
Put results in <skill-name>-workspace/ as a sibling to the skill directory. Within the workspace, organize results by iteration (iteration-1/, iteration-2/, etc.) and within that, each test case gets a directory (eval-0/, eval-1/, etc.). Don't create all of this upfront — just create directories as you go.
Step 1: Spawn all runs (with-skill AND baseline) in the same turn
For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.
With-skill run:
Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
Baseline run (same prompt, but the baseline depends on context):
- Creating a new skill: no skill at all. Same prompt, no skill path, save to
without_skill/outputs/. - Improving an existing skill: the old version. Before editing, snapshot the skill (
cp -r <skill-path> <workspace>/skill-snapshot/), then point the baseline subagent at the snapshot. Save toold_skill/outputs/.
Write an eval_metadata.json for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.
{
"eval_id": 0,
"eval_name": "descriptive-name-here",
"prompt": "The user's task prompt",
"assertions": []
}
Step 2: While runs are in progress, draft assertions
Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in evals/evals.json, review them and explain what they check.
Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.
Update the eval_metadata.json files and evals/evals.json with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.
Step 3: As runs complete, capture timing data
When each subagent task completes, you receive a notification containing total_tokens and duration_ms. Save this data immediately to timing.json in the run directory:
{
"total_tokens": 84852,
"duration_ms": 23332,
"total_duration_seconds": 23.3
}
This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.
Step 4: Grade, aggregate, and launch the viewer
Once all runs are done:
-
Grade each run — spawn a grader subagent (or grade inline) that reads
agents/grader.mdand evaluates each assertion against the outputs. Save results tograding.jsonin each run directory. The grading.json expectations array must use the fieldstext,passed, andevidence(notname/met/detailsor other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations. -
Aggregate into benchmark — run the aggregation script from the skill-creator directory:
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>This produces
benchmark.jsonandbenchmark.mdwith pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, seereferences/schemas.mdfor the exact schema the viewer expects. Put each with_skill version before its baseline counterpart. -
Do an analyst pass — read the benchmark data and surface patterns the aggregate stats might hide. See
agents/analyzer.md(the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs. -
Launch the viewer with both qualitative outputs and quantitative data:
nohup python <skill-creator-path>/eval-viewer/generate_review.py \ <workspace>/iteration-N \ --skill-name "my-skill" \ --benchmark <workspace>/iteration-N/benchmark.json \ > /dev/null 2>&1 & VIEWER_PID=$!For iteration 2+, also pass
--previous-workspace <workspace>/iteration-<N-1>.Cowork / headless environments: If
webbrowser.open()is not available or the environment has no display, use--static <output_path>to write a standalone HTML file instead of starting a server. Feedback will be downloaded as afeedback.jsonfile when the user clicks "Submit All Reviews". After download, copyfeedback.jsoninto the workspace directory for the next iteration to pick up.
Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.
- Tell the user something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."
What the user sees in the viewer
The "Outputs" tab shows one test case at a time:
- Prompt: the task that was given
- Output: the files the skill produced, rendered inline where possible
- Previous Output (iteration 2+): collapsed section showing last iteration's output
- Formal Grades (if grading was run): collapsed section showing assertion pass/fail
- Feedback: a textbox that auto-saves as they type
- Previous Feedback (iteration 2+): their comments from last time, shown below the textbox
The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.
Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to feedback.json.
Step 5: Read the feedback
When the user tells you they're done, read feedback.json:
{
"reviews": [
{"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
{"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
{"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
],
"status": "complete"
}
Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.
Kill the viewer server when you're done with it:
kill $VIEWER_PID 2>/dev/null
Improving the skill
This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.
How to think about improvements
-
Generalize from the feedback. The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.
-
Keep the prompt lean. Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.
-
Explain the why. Try hard to explain the why behind everything you're asking the model to do. Today's LLMs are smart. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.
-
Look for repeated work across test cases. Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a
create_docx.pyor abuild_chart.py, that's a strong signal the skill should bundle that script. Write it once, put it inscripts/, and tell the skill to use it. This saves every future invocation from reinventing the wheel.
This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.
The iteration loop
After improving the skill:
- Apply your improvements to the skill
- Rerun all test cases into a new
iteration-<N+1>/directory, including baseline runs. If you're creating a new skill, the baseline is alwayswithout_skill(no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration. - Launch the reviewer with
--previous-workspacepointing at the previous iteration - Wait for the user to review and tell you they're done
- Read the new feedback, improve again, repeat
Keep going until:
- The user says they're happy
- The feedback is all empty (everything looks good)
- You're not making meaningful progress
Advanced: Blind comparison
For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read agents/comparator.md and agents/analyzer.md for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.
This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.
Description Optimization
The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
Step 1: Generate trigger eval queries
Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:
[
{"query": "the user prompt", "should_trigger": true},
{"query": "another prompt", "should_trigger": false}
]
The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
Bad: "Format this data", "Extract text from PDF", "Create a chart"
Good: "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"
For the should-trigger queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.
For the should-not-trigger queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.
The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.
Step 2: Review with user
Present the eval set to the user for review using the HTML template:
- Read the template from
assets/eval_review.html - Replace the placeholders:
__EVAL_DATA_PLACEHOLDER__→ the JSON array of eval items (no quotes around it — it's a JS variable assignment)__SKILL_NAME_PLACEHOLDER__→ the skill's name__SKILL_DESCRIPTION_PLACEHOLDER__→ the skill's current description
- Write to a temp file (e.g.,
/tmp/eval_review_<skill-name>.html) and open it:open /tmp/eval_review_<skill-name>.html - The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
- The file downloads to
~/Downloads/eval_set.json— check the Downloads folder for the most recent version in case there are multiple (e.g.,eval_set (1).json)
This step matters — bad eval queries lead to bad descriptions.
Step 3: Run the optimization loop
Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."
Save the eval set to the workspace, then run in the background:
python -m scripts.run_loop \
--eval-set <path-to-trigger-eval.json> \
--skill-path <path-to-skill> \
--model <model-id-powering-this-session> \
--max-iterations 5 \
--verbose
Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.
While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with best_description — selected by test score rather than train score to avoid overfitting.
How skill triggering works
Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's available_skills list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
Step 4: Apply the result
Take best_description from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.
Package and Present (only if present_files tool is available)
Check whether you have access to the present_files tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:
python -m scripts.package_skill <path/to/skill-folder>
After packaging, direct the user to the resulting .skill file path so they can install it.
Claude.ai-specific instructions
In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:
Running test cases: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.
Reviewing results: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"
Benchmarking: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.
The iteration loop: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.
Description optimization: This section requires the claude CLI tool (specifically claude -p) which is only available in Claude Code. Skip it if you're on Claude.ai.
Blind comparison: Requires subagents. Skip it.
Packaging: The package_skill.py script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting .skill file.
Updating an existing skill: The user might be asking you to update an existing skill, not create a new one. In this case:
- Preserve the original name. Note the skill's directory name and
namefrontmatter field -- use them unchanged. E.g., if the installed skill isresearch-helper, outputresearch-helper.skill(notresearch-helper-v2). - Copy to a writeable location before editing. The installed skill path may be read-only. Copy to
/tmp/skill-name/, edit there, and package from the copy. - If packaging manually, stage in
/tmp/first, then copy to the output directory -- direct writes may fail due to permissions.
Cowork-Specific Instructions
If you're in Cowork, the main things to know are:
- You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
- You don't have a browser or display, so when generating the eval viewer, use
--static <output_path>to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser. - For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using
generate_review.py(not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself. You want to get them in front of the human ASAP! - Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download
feedback.jsonas a file. You can then read it from there (you may have to request access first). - Packaging works —
package_skill.pyjust needs Python and a filesystem. - Description optimization (
run_loop.py/run_eval.py) should work in Cowork just fine since it usesclaude -pvia subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape. - Updating an existing skill: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.
Reference files
The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.
agents/grader.md— How to evaluate assertions against outputsagents/comparator.md— How to do blind A/B comparison between two outputsagents/analyzer.md— How to analyze why one version beat another
The references/ directory has additional documentation:
references/schemas.md— JSON structures for evals.json, grading.json, etc.
Repeating one more time the core loop here for emphasis:
- Figure out what the skill is about
- Draft or edit the skill
- Run claude-with-access-to-the-skill on test prompts
- With the user, evaluate the outputs:
- Create benchmark.json and run
eval-viewer/generate_review.pyto help the user review them - Run quantitative evals
- Create benchmark.json and run
- Repeat until you and the user are satisfied
- Package the final skill and return it to the user.
Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run eval-viewer/generate_review.py so human can review test cases" in your TodoList to make sure it happens.
Good luck!
System Prompt Creator
Create prompts that implement the user's requirements and can be applied and evaluated. The evaluation target is the generated system prompt's behavior against the user's requirements, not this skill's writing style or a generic prompt-quality score.
Scope
Create a new system prompt or a requested set of stage prompts. Revisions and comparisons within that creation task are supported. Standalone review or optimization of an existing prompt, one-off user messages, agent/skill definition files, and image/video prompts are outside scope.
Workflow
- Recover requirements from the conversation. Identify purpose, runtime inputs, expected output, constraints, domain policies, and usage environment. Record material requirements with IDs and their source wording; distinguish user requirements, delegated design choices, and disclosed defaults. Do not ask again for supplied information.
- Resolve consequential gaps. Apply the clarification gate below. Ask focused questions only for decisions that change correctness or integration; retain known requirements while waiting. Do not issue a finished prompt or invented expected answers while such gaps remain.
- Choose the configuration. Default to one model-neutral prompt. Honor explicitly requested stages, branches, or loops; read multi_prompt_architecture.md when those apply. Multiple output fields alone do not require multiple prompts.
- Assemble and explain application. Read prompt_structure.md. Separate stable instructions, live user requests, and source material. Read data_format_selection.md when embedding structured data or defining a stage contract. If a model/provider is named, read only the applicable parts of model_guidance.md, check current official sources, and cite any resulting adaptation. Do not silently switch the requested target.
- Check requirement fidelity. Read quality_criteria.md. Check that policies, examples, output values, input placement, and stage contracts agree with the request. This is a document review, not an execution result.
- Prepare evaluation materials. Read
evaluation.md. Derive concrete cases and grading criteria from
requirements, their interactions, and plausible failures; there is no fixed case quota.
Include coverage and limitations. Initially mark results
not_run. - Deliver, then simulate only with approval. Provide the output below before requesting
simulation approval. Show the exact cases, prompt versions, run scope, and current-agent
limitation. Approval of prompt creation or evaluation-material preparation is not simulation
approval. Execute only the approved scope; otherwise leave results
not_runand finish the deliverable. Follow the result-preservation and comparison rules in the evaluation reference.
Clarification Gate
Use what is present in the conversation before deciding something is missing.
| Information | Ask when | Proceed when |
|---|---|---|
| Purpose and runtime input | The task or what the model receives is unclear enough to change its behavior | The transformation and input source are identifiable |
| Closed outputs | Required labels, exact keys/types, or label definitions are missing or contradictory | They are provided, or the user explicitly delegates designing a new taxonomy/schema |
| Business policy | Eligibility, priorities, cutoffs, category overlap, or consequential exception behavior is unspecified | The rule is provided or design of that rule is explicitly delegated |
| Integration | The output must match an existing API/schema but its contract is absent | The contract is supplied; or a new contract is explicitly requested for design |
| Presentation | A required channel/format has consequences for acceptance | Ordinary tone, headings, or length can use stated defaults without changing the task |
| Environment | A required capability depends on the target API, tools, or message interface | No target is specified: deliver a model-neutral prompt with generic input placement |
Delegation permits a proposed design, not fabricated facts about an existing system. Label designed taxonomies, policies, and schemas as proposals and keep them consistent across the prompt, usage note, and evaluation materials. "Just get it going" is not authority to invent an existing API or company policy.
Fallbacks and tie-breaks are task decisions. Preserve the allowed outputs; do not add Other,
unknown, neutral, a refusal, or a human-escalation route merely to complete a template. Ask
about a missing consequential rule, or design it when delegated. For open-ended tasks, a stated
default such as acknowledging absent source information can be appropriate without inventing
business policy.
Examples of the Gate
- Proceed with defaults: "Summarize weekly sales-call transcripts; keep it simple." Use a concise summary format, disclose it, and ground the summary in the transcript. Do not require a sales methodology or invent deal stages and qualification rules.
- Ask for labels: "Classify tickets as JSON with category and confidence." Ask for the taxonomy and relevant decision rules; the JSON keys are already known.
- Proceed with delegation: "Design a small taxonomy for our new helpdesk; choose the labels and an ambiguity rule." Propose that design, identify it as delegated, and use the same rules in evaluation cases.
- Ask for an existing contract: "Extract, validate, then format exactly as our quoting API expects." The three stages are clear; request the API schema and any missing mapping/error policy. Do not substitute a guessed payload and describe it as compatible.
- Ask about a conflict: "Return exactly positive or negative; use neutral for mixed reviews." Resolve the allowed-label conflict before generating the classifier or its expected answers.
Output Contract
By default, deliver all three items in the user's requested language (otherwise the request's language); use the target audience's language for the generated prompt when specified.
- Copyable prompt(s). Each complete system prompt has its own fenced block. Keep usage notes and evaluation materials outside the prompt. For multiple prompts, label stages and include their input/output contracts, routing, error propagation, and loop termination.
- Short application guidance. Identify where stable instructions and runtime inputs go, required variables and their meanings/types, source-material boundaries, and any required tools, API settings, or supplied policy data. Distinguish verified target settings from generic guidance; say when no provider-specific configuration has been selected. Disclose presentation defaults and delegated choices. Explain architecture only as much as needed.
- Request-derived evaluation materials. Include requirement IDs and source wording, observable success criteria, concrete inputs and needed conversation context, exact expected answers or acceptable-output rubrics, failure conditions, case-selection reasons, a coverage map, result records, and unverified requirements/limitations. Use the evaluation reference's reusable layouts. Expected outputs are not observed outputs.
Respect an explicit request to omit or narrow evaluation materials; briefly state the resulting unverified scope without forcing an evaluation workflow. Do not certify production suitability from a generated prompt, checklist, or current-agent simulation, even if asked for a finished prompt. Creating materials does not authorize any run.
When a prompt changes during creation, retain the prior prompt text/version and compare shared requirements using the same inputs and criteria. Record improved / unchanged / worsened / indeterminate with evidence, never hypothetical prior results. A new prompt has no previous run; its first authorized execution becomes the baseline.
Task Brief Creator (Caveman)
Produce an executable implementation work plan under docs/briefs/ that one coding agent authors and another coding agent executes without reconstructing the route or re-interviewing the requester.
The historical work-brief and handoff names remain activation aliases; the saved artifact's primary identity is a code-execution PLAN.
The plan is the execution artifact. Its job is to let a coding agent recover the first stage, intended order, stage deliverables and handoffs, replan boundaries, and whole-work completion criteria while routing to the right files and fixing the behavior envelope.
The plan is an executable work instruction — nothing else. It is not a scope-control memo, discussion summary, background briefing, or rationale document. Every section must answer "what does the coding agent do next?" — if a section reads like meeting minutes, negotiation history, or context prose, rewrite it until it routes to files, decisions, or verifiable outcomes. A plan that makes a coding agent reconstruct the execution sequence or re-interview the requester is a failed plan, regardless of polish.
"Executable, not discursive" is a prose style rule, not a content reduction rule. It tells you how each bullet should read — direct actions and necessary facts; a brief reason stays when it prevents misuse or changes execution. It does not tell you to drop distinct concerns, merge unrelated bullets, or summarize the input down to its highlights. A brief that omits a concern from the input is also a failed brief, because the downstream agent will silently miss it. Tight prose, full enumeration: short bullets are fine and encouraged, but every distinct concern from the input and the codebase review must land somewhere in the brief. Caveman tightens prose further; it never tightens enumeration.
Modes
This skill operates in one of two output modes:
- Single-plan mode (default; historical single-brief name remains) — emits one executable work plan per invocation. The workflow below covers this case end to end.
- Briefset mode — emits a parent execution-management document plus N independently executable child briefs.
Used when the input describes multiple execution contexts that need coordination (independent completion criteria, mixed work types, ordered dependencies, parallelizable waves, or shared conflict hotspots).
It is selected by the criteria in
references/briefset.md; long input, many files, or related edit points alone never trigger briefset mode.
Output-mode selection happens at Stage 1 alongside the ambiguity gate and is author-owned when the input and codebase make it evident.
In briefset mode, follow the workflow below with the per-stage adaptations in references/briefset.md (parent template, naming, decomposition decision table, dual-validator save).
Stage 4 always runs an ownership pass. When user-owned decisions remain after codebase review, present only them in a Markdown table with 순번, 내용, 수정 추천안, and 근거.
Codebase facts, output mode, evident work type, and reversible implementation choices are author- or worker-owned; product intent, scope, compatibility breaks, external ownership, and acceptance thresholds remain user-owned.
The decision table is the ownership-pass output when rows exist, not a separate mode.
See references/stage-4-interview.md for the full decision classification, codebase-precedence, and termination rules.
Code Agent Operating Path
Load references only when their decision point arrives:
- Use this file for the stage order, output contract, save flow, caveman constraints, and guardrails.
- Read references/caveman-style.md before composing or patching saved brief prose.
- Read references/work-types.md during Stage 2 when the work type is not obvious or when the type changes downstream behavior.
- Read references/briefset.md during Stage 1 when multiple execution contexts are plausible.
- Read references/bloat-decomposition.md only after a candidate child brief is independently executable but still looks oversized or mixed.
- Read references/stage-4-interview.md before the Stage 4 ownership pass, including requirements clarification and recommendations.
- Read references/plain-language.md and references/template.md while composing or revising the saved Markdown.
- Read references/cold-pickup.md only when the user explicitly requests cold-pickup verification (Stage 5.7); it never loads by default.
Do not re-open every reference by habit. The goal is to keep the live context focused on the next decision the coding agent must make. Caveman style applies to saved brief prose only, not to planning, validation, or chat.
When This Skill Runs
- Explicit caveman intent. Run when the user requests a caveman-register implementation work plan or invokes this skill by name. Mere mention while reviewing or editing the skill is not a request to generate a plan; normal-prose plan requests route to
task-brief-creator. - Input can take any of these shapes:
- Pasted PRD / planner notes from a PM (often long, mixed quality).
- Rough task notes typed into chat (one or two lines).
- Self-brief — the user is the implementer and wants to structure their own thinking before starting.
- Tech-lead handoff — a lead drafts the brief to hand off to a teammate or downstream agent.
- Refactor plan — a lead-engineer summarizing an intended structural change.
- The skill reviews the current repository, fills in what it can, and asks only for remaining user-owned decisions.
Interaction Language
- Chat / live interaction language follows the user's input. If the user writes in Korean, reply in Korean. If they write in English, reply in English. Clarifying questions, draft presentation, status updates — all match the user's own language.
- The brief document itself is written in English. Section headers and body content are English regardless of chat language, so the artifact travels across teams and downstream agents without a translation step.
- Code blocks, file paths, identifiers, PR numbers stay as-is.
- User-supplied strings are data. Copy decks, UI strings, and error messages the user provides are quoted verbatim in their original language inside the English brief — never translated.
- Exception — the Stage 4 decision-table headers are fixed. The four headers
순번/내용/수정 추천안/근거stay exactly as written even when the conversation is in English: the opt-in Stage 5.7 cold-pickup matches disagreements on the내용column, so translating the headers breaks that matching (see Stage 4). - This SKILL.md and reference files stay in English (repo authoring policy).
- Chat prose is normal mode — never caveman. Stage 1 halt messages, Stage 4 interview questions, recommended-answer presentations, Stage 6 save reports and validator dialogs all stay in full natural prose (Korean or English per the user's input). Caveman applies only to the saved brief file.
Caveman Output Style (full mode, file-only)
This skill is the caveman variant of task-brief-creator.
The saved brief is written in caveman full mode — fragments, dropped articles, short synonyms — as a register transform of the normal-mode brief.
Other intensity levels (lite, ultra, wenyan-*) are out of scope; do not switch.
Caveman compresses register, not content. The pre-conversion content inventory and the caveman plan must carry the same facts, bullets, section depth, execution stages, required fields, and nested checklist depth. Sentence fragments, omitted articles, and familiar synonyms change phrasing only; restore normal prose whenever brevity obscures meaning. If conversion merges distinct inventory items, removes a condition, or drops a stage, restore those items; do not justify lost content as a register change. There is no token-count target; the goal is a concise, readable register over a fully enumerated work instruction, not a smaller document. Readability takes priority over dropping articles or using fragments.
Two hard rules — both absolute:
- The brief file body uses caveman full, except the
## Open Questionssection, which stays in normal prose (questions are read by humans deciding what to clarify — see Auto-Clarity carve-outs below). - Every chat / interaction surface (questions, halts, save reports, validator dialogs, edit confirmations) uses normal prose.
What gets compressed inside the brief:
- Articles (
a/an/the) dropped. - Filler (
just/really/basically/actually/simply) dropped. - Pleasantries dropped; uncertainty, negation, conditions, and obligation stay intact.
- Sentence fragments OK; pattern
[thing] [action] [reason]. [next]. - Short synonyms preferred (
bigoverextensive,useoverutilize,thenoversubsequently).
What stays unchanged inside the brief (Auto-Clarity carve-outs):
- Code blocks, inline code, file paths, function names, identifiers.
- PR numbers, URLs, commit hashes.
- Error strings (quoted exact).
Acceptance Criteria/Side Effect Checkpointschecklist items — caveman compression OK on the prose, but order-sensitive multi-step verification stays disambiguated. If conjunction loss changes meaning, drop back to normal for that bullet.Reproductionsteps where step order matters.Behavior Contractinvariants and verification methods.Constraintslegal / API-shape constraints.- Section headers, the title
# [<type>] <title>, and the## Work Typevalue (feat,refactor, …). - The escape-hatch token
- N/A — <reason>for type-conditional sections. - The entire
## Open Questionssection body. Questions are read by humans deciding user-owned choices; caveman fragments lose nuance. Write each bullet in complete normal-prose- [non-blocking] ... — Default: ...; Reconfirm before: ...form. Execution Planstage headers, field labels, field order, andEnds whenindentation. Compress field values only; preserve stage count, handoff recipient, deliverable, and replan meaning.[confirmed]/[inferred],Evidence:, andConfirm by:tokens.
When in doubt — if compression creates technical ambiguity — write that bullet in normal prose. Caveman never wins over correctness.
See references/caveman-style.md for the full conversion rules, section-by-section guidance, and good/bad examples.
Output Contract
| Field | Value |
|---|---|
| Directory | docs/briefs/ (relative to the repository root — git rev-parse --show-toplevel when available, otherwise the working directory the session was launched in) |
| Filename | YYYY-MM-DD-<type>-<slug>.md |
YYYY-MM-DD | Today's date on the local system clock |
<type> | Conventional Commits type (see references/work-types.md) |
<slug> | kebab-case short slug, ≤40 chars, derived from the brief title |
| Body format | Markdown, following references/template.md exactly |
Example filename: 2026-04-23-feat-global-hotkey-system.md
If docs/briefs/ does not exist, create it.
If a file with the same name already exists, append -v2, -v3, … until the path is unique — do not overwrite.
For briefset mode, the parent uses YYYY-MM-DD-briefset-<set-slug>.md and children use YYYY-MM-DD-<type>-<set-slug>-NN-<child-slug>.md.
See references/briefset.md for the parent template and naming rules.
The nine required H2 sections are: Work Type, Current State (As-Is), Desired Outcome (To-Be), Scope (with In Scope / Out of Scope H3s), Related Files / Entry Points, Execution Plan, Side Effect Checkpoints, Acceptance Criteria, Open Questions.
Optional Constraints may appear between Scope and Related Files / Entry Points when task-specific constraints exist.
Execution Plan appears immediately after Related Files / Entry Points and before Side Effect Checkpoints.
Put stage-local completion under each stage's Ends when.
Reserve Acceptance Criteria for whole-work completion after all required stages and side-effect checkpoints finish.
Three work types require an additional H2 section between Current State (As-Is) and Desired Outcome (To-Be):
fix→## Reproductionperf→## Baseline Measurementrefactor→## Behavior Contract
These exist because the work type changes the downstream agent's behavior (reproduction-first, measurement-first, behavior-preservation), and the brief must carry the type-specific input that behavior depends on.
The escape hatch when the section legitimately has nothing concrete to capture is a single bullet - N/A — <reason>.
See references/template.md and references/work-types.md for the per-section guidance.
Bullet count is not capped. The rule is cohesion plus completeness, not brevity:
- Each bullet should describe one coherent unit of context, scope, risk, or verification.
- Enumerate every distinct concern. If the input or the Stage 3 codebase review surfaces N distinct concerns that map to a section, the section gets ≥ N bullets. Sections expand to fit the work; they are not capped. A section reduced to one bullet when the input contained multiple concerns for it is the failure mode this rule exists to prevent.
- Do not merge unrelated concerns into one bullet just to keep the document short. Caveman never merges bullets — it shortens each bullet's prose.
- Write as many bullets as the task needs; do not compress larger work into vague combined bullets. Short prose per bullet is fine and encouraged — short count is the failure.
Completeness does not mean every discovered issue enters scope.
Triage findings into must fix, check while here, and defer / record.
Keep must-fix plus tightly coupled checks in scope; put unrelated valid findings in [deferred] Out of Scope.
Use Open Questions only for non-blocking user-owned decisions with safe default and reconfirm milestone.
If more than five independent must-fix concerns remain after triage, reconsider briefset mode or ask user to choose first slice only when slicing is a user-owned scope decision.
Workflow
Stage 1 — Ambiguity Gate (HALT or CONTINUE)
Before full codebase review, check whether the input contains enough signal to ground the brief. Use the four-anchor heuristic:
| Anchor | What it answers | Maps to |
|---|---|---|
| PROBLEM | What is wrong or what is changing? | § Current State (As-Is) |
| GOAL | What should be true when it's done? | § Desired Outcome (To-Be) |
| SCOPE | Where does this apply (module, feature area, user surface)? | § In/Out of Scope |
| TARGET | Which part of the system is touched (file, subsystem, layer)? | § Related Files / Entry Points |
Count how many anchors are derivable from the input. Derivable = a reasonable engineer could answer the anchor from the user's input without inventing intent.
-
All 4 anchors present → CONTINUE to Stage 2.
-
3 anchors present, TARGET missing → run a narrow target probe before deciding. Use at most a few
rg/ glob queries to find likely files, directories, routes, commands, or modules. If a concrete entry point emerges, CONTINUE. If not, HALT and ask the user for the target area. -
3 anchors present, PROBLEM or GOAL or SCOPE missing → CONTINUE only when the missing anchor can be stated in one concrete sentence derived from the input (write that sentence into the brief; vague fillers like "make it better / cleaner" do not count). Otherwise HALT and ask for that anchor. Detail that survives this check gets filled in Stage 3 via codebase review or Stage 4 via user questions.
-
2 or fewer anchors present → HALT. Respond in the user's chat language naming exactly which anchors are missing, and ask for more input. Do NOT proceed through Stages 2–6 on an underspecified input. The briefset-mode check below also waits — never split an underspecified input into multiple equally underspecified child briefs. Example halt messages:
English:
I can't ground the brief from this input alone. Missing — PROBLEM (what is being fixed or changed) and TARGET (which area / file / subsystem is touched). Can you paste the spec or add one or two lines?
Korean:
입력만으로는 브리핑 만들기 어려워. 다음이 아직 확인 안 돼 — PROBLEM(뭘 고치거나 바꾸는지)과 TARGET(어느 영역/파일/시스템을 건드리는지). 더 얹어줄래? 기획서 붙여넣거나 한두 줄 더 써주면 돼.
Why halt instead of guess: an underspecified brief is worse than no brief — the downstream agent commits to the wrong problem framing and the rework cost eats the whole savings. Pushing back early is cheaper than producing a confident-looking but wrong document.
Edge case — pasted spec that looks long but is content-light: word count is not a proxy for the four anchors. A 2,000-word product narrative without a concrete PROBLEM or TARGET still halts. Judge by anchor coverage, not length.
See examples/03-halt-ambiguous.md for a worked halt case.
Briefset signal check (after CONTINUE): once anchors clear, also evaluate whether the input describes multiple execution contexts. Do not use file count, line count, input length, or several related edit points as triggers by themselves. Those are supporting evidence only.
If briefset signals are strong, select briefset mode and state evidence before Stage 2.
If the candidate contexts have unrelated outcomes and no shared acceptance boundary, select separate single-plan invocations. Independent children serving one coordinated outcome may share a briefset and start in the same wave; do not invent dependencies to justify the parent.
If evidence unclear, default to single-plan mode.
Ask only when topology depends on user-owned delivery boundary, release unit, or scope choice; do not ask user to choose document shape when code and input settle it.
Several stages inside one cohesive execution context do not justify briefset mode; consult references/bloat-decomposition.md before splitting oversized candidate.
Stage 2 — Work Type Selection
Determine the Conventional Commits type.
Consult references/work-types.md for the full list and per-type behavior hints.
- If the input explicitly names a type (e.g., "this is a refactor"), use it when the input evidence agrees.
- If named type conflicts with described outcome, classify by outcome and record mismatch; ask only if resolution requires user-owned behavior or scope choice.
- If type is implicit but high-confidence, assign without confirmation round-trip.
- If type is low-confidence but technically resolvable, probe codebase or put distinction into first
Execution Planstage as investigation withReplan whenboundary. - Ask in Stage 4 only when type depends on product or scope choice user owns; derive type from answer.
See references/work-types.md for author-selection routing table.
Stage 3 — Codebase Review
The goal is enough context to fill Current State (As-Is) and Related Files / Entry Points, not exhaustive exploration.
Use whatever code search / read / symbol tooling fits the host environment and repository guidance — default Grep / Read / Glob, allowed semantic tools, language servers, or a short-lived subagent (e.g. Explore) when parallel lookups or main-context isolation is worth it.
Tool choice is the runtime's call; this stage only fixes the purpose and budget of the review.
Review budget (soft limits):
- At most ~15 file reads
- At most ~10 search queries
- Stop when you can confidently enumerate the primary entry points and major affected areas implied by the input — not just the first file or symbol that grounds the brief.
If likely input-implied surfaces remain unverified within review budget, add bounded investigation stage with named deliverable and
Replan whencondition.
Strategy:
- Start wide with keyword search on terms from the input — feature names, function names, error strings, routes, type names.
- Narrow to a list of candidate files, then read the 2–4 most promising ones.
- If the input mentions a subsystem (e.g., "auth middleware", "checkout flow"), look at likely directories first.
- Capture an As-Is picture by coherent context units: how each relevant function, module, behavior, integration, or user surface is shaped today.
- Capture concrete Related File / entry-point hints with one-line purposes. At least one entry point must be solid before saving the brief.
Active judgement:
- Let the user's goal drive any extra probing. If first code reads surface a nearby signal that could change work direction — dependency, style hook, comment, product doc, older brief, or unused surface clearly tied to the same feature — check just enough to decide how it affects the brief. Do not turn this into mandatory repo-wide audit.
- Prefer a reasoned recommendation over asking the user.
If a nearby signal is relevant but not required for the requested slice, encode the judgment in
Constraints,Out of Scopeas[deferred],Side Effect Checkpoints, orAcceptance Criteria. Ask only when the choice changes product behavior, scope, ownership, or acceptance in a way the requester must own. - Separate implementation completion from user / operator success when both exist.
Code may already expose a pass condition, event, return value, validator status, or stored state that says "done"; user-facing or operator-facing success may be different.
Capture both when they matter: put existing pass condition in
Current State (As-Is)/Side Effect Checkpoints, and put intended observable outcome inDesired Outcome (To-Be)/Acceptance Criteria. - If a nearby signal is weak, mention it in the Stage 6 save report instead of bloating the brief. Brief stays executable; report can carry useful "noticed while reviewing" context in normal prose.
Evidence discipline:
- Mark load-bearing findings as confirmed when codebase review directly verified them. A confirmed finding cites the file and a stable locator: section heading, function / class name, validator message, command output, or nearby quoted token. Line numbers are useful as secondary hints, but do not rely on line numbers alone because they drift after edits.
- Mark risk statements as inferred when they describe likely downstream behavior rather than a fact already present in a file. Name what confirms inference, such as validator fixture, targeted test run, or specific command.
- Do not write inferred risk as confirmed defect. Caveman output may sound terse, but it must still let downstream agent tell evidence from judgment.
- Prefix every load-bearing
Current State (As-Is)bullet with[confirmed]or[inferred]. Caveman keeps evidence token and stable locator/probe explicit. Validator checks label shape only; Stage 5.6 and human review own truthfulness.
Contract discipline:
- Name existing contracts that must keep speaking old shape while change lands. Contracts can be public APIs, persisted ids, database rows, event names, config keys, file formats, CLI flags, i18n keys, analytics events, generated schemas, or cross-process payloads.
- Put contract-preservation facts in
ConstraintsorSide Effect Checkpoints, not as vagueOut of Scopefiller. Good:- [ ] Existing saved sessions with status "pending" still deserialize.Bad:- [ ] Do not break compatibility. - If requested outcome requires changing a contract, surface compatibility choice in Stage 4 unless user already explicitly approved the break.
Source-of-truth inputs. When the user provides a checklist, TODO file, review rubric, audit notes, or any document as the source of truth, do not turn it into a representative summary.
- Treat each listed item as required concern until mapped, explicitly deferred / out of scope, or represented as non-blocking user-owned Open Question with safe default.
- Preserve the source's own dimensions, such as named variants, files, examples, sections, or checklist groups. Do not collapse them unless the user asks for a summary rather than an executable brief.
- Use searches only for literal terms that come from the user's source document or the target files being reviewed. Do not invent generic banned-pattern searches unless the user, repository rules, or source document defines those patterns.
- The saved brief does not need to expose an internal ledger, but Stage 5.6 must be able to trace each source item to a concrete bullet or checklist item. Caveman wording must not merge two source items into one bullet just to sound shorter.
If source document is long, keep private coverage ledger. Every source item must end as in scope, out of scope/deferred, execution stage, acceptance criterion, side-effect checkpoint, related file, constraint, or structured non-blocking question.
Do not:
- Read entire large files when symbolic / targeted-range reads suffice.
- Chase tangential code just to pad the brief.
If it does not tighten
Current State (As-Is)orRelated Files / Entry Points, skip it. - Make architectural claims the code does not support.
If uncertain, label it
[inferred]and route confirmation into investigation stage orReplan whenboundary.
Already-satisfied gate. Before Stage 4, compare full requested outcome and acceptance boundary against current code plus current verification signals.
- If all requested outcomes are confirmed, all acceptance checks already hold, and no edit, integration, migration, or evidence-producing work remains, create no plan.
Report
no-work-neededin normal chat prose with inspected paths, verification action, and observed signal, then stop. - If user explicitly asked for saved verification record despite already-satisfied state, create verification-only plan that expects no edits and records no-change evidence route. First stage must also say failure route: stop dependent work, return to owning plan, activate bounded correction plus re-verification work, then recalculate briefset topology and handoffs before continue.
- If only part of outcome is already satisfied, keep remaining work and make no-change branch explicit instead of directing unconditional edit.
- In briefset mode, re-run topology after this gate: zero active children means
no-work-needed, one means single-plan mode, and two or more retain briefset mode. Followreferences/briefset.mdfor child and handoff rules.
This outcome is called no-work-needed.
Stage 4 — User Decision Table
After Stage 3 has enough context, run ownership pass and collect only remaining user-owned decisions into Markdown decision table. Stage 4 is not a pre-review guessing interview: ask only after the codebase has been checked enough to state the uncertainty, the recommended change, and the evidence behind it.
Use this exact table shape for user-decision questions:
| 순번 | 내용 | 수정 추천안 | 근거 |
|---|---|---|---|
| 1 | <decision the user must make> | <recommended change to apply to the brief> | <codebase/input evidence and risk> |
Keep these four headers exactly as written, even when the surrounding conversation is not Korean. They are the stable decision-table contract: number, decision content, recommended change, and rationale.
Intent before enumeration. Preserve each requirement's meaning, not an unresolved interpretation of its words.
If input and bounded review leave multiple plausible goals, behaviors, scope boundaries, or completion criteria, ask the user before treating one interpretation as the task.
Use the existing decision table to show the ambiguity, concrete alternatives, recommended interpretation, and supporting evidence.
Distinguish a missing condition needed for the stated goal from an optional enhancement; label recommendations as proposals, not existing requirements.
Offer only task-relevant additions. An unanswered optional enhancement stays excluded; do not enlarge the plan to make it look more complete.
Ask first and allow an opportunity to answer. If no answer arrives and a safe fallback exists, save it with its reconfirmation milestone in Open Questions; never label it approved.
If no safe fallback exists, halt without saving. A task cancellation stops authoring; it is not permission to use fallbacks and continue.
User-owned gaps to close before drafting:
- Desired Outcome (To-Be) — confirm when absent, ambiguous, or when the codebase review suggests more than one plausible interpretation.
- Out of Scope — the most valuable guardrail for the downstream agent. Put unclear or high-risk scope boundaries in the decision table with a recommended exclusion/inclusion.
- Acceptance Criteria — what makes the task verifiably done. If code has a separate internal completion condition and user has a separate success condition, carry both instead of collapsing them into one vague criterion.
- Compatibility and ownership — ask before breaking contract or crossing externally owned boundary.
- Open Questions — keep only non-blocking user-owned decisions with safe fallback and reconfirm milestone.
Author determines output mode, work type, entry points, side-effect checks, and technical sequencing when input and codebase make them evident.
Technical unknowns become investigation stages, bounded Worker decision fields, Replan when conditions, constraints, or author-selected defaults. Ask the user for relevant observations or access details only when they hold information unavailable from the reviewed artifacts; do not ask them to perform the technical investigation.
Decision-table rule. Each row must request a real decision or a specific unavailable user-held observation, not a vague status note.
내용 states what the user must decide.
수정 추천안 states the concrete brief change you recommend.
근거 cites the input, codebase finding, existing pattern, or risk.
After the user answers, patch the draft plan in memory before composing the brief.
An unanswered or skipped question is not approval: non-blocking rows use their declared safe fallback, remain in structured Open Questions form, and proceed; any blocking row halts without writing.
Full decision classification, table rules, and termination rules live in references/stage-4-interview.md.
Before writing Open Questions:
- Make one active judgement pass. Ask: would a downstream coding agent still need to ask the requester what to do, or can the brief make a reasonable call?
- Do not use
Open Questionsto avoid making an implementation recommendation. If answer is reasonable bounded choice, put it intoWorker decision,Constraints, or relevant execution stage. - Keep
Open Questionsfor user-owned decisions only. Product direction, scope expansion, compatibility breaks, acceptance thresholds, and external ownership can require question. - Save question only when non-blocking; use exact normal-prose form
- [non-blocking] <question> — Default: <safe fallback>; Reconfirm before: <stage or milestone>. - If user has not answered blocking decision and no safe fallback exists, HALT and create no file.
Open Questions: Noneis acceptable only after this pass. It means "downstream agent can proceed without re-interviewing requester," not "nothing interesting was found."
Stage 5 — Save + Validate
Once Stage 4 closes, compose the final Markdown internally and write it straight to disk — do not paste the full brief into chat first. The user reviews the file in their editor in Stage 6, where real markdown rendering and diff tooling are available.
-
Compute the filename per the Output Contract above.
-
Ensure
docs/briefs/exists; create it if not. -
Resolve filename collisions by appending
-v2,-v3, …. -
Render the complete template from
references/template.mdand write the file (English section headers, English body in caveman full mode — seereferences/caveman-style.mdfor conversion rules and the Auto-Clarity carve-outs that stay in normal prose). -
Run the structural validator — a fast smoke test for the template contract:
python3 <skill-dir>/scripts/validate_brief.py docs/briefs/<filename>.mdIf brief is stored in isolated artifact tree while entry-point paths belong to another checkout, add
--repo-root <repository-root>before brief path.<skill-dir>is the installed skill package directory — the directory containing this SKILL.md (resolve it from wherever this skill was loaded, e.g.~/.claude/skills/task-brief-creator-cavemanor a plugin cache). Never assume the user's repository contains the script: the brief lives in the user's repo, the validator lives with the skill.- Exit 0 → continue to Stage 5.6; the validator result is reported in the Stage 6 banner.
- Exit 1 (structural failure) → fix file and rerun validator without asking user. If same structural cause still fails after two repair attempts, leave file in place and carry residual failure into Stage 6.
- Exit 2 (file I/O error) → inspect the actual error: invalid arguments, invalid
--repo-root, missing artifact, or unreadable file. Correct the cause; do not infer that a saved file disappeared or recreate it unnecessarily.
The validator only checks structural conformity (section presence, checklist format, filename pattern, type coherence). It does not judge content quality — Stage 5.6 self-check, opt-in Stage 5.7 cold-pickup, and human review do that. Passing validator ≠ good brief; failing validator = malformed brief.
Validation Budget
A validation run covers the single plan or the entire parent-and-children set. It consists of the structural validator followed by the Stage 5.6 self-check; nothing in the default run spawns a sub-agent. Structural repairs: at most two attempts for the same structural cause, then carry the residual failure into Stage 6. Self-check: at most two passes per run; every content edit re-runs the structural validator before the next pass. When the budget is exhausted, keep the latest well-formed file, stop automatic repairs, and report the remaining gaps as incomplete, never as passed. A new user answer or requested edit starts a new validation run. The opt-in Stage 5.7 cold-pickup runs once per explicit user request after a completed run; the patches it causes re-enter this budget from the structural validator. Before applying cold-pickup patches, copy the affected files to a scratch directory outside the repository so a patch that breaks a previously passing check can be restored; delete the copies after the final state has been reported.
Stage 5.6 — Content and Intent Self-Check
The structural validator confirms the file has the required sections. It does not confirm the file is a complete work instruction, nor that it says what the user meant. Before handing off in Stage 6, re-read the saved brief from disk and run this self-check against the original input plus Stage 3 / Stage 4 findings. This is the only verification pass in the default run; an independent read by a fresh sub-agent is available on request through Stage 5.7.
The brief is a work instruction, not a summary. Caveman compresses how the brief reads, never what it contains — so this self-check is identical to the normal-mode skill's check, plus one caveman-only parity item. Run this checklist:
-
Reader-centred writing: apply the reader check in
references/plain-language.mdto the saved artifact. The required information is easy to locate, the action and conditions are clear, and the next step is usable; authoring tools and workflow narration do not appear in the plan. -
Intent fidelity: read the saved file as a stranger would and compare it with the original input and the answered Stage 4 decisions. The work purpose is the same; the scope is neither materially wider nor narrower; the first stage and entry points point where the input points; every user constraint, exclusion, and acceptance threshold survives; the brief assumes no work the input did not intend. A user-locked Stage 4 decision counts as intent even when it differs from the raw input. If caveman compression is what makes purpose or scope unclear, restore normal prose under the Auto-Clarity carve-out.
-
Input coverage: every distinct concern named in input maps to at least one bullet or stage (In Scope, Out of Scope, Related Files, Execution Plan, Constraints, Side Effect Checkpoints, Acceptance Criteria, or structured non-blocking Open Questions). If spec section is not implemented now, it appears in
Out of Scopeas[hard]/[deferred], or inOpen Questionsonly when a non-blocking user decision has safe default. Two unrelated implementation or verification obligations are never merged into one bullet. -
Source-of-truth coverage: if user supplied checklist, TODO, review rubric, audit notes, or source-of-truth document, every item is represented, explicitly deferred / out of scope, or saved as structured non-blocking user question. Representative theme coverage is not enough. Caveman wording may not merge two source items into one bullet just to sound shorter.
-
Scope triage: every discovered concern is either must-fix in this brief, a tightly coupled check, explicitly deferred / out of scope, or left for a user decision. Brief does not turn broad review into unbounded implementation task.
-
Stage 3 coverage: every primary entry point or affected area appears in
Related Files / Entry Points, and every technical uncertainty is resolved or routed into investigation stage,Worker decision, orReplan whenboundary. -
Contract preservation: existing contracts discovered in Stage 3 that must not change are named in
Constraints,Side Effect Checkpoints, orAcceptance Criteria; compatibility-sensitive changes are not hidden behind generic wording. -
Success split: when internal completion and user / operator success are different, both are represented; brief does not treat event firing, validator passing, or state transition as proof that user goal was achieved unless that is actually the goal.
-
Section depth: no section was reduced to a single bullet when the input or Stage 3 findings contain multiple distinct concerns for it. Sections expand to fit the work; they are not capped.
-
No content compression: no bullet was shortened by dropping qualifiers, quantities, units, thresholds, versions, environment conditions, or ordering words (
only on cold start,≤ 5KB gzipped,iOS Safari 17+,after move end). "Executable, not discursive" is a prose rule, not a content rule. -
Evidence clarity: every load-bearing current-state bullet uses
[confirmed]or[inferred]; confirmed facts cite stable evidence, inferred risks name confirmation method, and line numbers are not sole locator. -
Execution continuity: Stage 1 has concrete precondition; stage numbers are consecutive; every stage has bounded outcome, deliverable, local completion checks, explicit handoff, and replan boundary; each handoff satisfies next
Starts when. -
Already-satisfied discipline: plan does not force edit when current evidence already satisfies requested outcome; full satisfaction exited as
no-work-neededunless user explicitly requested verification record, partial satisfaction has bounded no-change route, and failed proof stops dependents and names correction/re-verification owner. -
Verification concreteness: every named verification action comes from repository evidence or is bounded inspection, identifies exact input/target, and states observable expected signal. When success means no matches, plan also identifies population checked so empty or wrong input cannot pass accidentally.
-
Completion separation: stage-local completion appears only under
Ends when; whole-workAcceptance Criteriarun after all required stages and side-effect checkpoints. -
Handoff readiness: coding agent reading only plan can recover first stage, order, deliverables, handoffs, replan conditions, and whole-work completion without re-interviewing requester. If a re-interview would be needed, identify the thin section and patch it.
-
Question discipline: every
Open Questionsitem is genuinely user-owned. Every saved question is non-blocking and names safe default plus reconfirm milestone; move technical/reversible choices into investigation,Worker decision,Replan when, constraints, or deferred scope. IfOpen QuestionssaysNone, the brief made the necessary calls instead of hiding them. -
Caveman parity: compare the saved prose with the pre-conversion inventory of requirements, conditions, quantities, stages, deliverables, and handoffs. Each concern remains separately addressable; identifiers, uncertainty, negation, and obligation retain their meaning. Do not infer parity from an imagined normal-mode brief or from bullet counts alone. Caveman is register-only.
If any check fails, fix the brief in place with Edit, re-run the structural validator (validate_brief.py for a single brief, validate_briefset.py for a briefset parent), then run this self-check again.
At most two self-check passes per validation run; if a gap remains after the second pass or has no justified patch, stop and report the latest file as incomplete, not passed.
The self-check outcome is separate from the structural validator — report both in Stage 6. A brief can pass structural validation and still fail this self-check; in that case the file is incomplete even though it is well-formed.
For briefset mode, run the self-check on the parent and on every child independently. The parent's coverage check asks whether every input-implied execution context maps to a child; each child uses all items above.
Stage 5.7 — Cold-Pickup Verification (opt-in)
The Stage 5.6 self-check is self-evaluated: the author cannot forget its own intent, so it cannot fully simulate a stranger reading the file cold. Stage 5.7 supplies that stranger — a fresh read-only sub-agent that first reconstructs the plan from the saved brief alone, then compares it with the original input and reports intent deviations, ask-backs, missing concerns, and over-terse bullets.
Stage 5.7 never runs by default. It has no signal gates and no automatic triggers; briefset mode, Stage 4 decision rows, non-empty Open Questions, work type, and the caveman register do not start it.
It runs only when the user explicitly asks — for example run cold-pickup, --cold-pickup, 콜드픽업 실행 — either together with the initial input or later in Stage 6 against the current on-disk file.
Do not spawn a sub-agent for verification without such a request. Report Stage 5.7 only when requested; omit unsolicited optional-check invitations from Stage 6.
When requested, read references/cold-pickup.md and follow it. In short:
- Complete the current validation run first (structural validator and Stage 5.6 pass or report residuals); cold-pickup does not replace either.
- Spawn one fresh read-only sub-agent per artifact — one for a single brief; in briefset mode one for the parent plus one per child the user did not exclude — with no inherited conversation and no Stage 3 register, Stage 4 decisions, self-check results, or hints about suspected gaps.
- Give it the brief path (plus the parent path for a child) and the path of a scratch file holding the original input verbatim; it reads those files only and never explores the repository.
- Collect the YAML report, route each finding through the reference's routing tables (disagreement vs drift against answered Stage 4 rows), patch drift in place, re-run the structural validator, then Stage 5.6.
- Report the outcome in the Stage 6 banner. One pass per request: do not re-run cold-pickup automatically after patching; the user asks again if they want another independent read.
Caveman extension. The report schema in the reference adds over_terse_bullets for bullets whose caveman compression left the coding agent unsure what to do.
They are register findings, never disagreements: rewrite each flagged bullet in normal prose under the Auto-Clarity carve-out, and verdict: clean also requires over_terse_bullets to be empty.
The sub-agent prompt, its report, and the banner stay in normal prose; caveman applies to the saved brief body only.
Cold-pickup never overrides a Stage 4 decision the user already locked, never invents Acceptance Criteria, Side Effect Checkpoints, or Out-of-Scope guardrails the input did not imply, and never silently rewrites Open Questions — drift fixes either resolve a question into another section or leave the question intact for the user.
If a fresh read-only sub-agent cannot be spawned or returns an unusable report, report cold-pickup unavailable (<actual reason>); the Stage 5.6 result stands on its own and is never relabeled as an independent read.
Stage 6 — Review + Iterate
The brief is on disk. Hand off to the user for review.
-
Report the path and one-line summary, then distinguish structural validation from content validation. Structural validation is the Stage 5 validator result. Content validation is the Stage 5.6 content and intent self-check (including caveman parity), and the actual Stage 5.7 result only when the user requested it. Do not imply that the self-check is an independent reader evaluation. Report unavailable, incomplete, restored, and exhausted outcomes explicitly; a missing required result is never a pass. Every reported check must belong to the final saved artifact state. Use the user's chat language; the banner is normal prose, never caveman.
English (validator + self-check passed, cold-pickup not requested):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; structural validation passed; content validation passed — content and intent self-check passed, caveman parity OK). Open it and let me know if anything needs editing.Korean (validator + self-check passed, cold-pickup not requested):
저장 완료 —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; 구조 검증 통과; 내용 검증 통과 — 내용/의도 자체 검증 통과, 문체 변환 동등성 확인). 파일 열어보고 고칠 부분 있으면 알려줘.English (user requested cold-pickup, clean):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; structural validation passed; content validation passed — content and intent self-check passed, caveman parity OK; cold-pickup: clean (no intent deviations, no ask-backs, no missing concerns, no over-terse bullets)). Open it and let me know if anything needs editing.English (user requested cold-pickup, findings):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; structural validation passed; content validation passed — content and intent self-check passed after 1 patch, caveman parity OK; cold-pickup flagged 3 item(s): 2 patched in place, 1 left as a user decision).- d1 (
scope_narrower): the input asks for the toggle on mobile too; added the mobile settings route to In Scope and Stage 2. - t1 (over-terse):
- Persist choice.lost the storage target; restored to normal prose naming thelocalStoragekeytheme. - a1 (
user_input_ambiguity, affects direction): "system default" could mean the OS theme or the app default — see the decision table below.
English (validator still fails after two repair attempts):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md, but structural validation still flags 2 issue(s) after two repair attempts: ✗ ✗ . The file is on disk; content validation did not run.Mirror any banner into the user's chat language as the Korean example above shows — translate the prose, keep paths, filenames, and technical fields (finding ids,
kindvalues, classifications, validator messages) verbatim. Briefset banners use the collapsed formats inreferences/cold-pickup.mdandreferences/briefset.md.When structural validation still fails after the repair budget, Stage 5.6 is skipped and Stage 5.7 is not offered — the plan is not yet well-formed enough to check content against. The banner stays as shown; do not append
self-check skipped/cold-pickup not runlines in this case.If the Stage 5.6 self-check surfaced gaps fixed within the budget, say what you patched (e.g., "self-check found 2 input concerns missing from In Scope and one bullet that had been merged for caveman compression; restored them, re-validated"). If Stage 5.7 patched the brief, list each patched and residual finding as bullets under the banner, as shown above. If the user requested cold-pickup and it could not run, report
cold-pickup unavailable (<actual reason>)instead of a result. - d1 (
-
If the user requests changes, apply them with
Editagainst the on-disk file. Do not re-render the full brief into chat — that defeats the point of save-then-review. Re-run the structural validator after each edit pass, then Stage 5.6, and report the delta. Re-run Stage 5.7 only if the user asks for it again. -
If saved single plan contains structured non-blocking
Open Questions(after any Stage 5.7 patches have landed), present them after save report using Stage 4 table:| 순번 | 내용 | 수정 추천안 | 근거 | |---|---|---|---| | 1 | <non-blocking user decision> | <recommended patch to apply to the plan> | <safe default and reconfirm milestone> |After user answers, patch saved plan, move resolved decisions into appropriate sections, leave only structured non-blocking user questions, then rerun the validator and Stage 5.6. If the user leaves a question unanswered, skips that question, or lets structured input expire, keep declared defaults active and questions unchanged; they do not block coding agent before named reconfirmation milestones. Chat stays normal prose; only saved brief body prose uses caveman full mode.
-
The user owns "done." A task cancellation stops further edits and verification. Do not stage or commit the file. Loop on Stage 6 until they explicitly stop.
Why save-then-review: an earlier iteration rendered the full brief in chat for approval before writing to disk.
In hands-on use that flooded the conversation with markdown that renders poorly inside a code fence and was awkward to edit conversationally.
Writing to disk first lets the user review in their editor (real markdown, real diff tools, real inline edits) and lets the validator surface structural issues immediately.
The tradeoff — a file briefly on disk before approval — is neutral: docs/briefs/ is the intended home for these files, and the commit step stays with the user.
Template
See references/template.md for:
- The exact nine-required-section Markdown template.
- Per-section writing guidance (what good looks like, what not to write).
- Worked example of a filled brief.
The emitted brief is in English. Chat interaction language follows the user's input.
Work Types
See references/work-types.md for:
- The ten Conventional Commits types.
- Per-type agent behavior hints (why the type matters — it changes how the downstream coding agent approaches the work).
- Classification tips for ambiguous cases.
Examples
See examples/ for worked end-to-end scenarios (input → codebase review → interview → output).
Start with examples/README.md for the index.
Structural Validator
scripts/validate_brief.py is a stand-alone Python 3 script (no external deps) that verifies structural conformity of a saved brief.
It runs as step 5 of Stage 5 (save + validate) but can also be run ad-hoc against any existing brief.
Always resolve the script path against <skill-dir> — the installed skill package directory containing this SKILL.md — never against the user's repository:
python3 <skill-dir>/scripts/validate_brief.py \
docs/briefs/2026-04-23-feat-global-hotkey-system.md
Exit codes: 0 pass with no warnings, 1 structural failure or any reported warning, 2 argument, repository-root, or file I/O error.
Scope of the validator (deliberately structural only):
- Filename pattern, exactly one H1 title outside fenced code, title format, type coherence across filename / title / section value, and slug length.
- Presence and template order of all nine required H2 sections + exactly one
In ScopethenOut of ScopeH3; duplicate H2 sections are rejected. Fenced examples do not establish sections or checklist items. [confirmed]/[inferred]prefixes inCurrent State (As-Is), unique consecutive execution-stage headings with required fields, and structured non-blockingOpen Questionsshape.- Type-conditional section (
Reproduction/Baseline Measurement/Behavior Contract) present and populated for the matching type;- N/A — <reason>cannot be mixed with other bullets. - Top-level bullet content in narrative sections; top-level
- [ ]items in checklist sections; populatedOpen Questionswith- None — <reason>when no questions remain. Related Files / Entry Pointsvalidates file tokens before the first prose-separating em dash outside inline code. At least one existing file/directory or adjacent(proposed)path is required. Root files, including dotfiles, resolve on disk. URLs and- Route: `/path` — <purpose>entries are supplementary and do not satisfy the file-entry requirement. Descriptive inline code after the separator is not checked as a file.- Optional
--repo-rootlets isolated brief artifacts validate their entry points against actual target checkout. - Optional
Constraintsheading shape. - Every top-level
Out of Scopeexclusion needs[hard]or[deferred]; a sole- None — <reason>means no exclusions. Missing labels fail. Other warnings also make validation fail; semantic correctness remains a content-review responsibility.
Out of scope (still on content review): whether evidence labels are truthful, stage outcomes and handoffs are executable, Out-of-Scope entries are real guardrails, entry points are good, Acceptance Criteria are measurable, type section is sufficient, and caveman conversion preserves meaning.
For briefset mode, use scripts/validate_briefset.py on the parent file — it validates the parent structure and re-runs validate_brief.py's checks transitively on every referenced child brief, so one invocation covers the whole set:
python3 <skill-dir>/scripts/validate_briefset.py \
docs/briefs/2026-04-30-briefset-checkout-i18n.md
Same exit codes.
See references/briefset.md for what the parent validator checks and what stays on the human reviewer.
Guardrails
- Executable, not discursive. Apply the intro's prose-style rule to every section — rewrite discussion-summary, negotiation-log, or rationale prose until it directs concrete action; retain only the brief rationale the reader needs to execute safely; author deliberations do not belong in the brief.
- Never fabricate file paths or PR numbers.
Related Files / Entry Pointsis mandatory because it is the downstream agent's starting route. If the codebase review does not surface at least one concrete file, directory, route, command, module, related brief, or confirmed proposed path, ask the user to provide or confirm the entry point before saving the brief. At least one top-level entry must carry that path in inline code; plain-text path, PR-only bullet, or symbol-only bullet is not structurally checkable. - Ground Acceptance Criteria in input or code evidence. Ask only for product or acceptance thresholds user owns; derive technical proof paths from repository.
- Never proceed past the Ambiguity Gate on a hunch. Halting is the correct answer when anchors are missing.
- Keep Out-of-Scope specific. "Don't refactor unrelated code" is filler.
"Do not change the
PaymentServiceinterface" is a real guardrail. - Triage scope before saving. Put required outcome first, tightly coupled checks second, unrelated findings in
[deferred]; technical unknowns go to investigation or replan boundaries. - Keep implementation judgment out of Out-of-Scope.
Out of Scopetells the downstream coding agent what not to do. Put bounded implementation choices inConstraints, and user-owned unresolved choices inOpen Questions. - Preserve named contracts. When a change touches existing callers, persisted state, user-visible ids, event flows, schemas, file formats, or generated outputs, name the exact contracts that must remain compatible. Do not rely on "avoid regressions" or "keep compatibility" as a substitute.
- One plan per invocation, unless input has multiple execution contexts. When it does, select briefset from documented signals and explain evidence; ask only when topology depends on user-owned delivery or scope boundary. Do not stuff unrelated execution contexts into one plan or nest briefsets. When contexts have unrelated outcomes and no shared acceptance boundary, recommend separate single-plan invocations (see Stage 1). Within a briefset, use parallel waves by default and add ordering only for actual preconditions, verified conflicts, or user-required delivery order.
- Decision table does not bypass the ambiguity gate. Halt-eligible inputs still halt at Stage 1.
Do not try to reconstruct missing PROBLEM / GOAL / SCOPE / TARGET through a large decision table — the gate exists precisely to prevent that failure mode.
See
references/stage-4-interview.mdfor the table rules and termination conditions. - Caveman never leaks into chat. Stage 1 halt messages, Stage 4 questions, recommended answers, Stage 6 save reports, validator dialogs and edit confirmations are full natural prose. If the user later asks for clarification of the brief, paraphrase a normal-prose summary in chat — do not just paste the caveman bullet back. Caveman is the file's register, not the conversation's.
- Caveman never overrides correctness. If full-mode compression creates technical ambiguity in a bullet (order-of-operations risk, ambiguous referent, irreversible-op warning), write that bullet in normal prose. Auto-Clarity rule: compression yields when meaning is at risk.
Pre-Save Checklist
Self-check before invoking Write in Stage 5.
The structural validator catches format errors after the fact; this list catches content gaps it cannot see.
Task Brief Creator
Produce an executable implementation work plan under docs/briefs/ that one coding agent authors and another coding agent can execute without reconstructing the route or re-interviewing the requester.
The historical work-brief and handoff names remain activation aliases; the saved artifact's primary identity is a code-execution PLAN.
The plan is the execution artifact. Its job is to let a coding agent recover the first stage, intended order, stage deliverables and handoffs, replan boundaries, and whole-work completion criteria — while routing it to the right files and fixing the behavior envelope.
The plan is an executable work instruction — nothing else. It is not a scope-control memo, discussion summary, background briefing, or rationale document. Every section must answer "what does the coding agent do next?" — if a section reads like meeting minutes, negotiation history, or context prose, rewrite it until it routes to files, decisions, or verifiable outcomes. A plan that makes the coding agent reconstruct its execution sequence or re-interview the requester is a failed plan, regardless of how polished it reads.
"Executable, not discursive" is a prose style rule, not a content reduction rule. It tells you how each bullet should read — direct actions and necessary facts; a brief reason stays when it prevents misuse or changes execution. It does not tell you to drop distinct concerns, merge unrelated bullets, or summarize the input down to its highlights. A brief that omits a concern from the input is also a failed brief, because the downstream agent will silently miss it. Tight prose, full enumeration: short bullets are fine and encouraged, but every distinct concern from the input and the codebase review must land somewhere in the brief.
Modes
This skill operates in one of two output modes:
- Single-plan mode (default; historical single-brief name remains) — emits one executable work plan per invocation. The workflow below covers this case end to end.
- Briefset mode — emits a parent execution-management document plus N independently executable child briefs.
Used when the input describes multiple execution contexts that need coordination (independent completion criteria, mixed work types, ordered dependencies, parallelizable waves, or shared conflict hotspots).
Selected by the criteria in
references/briefset.md; long input, many files, or many related edit points alone never trigger briefset mode.
Output-mode selection happens at Stage 1 alongside the ambiguity gate and is author-owned when the input and codebase make it evident.
In briefset mode, follow the workflow below with the per-stage adaptations in references/briefset.md (parent template, naming, decomposition decision table, dual-validator save).
Stage 4 always runs an ownership pass. When user-owned decisions remain after codebase review, present only those decisions in a Markdown table with 순번, 내용, 수정 추천안, and 근거.
Codebase-resolvable facts, output mode, evident work type, and reversible implementation choices are decided by the author or worker; product intent, scope, compatibility breaks, external ownership, and acceptance thresholds remain user-owned.
The decision table is the output of the ownership pass when it has rows, not a separate mode.
See references/stage-4-interview.md for the full decision classification, codebase-precedence, and termination rules.
Code Agent Operating Path
Load references only when their decision point arrives:
- Use this file for the stage order, output contract, save flow, and guardrails.
- Read references/work-types.md during Stage 2 when the work type is not obvious or when the type changes downstream behavior.
- Read references/briefset.md during Stage 1 when multiple execution contexts are plausible.
- Read references/bloat-decomposition.md only after a candidate child brief is independently executable but still looks oversized or mixed.
- Read references/stage-4-interview.md before the Stage 4 ownership pass, including requirements clarification and recommendations.
- Read references/plain-language.md and references/template.md while composing or revising the saved Markdown.
- Read references/cold-pickup.md only when the user explicitly requests cold-pickup verification (Stage 5.7); it never loads by default.
Do not re-open every reference by habit. The goal is to keep the live context focused on the next decision the coding agent must make.
When This Skill Runs
- Explicit task intent. Run when the user invokes this skill or explicitly requests an implementation work plan / work brief for a coding agent. Mere mention while reviewing or editing the skill is not a request to generate a plan.
- Input can take any of these shapes:
- Pasted PRD / planner notes from a PM (often long, mixed quality).
- Rough task notes typed into chat (one or two lines).
- Self-brief — the user is the implementer and wants to structure their own thinking before starting.
- Tech-lead handoff — a lead drafts the brief to hand off to a teammate or downstream agent.
- Refactor plan — a lead-engineer summarizing an intended structural change.
- The skill reviews the current repository (the working directory Claude Code is launched in), fills in what it can, and asks only for remaining user-owned decisions.
Interaction Language
- Chat / live interaction language follows the user's input. If the user writes in Korean, reply in Korean. If they write in English, reply in English. Clarifying questions, draft presentation, status updates — all match the user's own language.
- The brief document itself is written in English. Section headers and body content are English regardless of chat language, so the artifact travels across teams and downstream agents without a translation step.
- Code blocks, file paths, identifiers, PR numbers stay as-is.
- User-supplied strings are data. Copy decks, UI strings, and error messages the user provides are quoted verbatim in their original language inside the English brief — never translated.
- Exception — the Stage 4 decision-table headers are fixed. The four headers
순번/내용/수정 추천안/근거stay exactly as written even when the conversation is in English: the opt-in Stage 5.7 cold-pickup matches disagreements on the내용column, so translating the headers breaks that matching (see Stage 4). - This SKILL.md and reference files stay in English (repo authoring policy).
Output Contract
| Field | Value |
|---|---|
| Directory | docs/briefs/ (relative to the repository root — git rev-parse --show-toplevel when available, otherwise the working directory the session was launched in) |
| Filename | YYYY-MM-DD-<type>-<slug>.md |
YYYY-MM-DD | Today's date on the local system clock |
<type> | Conventional Commits type (see references/work-types.md) |
<slug> | kebab-case short slug, ≤40 chars, derived from the brief title |
| Body format | Markdown, following references/template.md exactly |
Example filename: 2026-04-23-feat-global-hotkey-system.md
If docs/briefs/ does not exist, create it.
If a file with the same name already exists, append -v2, -v3, … until the path is unique — do not overwrite.
For briefset mode, the parent uses YYYY-MM-DD-briefset-<set-slug>.md and children use YYYY-MM-DD-<type>-<set-slug>-NN-<child-slug>.md.
See references/briefset.md for the parent template and naming rules.
The nine required H2 sections are: Work Type, Current State (As-Is), Desired Outcome (To-Be), Scope (with In Scope / Out of Scope H3s), Related Files / Entry Points, Execution Plan, Side Effect Checkpoints, Acceptance Criteria, Open Questions.
Optional Constraints may appear between Scope and Related Files / Entry Points when task-specific constraints exist.
Execution Plan appears immediately after Related Files / Entry Points and before Side Effect Checkpoints.
Put stage-local completion under each stage's Ends when.
Reserve Acceptance Criteria for whole-work completion after all required stages and side-effect checkpoints finish.
Three work types require an additional H2 section between Current State (As-Is) and Desired Outcome (To-Be):
fix→## Reproductionperf→## Baseline Measurementrefactor→## Behavior Contract
These exist because the work type changes the downstream agent's behavior (reproduction-first, measurement-first, behavior-preservation), and the brief must carry the type-specific input that behavior depends on.
The escape hatch when the section legitimately has nothing concrete to capture is a single bullet - N/A — <reason>.
See references/template.md and references/work-types.md for the per-section guidance.
Bullet count is not capped. The rule is cohesion plus completeness, not brevity:
- Each bullet should describe one coherent unit of context, scope, risk, or verification.
- Enumerate every distinct concern. If the input or the Stage 3 codebase review surfaces N distinct concerns that map to a section, the section gets ≥ N bullets. Sections expand to fit the work; they are not capped. A section reduced to one bullet when the input contained multiple concerns for it is the failure mode this rule exists to prevent.
- Do not merge unrelated concerns into one bullet just to keep the document short.
- Write as many bullets as the task needs; do not compress larger work into vague combined bullets. Short prose per bullet is fine and encouraged — short count is the failure.
Completeness does not mean "put every discovered issue in scope." When review surfaces many valid concerns, separate them before saving:
- Must fix in this brief — issues that directly block the user's stated goal or would make the downstream task unsafe / wrong if left unresolved.
- Check while here — nearby contract or documentation consistency checks that are cheap and directly connected to the must-fix work.
- Defer / record — valid follow-up issues that do not have to change for this brief to succeed.
In Scope should usually hold the must-fix set plus tightly coupled checks, not the whole discovery list.
Record deferred items in Out of Scope as [deferred]; use Open Questions only for non-blocking user-owned decisions with a safe default and reconfirm milestone.
If more than five independent must-fix concerns remain after this triage, reconsider briefset mode or ask the user to choose the first slice only when slicing is a user-owned scope decision.
Workflow
Stage 1 — Ambiguity Gate (HALT or CONTINUE)
Before full codebase review, check whether the input contains enough signal to ground the brief. Use the four-anchor heuristic:
| Anchor | What it answers | Maps to |
|---|---|---|
| PROBLEM | What is wrong or what is changing? | § Current State (As-Is) |
| GOAL | What should be true when it's done? | § Desired Outcome (To-Be) |
| SCOPE | Where does this apply (module, feature area, user surface)? | § In/Out of Scope |
| TARGET | Which part of the system is touched (file, subsystem, layer)? | § Related Files / Entry Points |
Count how many anchors are derivable from the input. Derivable = a reasonable engineer could answer the anchor from the user's input without inventing intent.
-
All 4 anchors present → CONTINUE to Stage 2.
-
3 anchors present, TARGET missing → run a narrow target probe before deciding. Use at most a few
rg/ glob queries to find likely files, directories, routes, commands, or modules. If a concrete entry point emerges, CONTINUE. If not, HALT and ask the user for the target area. -
3 anchors present, PROBLEM or GOAL or SCOPE missing → CONTINUE only when the missing anchor can be stated in one concrete sentence derived from the input (write that sentence into the brief; vague fillers like "make it better / cleaner" do not count). Otherwise HALT and ask for that anchor. Detail that survives this check gets filled in Stage 3 via codebase review or Stage 4 via user questions.
-
2 or fewer anchors present → HALT. Respond in the user's chat language naming exactly which anchors are missing, and ask for more input. Do NOT proceed through Stages 2–6 on an underspecified input. The briefset-mode check below also waits — never split an underspecified input into multiple equally underspecified child briefs. Example halt messages:
English:
I can't ground the brief from this input alone. Missing — PROBLEM (what is being fixed or changed) and TARGET (which area / file / subsystem is touched). Can you paste the spec or add one or two lines?
Korean:
입력만으로는 브리핑 만들기 어려워. 다음이 아직 확인 안 돼 — PROBLEM(뭘 고치거나 바꾸는지)과 TARGET(어느 영역/파일/시스템을 건드리는지). 더 얹어줄래? 기획서 붙여넣거나 한두 줄 더 써주면 돼.
Why halt instead of guess: an underspecified brief is worse than no brief — the downstream agent commits to the wrong problem framing and the rework cost eats the whole savings. Pushing back early is cheaper than producing a confident-looking but wrong document.
Edge case — pasted spec that looks long but is content-light: word count is not a proxy for the four anchors. A 2,000-word product narrative without a concrete PROBLEM or TARGET still halts. Judge by anchor coverage, not length.
See examples/03-halt-ambiguous.md for a worked halt case.
Briefset signal check (after CONTINUE): once anchors clear, also evaluate whether the input describes multiple execution contexts. Do not use file count, line count, input length, or several related edit points as triggers by themselves. Those are supporting evidence only.
If briefset signals are strong, select briefset mode and state the evidence before Stage 2.
If the candidate contexts have unrelated outcomes and no shared acceptance boundary, select separate single-plan invocations. Independent children serving one coordinated outcome may share a briefset and start in the same wave; do not invent dependencies to justify the parent.
If the evidence is unclear, default to single-plan mode.
Ask only when output topology depends on a user-owned delivery boundary, release unit, or scope choice; do not ask the user to choose a document shape when code and input already settle it.
Several stages inside one cohesive execution context do not justify briefset mode; consult references/bloat-decomposition.md before splitting an oversized candidate.
Stage 2 — Work Type Selection
Determine the Conventional Commits type.
Consult references/work-types.md for the full list and per-type behavior hints.
- If the input explicitly names a type (e.g., "this is a refactor"), use it when the input evidence agrees.
- If the named type conflicts with the described outcome, classify by the outcome and record the mismatch; ask only if resolving it requires a user-owned behavior or scope decision.
- If the type is implicit but high-confidence, assign it without a confirmation round-trip.
- If the implicit type is low-confidence but technically resolvable, probe the codebase or put the distinction into the first
Execution Planstage as an investigation with aReplan whenboundary. - Ask in Stage 4 only when the work type depends on an underlying product or scope choice the user owns; derive the type from that answer.
See references/work-types.md for the full author-selection routing table.
Stage 3 — Codebase Review
The goal is enough context to fill Current State (As-Is) and Related Files / Entry Points, not exhaustive exploration.
Use whatever code search / read / symbol tooling fits the host environment and repository guidance — default Grep / Read / Glob, allowed semantic tools, language servers, or a short-lived subagent (e.g. Explore) when parallel lookups or main-context isolation is worth it.
Tool choice is the runtime's call; this stage only fixes the purpose and budget of the review.
Review budget (soft limits):
- At most ~15 file reads
- At most ~10 search queries
- Stop when you can confidently enumerate the primary entry points and major affected areas implied by the input — not just the first file or symbol that grounds the brief.
If likely input-implied surfaces remain unverified within the review budget, add a bounded investigation stage with a named deliverable and
Replan whencondition.
Strategy:
- Start wide with keyword search on terms from the input — feature names, function names, error strings, routes, type names.
- Narrow to a list of candidate files, then read the 2–4 most promising ones.
- If the input mentions a subsystem (e.g., "auth middleware", "checkout flow"), look at likely directories first.
- Capture an As-Is picture by coherent context units: how each relevant function, module, behavior, integration, or user surface is shaped today.
- Capture concrete Related File / entry-point hints with one-line purposes. At least one entry point must be solid before saving the brief.
Active judgement:
- Let the user's goal drive any extra probing. If the first code reads surface a nearby signal that could change the work direction — a dependency, style hook, comment, product doc, older brief, or unused surface that clearly belongs to the same feature — check just enough to decide how it affects the brief. Do not turn this into a mandatory repo-wide audit.
- Prefer a reasoned recommendation over asking the user.
If a nearby signal is relevant but not required for the requested slice, encode the judgment in
Constraints,Out of Scopeas[deferred],Side Effect Checkpoints, orAcceptance Criteria. Ask only when the choice changes product behavior, scope, ownership, or acceptance in a way the requester must own. - Separate implementation completion from user / operator success when both exist.
Code may already expose a pass condition, event, return value, validator status, or stored state that says "done"; the user-facing or operator-facing success may be different.
Capture both when they matter: put the existing pass condition in
Current State (As-Is)/Side Effect Checkpoints, and put the intended observable outcome inDesired Outcome (To-Be)/Acceptance Criteria. - If a nearby signal is weak, mention it in the Stage 6 save report instead of bloating the brief. The brief stays executable; the report can carry useful "noticed while reviewing" context.
Evidence discipline:
- Mark load-bearing findings as confirmed when the codebase review directly verified them. A confirmed finding cites the file and a stable locator: section heading, function / class name, validator message, command output, or nearby quoted token. Line numbers are useful as secondary hints, but do not rely on line numbers alone because they drift after edits.
- Mark risk statements as inferred when they describe likely downstream behavior rather than a fact already present in a file. Name what would confirm the inference, such as a validator fixture, a targeted test run, or a specific command.
- Do not write an inferred risk as if it were a confirmed defect. The saved brief may stay concise, but the wording must let the downstream agent tell evidence from judgment.
- Prefix every load-bearing
Current State (As-Is)bullet with[confirmed]or[inferred]. The validator checks the label shape only; Stage 5.6 and human review own the truthfulness of the classification.
Contract discipline:
- Name the existing contracts that must keep speaking the old shape while the change lands. Contracts can be public APIs, persisted ids, database rows, event names, config keys, file formats, CLI flags, i18n keys, analytics events, generated schemas, or cross-process payloads.
- Put contract-preservation facts in
ConstraintsorSide Effect Checkpoints, not as vagueOut of Scopefiller. Good:- [ ] Existing saved sessions with status "pending" still deserialize.Bad:- [ ] Do not break compatibility. - If the requested outcome requires changing a contract, surface the compatibility choice in Stage 4 unless the user already explicitly approved the break.
Source-of-truth inputs. When the user provides a checklist, TODO file, review rubric, audit notes, or any document as the source of truth, do not turn it into a representative summary.
- Treat each listed item as a required concern until it is mapped, explicitly deferred / out of scope, or represented as a non-blocking user-owned Open Question with a safe default.
- Preserve the source's own dimensions, such as named variants, files, examples, sections, or checklist groups. Do not collapse them unless the user asks for a summary rather than an executable brief.
- Use searches only for literal terms that come from the user's source document or the target files being reviewed. Do not invent generic banned-pattern searches unless the user, repository rules, or source document defines those patterns.
- The saved brief does not need to expose an internal ledger, but Stage 5.6 must be able to trace each source item to a concrete bullet or checklist item.
If the source document is long, keep a private coverage ledger during review. The ledger does not need to be saved, but every source item must end as one of: in scope, out of scope / deferred, execution stage, acceptance criterion, side-effect checkpoint, related file, constraint, or structured non-blocking open question.
Do not:
- Read entire large files when symbolic / targeted-range reads suffice.
- Chase tangential code just to pad the brief.
If it does not tighten
Current State (As-Is)orRelated Files / Entry Points, skip it. - Make architectural claims the code does not support.
If uncertain, label it
[inferred]and route confirmation into an investigation stage orReplan whenboundary.
Already-satisfied gate. Before Stage 4, compare the full requested outcome and acceptance boundary against current code plus current verification signals.
- If all requested outcomes are confirmed, all acceptance checks already hold, and no edit, integration, migration, or evidence-producing work remains, create no plan.
Report
no-work-neededin the user's language with the inspected paths, verification action, and observed signal, then stop. - If the user explicitly asked for a saved verification record despite the already-satisfied state, create a verification-only plan that expects no edits and records the no-change evidence route. Its first stage must also say what happens if the proof fails: stop dependent work, return to the owning plan, activate bounded correction plus re-verification work, then re-run the briefset topology and handoffs before continuing.
- If only part of the outcome is already satisfied, keep the remaining work and make the no-change branch explicit instead of directing an unconditional edit.
- In briefset mode, re-run topology after this gate: zero active children means
no-work-needed, one means single-plan mode, and two or more retain briefset mode. Followreferences/briefset.mdfor the child and handoff rules.
This outcome is called no-work-needed.
Stage 4 — User Decision Table
After Stage 3 has gathered enough codebase context, run an ownership pass and collect only remaining user-owned decisions into a Markdown decision table. Stage 4 is not a pre-review guessing interview: ask only after the codebase has been checked enough to state the uncertainty, the recommended change, and the evidence behind it.
Use this exact table shape for user-decision questions:
| 순번 | 내용 | 수정 추천안 | 근거 |
|---|---|---|---|
| 1 | <decision the user must make> | <recommended change to apply to the brief> | <codebase/input evidence and risk> |
Keep these four headers exactly as written, even when the surrounding conversation is not Korean. They are the stable decision-table contract: number, decision content, recommended change, and rationale.
Intent before enumeration. Preserve each requirement's meaning, not an unresolved interpretation of its words.
If input and bounded review leave multiple plausible goals, behaviors, scope boundaries, or completion criteria, ask the user before treating one interpretation as the task.
Use the existing decision table to show the ambiguity, concrete alternatives, recommended interpretation, and supporting evidence.
Distinguish a missing condition needed for the stated goal from an optional enhancement; label recommendations as proposals, not existing requirements.
Offer only task-relevant additions. An unanswered optional enhancement stays excluded; do not enlarge the plan to make it look more complete.
Ask first and allow an opportunity to answer. If no answer arrives and a safe fallback exists, save it with its reconfirmation milestone in Open Questions; never label it approved.
If no safe fallback exists, halt without saving. A task cancellation stops authoring; it is not permission to use fallbacks and continue.
User-owned gaps to close before drafting:
- Desired Outcome (To-Be) — confirm when absent, ambiguous, or when the codebase review suggests more than one plausible interpretation.
- Out of Scope — the most valuable guardrail for the downstream agent. Put unclear or high-risk scope boundaries in the decision table with a recommended exclusion/inclusion.
- Acceptance Criteria — what makes the task verifiably done. If the code has a separate internal completion condition and the user has a separate success condition, carry both instead of collapsing them into one vague criterion.
- Compatibility and ownership — ask before breaking a contract or crossing an externally owned boundary.
- Open Questions — keep only non-blocking user-owned decisions with a safe fallback and reconfirm milestone.
The author determines output mode, work type, entry points, side-effect checks, and technical sequencing when the input and codebase make them evident.
Technical unknowns become investigation stages, bounded Worker decision fields, Replan when conditions, constraints, or author-selected defaults. Ask the user for relevant observations or access details only when they hold information unavailable from the reviewed artifacts; do not ask them to perform the technical investigation.
Decision-table rule. Each row must request a real decision or a specific unavailable user-held observation, not a vague status note.
내용 states what the user must decide.
수정 추천안 states the concrete brief change you recommend.
근거 cites the input, codebase finding, existing pattern, or risk.
After the user answers, patch the draft plan in memory before composing the brief.
An unanswered or skipped question is not approval: non-blocking rows use their declared safe fallback, remain in structured Open Questions form, and proceed; any blocking row halts without writing.
Full decision classification, table rules, and termination rules live in references/stage-4-interview.md.
Before writing Open Questions:
- Make one active judgement pass. Ask: would a downstream coding agent still need to ask the requester what to do, or can the brief make a reasonable call?
- Do not use
Open Questionsto avoid making an implementation recommendation. If the answer is a reasonable bounded choice, put it intoWorker decision,Constraints, or the relevant execution stage. - Keep
Open Questionsfor user-owned decisions only. Product direction, scope expansion, compatibility breaks, acceptance thresholds, and external ownership can require a question. - Save a question only when it is non-blocking and use exactly
- [non-blocking] <question> — Default: <safe fallback>; Reconfirm before: <stage or milestone>. - If the user has not answered a blocking decision and no safe fallback exists, HALT and create no file.
Open Questions: Noneis acceptable only after this pass. It means "a downstream agent can proceed without re-interviewing the requester," not "nothing interesting was found."
Stage 5 — Save + Validate
Once Stage 4 closes, compose the final Markdown internally and write it straight to disk — do not paste the full brief into chat first. The user reviews the file in their editor in Stage 6, where real markdown rendering and diff tooling are available.
-
Compute the filename per the Output Contract above.
-
Ensure
docs/briefs/exists; create it if not. -
Resolve filename collisions by appending
-v2,-v3, …. -
Render the complete template from
references/template.mdand write the file (English section headers, English body). -
Run the structural validator — a fast smoke test for the template contract:
python3 <skill-dir>/scripts/validate_brief.py docs/briefs/<filename>.mdIf the brief is stored in an isolated artifact tree while its entry-point paths belong to another checkout, add
--repo-root <repository-root>before the brief path.<skill-dir>is the installed skill package directory — the directory containing this SKILL.md (resolve it from wherever this skill was loaded, e.g.~/.claude/skills/task-brief-creatoror a plugin cache). Never assume the user's repository contains the script: the brief lives in the user's repo, the validator lives with the skill.- Exit 0 → continue to Stage 5.6; the validator result is reported in the Stage 6 banner.
- Exit 1 (structural failure) → fix the file and rerun the validator without asking the user. If the same structural cause still fails after two repair attempts, leave the file in place and carry the residual failure into Stage 6.
- Exit 2 (file I/O error) → inspect the actual error: invalid arguments, invalid
--repo-root, missing artifact, or unreadable file. Correct the cause; do not infer that a saved file disappeared or recreate it unnecessarily.
The validator only checks structural conformity (section presence, checklist format, filename pattern, type coherence). It does not judge content quality — that's what the Stage 5.6 self-check, the opt-in Stage 5.7 cold-pickup, and the human review in Stage 6 are for. Passing validator ≠ good brief; failing validator = malformed brief.
Validation Budget
A validation run covers the single plan or the entire parent-and-children set. It consists of the structural validator followed by the Stage 5.6 self-check; nothing in the default run spawns a sub-agent. Structural repairs: at most two attempts for the same structural cause, then carry the residual failure into Stage 6. Self-check: at most two passes per run; every content edit re-runs the structural validator before the next pass. When the budget is exhausted, keep the latest well-formed file, stop automatic repairs, and report the remaining gaps as incomplete, never as passed. A new user answer or requested edit starts a new validation run. The opt-in Stage 5.7 cold-pickup runs once per explicit user request after a completed run; the patches it causes re-enter this budget from the structural validator. Before applying cold-pickup patches, copy the affected files to a scratch directory outside the repository so a patch that breaks a previously passing check can be restored; delete the copies after the final state has been reported.
Stage 5.6 — Content and Intent Self-Check
The structural validator confirms the file has the required sections. It does not confirm the file is a complete work instruction, nor that it says what the user meant. Before handing off in Stage 6, re-read the saved brief from disk and run this self-check against the original input plus Stage 3 / Stage 4 findings. This is the only verification pass in the default run; an independent read by a fresh sub-agent is available on request through Stage 5.7.
The brief is a work instruction, not a summary. Any concern that existed in the input must survive into the brief — possibly reshaped into the right section, never silently dropped. Run this checklist:
-
Reader-centred writing: apply the reader check in
references/plain-language.mdto the saved artifact. The required information is easy to locate, the action and conditions are clear, and the next step is usable; authoring tools and workflow narration do not appear in the plan. -
Intent fidelity: read the saved file as a stranger would and compare it with the original input and the answered Stage 4 decisions. The work purpose is the same; the scope is neither materially wider nor narrower; the first stage and entry points point where the input points; every user constraint, exclusion, and acceptance threshold survives; the brief assumes no work the input did not intend. A user-locked Stage 4 decision counts as intent even when it differs from the raw input.
-
Input coverage: every distinct concern named in the input, including referenced spec section headings that change the coding route, maps to at least one bullet or stage somewhere in the brief (In Scope, Out of Scope, Related Files, Execution Plan, Constraints, Side Effect Checkpoints, Acceptance Criteria, or structured non-blocking Open Questions, depending on the concern's shape). If a spec section is intentionally not implemented now, it appears in
Out of Scopeas[hard]or[deferred], or inOpen Questionsonly when a non-blocking user decision has a safe default. Two unrelated implementation or verification obligations are never merged into one bullet. -
Source-of-truth coverage: if the user supplied a checklist, TODO file, review rubric, audit notes, or other source-of-truth document, every listed item is represented in the saved brief, explicitly deferred / out of scope, or saved as a structured non-blocking user question. Representative theme coverage is not enough.
-
Scope triage: every discovered concern is either must-fix in this brief, a tightly coupled check, explicitly deferred / out of scope, or left for a user decision. The brief does not turn a broad review into an unbounded implementation task.
-
Stage 3 coverage: every primary entry point or major affected area surfaced during the codebase review appears in
Related Files / Entry Points, and every technical uncertainty is resolved or routed into an investigation stage,Worker decision, orReplan whenboundary. -
Contract preservation: existing contracts discovered in Stage 3 that must not change are named in
Constraints,Side Effect Checkpoints, orAcceptance Criteria; compatibility-sensitive changes are not hidden behind generic wording. -
Success split: when internal completion and user / operator success are different, both are represented; the brief does not treat an event firing, validator passing, or state transition as proof that the user's goal was achieved unless that is actually the goal.
-
Section depth: no section was reduced to a single bullet when the input or Stage 3 findings contain multiple distinct concerns for it. Sections expand to fit the work; they are not capped.
-
No content compression: no bullet was shortened by dropping qualifiers, quantities, units, thresholds, versions, environment conditions, or ordering words (
only on cold start,≤ 5KB gzipped,iOS Safari 17+,after move end). "Executable, not discursive" is a prose rule, not a content rule. -
Evidence clarity: every load-bearing current-state bullet uses
[confirmed]or[inferred]; confirmed facts cite stable evidence, inferred risks name what will confirm them, and line numbers are not the only locator. -
Execution continuity: Stage 1 has a concrete precondition; stage numbers are consecutive; every stage has a bounded outcome, deliverable, local completion checks, explicit handoff, and replan boundary; each handoff gives the next stage what its
Starts whenrequires. -
Already-satisfied discipline: the plan does not force an edit when current evidence already satisfies the requested outcome; full satisfaction exited as
no-work-neededunless the user explicitly requested a verification record, partial satisfaction has a bounded no-change route, and a failed proof stops dependents and names the correction/re-verification owner. -
Verification concreteness: every named verification action comes from repository evidence or is a bounded inspection, identifies its exact input/target, and states an observable expected signal. When success means no matches, the plan also identifies the population being checked so an empty or wrong input cannot pass accidentally.
-
Completion separation: stage-local completion appears only under
Ends when; whole-workAcceptance Criteriaare evaluated after all required stages and side-effect checkpoints finish. -
Handoff readiness: a downstream coding agent reading only the brief can recover the first stage, order, deliverables, handoffs, replan conditions, and whole-work completion judgement without re-interviewing the requester. If a re-interview would be needed, identify the thin section and patch it.
-
Question discipline: every
Open Questionsitem is genuinely user-owned. Every saved question is non-blocking and names a safe default plus reconfirm milestone; move technical and reversible choices into investigation,Worker decision,Replan when, constraints, or deferred scope. IfOpen QuestionssaysNone, the brief has made the necessary calls instead of hiding them.
If any check fails, fix the brief in place with Edit, re-run the structural validator (validate_brief.py for a single brief, validate_briefset.py for a briefset parent), then run this self-check again.
At most two self-check passes per validation run; if a gap remains after the second pass or has no justified patch, stop and report the latest file as incomplete, not passed.
The self-check outcome is a separate signal from the structural validator — both are reported in Stage 6. A brief can pass structural validation and still fail this self-check; in that case the file is incomplete even though it is well-formed.
For briefset mode, run the self-check on the parent and on every child independently. The parent's coverage check asks whether every input-implied execution context maps to a child; each child's coverage check uses all items above.
Stage 5.7 — Cold-Pickup Verification (opt-in)
The Stage 5.6 self-check is self-evaluated: the author cannot forget its own intent, so it cannot fully simulate a stranger reading the file cold. Stage 5.7 supplies that stranger — a fresh read-only sub-agent that first reconstructs the plan from the saved brief alone, then compares it with the original input and reports intent deviations, ask-backs, and missing concerns.
Stage 5.7 never runs by default. It has no signal gates and no automatic triggers; briefset mode, Stage 4 decision rows, non-empty Open Questions, and work type do not start it.
It runs only when the user explicitly asks — for example run cold-pickup, --cold-pickup, 콜드픽업 실행 — either together with the initial input or later in Stage 6 against the current on-disk file.
Do not spawn a sub-agent for verification without such a request. Report Stage 5.7 only when requested; omit unsolicited optional-check invitations from Stage 6.
When requested, read references/cold-pickup.md and follow it. In short:
- Complete the current validation run first (structural validator and Stage 5.6 pass or report residuals); cold-pickup does not replace either.
- Spawn one fresh read-only sub-agent per artifact — one for a single brief; in briefset mode one for the parent plus one per child the user did not exclude — with no inherited conversation and no Stage 3 register, Stage 4 decisions, self-check results, or hints about suspected gaps.
- Give it the brief path (plus the parent path for a child) and the path of a scratch file holding the original input verbatim; it reads those files only and never explores the repository.
- Collect the YAML report, route each finding through the reference's routing tables (disagreement vs drift against answered Stage 4 rows), patch drift in place, re-run the structural validator, then Stage 5.6.
- Report the outcome in the Stage 6 banner. One pass per request: do not re-run cold-pickup automatically after patching; the user asks again if they want another independent read.
Cold-pickup never overrides a Stage 4 decision the user already locked, never invents Acceptance Criteria, Side Effect Checkpoints, or Out-of-Scope guardrails the input did not imply, and never silently rewrites Open Questions — drift fixes either resolve a question into another section or leave the question intact for the user.
If a fresh read-only sub-agent cannot be spawned or returns an unusable report, report cold-pickup unavailable (<actual reason>); the Stage 5.6 result stands on its own and is never relabeled as an independent read.
Stage 6 — Review + Iterate
The brief is on disk. Hand off to the user for review.
-
Report the path and one-line summary, then distinguish structural validation from content validation. Structural validation is the Stage 5 validator result. Content validation is the Stage 5.6 content and intent self-check, and the actual Stage 5.7 result only when the user requested it. Do not imply that the self-check is an independent reader evaluation. Report unavailable, incomplete, restored, and exhausted outcomes explicitly; a missing required result is never a pass. Every reported check must belong to the final saved artifact state. Use the user's chat language.
English (validator + self-check passed, cold-pickup not requested):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; structural validation passed; content validation passed — content and intent self-check passed). Open it and let me know if anything needs editing.Korean (validator + self-check passed, cold-pickup not requested):
저장 완료 —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; 구조 검증 통과; 내용 검증 통과 — 내용/의도 자체 검증 통과). 파일 열어보고 고칠 부분 있으면 알려줘.English (user requested cold-pickup, clean):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; structural validation passed; content validation passed — content and intent self-check passed; cold-pickup: clean (no intent deviations, no ask-backs, no missing concerns)). Open it and let me know if anything needs editing.English (user requested cold-pickup, findings):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md(feat: Dark mode toggle in Settings; structural validation passed; content validation passed — content and intent self-check passed after 1 patch; cold-pickup flagged 3 item(s): 2 patched in place, 1 left as a user decision).- d1 (
scope_narrower): the input asks for the toggle on mobile too; added the mobile settings route to In Scope and Stage 2. - m1 (
infer_and_patch): the input's "remember the last choice" requirement was missing; added to Acceptance Criteria. - a1 (
user_input_ambiguity, affects direction): "system default" could mean the OS theme or the app default — see the decision table below.
English (validator still fails after two repair attempts):
Saved —
docs/briefs/2026-04-23-feat-dark-mode-settings.md, but structural validation still flags 2 issue(s) after two repair attempts: ✗ ✗ . The file is on disk; content validation did not run.Mirror any banner into the user's chat language as the Korean example above shows — translate the prose, keep paths, filenames, and technical fields (finding ids,
kindvalues, classifications, validator messages) verbatim. Briefset banners use the collapsed formats inreferences/cold-pickup.mdandreferences/briefset.md.When structural validation still fails after the repair budget, Stage 5.6 is skipped and Stage 5.7 is not offered — the plan is not yet well-formed enough to check content against. The banner stays as shown; do not append
self-check skipped/cold-pickup not runlines in this case.If the Stage 5.6 self-check surfaced gaps fixed within the budget, say what you patched (e.g., "self-check found 2 input concerns missing from In Scope; added them, re-validated"). If Stage 5.7 patched the brief, list each patched and residual finding as bullets under the banner, as shown above. If the user requested cold-pickup and it could not run, report
cold-pickup unavailable (<actual reason>)instead of a result. - d1 (
-
If the user requests changes, apply them with
Editagainst the on-disk file. Do not re-render the full brief into chat — that defeats the point of save-then-review. Re-run the structural validator after each edit pass, then Stage 5.6, and report the delta. Re-run Stage 5.7 only if the user asks for it again. -
If the saved single plan contains structured non-blocking
Open Questions(after any Stage 5.7 patches have landed), present them immediately after the save report using the same four-column decision table from Stage 4:| 순번 | 내용 | 수정 추천안 | 근거 | |---|---|---|---| | 1 | <non-blocking user decision> | <recommended patch to apply to the plan> | <safe default and reconfirm milestone> |After the user answers, patch the saved plan in place, move resolved decisions into the appropriate sections, leave only structured non-blocking user questions in
Open Questions, then re-run the validator and Stage 5.6. If the user leaves a question unanswered, skips that question, or lets structured input expire, leave the declared defaults active and the questions unchanged; they do not block the coding agent before their named reconfirmation milestones. -
The user owns "done." A task cancellation stops further edits and verification. Do not stage or commit the file. Loop on Stage 6 until they explicitly stop.
Why save-then-review: an earlier iteration rendered the full brief in chat for approval before writing to disk.
In hands-on use that flooded the conversation with markdown that renders poorly inside a code fence and was awkward to edit conversationally.
Writing to disk first lets the user review in their editor (real markdown, real diff tools, real inline edits) and lets the validator surface structural issues immediately.
The tradeoff — a file briefly on disk before approval — is neutral: docs/briefs/ is the intended home for these files, and the commit step stays with the user.
Template
See references/template.md for:
- The exact nine-required-section Markdown template.
- Per-section writing guidance (what good looks like, what not to write).
- Worked example of a filled brief.
The emitted brief is in English. Chat interaction language follows the user's input.
Work Types
See references/work-types.md for:
- The ten Conventional Commits types.
- Per-type agent behavior hints (why the type matters — it changes how the downstream coding agent approaches the work).
- Classification tips for ambiguous cases.
Examples
See examples/ for worked end-to-end scenarios (input → codebase review → interview → output).
Start with examples/README.md for the index.
Structural Validator
scripts/validate_brief.py is a stand-alone Python 3 script (no external deps) that verifies structural conformity of a saved brief.
It runs as step 5 of Stage 5 (save + validate) but can also be run ad-hoc against any existing brief.
Always resolve the script path against <skill-dir> — the installed skill package directory containing this SKILL.md — never against the user's repository:
python3 <skill-dir>/scripts/validate_brief.py \
docs/briefs/2026-04-23-feat-global-hotkey-system.md
Exit codes: 0 pass with no warnings, 1 structural failure or any reported warning, 2 argument, repository-root, or file I/O error.
Scope of the validator (deliberately structural only):
- Filename pattern, exactly one H1 title outside fenced code, title format, type coherence across filename / title / section value, and slug length.
- Presence and template order of all nine required H2 sections + exactly one
In ScopethenOut of ScopeH3; duplicate H2 sections are rejected. Fenced examples do not establish sections or checklist items. [confirmed]/[inferred]prefixes inCurrent State (As-Is), unique consecutive execution-stage headings with required fields, and structured non-blockingOpen Questionsshape.- Type-conditional section (
Reproduction/Baseline Measurement/Behavior Contract) present and populated for the matching type;- N/A — <reason>cannot be mixed with other bullets. - Top-level bullet content in narrative sections; top-level
- [ ]items in checklist sections; populatedOpen Questionswith- None — <reason>when no questions remain. Related Files / Entry Pointsvalidates file tokens before the first prose-separating em dash outside inline code. At least one existing file/directory or adjacent(proposed)path is required. Root files, including dotfiles, resolve on disk. URLs and- Route: `/path` — <purpose>entries are supplementary and do not satisfy the file-entry requirement. Descriptive inline code after the separator is not checked as a file.- Optional
--repo-rootlets isolated brief artifacts validate their entry points against the actual target checkout. - Optional
Constraintsheading shape. - Every top-level
Out of Scopeexclusion needs[hard]or[deferred]; a sole- None — <reason>means no exclusions. Missing labels fail. Other warnings also make validation fail; semantic correctness remains a content-review responsibility.
Out of scope (still on content review): whether evidence labels are truthful, stage outcomes and handoffs are executable, Out-of-Scope entries are real guardrails vs. filler, entry points are good, Acceptance Criteria are measurable, and the type-conditional section's content is sufficient.
For briefset mode, use scripts/validate_briefset.py on the parent file — it validates the parent structure and re-runs validate_brief.py's checks transitively on every referenced child brief, so one invocation covers the whole set:
python3 <skill-dir>/scripts/validate_briefset.py \
docs/briefs/2026-04-30-briefset-checkout-i18n.md
Same exit codes.
See references/briefset.md for what the parent validator checks and what stays on the human reviewer.
Guardrails
- Executable, not discursive. Apply the intro's prose-style rule to every section — rewrite discussion-summary, negotiation-log, or rationale prose until it directs concrete action; retain only the brief rationale the reader needs to execute safely; author deliberations do not belong in the brief.
- Never fabricate file paths or PR numbers.
Related Files / Entry Pointsis mandatory because it is the downstream agent's starting route. If the codebase review does not surface at least one concrete file, directory, route, command, module, related brief, or confirmed proposed path, ask the user to provide or confirm the entry point before saving the brief. At least one top-level entry must carry that path in inline code; a plain-text path, PR-only bullet, or symbol-only bullet is not structurally checkable. - Ground Acceptance Criteria in input or code evidence. Vague criteria poison the coding agent. Ask only for product or acceptance thresholds the user owns; derive technical proof paths from the repository.
- Never proceed past the Ambiguity Gate on a hunch. Halting is the correct answer when anchors are missing.
- Keep Out-of-Scope specific. "Don't refactor unrelated code" is filler.
"Do not change the
PaymentServiceinterface" is a real guardrail. - Triage scope before saving. A good review often finds more problems than one plan should fix.
Put the user's required outcome first, keep tightly coupled checks second, and move unrelated valid findings to
[deferred]; technical unknowns go to investigation or replan boundaries. - Keep implementation judgment out of Out-of-Scope.
Out of Scopetells the downstream coding agent what not to do. Put bounded implementation choices inConstraints, and user-owned unresolved choices inOpen Questions. - Preserve named contracts. When a change touches existing callers, persisted state, user-visible ids, event flows, schemas, file formats, or generated outputs, name the exact contracts that must remain compatible. Do not rely on "avoid regressions" or "keep compatibility" as a substitute.
- One plan per invocation, unless the input has multiple execution contexts. When it does, select briefset mode from the documented signals and explain the evidence (see
references/briefset.md). Ask only when topology depends on a user-owned delivery or scope boundary. Briefset mode is the supported way to handle multi-context work — do not stuff unrelated execution contexts into one plan, and do not nest briefsets (a child cannot become a parent). When contexts have unrelated outcomes and no shared acceptance boundary, recommend separate single-plan invocations (see Stage 1). Within a briefset, use parallel waves by default and add ordering only for actual preconditions, verified conflicts, or user-required delivery order. - Decision table does not bypass the ambiguity gate. Halt-eligible inputs still halt at Stage 1.
Do not try to reconstruct missing PROBLEM / GOAL / SCOPE / TARGET through a large decision table — the gate exists precisely to prevent that failure mode.
See
references/stage-4-interview.mdfor the table rules and termination conditions.
Pre-Save Checklist
Self-check before invoking Write in Stage 5.
The structural validator catches format errors after the fact; this list catches content gaps it cannot see.
- Filename matches
YYYY-MM-DD-<type>-<slug>.md. -
<type>is one of the ten Conventional Commits types. - Title on line 1 matches
# [<type>] <title>. -
Current State (As-Is)andDesired Outcome (To-Be)are both populated and distinguishable. - Every load-bearing current-state bullet starts with
[confirmed]or[inferred]; confirmed facts cite stable evidence and inferred findings name what will confirm them. - Existing contracts that must not change are named concretely: ids, keys, event names, API shapes, schemas, file formats, persisted values, commands, or generated outputs.
- If internal completion and user / operator success differ, both are represented in the brief and verification does not confuse one for the other.
- If type is
fix/perf/refactor, the type-conditional section (Reproduction/Baseline Measurement/Behavior Contract) is present and populated —- N/A — <reason>if genuinely none. -
Out of Scopehas at least one specific entry (or an explicit "None — self-contained." with rationale). Prefix every top-level exclusion with[hard]for must-not-touch guardrails or[deferred]for follow-up work; a sole- None — <reason>is the alternative. - Broad review findings have been triaged into must-fix / check-while-here / deferred; the brief does not ask the downstream agent to fix every valid concern discovered during review.
- If the brief asks the downstream agent to prove a validator or workflow bug, the verification path uses existing scripts or temporary scratch artifacts only when repository / user rules allow them.
-
Acceptance Criteriaare measurable (checkable, not aspirational). -
Related Files / Entry Pointsentries are existing repo paths, verified references, or confirmed proposed paths. Paths under inline-code that are not yet created carry the exact literal token(proposed)immediately after that path so the structural validator does not flag them as fabricated — variants like(proposed edit)are not recognized, and a marker elsewhere in the line does not skip path validation. At least one top-level entry contains a path-shaped inline-code token; plain-text paths do not count. Each entry routes the agent's first read or first edit, not just "related file" context. -
Execution Planhas consecutive### Stage N — <name>stages; every stage containsStarts when, boundedWork,Deliverable, indentedEnds whenchecks,Handoff, andReplan whenin order. - Each stage handoff supplies the next stage's start, and stage-local
Ends whenchecks are distinct from whole-workAcceptance Criteriaevaluated after all stages and side-effect checks. -
Open Questionscontains only structured non-blocking user decisions in- [non-blocking] <question> — Default: <safe fallback>; Reconfirm before: <stage or milestone>form, or- None — <reason>after one active judgement pass.
Post-Run Checklist (before the Stage 6 banner)
Evaluated after Stage 5.6 (and Stage 5.7 when the user requested it) has run, immediately before reporting the Stage 6 banner — these items cannot be checked before Write.
- Stage 5.6 ran against the file as saved on disk, within two passes; a gap left after the budget is reported as incomplete, never as passed.
- No verification sub-agent was spawned without an explicit user request for cold-pickup.
- When the user requested cold-pickup, Stage 5.7 ran once per artifact as the reference describes, or the banner names the documented
unavailablereason; when they did not, the banner reports the checks actually run without an optional-check line. - Stage 6 banner reflects what actually ran — no check is reported from an earlier artifact state.
- Any edit after Stage 5.6, Stage 5.7, or Stage 6 re-ran the structural validator and then Stage 5.6 before the banner was reported.
Typst Document Creation
Create the requested Typst source using the resolved compiler's language and export capabilities. This skill covers stable 0.13.0, 0.13.1, 0.14.0, 0.14.1, 0.14.2, 0.15.0, and 0.15.1. Sources were checked on 2026-09-09; this is a documented support range, not a promise about later releases.
Resolve the Target
Use the first applicable evidence: the user's requested version, a project toolchain/CI pin, then the active compiler's typst --version. Resolve a minor-only request to its supported latest patch: 0.13 → 0.13.1, 0.14 → 0.14.2, 0.15 → 0.15.1. If none is established, use 0.15.1 as an assumed target, not as a detected installation.
Record both the requested target and the executable actually available. If they differ, compilation with the available executable verifies only that version. For an unsupported release or prerelease, explain the boundary and establish a supported target or explicitly qualified best-effort work before claiming compatibility.
Establish the export target from the request or existing build. Default document creation to .typ source intended for PDF; preserve an existing export target. HTML and bundle export have experimental feature flags and distinct semantics.
Select Knowledge by Task and Version
- Open the compatibility index to locate relevant additions, removals, and migration boundaries.
- Read only the needed topic references from the table below.
- Apply the mode-specific version route:
- Exact version: Read the target minor's reference and any earlier reference the index points to for a needed feature. Earlier additions remain available unless a later change removes or alters them.
- Version range: Read all minor references crossed by the range. Use the common API subset for that range. If it cannot satisfy a requested capability, explain why and offer version-specific alternatives.
- Migration or review: Inspect the source and destination and every intervening minor boundary in either direction. Identify removed APIs, changed semantics, and necessary replacements.
- A reference's restrictions on newer APIs apply only when its own minor line is the final target. They are not global prohibitions when reading that reference for an inherited feature.
For example, a 0.15 document using title and frac.style needs their 0.14 details as well as the 0.15 migration constraints. Do not interpret a missing entry as evidence that an API is unsupported.
| Task | Read |
|---|---|
| Markup, modes, headings, lists, links and labels | Syntax |
| Set/show rules, text, fonts and multilingual typography | Styling |
| Values, functions, collections, imports and data | Scripting |
| Equations, symbols, delimiters and math fonts | Math |
| Pages, grids, tables, figures and positioning | Layout |
| Counters, state, location, queries and convergence | Context |
| Papers, outlines, citations, footnotes and long documents | Documents |
| Compiler, roots, packages, inputs, exports and diagnostics | Tooling |
| Slide pages, reusable layouts and presentation packages | Presentations |
When Local Knowledge Is Insufficient
Check the target release's official changelog and source tag, and the relevant official API documentation. Current API pages describe the current release, so establish introduction/removal boundaries before applying them to older targets. Record material uncertainty if the target's behavior cannot be confirmed. Topic references are curated starting points, not exhaustive API specifications.
Use the image source as a positional argument, distinguish drawing curve from 0.15 file path, and prefer tiling and top-level byte-loading functions over deprecated names in new source.
Work Sequence
- Resolve the compiler, compatibility mode, and requested output.
- Read the relevant references and inspect the existing template, imports, fonts, assets, labels, bibliography and export settings.
- Write or revise source. Separate content from reusable formatting; preserve the existing document's meaningful structure and selected resources unless the requested change affects them.
- Compile with the exact target when available and inspect diagnostics, including warnings. If unavailable, deliver source with explicit verification limits rather than inventing a successful run.
- For document layout work, render and inspect the output for clipping, overlaps, table continuation, numbering, references and glyph coverage. For syntax-only questions, use a small compilation check when helpful without creating a full document workflow.
- Return the source/edits and the compatibility handoff below. Provide rendered files when the task calls for them.
Successful compilation does not establish identical rendering between releases or conformance to an accessibility standard. Check the properties the user requested in the final output.
Compatibility Handoff
Include each of the following, briefly, outside the document body unless the user wants this information in the document:
- The exact target or range, whether it was requested, pinned, detected or assumed, and the executable actually used.
- The common/topic references and minor-version references actually consulted, using their relative filenames. This makes feature provenance reviewable, including features inherited from an earlier minor release.
- Material replacements, fallbacks or export limitations; the actual compile command and result; warnings and unperformed checks.
- For range work, list the releases compiled and separately state whether rendered output was compared. Explicitly distinguish successful compilation across releases from a guarantee of identical rendering.
Bundled Verification
The validator uses Python 3.9+ and supplied Typst executables; it does not install compilers. It compiles common fixtures on each selected release and earlier feature fixtures on later releases. This is a compilation check, not a semantic or visual judge.
From the skill directory:
python3 scripts/validate_version_support.py --compiler 0.15.1=/path/to/typst
python3 scripts/validate_version_support.py --typst-0.14 /path/to/typst-0.14.2
Repeat --compiler VERSION=PATH for the seven exact releases and add --require-all for full coverage. Legacy minor flags retain their latest-patch meaning. Exit codes: 0 for success, 1 for verification failure, 2 for invalid arguments. Warnings and unchecked releases remain visible; a partial run is not a full-range result. Version queries time out after 10 seconds and individual compilations after 60 seconds.
See fixture instructions for assets, expected output, HTML/bundle checks and visual checks; evaluation prompts exercise the skill's behavior beyond compilation.
Official Entry Points
Vite Guide
Establish the exact installed/target Vite, Node, and plugin versions and whether the path is client rendering, backend integration, or SSR. Check the target package's engines.node and plugin peer contracts from installed metadata or its tagged official source. Vite 7.0.0 and 8.0.0 declare ^20.19.0 || >=22.12.0: Node 21 does not satisfy this range. Do not replace that contract with "any later major" or infer it from the guide's major range.
When facts are missing, continue investigation and common guidance; defer only dependent API/configuration choices and unsupported execution. Existing failures are diagnosis and repair targets. Reconstruct migration evidence from current source if no prior report exists. Check official release support separately when maintenance status matters: this guide's diagnostic coverage of Vite 7/8 does not promise upstream maintenance or feature backports. Verify minor-specific and experimental features before using them.
Route
Start with the closest reference, then read related references directly as needed. Collect only the evidence relevant to the requested explanation, implementation, or review.
- Entry, dev server, proxy, env, assets, diagnostics: client runtime
- Imports, chunks, Rollup/Rolldown, plugins, performance: build and plugins
- Base path, caching, stale chunks, reload: deployment
- SSR middleware, module loading, separate builds, manifests, dependencies: SSR integration
- Vite 6 departure: Vite 6 to 7 migration
- Vite 7 departure and Vite 8 arrival: Vite 7 to 8 migration
Boundary
Vite owns module loading, build artifacts, plugin integration, and deployment configuration. UI-framework guidance owns rendering, hydration, component state, and recovery semantics. Use both guides for a task spanning these layers; React applications can pair this guide with react-guide. Gather missing framework evidence directly without requiring a formal handoff or caller identity. Respect actual task ownership restrictions.
Support Vite SSR inside an existing host. Framework-specific APIs, RSC/Server Functions implementation, and construction of a custom server runtime remain outside this guide. Preserve existing ssrLoadModule integrations; Environment API adoption is a separate decision based on the project's integration and the target version's stability contract.
Adapt the response to the request: decisions and evidence, changes or findings, performed verification, and unresolved risks. Claim performance gains only from comparable before/after measurements. Never report blocked, failed, or unrun verification as passed.
Runtime examples: Vite 7.0.0 package, Vite 8.0.0 package.
Sponsors
Details
- Marketplace
- buYoung/skills
- Category
- Community