@jaybeeuu/agent-cortex 1.20.0

package/docs/research/skill-design-research.md

@@ -0,0 +1,286 @@
+# Skill Design Research: Recommendations for agent-cortex
+
+This is a promoted research note.
+
+
+*Researched: 2026-05-26 — compares `mattpocock/skills` (commit b8be62f) against this repo's skills, cross-referenced with empirical prompt-engineering literature.*
+
+---
+
+## 1. Executive Summary
+
+Three parallel research streams were combined:
+
+1. **Structural analysis** of `mattpocock/skills` (14 active skills, authored by Matt Pocock)
+2. **Inventory** of the 31 skills in this repo (`agent-cortex`)
+3. **Literature review** of prompt/skill design research (Anthropic, Google, 10+ papers)
+
+The headline finding: **agent-cortex skills are well-structured but systematically over-long, under-exampled, and too passive in their body text.** The mattpocock repo is ahead on progressive disclosure, cross-skill composability, and opinionated philosophy. The research literature backs all three of those design choices.
+
+---
+
+## 2. Comparison: mattpocock/skills vs agent-cortex
+
+### 2.1 Structure
+
+| Dimension | mattpocock/skills | agent-cortex | Delta |
+|---|---|---|---|
+| YAML front-matter | `name`, `description`, optional `argument-hint`, `disable-model-invocation` | `name`, `description` | Missing 2 fields |
+| Description format | "What it does. Use when [natural-language triggers]." | Same — consistent | ✅ Aligned |
+| Body sections | No enforced schema; phase headers, checklists, philosophy, anti-patterns | No enforced schema; varies widely | Similar |
+| Typical SKILL.md length | 7–160 lines; strict 100-line soft cap | 29–169 lines; soft cap documented but not enforced | agent-cortex skews longer |
+| Progressive disclosure | `REFERENCE.md` + named supporting `.md` files linked inline | `REFERENCE.md` on 3 skills only | Under-used in agent-cortex |
+| Named supporting docs | `tests.md`, `mocking.md`, `ADR-FORMAT.md`, `CONTEXT-FORMAT.md`, `DEEPENING.md`, etc. | None — overflow goes to `REFERENCE.md` only | mattpocock more granular |
+| Checklists | Used as explicit phase gates (`- [ ]`) | Rare | Missing in agent-cortex |
+| Cross-skill references | Explicit inline calls: "run `/grill-with-docs`" | Implicit — no inline cross-refs | agent-cortex weaker |
+| Shared vocabulary file | `CONTEXT.md` at repo root; skills told to read it | None | Missing in agent-cortex |
+| Skill manifest | Flat JSON array of skill paths | Same | ✅ Aligned |
+| `disable-model-invocation` | Used for pure prompt-injection skills | Not used | Feature gap |
+| Missing SKILL.md | 0 | 1 (`prd-to-epics`) | Bug in agent-cortex |
+
+### 2.2 Tone and Voice
+
+| Dimension | mattpocock/skills | agent-cortex | Delta |
+|---|---|---|---|
+| Body voice | Imperative, 2nd person ("Read the full issue. Ask.") | Mixed — imperative in some, descriptive in others | Inconsistent in agent-cortex |
+| Emphasis style | **bold** for key decisions; minimal CAPS | Occasional ALL-CAPS (`CRITICAL`, `MUST`) | Over-emphasis in agent-cortex |
+| Conciseness | Punchy; no filler; "say it once" | Some skills have verbose rationale paragraphs | agent-cortex wordier |
+| Examples | Inline code blocks, before/after contrasts, XML output templates | Sparse — only a handful of skills include examples | agent-cortex under-exampled |
+| Philosophy | Explicitly baked in (Kent Beck references, banned practices with `DO NOT`) | Workflow-focused; philosophy largely absent | agent-cortex skips the "why" |
+| Anti-pattern sections | Common (`## Anti-Pattern:`, before/after code blocks) | Absent | Missing in agent-cortex |
+| Negative instructions | Mixed: "DO NOT write all tests first" (hard gate) + positive framing elsewhere | Heavy use of "do not", "never", "don't" | agent-cortex over-uses negatives |
+
+### 2.3 Description Field Quality
+
+Both repos follow the same two-part format: capability sentence + `"Use when..."`. The mattpocock descriptions tend to list *exact user vocabulary* (quoted phrases: `"diagnose this"`, `"let me play with it"`) which is more precise as a routing signal. agent-cortex descriptions are sometimes more abstract.
+
+**mattpocock example** (precise triggers):
+> "Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says 'diagnose this' / 'debug this', reports a bug, says something is broken/throwing/failing, or describes a performance regression."
+
+**agent-cortex example** (vaguer triggers):
+> "Create a bead, classify it, and if AFK expand it into pipeline stage child beads plus a HITL PR gate task. Use when creating a new task that should be tracked and moved through implementation and human review gates."
+
+The agent-cortex description describes internal mechanics rather than what the user is trying to accomplish.
+
+---
+
+## 3. Evidence-Backed Recommendations
+
+### Rec 1 — Progressive Disclosure: Split overlong skills
+
+**Evidence**: Anthropic Claude Code best practices: *"Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"* LIMA (Zhou et al., NeurIPS 2023) confirms quality beats quantity — 1,000 curated examples matched GPT-4; adding more degraded focus. Schulhoff et al. (ACL 2024, arXiv:2406.06608) found structure + clarity most consistently effective across 58 techniques.
+
+**Current state**: 11 of 28 agent-cortex skills exceed 100 lines (`run-beads` is 169, `style-code` 151). Only 3 have `REFERENCE.md`.
+
+**Recommendation**: Split all skills over ~100 lines. Prefer *named, purpose-specific files* over a catch-all `REFERENCE.md`:
+- `REFERENCE.md` — rarely-needed edge cases
+- `EXAMPLES.md` — worked examples (if multiple)
+- `FORMAT.md` — output schemas / templates
+- `WORKFLOW.md` — detailed step expansions
+
+Candidates to split immediately: `run-beads`, `style-code`, `tdd`, `ralph`.
+
+---
+
+### Rec 2 — Consistent Imperative Voice in Skill Bodies
+
+**Evidence**: The "26 Principles" paper (Bsharat et al., arXiv:2312.16171, VILA Lab 2024) tested 26 prompting principles on GPT-3.5/4 and LLaMA, finding an average **57.7% quality improvement** on GPT-4. Direct command framing (Principle 16) and specificity (Principle 5) had the largest gains on large models. Anthropic explicitly: *"treat the model as a brilliant but new employee who lacks context on your norms"* — this framing implies 2nd-person imperative.
+
+**Current state**: agent-cortex mixes voices. Some skills are tight and imperative (`review-security`); others narrate what the skill *will* do rather than commanding the agent to do it.
+
+**Recommendation**:
+- Skill body: imperative, 2nd person. "Run `gitleaks protect --staged`", not "The skill runs gitleaks."
+- Description field: third-person declarative. "Scans git changes for secrets."
+- Remove all-caps emphasis (`CRITICAL`, `MUST`). Anthropic Claude Code notes: *"Where you might have said 'CRITICAL: You MUST use this tool when...', you can use more normal prompting like 'Use this tool when...'"* — over-emphasis backfires with modern models.
+
+---
+
+### Rec 3 — Replace Negative Instructions with Positive Framing
+
+**Evidence**: Anthropic Prompting Best Practices gives an explicit side-by-side:
+> ❌ `"Do not use markdown in your response"`
+> ✅ `"Your response should be composed of smoothly flowing prose paragraphs."`
+
+The "26 Principles" paper lists "affirmative instructions, no 'don't'" as Principle 3 with consistent cross-model gains. Mechanistically, negative instructions require the model to hold a prohibited concept in working memory and suppress it — more error-prone than activating the desired pattern directly.
+
+**Current state**: agent-cortex skills have frequent negative phrasing: "Do not work a HITL bead", "Don't commit without scanning", "Never use relative paths."
+
+**Recommendation**:
+
+| Instead of | Use |
+|---|---|
+| "Do not work a HITL bead" | "Inform the user it requires human action and stop" |
+| "Never use relative paths" | "Use absolute paths — agents may change CWD mid-session" |
+| "Don't commit without scanning" | "Always run `review-security` before committing" |
+
+Reserve "do not" for hard correctness/safety constraints that genuinely need an explicit backstop. For stylistic preferences, positive framing only.
+
+---
+
+### Rec 4 — Include Rationale for Non-Obvious Rules
+
+**Evidence**: Anthropic best practices: *"Providing context or motivation behind your instructions, such as explaining why such behavior is important, can help Claude better understand your goals and deliver more targeted responses. Claude is smart enough to generalize from the explanation."* Chain-of-Thought (Wei et al., NeurIPS 2022, arXiv:2201.11903) showed that *reasoning traces* — not just input→output — dramatically outperform bare instructions. The "26 Principles" paper Principles 2 and 5 (explain purpose, specify stakes) were among the highest-impact on GPT-4.
+
+**Current state**: agent-cortex skills state rules but rarely explain them. A reader (or agent) encountering "Use absolute paths" won't know why.
+
+**Recommendation**: Add one-sentence rationale for any non-obvious rule. Pattern:
+
+```markdown
+Use absolute paths — agents may change CWD mid-session, breaking relative references.
+```
+
+Do **not** write paragraphs of rationale. One sentence is enough; the model generalises from it.
+
+---
+
+### Rec 5 — Add Worked Examples to Key Skills
+
+**Evidence**: Chain-of-Thought (Wei et al., NeurIPS 2022): *"prompting a 540B-parameter language model with just 8 chain-of-thought exemplars achieves state-of-the-art accuracy on GSM8K, surpassing even fine-tuned GPT-3."* Anthropic: *"A few well-crafted examples can dramatically improve accuracy and consistency."* Recommendation: 3–5 examples, wrapped in `<example>` tags, covering diverse cases. APE (Zhou et al., ICLR 2023, arXiv:2211.01910) found example-seeded instructions outperformed hand-written instructions on 19/24 tasks. Selective Annotation (Su et al., arXiv:2209.01975) showed *diverse* examples give a 12.9% relative gain over random ones.
+
+**Current state**: most agent-cortex skills have no worked examples. `run-beads` has a `---REPORT---` output template; `review-security` shows exact commands. These are the strongest skills.
+
+**Recommendation**: For each skill, identify what the agent produces as output and include 1 complete worked example. For CLI-heavy skills, show exact commands with substitution markers. For decision-heavy skills, add a decision table.
+
+```markdown
+## Example Output
+
+---REPORT---
+Bead: bd-42 "Add login page"
+Status: ✅ done
+PR: https://github.com/org/repo/pull/99
+---
+```
+
+Extract to `EXAMPLES.md` if more than ~30 lines.
+
+---
+
+### Rec 6 — Add Explicit Phase Gates (Checklists)
+
+**Evidence**: Schulhoff et al. (ACL 2024) found structured verification steps consistently reduce hallucination and task-deviation. Anthropic Building Effective Agents: *"Give Claude a way to verify its work."* The mattpocock `diagnose` and `tdd` skills use `- [ ]` checklists as explicit gates between phases — the agent cannot proceed without the checklist being satisfied.
+
+**Current state**: agent-cortex multi-phase skills (`ralph`, `run-beads`, `tdd`) describe phases in prose but have no explicit verification gates.
+
+**Recommendation**: For any multi-phase skill, add a short checklist at the end of each phase:
+
+```markdown
+## Phase 1 — Explore
+
+- Read the bead description and all linked files
+- Identify the affected modules
+- [ ] Can you describe the change in one sentence?
+- [ ] Do you know which files will change?
+
+Move to Phase 2 only when both boxes are checked.
+```
+
+---
+
+### Rec 7 — Sharpen Description Trigger Vocabulary
+
+**Evidence**: Anthropic Building Effective Agents: *"Think of this as writing a great docstring for a junior developer on your team."* For agents, descriptions are the only routing signal. FLAN (Wei et al., ICLR 2022) showed instruction-tuned models generalise from natural language task descriptions — use the vocabulary a user would *actually speak*, not internal system jargon. Anthropic tool use note: `"Use when"` language *actively counteracts* the model's default tendency to solve problems without invoking tools.
+
+**Current state**: some agent-cortex descriptions describe internal mechanics rather than user intent. E.g., `create-task`: *"Use when creating a new task that should be tracked and moved through implementation and human review gates"* — references internal workflow terms a user wouldn't say.
+
+**Recommendation**: Rewrite descriptions to lead with user-vocabulary triggers. Include 2–4 quoted phrases or scenario patterns a user might say:
+
+```yaml
+description: >
+  Break a piece of work into a tracked task with a full implementation pipeline.
+  Use when the user says "create a task", "let's track this", "add a bead", "file this 
+  as a ticket", or wants to turn a conversation into actionable work.
+```
+
+---
+
+### Rec 8 — Establish Composability via Explicit Cross-References
+
+**Evidence**: Anthropic Building Effective Agents promotes "orchestration" patterns where agents compose tools rather than re-implementing logic. mattpocock's skills reference each other by name inline (e.g., "run `/grill-with-docs`"), creating a composable skill library. Meta-prompting (Suzgun et al., arXiv:2401.12954) found high-level orchestration instructions (+17.1%) outperform monolithic step-by-step skills.
+
+**Current state**: agent-cortex skills are largely self-contained monoliths. `ralph` calls `run-beads` but this is the only explicit cross-reference.
+
+**Recommendation**: Where a skill currently duplicates logic from another skill, replace the duplication with an explicit invocation: *"Run the `review-security` skill before committing."* Document the skill dependency graph informally in `AGENTS.md`.
+
+---
+
+### Rec 9 — Add `argument-hint` to Input-Driven Skills
+
+**Evidence**: Anthropic tool design (Building Effective Agents, Appendix 2): *"Is it obvious how to use this tool? ... This is especially important when using many similar tools."* The `argument-hint` front-matter field (present in mattpocock's plugin schema) surfaces a prompt to the user at invocation time — preventing input ambiguity before the skill runs.
+
+**Current state**: agent-cortex plugin schema doesn't include `argument-hint`. Skills like `write-a-ticket`, `run-beads` take implicit input that could benefit from a hint.
+
+**Recommendation**: Add `argument-hint` support to `plugin.json` schema and add hints to skills that take input:
+
+```yaml
+argument-hint: "Describe the bug or paste the error message"
+```
+
+---
+
+### Rec 10 — Fix prd-to-epics Missing SKILL.md
+
+**Current state**: `skills/prd-to-epics/` directory exists in the repo but has no `SKILL.md`. It cannot be invoked.
+
+**Recommendation**: Either write the missing `SKILL.md` or remove the directory. This is a straightforward bug.
+
+---
+
+## 4. Prioritised Change List
+
+| Priority | Change | Effort | Evidence strength |
+|---|---|---|---|
+| P0 | Fix missing `prd-to-epics/SKILL.md` | Low | N/A — broken |
+| P1 | Split skills > 100 lines (7 candidates) | Medium | Strong — Anthropic production data |
+| P1 | Convert negative instructions to positive framing | Low | Strong — 26 Principles paper, Anthropic |
+| P1 | Sharpen description trigger vocabulary (use user-vocab) | Low | Strong — FLAN, Anthropic tool use docs |
+| P2 | Add imperative voice to passive skill bodies | Medium | Strong — 26 Principles paper |
+| P2 | Remove ALL-CAPS emphasis | Low | Medium — Anthropic Claude Code guide |
+| P2 | Add 1-sentence rationale to non-obvious rules | Low | Strong — CoT, 26 Principles |
+| P2 | Add worked examples to output-producing skills | Medium | Strong — Wei et al. CoT, Anthropic |
+| P3 | Add phase-gate checklists to multi-phase skills | Medium | Medium — Schulhoff survey, mattpocock pattern |
+| P3 | Add explicit cross-skill references | Low | Medium — Meta-prompting paper |
+| P3 | Add `argument-hint` support and populate | Medium | Medium — Anthropic tool design |
+
+---
+
+## 5. What mattpocock Does That We Should Consider Adopting Wholesale
+
+These are patterns present in `mattpocock/skills` that have no equivalent here and are backed by evidence:
+
+1. **`CONTEXT.md` at repo root** — a shared domain glossary that all skills read. Prevents terminology drift across skills and gives the agent grounding in project domain terms. (The `grill-with-docs` skill builds this automatically.)
+
+2. **Philosophy sections in skills** — `tdd` doesn't just describe TDD, it argues *why* horizontal slicing is wrong. This bakes intent into the skill so the agent handles novel cases correctly (backed by CoT rationale evidence).
+
+3. **`disable-model-invocation: true`** — for skills that *are* the prompt (pure injection, no interpretation). Prevents the model from summarising/transforming the skill content before executing it.
+
+4. **Composability by design** — skills reference each other by slash-command inline. This keeps each skill shorter and creates a network of reusable primitives rather than monolithic blobs.
+
+---
+
+## 6. What We Do Well That mattpocock Doesn't
+
+1. **Richer plugin manifest** — MCP server declarations, richer metadata.
+2. **Bundled scripts** — `run-beads`, `create-task`, `review-security`, `record-idea` all include deterministic scripts that reduce regeneration of boilerplate. mattpocock has this for `diagnose` and `git-guardrails` only.
+3. **Task tracking integration** — `bd` / beads integration is deeply embedded across skills; mattpocock uses GitHub Issues directly without an equivalent agent-native tracker.
+4. **HITL/AFK distinction** — explicitly modelled and surfaced in `run-beads`, `classify-bead`, etc. mattpocock's `to-issues` introduces the concept but doesn't enforce it system-wide.
+
+---
+
+## Sources
+
+| Source | Key Findings Used |
+|---|---|
+| Anthropic Prompting Best Practices | Positive framing, numbered steps, XML tags, 3–5 examples, rationale inclusion, query placement (+30%) |
+| Anthropic Building Effective Agents | Tool documentation = system prompt importance; ACI design; poka-yoke; verification criteria |
+| Anthropic Claude Code Best Practices | Conciseness critical; bloated files → ignored rules; positive examples > negative instructions; no ALL-CAPS |
+| Google Vertex AI Clear Instructions | Specificity + constraints → precise output |
+| Bsharat et al. (2024) arXiv:2312.16171 | 26 prompting principles; avg +57.7% quality / +36.4% correctness on GPT-4 |
+| Wei et al. (2022) arXiv:2201.11903 (CoT) | 8 CoT examples beat fine-tuned models; reasoning traces > bare instructions |
+| Wei et al. (2021) arXiv:2109.01652 (FLAN) | Natural-language commands generalise better than passive descriptions |
+| Zhou et al. (2022) arXiv:2211.01910 (APE) | Example-seeded instructions beat human instructions on 19/24 tasks |
+| Zhou et al. (2023) arXiv:2305.11206 (LIMA) | 1,000 curated examples ≈ GPT-4 quality; quality >> volume |
+| Suzgun et al. (2024) arXiv:2401.12954 | High-level orchestration +17.1% vs standard prompting |
+| Schulhoff et al. (2024) arXiv:2406.06608 | ACL survey of 58 techniques; structure + clarity most consistently effective |
+| mattpocock/skills (commit b8be62f) | Structural reference; progressive disclosure; composability; checklists |
+
+[Inspirations](../inspirations.md)

package/docs/research/skill-improvements-analysis.md

@@ -0,0 +1,117 @@
+# Skill Improvements: Lessons from addyosmani/agent-skills
+
+This is a promoted research note.
+
+
+> Source: https://github.com/addyosmani/agent-skills  
+> Reviewed: 2026-05-26
+
+## Summary
+
+Compared our skills with addyosmani/agent-skills across structure, tone, and evidence-backed
+patterns. Their skills are consistently richer (200–350 lines vs our 50–170), follow a strict
+shared skeleton, and include several patterns backed by LLM research that we currently lack.
+
+---
+
+## What they do that we don't
+
+### 1. "Common Rationalizations" table
+
+Every skill includes a table debunking common excuses for not following it:
+
+| Rationalization | Reality |
+|---|---|
+| "Tests slow me down" | Tests slow you now. They speed you up every change later. |
+
+**Evidence**: LLM sycophancy research (Perez et al.; Anthropic Constitutional AI) shows models
+rationalise away inconvenient instructions. Naming these in the prompt preemptively counters
+the behaviour.
+
+---
+
+### 2. "When NOT to use" sections
+
+Every skill explicitly states when _not_ to invoke it:
+
+> "When NOT to use: Single-line fixes, typo corrections, or changes where requirements are
+> unambiguous and self-contained."
+
+**Evidence**: Wang et al. (SuperNaturalInstructions, 2022) — explicit out-of-scope boundaries
+reduce false-positive invocations and improve precision.
+
+---
+
+### 3. "Red Flags" list
+
+Concrete, detectable anti-patterns named inline:
+
+- "Bug fixes without reproduction tests"
+- "Tests that pass on the first run"
+
+**Evidence**: Contrastive examples (positive + negative) improve instruction adherence. Naming
+failure modes alongside correct behaviour helps models self-correct.
+
+---
+
+### 4. Verification checklists at the end
+
+Every skill ends with a checkbox list:
+
+```
+- [ ] Every new behavior has a corresponding test
+- [ ] All tests pass: `npm test`
+```
+
+**Evidence**: Wei et al. (Chain-of-Thought, 2022) — decomposing into explicit steps reduces
+omission errors and improves task completion reliability.
+
+---
+
+### 5. Concrete code/output examples
+
+Skills show realistic before/after examples, not just abstract descriptions.
+
+**Evidence**: Brown et al. (GPT-3, 2020) — few-shot examples consistently outperform abstract
+prose descriptions for in-context learning.
+
+---
+
+### 6. 100-line limit is too restrictive
+
+Our `write-a-skill` caps SKILL.md at 100 lines. The addyosmani skills are 200–350 lines and
+their richness (rationalizations, red flags, examples, checklists) directly follows from that
+budget. The constraint is working against us.
+
+**Proposed change**: "prefer under 150 lines; overflow rarely-needed reference detail into
+REFERENCE.md" — keeping SKILL.md as the primary working document rather than gutting it.
+
+---
+
+## What we do better
+
+- **Workflow depth**: `run-beads` + `ralph` encode a full pipeline (test-writing → coding →
+  verifying → reviewing → fixing → documenting) that the external skills can't match.
+- **Philosophy**: `tdd` has a more rigorous treatment of vertical slicing and horizontal-slice
+  anti-patterns than the external TDD skill.
+- **Domain specificity**: our skills are tightly integrated with `bd`, worktrees, and the ralph
+  orchestrator — that's genuine value the external repo can't offer.
+- **Progressive disclosure**: `REFERENCE.md` + `EXAMPLES.md` support already documented.
+
+---
+
+## Bead IDs
+
+| Improvement | Status |
+|---|---|
+| Common Rationalizations tables | Planned |
+| When NOT to use sections | Planned |
+| Red Flags sections | Planned |
+| Verification checklists | Planned |
+| Concrete examples | Planned |
+| Reconsider 100-line limit | Done (raised to 150) |
+| ASCII workflow diagrams | Not yet |
+| Cross-references between skills | Planned |
+| Consistent skeleton template | Partially adopted |
+
+[Inspirations](../inspirations.md)

package/docs/research/skill-patterns-research.md

@@ -0,0 +1,24 @@
+# Skill Pattern Research Notes
+
+A promoted research note collecting evidence behind recurring skill structure patterns.
+
+## Patterns and evidence
+
+1. **Explicit scope boundaries improve instruction following**
+   - Super-NaturalInstructions (Wang et al., 2022): broad, explicit instruction framing improves task generalization.
+2. **Concrete examples outperform abstract-only guidance**
+   - GPT-3 paper (Brown et al., 2020): few-shot examples consistently improve downstream behavior.
+3. **Checklists reduce skipped steps**
+   - Chain-of-Thought prompting (Wei et al., 2022): structured intermediate prompts improve completion reliability.
+4. **Constrained behavior framing lowers unsafe compliance**
+   - Constitutional AI (Bai et al., 2022) and sycophancy analyses (Perez et al., 2022): explicit refusal/constraint framing improves adherence.
+
+## References
+
+- https://arxiv.org/abs/2204.02311
+- https://arxiv.org/abs/2005.14165
+- https://arxiv.org/abs/2201.11903
+- https://arxiv.org/abs/2212.08073
+- https://arxiv.org/abs/2211.03873
+
+[Inspirations](../inspirations.md)

package/docs/skills/skill-anatomy.md

@@ -0,0 +1,149 @@
+# Skill Anatomy
+
+This document is the **canonical skill anatomy** for `agent-cortex` skills.
+Use it as the source of truth for `SKILL.md` structure, language, and review quality gates.
+
+## Front-matter spec
+
+Required fields:
+- `name`: kebab-case skill identifier.
+- `description`: max 1024 characters.
+
+Optional fields:
+- `argument-hint`: input prompt shown to users at invocation.
+- `disable-model-invocation`: for deterministic prompt-injection skills that should not be summarized/interpreted.
+
+## Description format rules
+
+- Target ≤200 characters even though max is 1024.
+- Write in third-person declarative voice.
+- Sentence 1: what the skill does.
+- Sentence 2: starts with `Use when ...`.
+- Include 2-4 natural user trigger phrases (quoted) such as "diagnose this" or "something is broken".
+- Prefer user vocabulary over internal jargon.
+
+## Voice and tone rules
+
+- Write the body in imperative second-person: "Run X", "Check Y", "Report Z".
+- Use positive framing; reserve "do not" only for hard safety/correctness boundaries.
+- Add one rationale sentence for non-obvious rules so behavior generalizes in novel cases.
+- Avoid ALL-CAPS emphasis.
+
+## Required sections
+
+Every skill must include:
+1. `## When to use`
+2. `## Workflow` (numbered steps)
+3. `## Verification checklist` (`- [ ]` items)
+
+## Optional sections
+
+For each optional section, define **what it is**, include an **example snippet**, and state **when to include** and **when to omit**.
+
+| Section | What it is | Example snippet | When to include | When to omit |
+|---|---|---|---|---|
+| `When NOT to use` | Explicit out-of-scope invocation boundaries | `- When NOT to use: single-line typo fixes with no process risk.` | Skills with similar neighbors where invocation precision matters | Truly unique one-purpose utility skills |
+| `Red Flags` | Detectable anti-patterns the agent should self-correct during execution | `- Red flag: skipping boundary validation to save time.` | Discipline-enforcement skills (security, TDD, review) | Simple utility wrappers |
+| `Common Rationalizations` | Excuses models use to skip process with rebuttals | `| "This is small" | Small changes still need invariants checked. |` | Process-critical skills where shortcut pressure is common | Mechanical one-step skills |
+| `Philosophy / rationale` | Why the method exists and what trade-offs it protects | `- We front-load validation because downstream rollback cost is higher.` | Opinionated skills expected to handle novel variants | Purely mechanical instructions |
+| `Phase-gate checklists` | Mid-workflow gates that must pass before proceeding | `- [ ] Phase 1 complete: baseline tests captured.` | Multi-phase workflows (3+ distinct phases) | Linear single-phase tasks |
+| `Cross-skill references` | Explicit delegation to another skill for a real sub-task | `- Run \\`review-security\\` before committing.` | Another skill owns a sub-domain better than restating it | Self-contained skills |
+| `Examples` | Full worked sample of expected outcome/output | `- Input: ... Output: ...` | Any non-trivial output contract | Trivially self-evident skills |
+
+## Section ordering
+
+### When to use
+
+State concrete invocation triggers using natural language phrases users actually type.
+
+### When NOT to use
+
+Place this section immediately after `When to use` whenever present.
+
+### Workflow
+
+Provide ordered, deterministic steps with observable outcomes.
+
+### Verification checklist
+
+Provide completion gates that are testable and stage-scoped.
+
+## File layout and progressive disclosure
+
+- Target ~150 lines for `SKILL.md`.
+- Split long docs into purpose-named support files:
+  - `EXAMPLES.md` for worked examples.
+  - `FORMAT.md` for schemas/templates.
+  - `REFERENCE.md` for rare edge cases.
+- Use slash-command references when another skill should be invoked.
+
+## Acceptance criteria checklist
+
+A skill passes anatomy review when:
+- [ ] Front matter uses required fields and valid description format.
+- [ ] Required sections exist and follow canonical ordering.
+- [ ] Optional sections (if present) include what/when/example guidance.
+- [ ] Verification checklist contains concrete, machine-checkable items.
+- [ ] Supporting docs are split by purpose when `SKILL.md` would exceed ~150 lines.
+
+## Annotated template
+
+```md
+---
+name: skill-name
+description: This skill performs a specific capability. Use when a user asks for a matching workflow such as "triage this", "investigate this", or "prepare a handoff".
+argument-hint: Optional prompt shown to users when extra input is needed.
+disable-model-invocation: false
+---
+
+# Skill Name
+
+## When to use
+
+- Trigger phrases users actually say, e.g. "triage this failure".
+- Include 2-4 concrete patterns.
+
+## When NOT to use
+
+- Out-of-scope cases that should route elsewhere.
+
+## Workflow
+
+1. Gather required context and validate scope boundaries.
+2. Execute deterministic steps in order, recording key decisions.
+3. Produce the required output artifact or terminal response.
+
+## Red Flags
+
+- Red flag: skipping validation of unknown external input.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This is too small for process" | Process protects against regressions regardless of size. |
+
+## Philosophy / rationale
+
+- We optimize for explicit boundaries because they reduce rework and improve reliability.
+
+## Phase-gate checklist
+
+- [ ] Phase 1 complete and baseline checks captured.
+- [ ] Phase 2 complete and contract validation passed.
+
+## Cross-skill references
+
+- Run `review-security` before committing any externally exposed change.
+
+## Examples
+
+Input: "Investigate this flaky suite"
+Output: concise root-cause summary, failing tests list, and next action.
+
+## Verification checklist
+
+- [ ] Output matches requested format.
+- [ ] Required tests/lints were run and results recorded.
+- [ ] No unrelated files were changed.
+```

package/docs/user-preferences.md

@@ -0,0 +1,17 @@
+# User Preferences
+
+This file records personal development preferences for the author (**jaybeeuu**).
+Both Copilot CLI agents and PI coding agents should read this file for user-level
+context when making tooling and workflow decisions.
+
+## Package manager
+
+| Preference | Value |
+|---|---|
+| **Preferred tool** | **PNPM** (`pnpm`) over npm (`npm`) |
+| Rationale | Faster installs, disk-efficient with content-addressable store, stricter dependency resolution, and built-in workspace support. |
+| Impact | Use `pnpm` for installs, script execution, and package management. Use `pnpm dlx` instead of `npx`. Do not suggest `npm install` or `npx` unless the project explicitly uses npm. |
+
+## Future preferences
+
+Add new preferences below as they are established.