jsgui3-server 0.0.151 → 0.0.155

package/docs/agi/skills/instruction-adherence/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: instruction-adherence
+description: "Use when instruction drift is likely: multi-step tasks, mid-task detours (tooling upgrades), or when agents must consult Skills and re-anchor repeatedly. Triggers: 'stay on track', 'follow instructions', 'resume main task', 'detour', 'intermediate task done'."
+---
+
+# Skill: Instruction Adherence (Stay On Track)
+
+## Scope
+
+This Skill is about reliably following instructions across:
+- Multiple instruction sources (system/developer/mode files, repo docs, user request)
+- Memory sources (Skills registry, sessions, lessons/patterns)
+- Multi-step execution where detours happen (e.g., "improve CLI tooling" mid-stream)
+
+## Inputs
+
+- The current user request (objective + success criteria)
+- The active mode/persona (if any)
+- Repo guardrails (AGENTS.md, testing commands)
+
+## Procedure
+
+### 1) Capture an "Instruction Snapshot" (mandatory)
+
+In your working notes, write a short snapshot:
+- **Objective**: 1 sentence
+- **Must do**: 3–7 bullets
+- **Must not**: 3–7 bullets
+- **Evidence**: what output/tests/checks will prove done
+
+This becomes the "north star" when you get interrupted.
+
+### 2) Run the memory retrieval ritual (Skills → Docs)
+
+- Skills: scan `docs/agi/skills/` and follow any matching SOP.
+- Docs: check `AGENTS.md` and relevant documentation.
+
+### 3) Build a "Task Ledger" with explicit parent/child tasks
+
+Use a structured task list that prevents detours from becoming the main task:
+- Parent task: user's objective
+- Child tasks: discovery → implement → validate → document
+- If a detour is required (e.g., CLI tooling improvement), make it a **child task** with:
+  - **Entry criteria** (why it's needed)
+  - **Exit criteria** (what "done" means)
+  - **Return step** (the exact next step to resume)
+
+### 4) The Re-anchor loop (run after every subtask)
+
+After any meaningful milestone (or after 3–5 tool calls):
+- Re-read the Instruction Snapshot
+- Mark completed tasks
+- Confirm the next step is still on the parent objective
+- If you drifted, explicitly choose to:
+  - Resume parent objective, or
+  - Create a follow-up and stop the detour
+
+### 5) "Detour complete → resume" protocol
+
+When an intermediate task (like CLI tooling improvement) is completed:
+1. Record a one-paragraph summary + evidence in the session notes.
+2. Add/update a Skill or Lesson if it will recur.
+3. Immediately take the "Return step" you wrote in the task ledger.
+
+## Validation (evidence checklist)
+
+- Working notes contain an Instruction Snapshot.
+- Task ledger clearly separates parent objective vs detours.
+- At least one re-anchor checkpoint is recorded.
+- Session summary includes an **Instruction Reflection**:
+  - What instructions helped?
+  - What was missing/wrong?
+  - What durable doc/agent update was made?

package/docs/agi/skills/jsgui3-activation-debug/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: jsgui3-activation-debug
+description: Debug jsgui3 client-side activation issues. Use when SSR renders but clicks don't work, this.dom.el is null, or you see Missing context.map_Controls / activation failures.
+---
+
+# jsgui3 Activation Debug
+
+## Triggers
+
+- "jsgui3", "clicks don't work", "activation", "Missing context.map_Controls"
+
+## Scope
+
+- Diagnose "renders but no interactivity" failures
+- Ensure client bundle is current when tests run in a browser
+- Add a minimal check script when behavior is unclear
+
+## Inputs
+
+- Which server/route/control is affected
+- Whether the issue reproduces in E2E (Puppeteer/Playwright)
+- Whether client bundling is involved
+
+## Procedure
+
+1. Confirm this is an activation issue, not just CSS/DOM.
+   - View the page source — if the HTML looks correct, it's likely activation.
+   - If the HTML is wrong, it's an SSR bug (different skill).
+
+2. Follow the documented activation flow and look for the canonical signatures:
+   - `data-jsgui-id` attributes on SSR elements
+   - `data-jsgui-type` for constructor mapping
+   - Client bundle loading correctly in browser Network tab
+
+3. Check the client bundle is up to date:
+   - If using bundled client JS, ensure it was rebuilt after any control changes.
+   - The server's bundler in `serve-factory.js` handles this automatically in most cases.
+
+4. Check `activate()` implementation:
+   - Is `super.activate()` being called?
+   - Is `this.dom.el` available at the time of activation?
+   - Are event listeners being attached in `activate()`, not in the constructor?
+
+5. If unclear, create a minimal reproduction check:
+   ```javascript
+   // Quick check: does the control load and render?
+   const Server = require('./server');
+   const s = new Server({port: 0});
+   // ... mount the control, start, check response
+   ```
+
+## Common Error Messages
+
+- **`Missing context.map_Controls for type <X>`**: SSR said the element is type X, but the client doesn't have a constructor registered. Client falls back to generic `Control`.
+- **`Missing context.map_Controls for type undefined`**: Often corresponds to tags where `data-jsgui-type` is intentionally not emitted (html/head/body). Usually log noise.
+- **`&&& no corresponding control`**: Emitted during pre-activation when DOM contains text nodes that don't correspond to a control entry. Often benign whitespace.
+
+## Validated Patterns
+
+### Pattern: Manual DOM Query in `activate()`
+When standard control field linking is insufficient, explicitly querying the DOM in `activate()` is a robust fallback:
+
+```javascript
+activate() {
+  if (this.__active) return;
+  this.__active = true;
+
+  const el = this.dom?.el;
+  if (!el) return;
+
+  // 1. Read config from data attributes
+  this.initial_width = parseInt(el.dataset.initialWidth, 10);
+
+  // 2. Query explicitly for child elements
+  this._expand_handle_el = el.querySelector("[data-expand-handle]");
+  
+  // 3. Bind events
+  if (this._expand_handle_el) {
+    this._expand_handle_el.addEventListener("click", this._handle_expand.bind(this));
+  }
+}
+```
+
+## Anti-Patterns to Avoid
+
+- **Blindly Editing CSS**: Assuming a control isn't working because of z-index or pointer-events, when the real issue is that the JS `activate()` method never fired on the client.
+- **Skipping Build**: Making changes to control logic and running E2E tests without rebuilding the client bundle first, leading to false negatives.
+
+## References
+
+- jsgui3 understanding: `docs/agi/skills/understanding-jsgui3/SKILL.md`
+- Comprehensive documentation: `docs/comprehensive-documentation.md`
+- Controls development guide: `docs/controls-development.md`
+- Server source: `server.js`, `serve-factory.js`

package/docs/agi/skills/jsgui3-context-menu-patterns/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: jsgui3-context-menu-patterns
+description: Standard pattern for implementing context menus in jsgui3 applications (Web & Electron), ensuring consistent behavior for activation, positioning, and dismissal. Triggers — context menu, right-click menu, popup menu, overlay positioning, click-outside dismissal.
+---
+
+# Skill: jsgui3 Context Menu Patterns
+
+## Description
+Standard pattern for implementing context menus in jsgui3 applications, ensuring consistent behavior for activation, positioning, and dismissal.
+
+## The Pattern
+
+1.  **Activation**: Listen for `contextmenu` event on the target element (or delegated container).
+2.  **Prevention**: Call `e.preventDefault()` to stop the native browser context menu.
+3.  **Creation**: Create or show the menu DOM element.
+    *   Append to `document.body` (or a dedicated overlay layer) to avoid z-index/clipping issues.
+    *   Position using `fixed` or `absolute` coordinates based on `e.clientX` / `e.clientY`.
+    *   **Clamp** coordinates to viewport bounds to prevent overflow.
+4.  **Dismissal**:
+    *   Add **global** `click` listener to `document` (use `capture: true` or check `e.target` to allow clicks inside the menu).
+    *   Add **global** `keydown` listener for `Escape` key.
+    *   Remove these listeners immediately upon menu closure to prevent leaks.
+5.  **Cleanup**: Always remove the menu element and listeners when closed.
+
+## Implementation Example (jsgui3)
+
+```javascript
+// In your control's activate() method:
+this.dom.el.addEventListener('contextmenu', (e) => {
+    e.preventDefault();
+    this.show_context_menu(e.clientX, e.clientY);
+});
+
+show_context_menu(x, y) {
+    // 1. Close existing
+    if (this._active_menu) this._active_menu.remove();
+
+    // 2. Create Menu (using jsgui or raw DOM)
+    const menu = document.createElement('div');
+    menu.className = 'context-menu';
+    
+    // 3. Position & Clamp
+    const width = 150; // Estimated or measured
+    const height = 100;
+    
+    // Clamp X
+    if (x + width > window.innerWidth) x -= width;
+    // Clamp Y
+    if (y + height > window.innerHeight) y -= height;
+    
+    menu.style.left = `${x}px`;
+    menu.style.top = `${y}px`;
+    
+    // 4. Add Items
+    // ... append items ...
+
+    document.body.appendChild(menu);
+    this._active_menu = menu;
+
+    // 5. Setup Dismissal
+    const close_handler = (ev) => {
+        // Don't close if clicking inside menu
+        if (ev.type === 'click' && menu.contains(ev.target)) return;
+        
+        // Close on click outside or Escape
+        if (ev.type === 'click' || (ev.type === 'keydown' && ev.key === 'Escape')) {
+            menu.remove();
+            this._active_menu = null;
+            document.removeEventListener('click', close_handler);
+            document.removeEventListener('keydown', close_handler);
+        }
+    };
+
+    // Defer listener to avoid immediate trigger
+    setTimeout(() => {
+        document.addEventListener('click', close_handler);
+        document.addEventListener('keydown', close_handler);
+    }, 0);
+}
+```
+
+## Validation
+
+Verify context menu behavior:
+- Right-click shows menu at cursor position
+- Menu is clamped within viewport
+- Click outside dismisses menu
+- Escape key dismisses menu
+- No event listener leaks after menu closure
+
+## References
+
+- Understanding jsgui3: `docs/agi/skills/understanding-jsgui3/SKILL.md`
+- Controls development: `docs/controls-development.md`

package/docs/agi/skills/puppeteer-efficient-ui-verification/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: puppeteer-efficient-ui-verification
+description: Fast, repeatable UI verification using Puppeteer without paying browser startup per test. Use scenario suites + deterministic fixtures before jumping to full E2E tests.
+---
+
+# Puppeteer Efficient UI Verification
+
+## Scope
+
+- Choose the fastest *correct* browser-level verification method
+- Run multiple UI scenarios per browser session (scenario suites)
+- Capture evidence (artifacts + console/network logs) so failures are actionable
+
+## Inputs
+
+- What changed (files / feature)
+- Do you need browser semantics (events, CSS/layout, client bundle activation)?
+- Do you need a deterministic fixture (DB seed, synthetic page)?
+
+## Procedure (verification ladder)
+
+1. Prefer server-side/SSR checks when possible
+   - If the change is server-only or SSR-only, create/run a check script that loads the module and verifies output.
+   - If the change touches server startup, start the server and verify it responds:
+     ```bash
+     node -e "const s = require('./server'); console.log('Server module loaded OK')"
+     ```
+
+2. If you need "one URL in a browser", use a simple Puppeteer script
+   - Navigate to the page, wait for a key selector, capture screenshot + console logs.
+   - Best for quick debugging of console errors and 404s.
+
+3. If you need multiple interactions, use a scenario suite (single browser)
+   - Use a runner script that starts one browser and runs multiple scenarios sequentially.
+   - Each scenario navigates, waits for readiness, and asserts conditions.
+   - Artifacts are written to `tmp/ui-scenarios/` by default.
+
+4. Promote to full E2E test when it's a regression
+   - Add a proper test file in `tests/`.
+
+## Suite authoring SOP (deterministic fixtures)
+
+When creating a new scenario suite:
+
+1. Create a runner script under `tests/scenarios/` or `scripts/scenarios/`.
+2. Export `start_server()` that:
+   - starts the server on port `0` (random port)
+   - returns `{ base_url, shutdown() }`
+3. Add scenarios with stable ids (`"001"`, `"002"`, …).
+4. Add **readiness gates** for client activation (jsgui3):
+   - prefer `page.waitForFunction()` on deterministic signals
+5. On failures, ensure you have evidence:
+   - screenshot + HTML snapshot + captured logs
+
+## Validation
+
+- Scenario suite run exits cleanly (no hanging server/browser)
+- At least one scenario validates the user-visible invariant
+- Failures produce artifacts that explain the bug (not just "timeout")
+
+## References
+
+- Test directory: `tests/`
+- jsgui3 activation flow: `docs/comprehensive-documentation.md`
+- Control lifecycle: see `understanding-jsgui3` skill

package/docs/agi/skills/runaway-process-guard/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: runaway-process-guard
+description: Prevents infinite loops and runaway execution by enforcing strict timeouts, circuit breakers, and semantic repetition detection.
+---
+
+# Runaway Process Guard
+
+This skill codifies explicit rules for preventing an AI agent from getting stuck in infinite loops, runaway scripts, or deadlocked background processes. Because agents inherently optimize for continuation and lack an intuitive "sense of time," these external operational rules must be strictly adhered to whenever interacting with the terminal or writing polling loops.
+
+## Scope
+- Applies to all custom scripts written by the agent that involve loops (`while`, `for`, `setInterval`).
+- Applies to all agent interactions with background commands (using `run_command` and `command_status`).
+- Does **not** supersede domain-specific graceful degradation if a tool provides a native way to timeout gracefully, but acts as the hard ceiling above it.
+
+## The 3 Pillars of Runaway Prevention
+
+### 1. Hard Timeboxing (Programmatic Circuit Breakers)
+Never write a custom polling script or infinite loop without a programmatic wall-clock timeout.
+*   **Rule:** Every `while(running)` or indefinite status check loop MUST track `Date.now()`.
+*   **Implementation:** 
+    ```javascript
+    const MAX_WAIT_MS = 60000; // 1 minute
+    const start = Date.now();
+    while (running && (Date.now() - start < MAX_WAIT_MS)) {
+        // ... poll ...
+    }
+    if (running) {
+        console.error("TIMEOUT_CIRCUIT_BREAKER_TRIPPED");
+        process.exit(1);
+    }
+    ```
+*   **Rule:** When using `execSync` from Node, ALWAYS pass the `{ timeout: X }` flag.
+
+### 2. Semantic Repetition Detection (Agent Circuit Breaker)
+When polling a background process using the `command_status` tool, you must act as the circuit breaker.
+*   **Rule:** If you check the status of a command 3 times and the text output reveals identical states (e.g., repeatedly showing the same output over 60 seconds), you MUST assume the process is deadlocked or state tracking has failed.
+*   **Action:** Immediately cease waiting. Do not passive-poll in hopes that it will magically resolve.
+
+### 3. Immediate Termination Protocols
+If a process is determined to be stuck (either by tripping the semantic repetition detector or visually hanging during a user interaction):
+*   **Action:** Use the `send_command_input` tool with `Terminate: true` to kill the background job.
+*   **Action:** If a script spawned detached daemon processes, terminating the parent CLI command will not kill the workers. You MUST issue explicit kill/stop commands to eradicate the orphaned runaways.
+
+## Escalation / Pivot
+When a circuit breaker is tripped:
+1. Do not immediately rewrite the script and try the exact same approach again. 
+2. Record the timeout failure in an artifact or thought process.
+3. Investigate if the underlying system provides an alternate, safer primitive.
+4. Prompt the user for guidance if the underlying mechanism seems fundamentally broken.

package/docs/agi/skills/session-discipline/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: session-discipline
+description: Enforce session-first workflow (plan → implement → verify → document). Use whenever starting non-trivial work, debugging >15 minutes, or doing cross-cutting changes.
+---
+
+# Session Discipline
+
+## Scope
+
+- Ensure every non-trivial task has proper planning and tracking
+- Keep evidence (commands/tests) and outcomes discoverable
+- Reduce "handover friction" by making every action resumable from docs
+
+## Inputs
+
+- Task description and objective one-liner
+- Type/category of work
+
+## Procedure
+
+1. Create working notes with a clear objective, done-when criteria, change set, risks, and tests.
+2. Log commands + findings in working notes as you go.
+3. Summarize outcomes + follow-ups with named owners when done.
+
+## Validation
+
+- Ensure follow-ups have owners if anything is deferred.
+- Working notes capture actual commands run and their outcomes.
+
+## Escalation / Research request
+
+If you need deeper background and existing docs aren't sufficient:
+
+- Add a follow-up: "Request research agent to expand Skill <name>"
+- Include: expected triggers, target files, and what validation should exist
+
+## References
+
+- Repo guidelines: `AGENTS.md`
+- Skills directory: `docs/agi/skills/`

package/docs/agi/skills/skill-writing/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: skill-writing
+description: "Write excellent Antigravity Skills — reusable capability packs with trigger phrases, SOPs, and validation. Use when creating a new Skill, improving an existing one, or auditing skill quality. Triggers: write a skill, new skill, create skill, skill review, improve skill, skill quality."
+---
+
+# Skill: Writing Excellent Antigravity Skills
+
+## Scope
+
+Use this Skill when you need to:
+
+- **Create a new Skill** from scratch (or from session learnings)
+- **Upgrade an existing Skill** that's thin, outdated, or missing key sections
+- **Audit skill quality** across the registry
+- **Extract a Skill** from a successful session or workflow
+
+This is a meta-skill: it teaches how to write Skills that teach agents to do things well.
+
+Out of scope:
+- Writing *workflows* (`.agent/workflows/`) — those are sequential checklists, not capability packs
+- Writing *lessons* or *patterns* — those are distilled one-liners, not SOPs
+
+## Core Principle: A Skill Is a Decision-Making Machine
+
+> **A good Skill doesn't just tell the agent *what to do* — it tells the agent *what to think about* while doing it.**
+
+The difference between a weak Skill and a strong one:
+
+| Weak Skill | Strong Skill |
+|-----------|-------------|
+| "Run these 5 commands" | "Here's the mental model. Here are the commands. Here's how to tell if they worked. Here's what to do when they don't." |
+| Agent follows steps blindly | Agent *reasons* about the domain and adapts |
+| Breaks when reality deviates | Handles edge cases because the agent understands *why* |
+
+## Mental Model: The Skill Quality Pyramid
+
+```
+                    ┌─────────────┐
+                    │  MENTAL     │  ← The agent can reason about WHY
+                    │  MODELS     │     (principles, heuristics, trade-offs)
+                    ├─────────────┤
+                    │  DECISION   │  ← The agent knows WHEN to do what
+                    │  POINTS     │     (if X → do A, if Y → do B)
+                    ├─────────────┤
+                    │  CONCRETE   │  ← The agent knows HOW
+                    │  ACTIONS    │     (commands, code patterns, API calls)
+                    ├─────────────┤
+                    │  GUARD      │  ← The agent knows when to STOP
+                    │  RAILS      │     (anti-patterns, stopping rules, escalation)
+                    └─────────────┘
+```
+
+**Level 1 (Actions only)** — the agent can follow the steps. Fragile.
+**Level 2 (Actions + Decisions)** — the agent can handle branching. Better.
+**Level 3 (Actions + Decisions + Mental Models)** — the agent can adapt. Strong.
+**Level 4 (All four layers)** — the agent can self-correct. Excellent.
+
+Your goal: write Level 3–4 Skills.
+
+---
+
+## Procedure
+
+### Phase 0 — Decide If This Should Be a Skill
+
+Not everything deserves a Skill. Use this decision tree:
+
+```
+Is this a repeatable capability (not a one-off task)?
+├── No → Write a session note or follow-up instead
+└── Yes
+    ├── Is it a simple checklist with no branching logic?
+    │   ├── Yes → Write a workflow (`.agent/workflows/`)
+    │   └── No
+    │       └── Does it require domain reasoning or decision-making?
+    │           ├── Yes → WRITE A SKILL ✓
+    │           └── No → Consider a pattern
+```
+
+### Phase 1 — Deep Research Before Writing
+
+**Never write a Skill from scratch.** Always research first:
+
+1. **Check for existing Skills** that overlap
+2. **Mine session history** for the source material
+3. **Identify the core mental model**
+4. **Identify anti-patterns**
+
+### Phase 2 — Design the Skill Structure
+
+Every Skill MUST have these sections (the **Mandatory Six**):
+
+| Section | Purpose | Quality Test |
+|---------|---------|-------------|
+| **Frontmatter** | Discovery — when should this Skill activate? | Would a search for any related keyword find this Skill? |
+| **Scope** | Boundaries — what does/doesn't this Skill cover? | Could an agent confidently decide "this Skill applies" or "this Skill doesn't apply"? |
+| **Inputs** | Prerequisites — what info does the agent need? | If the agent doesn't have these inputs, would it know to ask? |
+| **Procedure** | The SOP — step-by-step with decision points | Could an agent follow this without asking for help on the happy path? |
+| **Validation** | Proof — how does the agent verify the work? | Are there specific commands with expected outputs? |
+| **References** | Pointers — related docs, tools, skills | Would an agent know where to go for deeper context? |
+
+### Phase 3 — Write the Frontmatter (Most Important Part)
+
+```yaml
+---
+name: my-skill-name
+description: "Verb-first description of what the skill does and WHEN to use it. Include trigger phrases."
+---
+```
+
+**Rules for great frontmatter:**
+
+1. **Name**: lowercase, hyphenated, 2-4 words. Self-explanatory without reading the description.
+2. **Description**: Must answer TWO questions in a single sentence:
+   - What does this Skill **do**? (verb-first: "Diagnose...", "Write...", "Debug...")
+   - When should an agent **use** it? (situation triggers)
+3. **Trigger phrases**: Include exact words a user or agent would use.
+
+### Phase 4 — Write the Procedure
+
+Follow these writing principles:
+
+1. **Use imperative voice** ("Run this command", not "The agent should run")
+2. **Number the steps**
+3. **Include decision points inline**
+4. **Show exact commands**
+5. **Explain WHY alongside WHAT**
+6. **Include concrete thresholds** when applicable
+7. **Keep the Skill under 500 lines.**
+
+### Phase 5 — Write Anti-Patterns
+
+Good anti-patterns are:
+- **Named** (so they can be referenced in conversation)
+- **Grounded** in real experience
+- **Specific** about cost
+
+### Phase 6 — Write Validation and Escalation
+
+**Validation** answers: "How does the agent know the Skill worked?"
+**Escalation** answers: "When should the agent stop and ask for help?"
+
+Both must be concrete. Avoid "if something goes wrong" — specify *what*.
+
+---
+
+## Quality Audit Checklist
+
+| # | Check | Pass? |
+|---|-------|-------|
+| 1 | Frontmatter has verb-first description with trigger phrases | |
+| 2 | Scope clearly separates in-scope from out-of-scope | |
+| 3 | Inputs lists what the agent needs before starting | |
+| 4 | Procedure uses numbered steps with inline decision points | |
+| 5 | Procedure shows exact commands (not abstract descriptions) | |
+| 6 | Procedure explains WHY alongside WHAT | |
+| 7 | Validation has concrete commands with expected outputs | |
+| 8 | References points to related docs, tools, and Skills | |
+| 9 | Mental model names the core thinking pattern (if applicable) | |
+| 10 | Anti-patterns listed with names, costs, and alternatives | |
+| 11 | Escalation criteria are specific (not "if something goes wrong") | |
+| 12 | Under 500 lines (deeper content in references/) | |
+
+**Scoring:** 10-12 Excellent · 7-9 Good · 4-6 Needs work · 1-3 Stub
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ The Checklist Masquerading as a Skill
+**Symptom:** Skill is just a numbered list of commands with no decision logic.
+**Fix:** Add decision points, WHY explanations, and a mental model section.
+
+### ❌ The Encyclopaedia
+**Symptom:** Skill is 800+ lines and tries to cover every scenario.
+**Fix:** Keep SKILL.md under 500 lines. Put deep reference in `references/` files.
+
+### ❌ The Vague Oracle
+**Symptom:** Skill uses "use your judgment", "handle appropriately", "investigate as needed".
+**Fix:** Replace every vague phrase with a concrete criterion, threshold, or decision point.
+
+### ❌ The Island Skill
+**Symptom:** Skill doesn't reference any other Skills.
+**Fix:** Add an Integration section naming related Skills and when to chain them.
+
+### ❌ Trigger Poverty
+**Symptom:** Frontmatter has a generic description and 1-2 trigger phrases.
+**Fix:** Add 5-10 trigger phrases covering problem-phrasing, task-phrasing, domain terms, and error messages.
+
+---
+
+## Validation
+
+After writing a Skill:
+
+1. **Frontmatter search test:** Search for 3 different trigger phrases. Does the Skill appear?
+2. **Cold-start test:** Could an agent encountering this domain for the first time follow the Skill without asking for help?
+3. **Edge-case test:** Does the Skill handle the most common failure mode?
+4. **Audit checklist:** Score using the Quality Audit Checklist. Target 10+.
+
+## Escalation
+
+- If unsure whether to write a Skill vs. workflow vs. pattern: default to Skill if it requires judgment calls, workflow if it's a pure checklist
+- If the Skill's domain is unfamiliar: use `deep-research` first to build understanding
+
+## References
+
+- Skills directory: `docs/agi/skills/`
+- Exemplar Skills (study these):
+  - `docs/agi/skills/deep-research/SKILL.md` — authoritative, reasoning toolkit
+  - `docs/agi/skills/runaway-process-guard/SKILL.md` — tactical, guard-rail focused