claude-dev-env 1.0.0

package/skills/prompt-generator/REFERENCE.md

@@ -0,0 +1,150 @@
+# Prompt generator -- reference
+
+## Canonical resources
+
+When authoring or refining prompts, ground decisions in these sources. If guidance conflicts, defer to the higher tier.
+
+### Tier 1: Anthropic (primary authority for Claude)
+
+- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview -- overview, links to all sub-guides
+- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices -- the single living reference for Claude's latest models. Covers general principles, XML tags, prefill deprecation, tool use, thinking, agentic systems, overeagerness, anti-hallucination.
+- https://transformer-circuits.pub/2026/emotions/index.html -- emotion concepts research (April 2026): 171 internal activation patterns that causally influence behavior. Key prompt-engineering takeaways: clear criteria and escape routes improve output quality, collaborative framing activates engagement, positive task framing correlates with better results, inviting transparency produces more reliable output. Cross-model caveat: studied on Sonnet 4.5; patterns align with best practices independently.
+- https://www.anthropic.com/research/emotion-concepts-function -- blog summary of the above paper.
+- https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking -- adaptive thinking reference; replaces manual budget_tokens with effort-based control.
+
+### Tier 2: Major labs (strong secondary, often transfers across models)
+
+- https://platform.openai.com/docs/guides/prompt-engineering -- six strategies: write clear instructions, provide reference text, split complex tasks, give models time to think, use external tools, test systematically.
+- https://deepmind.google/research/ -- learning resources and chain-of-thought research.
+- https://www.microsoft.com/en-us/research/blog/ -- publications and applied research.
+
+### Tier 3: Courses, communities, individuals (supplementary)
+
+**Courses:**
+
+- https://www.deeplearning.ai/short-courses/ -- Andrew Ng's courses. "ChatGPT Prompt Engineering for Developers" (with OpenAI) is the foundational one.
+- https://course.fast.ai/ -- Jeremy Howard's top-down teaching style.
+- https://www.elementsofai.com/ -- University of Helsinki introductory course.
+- https://ocw.mit.edu/search/?t=Artificial%20Intelligence -- MIT OpenCourseWare AI curriculum.
+
+**Communities and individuals:**
+
+- https://discuss.huggingface.co/ -- open-source model community.
+- https://www.latent.space/ -- AI engineering perspective (Latent Space Podcast & Newsletter).
+- https://simonwillison.net/ -- practical LLM experiments. His "LLM" tag is especially valuable.
+
+### Conflict resolution rule
+
+If sources disagree on a technique, apply in order: Anthropic documentation first (it describes the actual model behavior), then OpenAI/Google/Microsoft (large-scale research with cross-model relevance), then community sources (patterns and intuition, not authoritative on model internals). When Tier 3 contradicts Tier 1, Tier 1 wins without exception.
+
+## NotebookLM Audio Overview customization (example)
+
+Adapt `[FOCUS AREA]` per notebook. Pair with Deep Dive + Longer in the product UI when that matches the user's plan.
+
+```text
+Target audience: [Expert-level listener profile -- skip beginner padding.]
+
+Focus: [FOCUS AREA -- single notebook-specific paragraph.]
+
+Style: [Technical depth, anti-patterns, implications for builders.]
+
+Prioritize: [Technical depth and specific findings over marketing tone or generic summaries.]
+```
+
+## Agent checklist pattern
+
+For long tasks, optional checklist the model can mirror:
+
+```text
+Copy this checklist and mark items as you go:
+
+Progress:
+- [ ] ...
+- [ ] ...
+```
+
+## Agentic state management
+
+For `agent-harness` prompts that span multiple context windows, include state persistence and multi-window patterns. Based on Anthropic's guidance:
+
+### Context awareness
+
+Claude 4.6 tracks its remaining context window. Include harness capabilities so Claude can plan accordingly:
+
+```text
+<context_management>
+Your context window will be automatically compacted as it approaches its limit, allowing you to continue working indefinitely from where you left off. Do not stop tasks early due to token budget concerns. As you approach the limit, save current progress and state before the context window refreshes. Always be as persistent and autonomous as possible and complete tasks fully.
+</context_management>
+```
+
+### Multi-window workflow
+
+Anthropic recommends differentiating the first context window from subsequent ones:
+
+**First window:** Set up the framework -- write tests, create setup scripts, establish the todo-list.
+
+**Subsequent windows:** Iterate on the todo-list, using state files to resume.
+
+Key patterns from Anthropic:
+- Have the model write tests in a **structured format** (e.g. `tests.json` with `{id, name, status}`) before starting work. Remind: "It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality."
+- Encourage **setup scripts** (e.g. `init.sh`) to start servers, run test suites, and linters. This prevents repeated work across windows.
+- When starting fresh, be **prescriptive about resumption**: "Review progress.txt, tests.json, and the git logs."
+- Provide **verification tools** (Playwright, computer use) for autonomous UI testing.
+
+### State tracking
+
+```text
+<state_management>
+Track progress in structured + freeform files:
+- tests.json: structured test status {id, name, status}
+- progress.txt: freeform session notes and next steps
+- Use git commits as checkpoints for rollback
+
+When approaching context limits, save current state before the window refreshes.
+Do not stop tasks early due to token budget concerns.
+</state_management>
+```
+
+### Encouraging complete context usage
+
+```text
+This is a very long task, so it may be beneficial to plan out your work clearly. It's encouraged to spend your entire output context working on the task - just make sure you don't run out of context with significant uncommitted work. Continue working systematically until you have completed this task.
+```
+
+## Research prompt pattern
+
+For `research` prompt types, include structured investigation with hypothesis tracking:
+
+```text
+<research_approach>
+Search for this information in a structured way. As you gather data, develop several competing hypotheses. Track your confidence levels in your progress notes to improve calibration. Regularly self-critique your approach and plan. Update a hypothesis tree or research notes file to persist information and provide transparency. Break down this complex research task systematically.
+</research_approach>
+```
+
+Key elements:
+- Define clear **success criteria** for the research question
+- Encourage **source verification** across multiple sources
+- Track **competing hypotheses** with confidence levels
+- **Self-critique** approach and plan regularly
+
+## Evaluation loop
+
+For prompt drafts that must hold up over time:
+
+1. Run the draft on 2-3 representative user utterances.
+2. Note failure modes (skipped steps, wrong format, over-refusal).
+3. Tighten **constraints** or add **examples** for the failure class only.
+
+Anthropic's **self-correction chaining** pattern extends this: generate a draft, have Claude review it against criteria, then have Claude refine based on the review. Each step can be a separate API call for inspection and branching.
+
+## Anti-test-fixation pattern
+
+```text
+Write general-purpose solutions using the standard tools available. Implement logic that works correctly for all valid inputs, not just the test cases. Tests verify correctness -- they do not define the solution. If a test seems incorrect or the task is unreasonable, flag it rather than working around it.
+```
+
+## Commit-and-execute pattern
+
+```text
+When deciding how to approach a problem, choose an approach and commit to it. Avoid revisiting decisions unless you encounter new information that directly contradicts your reasoning. If you are weighing two approaches, pick one and see it through. You can always course-correct later if the chosen approach fails.
+```

