@massa-ai/codex-plugin 1.27.0 → 1.30.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "massa-ai",
-  "version": "1.27.0",
+  "version": "1.30.0",
   "description": "massa-ai — semantic code search, memory, and context compression for Codex",
   "author": {
     "name": "Luiz Massa",

package/agent-profiles/balanced/massa-ai-judge.toml

@@ -1,9 +1,9 @@
 # massa-ai-owned
 name = "massa-ai-judge"
-description = "Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
+description = "Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
 model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """# Judge Agent Skill
 
 ## Mission

package/agent-profiles/cheap/massa-ai-judge.toml

@@ -1,9 +1,9 @@
 # massa-ai-owned
 name = "massa-ai-judge"
-description = "Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
+description = "Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "high"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """# Judge Agent Skill
 
 ## Mission

package/agent-profiles/heavy/massa-ai-judge.toml

@@ -1,9 +1,9 @@
 # massa-ai-owned
 name = "massa-ai-judge"
-description = "Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
+description = "Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
 model = "gpt-5.6-sol"
 model_reasoning_effort = "xhigh"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """# Judge Agent Skill
 
 ## Mission

package/agent-profiles/home/massa-ai-judge.toml

@@ -1,9 +1,9 @@
 # massa-ai-owned
 name = "massa-ai-judge"
-description = "Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
+description = "Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
 model = "gpt-5.6-terra"
 model_reasoning_effort = "xhigh"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """# Judge Agent Skill
 
 ## Mission

package/agent-profiles/work/massa-ai-judge.toml

@@ -1,9 +1,9 @@
 # massa-ai-owned
 name = "massa-ai-judge"
-description = "Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
+description = "Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
 model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """# Judge Agent Skill
 
 ## Mission

package/agents/massa-ai-judge.toml

@@ -1,9 +1,9 @@
 # massa-ai-owned
 name = "massa-ai-judge"
-description = "Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
+description = "Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence."
 model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """# Judge Agent Skill
 
 ## Mission

package/install.sh

@@ -68,6 +68,38 @@ done
 source "$SCRIPT_DIR/../../scripts/banner.sh"
 massa_ai_banner
 
+# ── Generated-bundle contract (T6, design Component 4 / UGB-05..07) ─────────
+# Why: apps/*-plugin generated subtrees (skills/, agents/, agent-profiles/,
+#      hooks/massa-ai-hook, lib/opencode-config.cjs) are gitignored build
+#      output (UGB-01) — a repo checkout must regenerate them before this
+#      installer copies or registers anything; a published tarball ships them
+#      pre-generated and has no generator sources to run at all. Runs before
+#      any host-config mutation (before CODEX_DIR resolution below).
+# Impacts: UGB-05 checkout generates, UGB-06 tarball skips, UGB-07 loud
+#          failure before mutation, UGB-08 (skip-env honored for harness runs).
+# Test: apps/codex-plugin/__tests__/install.test.ts (skip-branch + loud-failure cases)
+if [[ -f "$REPO_ROOT/scripts/generate-skill-artifacts.ts" ]]; then
+  if [[ "${MASSA_AI_SKIP_ARTIFACT_GENERATION:-0}" != "1" ]]; then
+    if ! command -v bun &>/dev/null; then
+      echo "Error: bun required to generate plugin bundles in a repo checkout (scripts/generate-*.ts)" >&2
+      exit 3
+    fi
+    bun "$REPO_ROOT/scripts/generate-skill-artifacts.ts"
+    bun "$REPO_ROOT/scripts/generate-subagent-artifacts.ts"
+  fi
+fi
+# Tarball installs (generator sources absent) skip the block above entirely
+# and fall straight through to this sentinel, which every context must pass:
+# the bundle this installer is about to copy/register has to actually exist.
+if [[ ! -f "$SCRIPT_DIR/skills/massa-ai/SKILL.md" ]]; then
+  echo "Error: missing $SCRIPT_DIR/skills/massa-ai/SKILL.md — run 'bun run generate:artifacts' first" >&2
+  exit 1
+fi
+if [[ ! -d "$SCRIPT_DIR/agents" ]] || [[ -z "$(ls -A "$SCRIPT_DIR/agents" 2>/dev/null)" ]]; then
+  echo "Error: missing or empty $SCRIPT_DIR/agents — run 'bun run generate:artifacts' first" >&2
+  exit 1
+fi
+
 # Resolve target base dir
 if [[ "$SCOPE" == "project" ]]; then
   CODEX_DIR="$(pwd)/.codex"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/codex-plugin",
-  "version": "1.27.0",
+  "version": "1.30.0",
   "description": "massa-ai plugin for Codex — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/agents/judge/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 license: MIT
 metadata:
   author: S1LV4, luizgmassa
-  version: "1.1.0"
+  version: "1.2.0"
   model_tier: deep
-  permission: read-only
+  permission: write
 ---
 
 # Judge Agent Skill

package/skills/massa-ai/SKILL.md

@@ -46,7 +46,7 @@ Before reading any massa-ai file:
   Never pass `workflowSessionId` in that field. Use `synapse_task_begin`/`synapse_task_end`
   for task envelopes and `synapse_prefetch` to warm the buffer on file open.
 - Prefer the shared v2 retrieval order; fall back gracefully if the massa-ai
-  server or Synapse is unavailable. The full tool surface includes 52 tools
+  server or Synapse is unavailable. The full tool surface includes 54 tools
   (see `references/mcp-tools.md`): indexing, search, symbol graph
   (`trace_path`, `impact_analysis`, `get_architecture`), memory CRUD
   (`remember`, `recall`, `memory_update`, `memory_delete`), checkpoints
@@ -80,6 +80,8 @@ Before reading any massa-ai file:
   requirement meaning, scope boundaries, destructive/irreversible choices,
   contradictory evidence — ask the user rather than choose silently. Facts
   are looked up; decisions are asked.
+- Before writing or changing implementation code, load
+  `references/coding-guidelines.md` if not already loaded.
 - Complete Evidence Gate before claiming done.
 
 Use internal references only when needed:
@@ -164,6 +166,9 @@ current context already contains it.
 | `commit` | draft or create safe Conventional Commits with Jira branch prefixes and audit report exclusions | `workflows/commit.md` |
 | `the-fool` | direct challenge, red-team, pre-mortem, evidence audit | `workflows/the-fool.md` |
 | `judge-with-debate` | standalone multi-judge debate evaluation of user-supplied artifacts | `workflows/judge-with-debate.md` |
+| `pr-review` | review a hosted GitHub PR / GitLab MR and post findings via `gh`/`glab` | `workflows/pr-review.md` |
+| `to-prd` | turn the current conversation into a PRD without a new interview | `workflows/to-prd.md` |
+| `skill-architect` | design and build a new skill through structured conversation | `workflows/skill-architect.md` |
 | `furps-refinement` | FURPS+ refinement of a PRD and/or ADR before implementation, with The Fool pre-validation and DoR coverage | `workflows/refinement/furps-refinement.md` |
 | `general` | coding work with no more specific workflow | `workflows/general.md` |
 
@@ -176,8 +181,8 @@ match or no match is resolved deterministically without asking.
 Deterministic routing precedence, first match wins:
 
 1. **Explicit route:** user names a massa-ai workflow, report family, saved finding type, or asks for a direct challenge.
-2. **Requested artifact:** ADR, RFC, TDD, Jira ticket, commit, session guide, audit report, implementation audit report, mobile Figma report, or FURPS refinement report.
-3. **Target type:** broken behavior/error -> `debug`; saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; Maestro E2E/device automation target -> `maestro`, `maestro-audit`, or child-only `maestro-fix` before generic tests workflows; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
+2. **Requested artifact:** ADR, RFC, TDD, Jira ticket, commit, session guide, audit report, implementation audit report, mobile Figma report, FURPS refinement report, PRD synthesized from the current conversation -> `to-prd` (explicit request only; refining an existing PRD stays `furps-refinement`), or new SKILL.md / skill design -> `skill-architect`.
+3. **Target type:** broken behavior/error -> `debug`; hosted PR/MR reference (number or URL) to review with posted findings -> `pr-review` (local working diff stays with audit routes); saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; Maestro E2E/device automation target -> `maestro`, `maestro-audit`, or child-only `maestro-fix` before generic tests workflows; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
 4. **Primary verb:** create/add/implement -> `feature` unless the concrete target is new Maestro flow work, which routes to `maestro`; restructure without behavior change -> `refactor`; inspect/understand only -> `exploration`; record selected decision -> `adr`; compare open options -> `rfc`; design settled implementation -> `tdd`; refine/quality-check an existing PRD or ADR document (not implementation auditing) -> `furps-refinement`.
 5. **Risk domain escalation:** migrations, irreversible operations, auth/privacy, cross-service contracts, public compatibility, or work over 10 files routes to `spec-driven` unless the user explicitly requests a narrower workflow and accepts the containment.
 6. **General fallback:** use `general` only after a one-line General fallback preflight names the specialized workflow considered, rejected reason, and why fallback does not change verification or mutation behavior.

package/skills/massa-ai/references/agent-orchestration.md

@@ -148,7 +148,7 @@ only, never a dispatch target.
 
 ## Capability Packet
 
-**This section is the sole canonical Capability Packet definition.** `references/subagent-design.md` and the root `skills/AGENTS.md` registry defer to or mirror this list; `scripts/__tests__/capability-packet-parity.test.ts` fails when the `skills/AGENTS.md` mirror diverges. Bespoke packets (judge panel, FURPS analyst, phase-batch worker) are declared specializations that map onto these fields in their own workflow files.
+**This section is the sole canonical Capability Packet definition.** `references/subagent-design.md` mirrors this list and the root `skills/AGENTS.md` registry points here without restating it. Bespoke packets (judge panel, FURPS analyst, phase-batch worker) are declared specializations that map onto these fields in their own workflow files.
 
 **A subagent inherits nothing from the parent session** — no skills, no personas, no loaded references, no conversation history. Everything the subagent needs is named explicitly in the packet, including the exact reference file paths it must read itself.
 

package/skills/massa-ai/references/coding-guidelines.md

@@ -0,0 +1,67 @@
+# Coding Guidelines
+
+Source: Karpathy Guidelines (Useful-Agent-Skills)
+
+Behavioral guidelines to reduce common LLM coding mistakes. These principles bias toward caution over speed—for trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them—don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- Disagree honestly. If the user's approach seems wrong, say so—don't be sycophantic.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it—don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+**The test:** Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

package/skills/massa-ai/references/installation.md

@@ -100,9 +100,9 @@ behavior through MCP declarations and non-destructive runtime probes.
 - Preferred: `bash scripts/install-agents.sh --agent <host>` — the single writer
   of host MCP config (Claude Code, Claude Desktop, Codex, Cursor, OpenCode).
   Plugin installers call it; nothing else writes an MCP entry.
-- OpenCode: local MCP package via `bunx @massa-ai/mcp-client`, or
-  `@massa-ai/opencode-plugin` (which registers tools in-process, so
-  `install-agents.sh` skips the MCP entry when that plugin is present).
+- OpenCode: `@massa-ai/opencode-plugin` is hooks-only (AD-017) and delegates
+  MCP registration to `install-agents.sh --agent opencode` on every install,
+  same as every other host — no separate MCP step needed.
 - VS Code/Antigravity: `.vscode/mcp.json` or `./scripts/setup-vscode.sh`.
 - Docker: run the `mcp` service through `docker compose run --rm -i mcp`.
 

package/skills/massa-ai/references/mcp-tools.md

@@ -1,4 +1,4 @@
-# massa-ai Tool Contracts (52 Tools)
+# massa-ai Tool Contracts (54 Tools)
 
 Load when exact MCP schemas, REST fallbacks, response modes, or
 polling rules are needed. Prefer the active tool declaration over copied
@@ -138,6 +138,8 @@ depends on exact content.
 |---|---|---|
 | `rename_project` | Rename a project identity transactionally | Req: `sourceProjectId`, `targetProjectId`. Default `dryRun=true`; apply with `dryRun=false` + `operationId` + `expectedPlanHash`. Administrative, not workflow-recurring. |
 | `merge_projects` | Merge one project identity into another | Req: `sourceProjectId`, `targetProjectId`. Same dryRun/planHash contract as `rename_project`. Administrative, not workflow-recurring. |
+| `profile_list` | List shipped model profiles and each detected host's current profile + bundle version | No required args; optional `host` to scope to one. Offline — reads on-disk variant directories only, never the registry. |
+| `profile_set` | Switch the installed massa-ai agents to a registry model profile | Req: `profile`. Optional `host` (default: every detected, supported host), `dryRun` (default `false`) to preview without writing. Local trust model — mutates installed agent files on the machine the MCP server runs on; a host session restart is required to take effect. |
 
 ## Retrieval Order
 

package/skills/massa-ai/references/skill-architect/examples.md

@@ -0,0 +1,256 @@
+# Description & Instruction Examples
+
+Reference for writing effective skill descriptions and instructions.
+Read this during the Architecture phase (for descriptions) and Craft phase
+(for instructions).
+
+---
+
+## Good Descriptions
+
+Each example follows the pattern: [What] + [When/Triggers] + [Not-when].
+
+### Document & Asset Creation
+
+```yaml
+description: Analyzes Figma design files and generates developer handoff documentation.
+  Use when user uploads .fig files, asks for "design specs", "component
+  documentation", or "design-to-code handoff". Do NOT use for general
+  design discussions or UI feedback.
+```
+
+```yaml
+description: Creates distinctive, production-grade frontend interfaces with high design
+  quality. Use this skill when the user asks to build web components, pages,
+  artifacts, posters, or applications (examples include websites, landing
+  pages, dashboards, React components, HTML/CSS layouts, or when
+  styling/beautifying any web UI). Generates creative, polished code and UI
+  design that avoids generic AI aesthetics.
+```
+
+### Workflow Automation
+
+```yaml
+description: Manages Linear project workflows including sprint planning, task creation,
+  and status tracking. Use when user mentions "sprint", "Linear tasks",
+  "project planning", or asks to "create tickets". Do NOT use for general
+  project management advice without Linear context.
+```
+
+```yaml
+description: End-to-end customer onboarding workflow for PayFlow. Handles account
+  creation, payment setup, and subscription management. Use when user says
+  "onboard new customer", "set up subscription", or "create PayFlow account".
+```
+
+### MCP Enhancement
+
+```yaml
+description: Automatically analyzes and fixes detected bugs in GitHub Pull Requests
+  using Sentry's error monitoring data via their MCP server. Use when user
+  mentions "Sentry errors", "fix bugs from monitoring", "PR review with
+  error data", or asks to analyze production errors in code.
+```
+
+---
+
+## Bad Descriptions (and Why)
+
+```yaml
+# ❌ Too vague — no trigger phrases, no specifics
+description: Helps with projects.
+# Why it fails: the agent can't determine WHEN to load this.
+```
+
+```yaml
+# ❌ Missing triggers — describes capability but not activation
+description: Creates sophisticated multi-page documentation systems.
+# Why it fails: What would a user SAY to trigger this? "Create docs"?
+# "Write documentation"? Include the actual phrases.
+```
+
+```yaml
+# ❌ Too technical, no user perspective
+description: Implements the Project entity model with hierarchical relationships.
+# Why it fails: Users don't think in entity models. They think in tasks.
+```
+
+```yaml
+# ❌ Too broad — will overtrigger
+description: Processes documents.
+# Why it fails: Loads for ANY document task. Add file types and specifics.
+```
+
+```yaml
+# ❌ Overlap without boundaries
+description: Analyzes data and creates visualizations.
+# Why it fails: Conflicts with built-in capabilities and other skills.
+# Add specifics about WHAT data and WHAT kind of visualizations.
+```
+
+---
+
+## Fixing Overtriggering with Negative Triggers
+
+```yaml
+# Before: triggers on all data tasks
+description: Advanced data analysis for CSV files.
+
+# After: scoped with negative triggers
+description: Advanced data analysis for CSV files. Use for statistical modeling,
+  regression, clustering. Do NOT use for simple data exploration
+  (use data-viz skill instead) or for reading CSV files without analysis.
+```
+
+---
+
+## Good Instructions
+
+### Specific and Actionable
+
+```markdown
+# ✅ Good — tells the agent exactly what to do
+
+Run `python scripts/[validate].py --input {filename}` to check data format.
+If validation fails, common issues include:
+
+- Missing required fields → add them to the CSV
+- Invalid date formats → use YYYY-MM-DD
+- Encoding errors → convert to UTF-8 first
+```
+
+```markdown
+# ❌ Bad — vague and unactionable
+
+Validate the data before proceeding.
+```
+
+### Error Handling
+
+```markdown
+# ✅ Good — specific error, cause, solution
+
+## Common Issues
+
+### MCP Connection Failed
+
+If you see "Connection refused":
+
+1. Verify MCP server is running: Check Settings > Extensions
+2. Confirm API key is valid
+3. Try reconnecting: Settings > Extensions > [Service] > Reconnect
+```
+
+```markdown
+# ❌ Bad — no specifics
+
+If something goes wrong, try again.
+```
+
+### Resource References
+
+```markdown
+# ✅ Good — says WHEN and WHY to read the file
+
+Before writing queries, consult `references/[api-patterns].md` for:
+
+- Rate limiting guidance (if making >10 calls)
+- Pagination patterns (if results may exceed 100 items)
+- Error codes and handling (if calls may fail)
+```
+
+```markdown
+# ❌ Bad — no guidance on when to read
+
+See references/ for more information.
+```
+
+### Critical Instructions
+
+```markdown
+# ✅ Good — prominent, specific, verifiable
+
+CRITICAL: Before calling create_project, verify:
+
+- Project name is non-empty
+- At least one team member assigned
+- Start date is not in the past
+  If any check fails, tell the user what's missing before proceeding.
+```
+
+```markdown
+# ❌ Bad — buried, vague, not verifiable
+
+Make sure to validate things properly.
+```
+
+### Examples in Skills
+
+```markdown
+# ✅ Good — realistic user input with concrete output
+
+## Examples
+
+### Example 1: New sprint setup
+
+User says: "Help me plan the Q4 sprint for the mobile team"
+Actions:
+
+1. Fetch current backlog from Linear (MCP)
+2. Check team capacity (3 engineers, 2-week sprint)
+3. Prioritize by impact score
+4. Create 12 tasks with estimates
+   Result: Sprint board populated with 12 prioritized tasks, each with
+   story points and assignees. Summary posted to #mobile-team Slack.
+```
+
+```markdown
+# ❌ Bad — generic, no concrete details
+
+### Example 1: Setup
+
+User says: "Set up a project"
+Result: Project gets created.
+```
+
+---
+
+## Anti-Patterns Checklist
+
+Before finalizing any skill, verify NONE of these are present:
+
+### Structural Anti-Patterns
+
+- [ ] File named SKILL.MD, skill.md, or any variant (must be exactly SKILL.md)
+- [ ] Folder has spaces or capitals (must be kebab-case)
+- [ ] README.md exists inside the skill folder
+- [ ] XML angle brackets (< >) in YAML frontmatter
+- [ ] "claude" or "anthropic" in the skill name
+- [ ] Missing --- delimiters around frontmatter
+- [ ] SKILL.md exceeds 500 lines without progressive disclosure
+
+### Description Anti-Patterns
+
+- [ ] No trigger phrases included
+- [ ] Too vague (could match anything)
+- [ ] Too technical (user perspective missing)
+- [ ] No negative triggers when overlap risk exists
+- [ ] Exceeds 1024 characters
+
+### Instruction Anti-Patterns
+
+- [ ] Vague directions without specific actions
+- [ ] Critical instructions buried in middle of document
+- [ ] No examples of realistic usage
+- [ ] No error handling guidance
+- [ ] References to external files without load conditions
+- [ ] Wall-of-text instructions without structure
+- [ ] Assumes skill is the only one loaded
+- [ ] Uses prose where a script would be deterministic
+
+### Quality Anti-Patterns
+
+- [ ] No validation step in workflow
+- [ ] No stopping conditions for iterative processes
+- [ ] Missing rollback/failure handling
+- [ ] Over-reliance on "be careful" instead of specific checks