@cubis/foundry 0.3.71 → 0.3.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.71",
+  "version": "0.3.73",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {

package/src/cli/core.ts

@@ -987,15 +987,8 @@ function buildEngineeringRulesTemplate() {
     "",
     "- For planning/review/execution summaries, use a `Decision Log` structure.",
     "- Each decision entry must include: `Context`, `Decision`, `Rationale`, `Tradeoffs`, `Validation`.",
-    "- Include `Files Used` with labeled keys and full absolute paths (not shorthand names).",
-    "- Include `Skills Used` with skill IDs and full skill file paths when skills are loaded.",
-    "- Minimum required entries in `Files Used` for project work:",
-    "  - `active_rules_file`: active platform rules file path (for example `AGENTS.md`, `.agent/rules/GEMINI.md`, or `.github/copilot-instructions.md`)",
-    "  - `engineering_rules_file`: `/abs/path/ENGINEERING_RULES.md`",
-    "  - `tech_map_file`: `/abs/path/TECH.md`",
+    "- Include `Skills Used` listing the skill, workflow, or agent names that were loaded.",
     "- If no skill is loaded, write `Skills Used: none` explicitly.",
-    "- Never hide key file paths behind aliases or abbreviated labels.",
-    "- A Decision Log without required `Files Used` and `Skills Used` is incomplete and must be corrected before final response.",
     "",
     "Required shape:",
     "",
@@ -1006,14 +999,8 @@ function buildEngineeringRulesTemplate() {
     "Tradeoffs: ...",
     "Validation: ...",
     "",
-    "Files Used",
-    "- active_rules_file: /abs/path/<platform-rule-file>",
-    "- engineering_rules_file: /abs/path/ENGINEERING_RULES.md",
-    "- tech_map_file: /abs/path/TECH.md",
-    "- implementation_file: /abs/path/other/file.ts (as needed)",
-    "",
     "Skills Used",
-    "- skill-id: /abs/path/<platform-skills-root>/<skill-id>/SKILL.md",
+    "- skill-name, workflow-name, or agent-name",
     "- or: none",
     "",
     "## 9) Keep TECH.md Fresh",
@@ -1051,9 +1038,8 @@ function buildEngineeringRulesManagedBlock({
     "4. Use clear naming with focused responsibilities and explicit boundaries.",
     "5. Require validation evidence (lint/types/tests) before merge.",
     "6. Use Decision Log response style.",
-    "7. Every Decision Log must include both `Files Used` and `Skills Used` sections.",
-    "8. `Files Used` must include labeled keys (`active_rules_file`, `engineering_rules_file`, `tech_map_file`) with full absolute paths.",
-    "9. If no skill loaded, `Skills Used: none` is mandatory.",
+    "7. Every Decision Log must include a `Skills Used` section listing skill, workflow, or agent names.",
+    "8. If no skill loaded, `Skills Used: none` is mandatory.",
     "",
     "<!-- cbx:engineering:auto:end -->",
   ].join("\n");
@@ -3801,15 +3787,20 @@ function buildManagedWorkflowBlock(platformId, workflows) {
   lines.push("<!-- cbx:managed:skill-routing start -->");
   lines.push("Classify intent before any MCP call.");
   lines.push(
-    "- TIER 1 DIRECT: `skill_get <exact-skill-id>` when domain and skill are obvious.",
+    "- TIER 1 DIRECT: `skill_get <exact-skill-id>` when skill ID is known from route or context.",
+  );
+  lines.push(
+    "- TIER 1b ROUTE-RECOMMENDED: after `route_resolve`, load `primarySkillHint` or first `primarySkills` entry via `skill_validate` -> `skill_get` before executing non-trivial tasks.",
+  );
+  lines.push(
+    "- TIER 2 TARGETED SEARCH: one `skill_search <1-3 word noun>` max when domain is unclear, then `skill_validate` -> `skill_get`.",
   );
   lines.push(
-    "- TIER 2 TARGETED SEARCH: one `skill_search <1-3 word noun>` max, then `skill_validate` -> `skill_get`.",
+    "- TIER 3 SKIP: no MCP call for conversational replies, trivial one-liners, or identical skill already loaded this session.",
   );
   lines.push(
-    "- TIER 3 SKIP: no MCP call for conversational, same-session, or native-tool-sufficient work.",
+    "- Never pre-load skills or agents speculatively before route resolution.",
   );
-  lines.push("- Never pre-load skills or agents speculatively.");
   lines.push("- Keep one primary agent and one primary skill by default.");
   lines.push(
     "- Add supporting skills only when the active task explicitly crosses domains.",

package/workflows/powers/accessibility/POWER.md

@@ -1,105 +1,94 @@
 ````markdown
 ---
 inclusion: manual
-name: "accessibility"
-displayName: "Accessibility Expert"
-description: "Ensure Flutter apps meet WCAG 2.1 AA standards with proper semantics, focus management, and screen reader support"
-keywords:
-  [
-    "accessibility",
-    "a11y",
-    "wcag",
-    "semantics",
-    "screen reader",
-    "focus",
-    "contrast",
-    "flutter accessibility",
-  ]
+name: accessibility
+description: "Use when auditing, implementing, or reviewing web accessibility (WCAG, ARIA, keyboard navigation, screen reader support, and inclusive interaction patterns)."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-# Accessibility Expert
+# Accessibility
 
-## Overview
+## Purpose
 
-This power helps you build accessible Flutter widgets that work well with screen readers (TalkBack/VoiceOver), keyboard navigation, and meet WCAG 2.1 AA standards.
+Use when auditing, implementing, or reviewing web accessibility (WCAG, ARIA, keyboard navigation, screen reader support, and inclusive interaction patterns).
 
 ## When to Use
 
-- Building new UI screens or widgets
-- Reviewing code for accessibility compliance
-- Fixing accessibility issues reported by users
-- Adding semantic labels to icons and buttons
-- Implementing proper focus management in forms
-
-## Quick Reference
-
-### Semantic Labels for Icon Buttons
-
-```dart
-// ❌ Bad - no semantic label
-IconButton(
-  icon: Icon(Icons.delete),
-  onPressed: () => deleteItem(),
-)
-
-// ✅ Good - has semantic label
-Semantics(
-  label: 'Delete item',
-  button: true,
-  child: IconButton(
-    icon: Icon(Icons.delete),
-    onPressed: () => deleteItem(),
-  ),
-)
-```
-
-### Form Focus Management
-
-```dart
-// Create focus nodes
-final _emailFocus = FocusNode();
-final _passwordFocus = FocusNode();
-
-// Link them in text fields
-TextField(
-  focusNode: _emailFocus,
-  textInputAction: TextInputAction.next,
-  onSubmitted: (_) => _passwordFocus.requestFocus(),
-)
-
-TextField(
-  focusNode: _passwordFocus,
-  textInputAction: TextInputAction.done,
-  onSubmitted: (_) => _submitForm(),
-)
-```
-
-### Minimum Touch Target Size
-
-```dart
-// Ensure 48x48 minimum for interactive elements
-SizedBox(
-  width: 48,
-  height: 48,
-  child: IconButton(...),
-)
-```
-
-## Key Principles
-
-1. **Semantic Labels**: All icon buttons, images, and non-text elements need labels
-2. **Focus Order**: Tab order should follow visual/logical flow
-3. **Touch Targets**: Minimum 48x48 dp for all interactive elements
-4. **Color Contrast**: Text must have 4.5:1 contrast ratio (3:1 for large text)
-5. **Screen Reader**: Test with TalkBack (Android) and VoiceOver (iOS)
-
-## Steering Files
-
-Load detailed guidance:
-- `a11y_checklist.md` - Complete accessibility checklist for reviews
-
-## Templates
-
-- `focus_form` - Form with proper focus management
-- `semantics_icon_button` - Icon button with semantic labels
+- Auditing existing UI for WCAG 2.2 AA compliance.
+- Building new components that must be keyboard-navigable and screen-reader friendly.
+- Reviewing PR diffs for accessibility regressions.
+- Fixing focus management, ARIA labeling, or color contrast issues.
+- Choosing between native HTML semantics and ARIA attributes.
+
+## Instructions
+
+1. Identify the interaction pattern and which WCAG success criteria apply.
+2. Use semantic HTML first — only add ARIA when native semantics are insufficient.
+3. Verify keyboard flow: focus order, focus visibility, escape/close behavior.
+4. Check screen reader announcements for dynamic content and state changes.
+5. Validate contrast ratios and motion preferences before shipping.
+
+### Baseline standards
+
+- Use native HTML elements (`<button>`, `<nav>`, `<dialog>`, `<details>`) before custom ARIA widgets.
+- Every interactive element must be keyboard-reachable and operable.
+- Every image has `alt` text (or `alt=""` for decorative images).
+- Color alone is never the only way to convey information.
+- Focus indicators are visible in all themes (light, dark, high contrast).
+- Dynamic content changes are announced via live regions or focus management.
+- Forms have visible labels, error messages linked to inputs, and clear required-field indicators.
+
+### ARIA rules
+
+- First rule of ARIA: don't use ARIA if a native HTML element does the job.
+- Never change native semantics unless absolutely necessary (`<button>` is always better than `<div role="button">`).
+- All interactive ARIA elements must be keyboard-operable.
+- All ARIA references (`aria-labelledby`, `aria-describedby`, `aria-controls`) must point to existing element IDs.
+- Use `aria-live="polite"` for status updates, `aria-live="assertive"` only for critical errors.
+
+### Testing checklist
+
+- Tab through every interactive element — focus order must be logical.
+- Operate every control with keyboard only (Enter, Space, Escape, Arrow keys).
+- Run axe-core or Lighthouse accessibility audit — zero critical/serious violations.
+- Test with a screen reader (VoiceOver, NVDA, or JAWS) on at least one real flow.
+- Check `prefers-reduced-motion` — animations must respect this media query.
+- Verify contrast with a tool (minimum 4.5:1 for normal text, 3:1 for large text and UI).
+- Test with zoom at 200% — layout must not break or hide content.
+
+### Constraints
+
+- Avoid using `div` or `span` with click handlers instead of `<button>`.
+- Avoid suppressing focus outlines globally (`outline: none` without replacement).
+- Avoid using `aria-hidden="true"` on elements that contain interactive content.
+- Avoid auto-playing audio or video without user consent or a stop mechanism.
+- Avoid using only color to indicate errors, status, or selected state.
+- Avoid positive `tabindex` values — they create unpredictable focus order.
+- Avoid tooltip-only labels with no accessible name on the trigger element.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                 | Load when                                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `references/wcag-audit-checklist.md` | You need a structured WCAG 2.2 AA audit checklist for a full-page or full-app review.                      |
+| `references/aria-patterns-guide.md`  | The task involves custom widgets (modals, menus, tabs, trees, comboboxes) that need correct ARIA patterns. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with accessibility best practices in this project"
+- "Review my accessibility implementation for issues"
 ````

package/workflows/powers/accessibility/SKILL.md

@@ -1,103 +1,91 @@
 ---
-name: "accessibility"
-displayName: "Accessibility Expert"
-description: "Ensure Flutter apps meet WCAG 2.1 AA standards with proper semantics, focus management, and screen reader support"
-keywords:
-  [
-    "accessibility",
-    "a11y",
-    "wcag",
-    "semantics",
-    "screen reader",
-    "focus",
-    "contrast",
-    "flutter accessibility",
-  ]
+name: accessibility
+description: "Use when auditing, implementing, or reviewing web accessibility (WCAG, ARIA, keyboard navigation, screen reader support, and inclusive interaction patterns)."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-# Accessibility Expert
+# Accessibility
 
-## Overview
+## Purpose
 
-This power helps you build accessible Flutter widgets that work well with screen readers (TalkBack/VoiceOver), keyboard navigation, and meet WCAG 2.1 AA standards.
+Use when auditing, implementing, or reviewing web accessibility (WCAG, ARIA, keyboard navigation, screen reader support, and inclusive interaction patterns).
 
 ## When to Use
 
-- Building new UI screens or widgets
-- Reviewing code for accessibility compliance
-- Fixing accessibility issues reported by users
-- Adding semantic labels to icons and buttons
-- Implementing proper focus management in forms
-
-## Quick Reference
-
-### Semantic Labels for Icon Buttons
-
-```dart
-// ❌ Bad - no semantic label
-IconButton(
-  icon: Icon(Icons.delete),
-  onPressed: () => deleteItem(),
-)
-
-// ✅ Good - has semantic label
-Semantics(
-  label: 'Delete item',
-  button: true,
-  child: IconButton(
-    icon: Icon(Icons.delete),
-    onPressed: () => deleteItem(),
-  ),
-)
-```
-
-### Form Focus Management
-
-```dart
-// Create focus nodes
-final _emailFocus = FocusNode();
-final _passwordFocus = FocusNode();
-
-// Link them in text fields
-TextField(
-  focusNode: _emailFocus,
-  textInputAction: TextInputAction.next,
-  onSubmitted: (_) => _passwordFocus.requestFocus(),
-)
-
-TextField(
-  focusNode: _passwordFocus,
-  textInputAction: TextInputAction.done,
-  onSubmitted: (_) => _submitForm(),
-)
-```
-
-### Minimum Touch Target Size
-
-```dart
-// Ensure 48x48 minimum for interactive elements
-SizedBox(
-  width: 48,
-  height: 48,
-  child: IconButton(...),
-)
-```
-
-## Key Principles
-
-1. **Semantic Labels**: All icon buttons, images, and non-text elements need labels
-2. **Focus Order**: Tab order should follow visual/logical flow
-3. **Touch Targets**: Minimum 48x48 dp for all interactive elements
-4. **Color Contrast**: Text must have 4.5:1 contrast ratio (3:1 for large text)
-5. **Screen Reader**: Test with TalkBack (Android) and VoiceOver (iOS)
-
-## Steering Files
-
-Load detailed guidance:
-- `a11y_checklist.md` - Complete accessibility checklist for reviews
-
-## Templates
-
-- `focus_form` - Form with proper focus management
-- `semantics_icon_button` - Icon button with semantic labels
+- Auditing existing UI for WCAG 2.2 AA compliance.
+- Building new components that must be keyboard-navigable and screen-reader friendly.
+- Reviewing PR diffs for accessibility regressions.
+- Fixing focus management, ARIA labeling, or color contrast issues.
+- Choosing between native HTML semantics and ARIA attributes.
 
+## Instructions
+
+1. Identify the interaction pattern and which WCAG success criteria apply.
+2. Use semantic HTML first — only add ARIA when native semantics are insufficient.
+3. Verify keyboard flow: focus order, focus visibility, escape/close behavior.
+4. Check screen reader announcements for dynamic content and state changes.
+5. Validate contrast ratios and motion preferences before shipping.
+
+### Baseline standards
+
+- Use native HTML elements (`<button>`, `<nav>`, `<dialog>`, `<details>`) before custom ARIA widgets.
+- Every interactive element must be keyboard-reachable and operable.
+- Every image has `alt` text (or `alt=""` for decorative images).
+- Color alone is never the only way to convey information.
+- Focus indicators are visible in all themes (light, dark, high contrast).
+- Dynamic content changes are announced via live regions or focus management.
+- Forms have visible labels, error messages linked to inputs, and clear required-field indicators.
+
+### ARIA rules
+
+- First rule of ARIA: don't use ARIA if a native HTML element does the job.
+- Never change native semantics unless absolutely necessary (`<button>` is always better than `<div role="button">`).
+- All interactive ARIA elements must be keyboard-operable.
+- All ARIA references (`aria-labelledby`, `aria-describedby`, `aria-controls`) must point to existing element IDs.
+- Use `aria-live="polite"` for status updates, `aria-live="assertive"` only for critical errors.
+
+### Testing checklist
+
+- Tab through every interactive element — focus order must be logical.
+- Operate every control with keyboard only (Enter, Space, Escape, Arrow keys).
+- Run axe-core or Lighthouse accessibility audit — zero critical/serious violations.
+- Test with a screen reader (VoiceOver, NVDA, or JAWS) on at least one real flow.
+- Check `prefers-reduced-motion` — animations must respect this media query.
+- Verify contrast with a tool (minimum 4.5:1 for normal text, 3:1 for large text and UI).
+- Test with zoom at 200% — layout must not break or hide content.
+
+### Constraints
+
+- Avoid using `div` or `span` with click handlers instead of `<button>`.
+- Avoid suppressing focus outlines globally (`outline: none` without replacement).
+- Avoid using `aria-hidden="true"` on elements that contain interactive content.
+- Avoid auto-playing audio or video without user consent or a stop mechanism.
+- Avoid using only color to indicate errors, status, or selected state.
+- Avoid positive `tabindex` values — they create unpredictable focus order.
+- Avoid tooltip-only labels with no accessible name on the trigger element.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                 | Load when                                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `references/wcag-audit-checklist.md` | You need a structured WCAG 2.2 AA audit checklist for a full-page or full-app review.                      |
+| `references/aria-patterns-guide.md`  | The task involves custom widgets (modals, menus, tabs, trees, comboboxes) that need correct ARIA patterns. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with accessibility best practices in this project"
+- "Review my accessibility implementation for issues"

package/workflows/powers/agent-design/POWER.md

@@ -0,0 +1,201 @@
+````markdown
+---
+inclusion: manual
+name: agent-design
+description: "Use when designing, building, or improving a CBX agent, skill, or workflow: clarification strategy, progressive disclosure structure, workflow pattern selection (sequential, parallel, evaluator-optimizer), skill type taxonomy, description tuning, and eval-first testing."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
+---
+
+# Agent Design
+
+## Purpose
+
+You are the specialist for designing CBX agents and skills that behave intelligently — asking the right questions, knowing when to pause, executing in the right workflow pattern, and testing their own output.
+
+Your job is to close the gap between "it kinda works" and "it works reliably under any input."
+
+## When to Use
+
+- Designing or refactoring a SKILL.md or POWER.md
+- Choosing between sequential, parallel, or evaluator-optimizer workflow
+- Writing clarification logic for an agent that handles ambiguous requests
+- Deciding whether a task needs a skill or just a prompt
+- Testing whether a skill actually works as intended
+- Writing descriptions that trigger the right skill at the right time
+
+## Core Principles
+
+These come directly from Anthropic's agent engineering research (["Equipping agents for the real world"](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills), March 2026):
+
+1. **Progressive disclosure** — A skill's SKILL.md provides just enough context to know when to load it. Full instructions, references, and scripts are loaded lazily, only when needed. More context in a single file does not equal better behavior — it usually hurts it.
+
+2. **Eval before optimizing** — Define what "good looks like" (test cases + success criteria) before editing the skill. This prevents regression and tells you when improvement actually happened.
+
+3. **Description precision** — The `description` field in YAML frontmatter controls triggering. Too broad = false positives. Too narrow = the skill never fires. Tune it like a search query.
+
+4. **Two skill types** — See [Skill Type Taxonomy](#skill-type-taxonomy). These need different testing strategies and have different shelf lives.
+
+5. **Start with a single agent** — Before adding workflow complexity, first try a single agent with a rich prompt. Only add orchestration when it measurably improves results.
+
+## Skill Type Taxonomy
+
+| Type                   | What it does                                                                                                                                | Testing goal                                | Shelf life                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------- |
+| **Capability uplift**  | Teaches Claude to do something it can't do alone (e.g. manipulate PDFs, fill forms, use a domain-specific API)                              | Verify the output is correct and consistent | Medium — may become obsolete as models improve          |
+| **Encoded preference** | Sequences steps Claude could do individually, but in your team's specific order and style (e.g. NDA review checklist, weekly update format) | Verify fidelity to the actual workflow      | High — these stay useful because they're uniquely yours |
+
+Design question: "Is this skill teaching Claude something new, or encoding how we do things?"
+
+## Clarification Strategy
+
+An agent that starts wrong wastes everyone's time. Smart agents pause at the right moments.
+
+Load `references/clarification-patterns.md` when:
+
+- Designing how a skill should handle ambiguous or underspecified inputs
+- Writing the early steps of a workflow where user intent matters
+- Deciding what questions to ask vs. what to infer
+
+## Workflow Pattern Selection
+
+Three patterns cover 95% of production agent workflows:
+
+| Pattern                 | Use when                                                        | Cost                    | Benefit                                   |
+| ----------------------- | --------------------------------------------------------------- | ----------------------- | ----------------------------------------- |
+| **Sequential**          | Steps have dependencies (B needs A's output)                    | Latency (linear)        | Focus: each step does one thing well      |
+| **Parallel**            | Steps are independent and concurrency helps                     | Tokens (multiplicative) | Speed + separation of concerns            |
+| **Evaluator-optimizer** | First-draft quality isn't good enough and quality is measurable | Tokens × iterations     | Better output through structured feedback |
+
+Default to sequential. Add parallel when latency is the bottleneck and tasks are genuinely independent. Add evaluator-optimizer only when you can measure the improvement.
+
+Load `references/workflow-patterns.md` for the full decision tree, examples, and anti-patterns.
+
+## Progressive Disclosure Structure
+
+A well-structured CBX skill looks like:
+
+```
+skill-name/
+  SKILL.md           ← lean entry: name, description, purpose, when-to-use, load-table
+  references/        ← detailed guides loaded lazily when step requires it
+    topic-a.md
+    topic-b.md
+  commands/          ← slash commands (optional)
+    command.md
+  scripts/           ← executable code (optional)
+    helper.py
+```
+
+**SKILL.md should be loadable in <2000 tokens.** Everything else lives in references.
+
+The metadata table pattern that works:
+
+```markdown
+## References
+
+| File                    | Load when                                  |
+| ----------------------- | ------------------------------------------ |
+| `references/topic-a.md` | Task involves [specific trigger condition] |
+| `references/topic-b.md` | Task involves [specific trigger condition] |
+```
+
+This lets the agent make intelligent decisions about what context to load rather than ingesting everything upfront.
+
+## Description Writing
+
+The `description` field is a trigger — write it like a search query, not marketing copy.
+
+**Good description:**
+
+```yaml
+description: "Use when evaluating an agent, skill, workflow, or MCP server: rubric design, evaluator-optimizer loops, LLM-as-judge patterns, regression suites, or prototype-vs-production quality gaps."
+```
+
+**Bad description:**
+
+```yaml
+description: "A comprehensive skill for evaluating things and making sure they work well."
+```
+
+Rules:
+
+- Lead with the specific trigger verb: "Use when [user does X]"
+- List the specific task types with commas — these act like search keywords
+- Include domain-specific nouns the user would actually type
+- Avoid generic adjectives ("comprehensive", "powerful", "advanced")
+
+Test your description: would a user's natural-language request match the intent of these words?
+
+## Testing a Skill
+
+Before shipping, verify with this checklist:
+
+1. **Positive trigger** — Does the skill load when it should? Test 5 natural phrasings of the target task.
+2. **Negative trigger** — Does it stay quiet when it shouldn't load? Test 5 near-miss phrasings.
+3. **Happy path** — Does the skill complete the standard task correctly?
+4. **Edge cases** — What happens with missing input, ambiguous phrasing, or edge-case content?
+5. **Reader test** — Run the delivery (e.g., a generated doc, a plan) through a fresh sub-agent with no context. Can it answer questions about the output correctly?
+
+For formal regression suites, load `references/skill-testing.md`.
+
+## Instructions
+
+### Step 1 — Understand the design task
+
+Before touching any file, clarify:
+
+- Is this a new skill or improving an existing one?
+- Is it capability uplift or encoded preference?
+- What's the specific failure mode being fixed?
+- What would passing look like?
+
+If any of these are unclear, apply the clarification pattern from `references/clarification-patterns.md`.
+
+### Step 2 — Choose the structure
+
+- If the skill is simple (single task, single purpose): lean SKILL.md with no references
+- If the skill is complex (multiple phases, conditional logic): SKILL.md + references loaded lazily
+- If the skill has reusable commands: add `commands/` directory
+
+### Step 3 — Design the workflow
+
+Use the pattern selection table above. Start with sequential. Prove you need complexity before adding it.
+
+### Step 4 — Write the description
+
+Write it last. Once you know what the skill does and how it differs from adjacent skills, the right description is usually obvious.
+
+### Step 5 — Define a test
+
+Write at least 3 test cases (input → expected output or behavior) before considering the skill done. These become the regression suite.
+
+## Output Format
+
+Deliver:
+
+1. **Skill structure** — directory layout, file list
+2. **SKILL.md** — production-ready with lean body and reference table
+3. **Reference files** — if needed, each scoped to a specific phase or topic
+4. **Test cases** — 3-5 natural language inputs with expected behaviors
+5. **Description** — the final `description` field, tuned for triggering
+
+## References
+
+| File                                   | Load when                                                                      |
+| -------------------------------------- | ------------------------------------------------------------------------------ |
+| `references/clarification-patterns.md` | Designing how the agent handles ambiguous or underspecified input              |
+| `references/workflow-patterns.md`      | Choosing or implementing sequential, parallel, or evaluator-optimizer workflow |
+| `references/skill-testing.md`          | Writing evals, regression sets, or triggering tests for a skill                |
+
+## Examples
+
+- "Design a skill for our NDA review process — it should follow our checklist exactly."
+- "The feature-forge skill triggers on the wrong prompts. Help me fix the description."
+- "How do I test whether my skill still works after a model update?"
+- "I need a workflow where 3 agents review code in parallel then one synthesizes findings."
+- "This skill's SKILL.md is 4000 tokens. Help me split it into lean structure with references."
+````