package/skills/prompt-generator/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: prompt-generator
+description: >-
+  Write, generate, or improve prompts and system instructions for Claude.
+  Covers system prompts, agent harness, tool-use, evaluation rubrics,
+  NotebookLM audio, and MCP/browser automation prompts.
+---
+@~/.claude/skills/prompt-generator/REFERENCE.md
+
+# Prompt generator
+
+**Core principle:** A good prompt is explicit, structured, and matched to task fragility -- high freedom for open-ended work, low freedom for fragile sequences.
+
+**Canonical source:** https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices -- the single reference for Claude's latest models. When sources conflict, defer to the authority tiers (Anthropic > major labs > community).
+
+## When this skill applies
+
+Trigger for any request to **author** or **refine** text that steers Claude: system prompts, developer messages, agent harness instructions, evaluation rubrics, MCP/browser automation prompts, NotebookLM Audio Overview customization, etc.
+
+Do **not** use this skill when the user only wants a one-line reply with no template.
+
+When invoked with arguments (e.g. `/prompt-generator improve this: [paste]`), treat `$ARGUMENTS` as the prompt to refine.
+
+## Workflow (run in order)
+
+### 1. Classify the prompt type
+
+Pick one primary: `system` | `user-task` | `agent-harness` | `tool-use` | `audio-customization` | `evaluation` | `research` | `other`.
+
+### 2. Set degree of freedom
+
+Match specificity to task fragility:
+- **High:** Multiple valid approaches; use numbered goals and acceptance criteria.
+- **Medium:** Preferred pattern exists; use pseudocode or a parameterised template.
+- **Low:** Fragile or safety-critical; use exact steps, exact labels, and "do not" boundaries.
+
+### 3. Collect only missing facts
+
+Ask 1-3 short questions if needed: audience, output format, constraints, tools available, tone, length.
+
+### 4. Build the prompt
+
+Apply these principles (source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices):
+
+**Structure with XML section tags** (`<role>`, `<context>`, `<instructions>`, `<constraints>`, `<examples>`, `<output_format>`) for prompts that mix instruction + context + examples. Skip XML for simple prompts under ~3 lines. Anthropic: "Use consistent, descriptive tag names across your prompts. Nest tags when content has a natural hierarchy."
+
+**Set a role** in the system prompt. Anthropic: "Setting a role in the system prompt focuses Claude's behavior and tone for your use case. Even a single sentence makes a difference."
+
+**Add motivation behind constraints** in `<context>`. Anthropic: "Providing context or motivation behind your instructions... can help Claude better understand your goals and deliver more targeted responses." Claude generalizes from the explanation.
+
+**Frame positively.** Anthropic: tell Claude what to DO, not only what to avoid. "Your response should be composed of smoothly flowing prose paragraphs" beats "Do not use markdown."
+
+**Emotion-informed framing.** Anthropic's emotion concepts research (2026) found that internal activation patterns causally influence output quality. Five patterns apply to prompt design: (1) provide clear criteria and escape routes — the model produces better results when success criteria are explicit and "say so if you're unsure" is an accepted response; (2) use collaborative framing — collaborative language ("help figure out", "work on this together") activates engagement states that correlate with higher quality; (3) frame tasks with positive engagement — presenting tasks as interesting problems activates curiosity states; (4) invite transparency — include "say so if you're unsure" or placeholder notation so the model expresses uncertainty directly; (5) use constructive, forward-looking tone — post-training RLHF creates a reflective default that benefits from energetic counterbalancing. Cross-model caveat: studied on Sonnet 4.5; the patterns align with Anthropic's best practices independently.
+
+**Golden rule check.** Anthropic: "Show your prompt to a colleague with minimal context on the task and ask them to follow it. If they'd be confused, Claude will be too."
+
+**Commit-and-execute pattern.** Anthropic: "When you're deciding how to approach a problem, choose an approach and commit to it. Avoid revisiting decisions unless you encounter new information that directly contradicts your reasoning." For prompts that guide agents through multi-step work, include this pattern so the agent doesn't spin revisiting decisions.
+
+**For long context** (20k+ tokens): put documents first, query/instructions last. Anthropic: "Queries at the end can improve response quality by up to 30% in tests." Ground responses in quotes from source material before analysis.
+
+### 5. Control output format
+
+Apply these four techniques from the Anthropic guide:
+
+1. **Tell Claude what to do, not what to avoid.** "Your response should be composed of smoothly flowing prose paragraphs" is more effective than "Do not use markdown."
+2. **Use XML format indicators.** "Write the prose sections of your response in `<smoothly_flowing_prose_paragraphs>` tags."
+3. **Match your prompt style to the desired output.** The formatting in your prompt influences the response. Removing markdown from the prompt reduces markdown in the output.
+4. **Use detailed formatting preferences** when precision matters. Provide explicit guidance on markdown usage, list vs. prose preference, heading levels.
+
+For structured data output, prefer **structured outputs** (schema-constrained) or **tool calling** over prefill. Anthropic: "The Structured Outputs feature is designed specifically to constrain Claude's responses to follow a given schema."
+
+### 6. Control communication style
+
+Anthropic notes Claude 4.6 is "more direct and grounded... less verbose: may skip detailed summaries for efficiency unless prompted otherwise."
+
+- If more visibility is wanted: "After completing a task that involves tool use, provide a quick summary of the work you've done."
+- If less verbosity is wanted: "Respond directly without preamble. Do not start with phrases like 'Here is...', 'Based on...'."
+
+### 7. Add examples
+
+3-5 concrete examples for structured output, format, or tone-sensitive prompts. Wrap in `<example>` tags with diverse, representative inputs. Anthropic: "Include 3-5 examples for best results. You can also ask Claude to evaluate your examples for relevance and diversity."
+
+### 8. Self-check
+
+Before delivering, verify against the rubric:
+
+- [ ] States what to do in positive terms (not only what to avoid)
+- [ ] Output shape is specified if it matters (prose vs JSON vs XML vs structured outputs)
+- [ ] Communication style addressed (verbosity, summaries, preamble)
+- [ ] If tools exist: instructions tell Claude **when** to call each tool -- use natural phrasing ("Use this tool when...") over forceful directives to avoid overtriggering
+- [ ] No time-sensitive claims unless user asked for a snapshot date
+- [ ] For agent/tool prompts: includes a scope boundary ("Only make changes directly requested; do not refactor surrounding code")
+- [ ] For agent/tool prompts: includes autonomy/safety guidance (see pattern below)
+- [ ] For code/research prompts: includes grounding ("Read files before answering; say 'I don't know' when uncertain")
+- [ ] For research prompts: anti-hallucination ("Never speculate about code you have not opened")
+- [ ] For research prompts: structured approach ("Develop competing hypotheses, track confidence, self-critique")
+- [ ] Self-correction chain considered: would a generate-review-refine loop improve output?
+- [ ] For agentic prompts: state management addressed (context awareness, multi-window workflow, state tracking patterns)
+- [ ] Emotion-informed: uses collaborative framing (roles, motivation, partnership language)
+- [ ] Emotion-informed: includes permission to express uncertainty ("say so if unsure", placeholder notation)
+- [ ] Emotion-informed: proactive constraint awareness (inform about constraints upfront so the model can incorporate them into its plan)
+- [ ] For code prompts: includes anti-test-fixation ("Write general solutions, not code that only passes specific test cases; if tests seem wrong, flag them")
+- [ ] For agent prompts: includes temp file cleanup ("Clean up temporary files, scripts, or helper files created during the task")
+- [ ] For agent prompts: includes commit-and-execute pattern ("Choose an approach and commit; avoid revisiting decisions without new contradicting information")
+
+### 9. Deliver
+
+Final artifact as **one or more fenced blocks** the user can paste as-is. Offer a **one-line "when to use"** summary if the prompt is long.
+
+## Claude 4.6 considerations
+
+When generating prompts for current Claude models, apply these patterns:
+
+- **Prefill deprecated:** Do not use prefilled assistant responses. Anthropic: "Model intelligence and instruction following has advanced such that most use cases of prefill no longer require it." Use structured outputs, direct instructions, or XML tags instead.
+- **Overtriggering:** Dial back aggressive language. Anthropic: "Where you might have said 'CRITICAL: You MUST use this tool when...', you can use more normal prompting like 'Use this tool when...'."
+- **Overeagerness:** Include scope constraints. Anthropic: "Claude Opus 4.5 and Claude Opus 4.6 have a tendency to overengineer by creating extra files, adding unnecessary abstractions, or building in flexibility that wasn't requested."
+- **Overthinking:** Anthropic: "Replace blanket defaults with more targeted instructions. Instead of 'Default to using [tool],' add guidance like 'Use [tool] when it would enhance your understanding of the problem.'"
+- **Adaptive thinking replaces budget_tokens:** Claude 4.6 uses adaptive thinking (thinking: {type: "adaptive"}) where the model dynamically decides when and how much to think. Use the effort parameter (low | medium | high | max) to control depth. Anthropic: "In internal evaluations, adaptive thinking reliably drives better performance than extended thinking." Manual budget_tokens is deprecated.
+- **Subagent orchestration:** Include guidance for when subagents ARE and ARE NOT warranted. Anthropic: "Use subagents when tasks can run in parallel, require isolated context, or involve independent workstreams that don't need to share state. For simple tasks, sequential operations, single-file edits, or tasks where you need to maintain context across steps, work directly rather than delegating."
+- **Conservative vs proactive action:** For tools that should act, use explicit language ("Change this function"). For tools that should advise, use: "Default to providing information... Only proceed with edits when the user explicitly requests them."
+- **Anti-hallucination:** Anthropic: "Never speculate about code you have not opened. If the user references a specific file, you MUST read the file before answering."
+- **Self-correction chaining:** Anthropic: "The most common chaining pattern is self-correction: generate a draft, have Claude review it against criteria, have Claude refine based on the review." Consider adding a generate-review-refine loop for prompts that must hold up over time.
+
+## Autonomy and safety pattern
+
+For `agent-harness` and `tool-use` prompt types, include guidance on reversibility. Anthropic provides this pattern:
+
+```text
+Consider the reversibility and potential impact of your actions. You are encouraged to take local, reversible actions like editing files or running tests, but for actions that are hard to reverse, affect shared systems, or could be destructive, ask the user before proceeding.
+
+Examples of actions that warrant confirmation:
+- Destructive operations: deleting files or branches, dropping database tables, rm -rf
+- Hard to reverse operations: git push --force, git reset --hard, amending published commits
+- Operations visible to others: pushing code, commenting on PRs/issues, sending messages
+When encountering obstacles, do not use destructive actions as a shortcut. For example, don't bypass safety checks (e.g. --no-verify) or discard unfamiliar files that may be in-progress work.
+```
+
+## Research prompt pattern
+
+For `research` prompt types, include structured investigation. Anthropic provides this pattern:
+
+```text
+Search for this information in a structured way. As you gather data, develop several competing hypotheses. Track your confidence levels in your progress notes to improve calibration. Regularly self-critique your approach and plan. Update a hypothesis tree or research notes file to persist information and provide transparency.
+```
+
+## Conflict resolution
+
+When prompt engineering guidance conflicts across sources, defer to the authority tier:
+
+1. **Tier 1 (primary):** Anthropic -- the model provider's own documentation is authoritative for Claude behavior
+2. **Tier 2 (strong secondary):** OpenAI, Google DeepMind, Microsoft Research -- major lab guidance often transfers across models
+3. **Tier 3 (supplementary):** Community resources, courses, individual blogs -- valuable for patterns and intuition, not authoritative on model specifics
+
+The full curated resource list with links is in the canonical resources section above.

package/skills/readability-review/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: readability-review
+description: 8-dimension readability rubric scoring code so a 6-year-old could understand it through structure alone. Scores functions, then FIXES anything below threshold. Use after writing code and before committing. Triggers on "readability review", "clean code", "score readability".
+---
+
+# Readability Review
+
+## Overview
+
+Score every function across 8 readability dimensions (160 points total), then automatically fix anything scoring below threshold by rewriting and applying via Edit tool.
+
+**Core principle:** A 6-year-old could understand what every line does -- through code structure alone, not comments.
+
+**Announce at start:** "I'm using the readability-review skill to score and fix code readability across 8 dimensions."
+
+**Context:** Use after code is written but before committing. Complements code-quality-reviewer (architectural patterns) and review-code (standards compliance). This skill focuses purely on structural readability.
+
+## Comment Preservation (ABSOLUTE RULE)
+
+**NEVER remove ANY existing comments. ALL existing comments are SACRED.**
+
+This is an unconditional rule. Do not evaluate, judge, or clean up existing comments. If you are not modifying the code on that line, do not touch its comments.
+
+- Do not add NEW inline comments -- write self-documenting code instead
+- Docstrings for new files/methods/classes are allowed
+- If code is untouched, its comments are untouched
+- Scope: Only evaluate comments on lines YOU are actively changing
+
+## The 8 Dimensions (20 points each, 160 total)
+
+### 1. Naming Quality (20 pts)
+Every name reads as natural English. No mental translation required. No single-letter variables.
+Red flags: result, data, output, response, value, item, temp as variable names.
+
+### 2. Function SRP (20 pts)
+Every function does exactly one thing. Its name IS its documentation.
+
+### 3. Abstraction Consistency (20 pts)
+Each function operates at ONE conceptual level.
+
+### 4. Control Flow Clarity (20 pts)
+Zero nesting. Guard clauses first. Flat happy path.
+
+### 5. Domain Language Fidelity (20 pts)
+Code uses business vocabulary, not computer vocabulary.
+
+### 6. Call Site Readability (20 pts)
+Function calls read as English sentences at the call site.
+
+### 7. State and Assignment Clarity (20 pts)
+Variables never change meaning.
+
+### 8. Visual Rhythm and Code Shape (20 pts)
+Code has paragraph breaks. Related lines group together.
+
+## The Process
+
+### Step 1: Discover Changed Files
+
+Identify all files modified in the current session using `git diff --name-only`. Focus on production code files, not test files or config.
+
+### Step 2: Read Every Changed File
+
+Read the ENTIRE file, not just the diff. Readability depends on context -- a function name that seems clear in isolation may be confusing alongside its neighbors.
+
+### Step 3: Score Each Function
+
+Apply all 8 dimensions to every function in the changed files. Be specific with scores -- a function scoring 14/20 on Naming Quality needs concrete feedback on which names fail.
+
+### Step 4: Rewrite and APPLY to Source Files
+
+For every function scoring below 16/20 in ANY dimension, write the 160/160 version and USE THE EDIT TOOL to replace the original function in-place. Verify the file on disk contains the rewritten version. NEVER remove existing comments during rewrites.
+
+### Step 5: Report What Was Fixed
+
+Show the before/after scores for each function that was rewritten. Include which dimensions improved and by how much.
+
+## Output Format
+
+```
+## Readability Review: [File Name]
+
+### [function_name] - Score: [X]/160
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Naming Quality | /20 | ... |
+| Function SRP | /20 | ... |
+| ... | ... | ... |
+
+**Action:** [Fixed / Acceptable]
+```
+
+## After Completion
+
+If any functions were rewritten, run the test suite to verify no behavior changed. Report the final score for all reviewed functions.
+
+**If score is below 120/160 overall:**
+- Perform deeper architectural analysis inline: check DRY violations, unnecessary abstractions, and mixed abstraction levels
+
+## Red Flags - STOP
+
+- Function names that require reading the body to understand
+- Variables reused for different purposes (meaning changes mid-function)
+- Mixed abstraction levels (SQL query next to business logic)
+- Deeply nested conditionals (more than 1 level)
+- Computer vocabulary where domain vocabulary exists (e.g., "handler" instead of "validator")
+- No visual grouping -- wall of code with no paragraph breaks
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "The naming is close enough" | Close enough means the next reader pauses. Pausing means it's not readable. |
+| "Refactoring this function would be too risky" | The Edit tool preserves behavior. If tests pass, the rewrite is safe. |
+| "It's only one dimension below threshold" | One weak dimension drags down comprehension of the entire function. |
+| "This is how the rest of the codebase looks" | Existing low scores are not a license to add more. Fix what you touch. |
+| "Adding guard clauses would make it longer" | Flat code reads faster than nested code, even if it has more lines. |
+
+## Remember
+
+- Score ALL 8 dimensions for EVERY function -- no shortcuts
+- Threshold is 16/20 in ANY single dimension, not average
+- Fix without asking permission -- just fix and report
+- Preserve all existing functionality and test assertions
+- NEVER add comments -- code must be self-documenting
+- NEVER remove existing comments -- they are sacred
+- Read entire files, not just diffs -- context matters

package/skills/recall/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: recall
+description: "Retrieve prior session context and decisions from Obsidian vault for the current project."
+argument-hint: "[search query or project name]"
+---
+
+# Recall
+
+Search the Obsidian vault for prior session context, decisions, research, and gotchas relevant to the current task.
+
+## Instructions
+
+1. **Determine search query.** If `$ARGUMENTS` is provided, use it as the search query. Otherwise, infer the project name from the current conversation context (git remote, working directory, or topic being discussed).
+
+2. **Search by frontmatter first.** Use `mcp__obsidian__search_notes` with `searchFrontmatter: true` and the project name. This finds session reports and decision notes tagged with the project.
+
+3. **Search by content keywords.** If frontmatter search returns few results, search again by content using relevant keywords from the current task (component names, error messages, library names).
+
+4. **Read top matches.** Use `mcp__obsidian__read_note` to read the top 3 most relevant results. Prefer recent notes over older ones. Prefer decision notes and session summaries over raw research.
+
+5. **Present findings with attribution.** For each note, include:
+   - Note path and date
+   - Project name
+   - Relevant excerpts (not the full note unless it's short)
+   - Whether any decisions are marked `status: Superseded`
+
+6. **Handle no results honestly.** If no vault history exists for this project, say so explicitly. Do not fabricate or infer history that isn't in the vault.

package/skills/remember/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: remember
+description: "Save a decision, gotcha, or architectural choice to the Obsidian vault. User-initiated only."
+disable-model-invocation: true
+argument-hint: "[what to remember]"
+---
+
+# Remember
+
+Save a structured decision, gotcha, or architectural choice to the Obsidian vault as an individual note in the `decisions/` directory.
+
+## Instructions
+
+1. **Parse the input.** Extract the core decision, fact, or gotcha from `$ARGUMENTS`.
+
+2. **Classify the type** based on content:
+   - `decision` -- a choice made between alternatives (e.g., "chose Groq over Gemini")
+   - `procedural` -- a how-to or workflow step (e.g., "deploy requires manual cookie refresh first")
+   - `fact` -- an objective piece of information (e.g., "YNAB API cannot overwrite split transactions")
+   - `gotcha` -- a surprising behavior or trap (e.g., "Amazon blocks Cloud Run datacenter IPs")
+
+3. **Infer the project name** from conversation context (git remote, working directory, or topic).
+
+4. **Generate a short title** (3-7 words) that captures the essence.
+
+5. **Write to vault** via `mcp__obsidian__write_note`:
+
+   **Path:** `decisions/[Project] - [Short Title].md`
+
+   **Frontmatter:**
+   ```yaml
+   name: [Short Title from step 4]
+   description: [One-line summary of the decision/fact/gotcha -- concise enough for frontmatter search]
+   type: [decision|procedural|fact|gotcha]
+   project: [Project Name]
+   date: [YYYY-MM-DD]
+   status: Active
+   tags: [relevant, tags]
+   ```
+
+   **Body format depends on type:**
+
+   For `decision`:
+   ```
+   **Decision:** [One sentence stating what was decided]
+   **Reasoning:** [Why this was chosen]
+   **Alternatives considered:** [What was rejected and why]
+   **Consequences:** [What this means going forward]
+   ```
+
+   For `gotcha`:
+   ```
+   **Gotcha:** [One sentence stating the surprising behavior]
+   **Symptom:** [What you observe when you hit this]
+   **Fix:** [How to work around or resolve it]
+   ```
+
+   For `fact` or `procedural`:
+   ```
+   [The fact or procedure, written clearly in 1-3 sentences with relevant context]
+   ```
+
+6. **Confirm** what was saved and where (vault path).