feat: add aeo-optimizer, context-mode, claude-superpowers skills

https://claude.ai/code/session_01E4bTUWxx4Zo5rsFpad5X5B
2026-05-27 09:32:40 +00:00
parent 5f12fcff50
commit 6bb25a8c13
3 changed files with 923 additions and 0 deletions
@@ -0,0 +1,393 @@
+---
+name: aeo-optimizer
+description: "Optimize an article for Answer Engine Optimization (AEO) — restructuring content so AI engines like ChatGPT, Perplexity, and Claude can extract, quote, and cite it. Rewrites headings as questions, drops 50-80 word answer capsules, audits paragraph length, and flags trust signals. Use when asked to AEO-optimize, make content AI-readable, improve AI citation chances, or adapt an article for answer engines."
+---
+
+# AEO Optimizer Skill
+
+AEO — Answer Engine Optimization — is the discipline of structuring content so that AI engines (ChatGPT, Perplexity, Claude, Gemini) can extract clean, quotable answers and confidently cite your content as a source.
+
+Most articles are written for humans who scroll, skim, and click. AI engines don't scroll — they scan for extractable answer units. They look for short, self-contained answer blocks sitting directly beneath a clear question heading. If they can't find those, they either skip the content or paraphrase it poorly. This skill fixes that.
+
+---
+
+## The AEO Problem
+
+Here is what AI engines are scanning for, and what most articles fail to provide:
+
+| What AI engines want | What most articles deliver |
+|---|---|
+| H2 = a direct question ("What is X?") | H2 = a vague topic label ("About X" or "Understanding X") |
+| 50-80 word answer capsule immediately under the heading | Long intro paragraphs before the actual answer |
+| No links inside the answer block | Inline links that break extractability |
+| ≤3 sentences per paragraph | Dense 6-8 sentence paragraphs |
+| Named frameworks, original data, first-person experience | Generic statements with no attribution or specificity |
+| Consistent question-answer-expand structure throughout | Inconsistent structure that varies section by section |
+
+When an AI engine cannot cleanly extract a 50-80 word answer, it either skips the article or provides a vague paraphrase without a citation link. AEO optimization removes those barriers.
+
+---
+
+## Required Inputs
+
+Claude will ask for these if not provided:
+
+| Input | Required | Notes |
+|---|---|---|
+| Article content | Yes | Paste the full draft text, or provide a URL Claude can fetch |
+| Target audience | No | Helps calibrate question phrasing — e.g. "beginner founders" vs "senior engineers" |
+| Primary keyword or topic | No | If provided, Claude ensures H2 questions cover it directly |
+| Existing URL (if published) | No | Used in the audit report to note the live page |
+| Preserve exact section order | No | Defaults to yes — Claude rewrites in place, doesn't restructure |
+
+If providing a URL instead of pasted text, Claude will fetch the page content. Note: paywalled or JavaScript-rendered articles may require manual paste.
+
+---
+
+## Output Structure
+
+Claude produces two deliverables in sequence:
+
+### Deliverable 1 — AEO-Ready Article
+
+The full rewritten article with:
+- All H2s rewritten as direct questions
+- 50-80 word answer capsule inserted directly beneath each H2
+- Paragraphs trimmed to ≤3 sentences where they exceeded that
+- Trust signals preserved and lightly emphasized
+- No links inside any answer capsule
+- Original voice and structure maintained — this is an optimization, not a rewrite
+
+**Format:**
+
+```markdown
+# [Original H1 title — unchanged unless it needs question format]
+
+[Introduction — keep as-is or trim to ≤3 sentences. Add a "What this covers:" summary if intro is >150 words.]
+
+## [H2 rewritten as a direct question?]
+
+[Answer capsule — 50-80 words, no links, self-contained, answers the question completely on its own.]
+
+[Rest of the section body — expanded explanation, examples, data, links allowed here]
+
+## [Next H2 as a direct question?]
+
+[Answer capsule — 50-80 words, no links]
+
+[Section body]
+```
+
+---
+
+### Deliverable 2 — AEO Audit Report
+
+Structured report showing all changes made and signals identified.
+
+**Format:**
+
+---
+
+## AEO Audit Report
+
+**Article:** [Title]
+**URL:** [If provided]
+**Audit date:** [Today's date]
+**AEO readiness score (before):** [X/10]
+**AEO readiness score (after):** [X/10]
+
+---
+
+### Heading Rewrites
+
+| Original H2 | Rewritten H2 | Change type |
+|---|---|---|
+| Understanding Content Strategy | What is content strategy and why does it matter? | Topic label → direct question |
+| The Benefits of X | What are the main benefits of X? | Vague noun phrase → question |
+| How We Do It at [Company] | How does [Company] approach X? | First-person → question format |
+
+---
+
+### Answer Capsule Placements
+
+For each section, confirm capsule word count is within 50-80 words:
+
+| Section | Capsule word count | Links removed from capsule | Status |
+|---|---|---|---|
+| What is content strategy...? | 64 words | 2 links removed | OK |
+| How do you build a content calendar? | 71 words | 0 links (none were present) | OK |
+| What tools do content teams use? | 58 words | 1 link removed | OK |
+
+---
+
+### Paragraph Length Audit
+
+| Section | Original max paragraph (sentences) | Action taken |
+|---|---|---|
+| Introduction | 6 sentences | Split into 2 paragraphs |
+| Section 2 body | 4 sentences | Trimmed to 3 |
+| Section 4 body | 2 sentences | No change needed |
+
+**Paragraphs flagged as too long (before optimization):** [N]
+**Paragraphs within ≤3 sentences (after optimization):** [all]
+
+---
+
+### Trust Signal Inventory
+
+Trust signals are the elements AI engines treat as credibility markers — original data, named frameworks, first-person experience, and specific attributions. These make AI engines more likely to cite rather than paraphrase.
+
+| Signal type | Found in article | Example | AEO value |
+|---|---|---|---|
+| Original data / research | Yes | "Our analysis of 400 posts showed..." | High — cite-worthy claim |
+| Named framework | Yes | "The RICE scoring model" | High — search anchor |
+| First-person experience | Yes | "After running 3 content audits..." | Medium — authority signal |
+| Named expert / quote | No | — | Recommend adding |
+| Specific numbers / stats | Yes | "34% increase in organic traffic" | High — extractable fact |
+| Date-stamped content | No | — | Recommend adding publication date |
+| Case study reference | Yes | "At Acme Corp, we ran..." | High — concrete example |
+
+**Trust signals present:** [N]
+**Recommended additions:** [list any gaps]
+
+---
+
+### AEO Scoring Rubric
+
+| Criterion | Before | After |
+|---|---|---|
+| H2s as direct questions (% of total) | [X%] | [X%] |
+| Answer capsule present under each H2 | No | Yes |
+| Capsules within 50-80 words | N/A | [X/N sections] |
+| No links inside capsules | N/A | Yes |
+| Paragraphs ≤3 sentences | [X%] | [X%] |
+| Trust signals present | [N] | [N] |
+| **Total score** | **[X/10]** | **[X/10]** |
+
+---
+
+### Recommended Next Steps
+
+1. [Any remaining gaps — e.g. "Section 4 capsule is 88 words — trim by 10"]
+2. [Structural suggestions — e.g. "Add a FAQ section at the end for high-volume PAA questions"]
+3. [Missing trust signals — e.g. "Add a publication date and last-updated date for freshness signals"]
+4. [Schema markup suggestion if applicable — FAQ schema, HowTo schema, etc.]
+
+---
+
+*End of AEO Audit Report*
+
+---
+
+## How Claude Should Execute This Skill
+
+### Step 1 — Ingest the article
+
+Accept the content as either:
+- **Pasted text:** Treat as-is. Do not attempt to fetch a URL if text is pasted.
+- **URL:** Fetch the page. Extract the main article body — ignore nav, sidebars, footers, and ad blocks. If the page is JavaScript-rendered and fetch returns only a shell, ask the user to paste the text instead.
+
+Count the headings. Note the number of H2s, H3s, and H1s. This sets expectations for how many capsules will be written.
+
+### Step 2 — Assess AEO readiness before touching anything
+
+Before rewriting, score the article on the AEO rubric (see Deliverable 2 scoring table). This gives the user a before/after comparison and helps Claude identify where to focus effort.
+
+Run through each criterion and note the count:
+- How many H2s are already in question format? (count ones that end with "?")
+- Does any section already have a 50-80 word self-contained answer block?
+- What is the average and maximum paragraph length in sentences?
+- How many trust signals are present? (scan for numbers, named frameworks, first-person phrases, quotes)
+
+Record the before scores. Do not round up — be honest.
+
+### Step 3 — Rewrite H2 headings as questions
+
+For each H2 in the article, rewrite it as a direct question that a real person would ask an AI engine. Guidelines:
+
+**The question must:**
+- Be specific enough that the answer could stand alone as a snippet
+- Use "What", "How", "Why", "When", "Which", or "Who" — not vague gerunds ("Understanding", "Exploring", "Unpacking")
+- Match the search intent of the original section, not just rephrase it generically
+- Be 8 words or fewer when possible (longer questions are harder for AI engines to match)
+
+**Examples of heading transformations:**
+
+| Before | After |
+|---|---|
+| Introduction to Agile | What is Agile methodology? |
+| Why We Built This | Why did [Company] build [product]? |
+| The Case for Async Work | Why do distributed teams choose async work? |
+| Benefits | What are the main benefits of X? |
+| Tools and Resources | Which tools do [audience] use for X? |
+| Getting Started | How do you get started with X? |
+| Common Mistakes | What mistakes do beginners make with X? |
+| Our Approach | How does [Company/author] approach X? |
+
+Do not rewrite H3s unless the user requests it. H3s can stay as labels — AI engines primarily anchor on H2s.
+
+Do not change the H1. The H1 is the article title and SEO title — it follows different rules.
+
+### Step 4 — Write answer capsules
+
+For each H2, write a 50-80 word answer capsule to be inserted immediately after the heading and before any existing body text.
+
+**Capsule rules:**
+- Must be self-contained — someone reading only the heading + capsule should have a complete, useful answer
+- No links of any kind inside the capsule (links break AI extractability)
+- No hedging phrases ("It depends", "There are many factors") — commit to the answer
+- Use the same voice and terminology as the article — do not change the author's perspective
+- If the section has an existing strong first paragraph that is already 50-80 words and self-contained, use it as the capsule with minimal edits rather than writing a new one
+- Count words precisely — under 50 is too thin, over 80 and AI engines may not extract it cleanly
+
+**Capsule structure options:**
+
+Option A — Definition then application:
+```
+[Concise definition of the concept in 1-2 sentences.] [How it applies in practice, with one specific example or number.] [Why it matters for the reader's situation.]
+```
+
+Option B — Direct answer then context:
+```
+[Direct answer to the heading question in 1 sentence.] [2-3 sentences of supporting context, specifics, or mechanism.] [Optional: one concrete example or stat.]
+```
+
+Option C — How-to opener:
+```
+[State the outcome in 1 sentence.] [Steps 1, 2, 3 in compressed form.] [Note on when this applies or what to watch for.]
+```
+
+Mark each capsule clearly with an HTML comment so the author knows it was added:
+```html
+<!-- AEO Answer Capsule — 64 words -->
+[capsule text]
+<!-- End AEO Capsule -->
+```
+
+### Step 5 — Audit and trim paragraph length
+
+Scan every paragraph in the body sections (not the capsules). If a paragraph exceeds 3 sentences:
+- Split it into two paragraphs at the most natural break
+- Do not summarise or remove content — just add a paragraph break
+- If a paragraph is a list in disguise (long run-on sentence with "and", "then", "also"), convert it to a bullet list instead
+
+Note every change in the audit report's paragraph length table.
+
+### Step 6 — Identify and flag trust signals
+
+Scan the full article for trust signals. Do not add trust signals — only identify what exists and flag gaps. Trust signals are:
+
+| Signal type | What to look for |
+|---|---|
+| Original data | "Our data shows", "We analysed X", "In our survey of N..." |
+| Named frameworks | Any named methodology, model, or system (RICE, Jobs-to-be-Done, etc.) |
+| First-person experience | "I found", "We ran", "When I built", "After testing..." |
+| Specific numbers | Percentages, counts, timeframes, dollar amounts |
+| Expert quotes | Direct quotes attributed to a named person |
+| Case studies | Named company or project with specific outcomes |
+| Publication freshness | A visible publish or update date |
+
+Flag any category with zero signals as a gap. Include specific recommendations for what could be added (e.g. "Add a statistic to the intro — even a well-known industry stat cited correctly adds credibility").
+
+### Step 7 — Assemble the output
+
+Produce the two deliverables in this order:
+
+1. First: the full AEO-ready article. Use the original markdown structure with the changes applied. Make sure capsules have the HTML comment markers.
+2. Second: the AEO Audit Report, using the exact table structure from the Output Structure section above.
+
+Separate the two deliverables with a clear horizontal rule (`---`) and a heading (`## AEO Audit Report`).
+
+### Step 8 — Optional: FAQ section recommendation
+
+If the article does not already have a FAQ section, and the topic has obvious high-volume PAA (People Also Ask) questions, recommend adding one. Provide 3-5 suggested FAQ questions in question format with brief capsule answers. Note that FAQ sections with proper schema markup (`FAQPage` JSON-LD) get preferential treatment in both traditional SEO and AI engine extraction.
+
+---
+
+## AEO Reference: What Makes a Good Answer Capsule
+
+This section is reference material — Claude should use it when evaluating capsule quality.
+
+**Strong capsule (62 words):**
+> Content strategy is the planning and management of content to achieve specific business goals. It defines what to publish, for whom, through which channels, and how often. A strong content strategy starts with audience research, maps content to stages of the buyer journey, and includes a measurement framework. Without it, content teams produce output without direction — publishing more without knowing whether it drives outcomes.
+
+Why it works:
+- Answers the question completely in isolation
+- No links
+- Specific enough to be citable (mentions audience research, buyer journey, measurement framework)
+- Under 80 words
+
+**Weak capsule (48 words — too short, too vague):**
+> Content strategy is important for businesses. It helps you plan what content to create. Many companies use content strategy to grow their audience. There are different approaches depending on your goals. It's a broad topic that covers many areas of marketing.
+
+Why it fails:
+- Does not complete the answer — "many areas" is not an answer
+- No specifics, no named concepts
+- Under 50 words
+- AI engine would not cite this — it says nothing citable
+
+---
+
+## Quality Checks
+
+Before marking this task complete, verify each item:
+
+- [ ] Every H2 in the article is now a direct question ending with "?"
+- [ ] Every question-format H2 has an answer capsule immediately below it (no intervening text)
+- [ ] Every capsule is between 50 and 80 words — count precisely, not approximately
+- [ ] No links appear inside any capsule block
+- [ ] Every capsule has the HTML comment markers noting word count
+- [ ] Paragraphs throughout the article body are ≤3 sentences (flag any exceptions in the report)
+- [ ] The H1 title is unchanged
+- [ ] H3s are unchanged (unless user requested otherwise)
+- [ ] Original voice, tone, and terminology are preserved — this is optimization, not ghostwriting
+- [ ] Trust signal inventory table is populated with actual examples from the text, not generic placeholders
+- [ ] Gaps in trust signals are noted with specific recommendations, not just "add more data"
+- [ ] Before and after AEO scores are both present in the audit report
+- [ ] Heading rewrites table is complete — one row per H2
+- [ ] Paragraph length audit table is complete — covers all sections
+- [ ] Any FAQ section recommendation is based on real PAA-style questions for the topic, not invented ones
+- [ ] Both deliverables (article + audit report) are present in the response
+- [ ] Total word count of the rewritten article is within ±10% of the original (optimization, not expansion)
+
+---
+
+## Example Trigger Phrases
+
+- "AEO optimize this article"
+- "Make this content AI-readable"
+- "Rewrite my headings as questions and add answer capsules"
+- "Optimize this for ChatGPT and Perplexity to cite"
+- "Run an AEO audit on this draft"
+- "Make this article get picked up by AI search"
+- "I want Perplexity to cite my content — can you fix this article?"
+- "Turn these headings into questions and add short answer blocks"
+- "Can you add answer capsules under each section?"
+- "Audit this for answer engine optimization"
+- "My content isn't showing up in AI answers — fix the structure"
+- "AEO this" [followed by article text or URL]
+- "Optimize for AI citation"
+- "Make each section self-contained for AI extraction"
+
+---
+
+## Appendix: AEO vs SEO — Key Differences
+
+This is useful context Claude can share with users who are unfamiliar with AEO:
+
+| Dimension | SEO (Search Engine Optimization) | AEO (Answer Engine Optimization) |
+|---|---|---|
+| Target | Google's ranking algorithm | AI engine extraction models |
+| Primary signal | Backlinks, authority, keyword density | Structured Q&A, answer capsule clarity |
+| Content format | Long-form, comprehensive coverage | Question-first, capsule-first, then expand |
+| Heading style | Keyword-rich labels ("Best Project Management Tools") | Direct questions ("What are the best project management tools?") |
+| Paragraph length | Not a ranking factor | Short (≤3 sentences) is strongly preferred |
+| Links in body | Important for authority passing | Links inside answer capsules break extractability |
+| Trust signals | Domain authority, backlink profile | Named data, frameworks, first-person experience |
+| Measurement | Organic ranking position, CTR | AI citation frequency, answer box appearances |
+
+AEO does not replace SEO — it complements it. A well-structured article optimized for AEO will also perform better in traditional search because its structure is clearer and its headings are more specific to user intent.
+
+---
+
+*Originally created by Gencay (LearnAIwithMe) — adapted and extended for this library.*
@@ -0,0 +1,282 @@
+---
+name: claude-superpowers
+description: "Force Claude Code to work like a senior developer: plan before coding, work in isolation, write tests first, and review its own output twice before presenting it. Use when asked to enable superpowers mode, activate the superpowers framework, or turn on superpowers for this session. Installs a 4-stage framework — Plan, Isolate, Test First, Double Review — that prevents Claude from sprinting into broken code."
+---
+
+# Claude Superpowers Skill
+
+Stop Claude from shipping the first thing it writes. Superpowers mode locks Claude into four stages — Plan, Isolate, Test First, Double Review — so that what it presents at the end is actually right.
+
+The default problem: Claude sprints out of the gate, writes the whole thing in one shot, and it looks great — until someone runs it. It doesn't plan. It doesn't test. It doesn't verify. The result: code that breaks on edge cases, debugging rounds that burn tokens, and rework that costs more than doing it right the first time.
+
+> **Credit:** Inspired by a skill from Nate Herk's YouTube channel — adapted and extended for this library.
+
+---
+
+## Required Inputs
+
+No inputs required. Superpowers activates on command, then applies to whatever coding task follows.
+
+---
+
+## The Four Stages
+
+### Stage 1 — Plan
+
+Before writing a single line of code, Claude must produce a written plan and wait for user confirmation.
+
+**Plan format:**
+
+```
+PLAN
+════
+
+TASK
+[One-sentence restatement of what was asked. If anything is ambiguous, flag it here before proceeding.]
+
+APPROACH
+[2–4 sentences describing the implementation approach and key decisions. If there are multiple valid approaches, briefly explain why this one was chosen.]
+
+FILES TO CREATE OR MODIFY
+- [path/to/file.ts] — [what changes: create / modify / delete — one line reason]
+- [path/to/file.ts] — [what changes]
+
+EDGE CASES I WILL HANDLE
+- [Edge case 1]
+- [Edge case 2]
+- [Edge case 3]
+
+EDGE CASES I AM NOT HANDLING (out of scope)
+- [Out of scope case — reason]
+
+ASSUMPTIONS
+- [Any assumption made where the requirements were unclear]
+
+Confirm this plan before I start coding.
+```
+
+Claude must not proceed until the user says yes (or provides corrections). If the user corrects the plan, revise and re-confirm before starting.
+
+---
+
+### Stage 2 — Isolate
+
+Claude works in isolation until the output is complete and reviewed. Nothing touches the main project until explicitly approved.
+
+**Isolation rules:**
+- If git is available: create a feature branch before making any changes. Branch name format: `superpowers/[task-slug]`
+- If no git: note that changes are being made to a working copy and flag all modified files at the end for user review before they're considered "shipped"
+- Do not modify files outside the scope defined in the plan unless the user explicitly expands scope during the session
+- If new scope is discovered mid-task (e.g. a dependency needs to change), surface it: "This requires also modifying [X] — should I include that in scope?"
+
+**On starting Stage 2, announce:**
+```
+ISOLATE
+Working in isolation on branch: superpowers/[task-slug]
+No changes will be considered final until Stage 4 review is complete.
+```
+
+---
+
+### Stage 3 — Test First
+
+Before writing the implementation, write the tests (or at minimum, define the expected behaviour as executable assertions).
+
+**Test-first approach:**
+1. Write tests that define the expected behaviour for the task
+2. Write tests that cover each edge case identified in the plan
+3. Run the tests — they should fail (implementation doesn't exist yet)
+4. Confirm the tests are failing for the right reason before writing implementation
+5. Write the implementation
+6. Run the tests — they should now pass
+7. If tests fail: fix the implementation, not the tests
+
+**If the project has no test setup:** flag it and offer two options:
+- Option A: Set up a minimal test harness before proceeding (recommended)
+- Option B: Define the expected behaviour as a checklist of manual verification steps (faster but weaker)
+
+**Test summary to show before writing implementation:**
+
+```
+TESTS WRITTEN
+─────────────
+File: [test file path]
+Tests:
+  ✗ [test description — covers: happy path]
+  ✗ [test description — covers: edge case 1]
+  ✗ [test description — covers: edge case 2]
+  ✗ [test description — covers: error state]
+
+All tests failing as expected. Starting implementation.
+```
+
+---
+
+### Stage 4 — Double Review
+
+After completing the code and running tests, Claude reviews its own work twice before presenting it. Neither review is a formality.
+
+**Review 1 — "Does this match what was asked for?"**
+
+Check the completed code against the original request and confirmed plan:
+- Does it do everything that was asked?
+- Does it handle all edge cases from the plan?
+- Are there any mismatches between what was planned and what was built?
+- Are there any assumptions baked in that weren't confirmed?
+
+**Review 2 — "Is this good code?"**
+
+Check for technical quality independent of the requirements:
+- Obvious bugs or logic errors
+- Missing error handling (especially at boundaries: API calls, file I/O, user input)
+- Security issues (injection vulnerabilities, exposed secrets, missing auth checks)
+- Readability: would another developer understand this in 6 months?
+- Performance: any obvious inefficiencies on the critical path?
+- Dead code or unused imports introduced
+
+**Double Review output format:**
+
+```
+REVIEW 1 — CORRECTNESS
+───────────────────────
+✅ Handles [requirement 1]
+✅ Handles [requirement 2]
+✅ Edge case [X] covered
+⚠️  [Issue found — what it is and what was changed to fix it]
+
+REVIEW 2 — CODE QUALITY
+────────────────────────
+✅ Error handling present at all API boundaries
+✅ No obvious security issues
+⚠️  [Issue found — what it was and how it was fixed]
+✅ Readable — no unexplained complexity
+
+VERDICT: [Ready to present / Fixed N issues before presenting]
+```
+
+If issues are found in either review, fix them and note what was fixed. Present the corrected version, not the original draft.
+
+---
+
+## Activation Response
+
+When the user triggers Superpowers mode, respond with:
+
+```
+Superpowers mode active.
+
+I'll work in 4 stages for every coding task this session:
+  1. PLAN    — Write a plan and wait for your confirmation before coding
+  2. ISOLATE — Work on a branch; nothing ships until you approve
+  3. TEST    — Write tests before the implementation
+  4. REVIEW  — Review my own work twice before presenting it
+
+What are we building?
+```
+
+---
+
+## Output Structure
+
+### Full task flow (all four stages)
+
+```
+PLAN
+════
+[Plan format as above]
+Confirm this plan before I start coding.
+
+---
+[User confirms]
+---
+
+ISOLATE
+Working in isolation on branch: superpowers/[task-slug]
+
+TESTS WRITTEN
+─────────────
+[Test summary — all failing]
+Starting implementation.
+
+---
+[Implementation runs]
+---
+
+REVIEW 1 — CORRECTNESS
+───────────────────────
+[Checklist]
+
+REVIEW 2 — CODE QUALITY
+────────────────────────
+[Checklist]
+
+VERDICT: Ready to present.
+
+---
+
+COMPLETE
+════════
+[Summary of what was built, files created/modified, how to run/test it]
+Branch: superpowers/[task-slug] — merge when ready.
+```
+
+---
+
+## CLAUDE.md Installation Text
+
+After activating Superpowers for the session, provide the user with the exact text to add to their `CLAUDE.md` to make it permanent:
+
+````
+```
+## Superpowers Framework
+
+This framework is always active for coding tasks in this project.
+
+### Stage 1 — Plan
+Before writing any code: produce a written plan including task restatement, approach, files to create/modify, edge cases to handle, and assumptions. Wait for explicit user confirmation before proceeding.
+
+### Stage 2 — Isolate
+Work on a feature branch (superpowers/[task-slug]) or clearly flagged working copy. Nothing is considered shipped until the user approves after Stage 4.
+
+### Stage 3 — Test First
+Write tests before writing the implementation. Tests should fail before implementation, pass after. If no test setup exists, offer to create one or produce a manual verification checklist.
+
+### Stage 4 — Double Review
+After completing code, run two reviews before presenting:
+- Review 1: Does this match what was asked for? Check against original request and plan.
+- Review 2: Is this good code? Check for bugs, missing error handling, security issues, readability.
+Fix any issues found. Present the corrected version. Show the review checklist.
+```
+````
+
+Tell the user: "Add this to your CLAUDE.md and Superpowers will be active permanently for this project."
+
+---
+
+## Quality Checks
+
+- [ ] Stage 1 plan was shown and user explicitly confirmed before any code was written
+- [ ] Plan includes: task restatement, approach, files to modify, edge cases in scope, edge cases out of scope, assumptions
+- [ ] Ambiguities in the original request were flagged in the plan (not silently assumed)
+- [ ] Stage 2 isolation: a feature branch was created (or flagged as working copy if no git)
+- [ ] Stage 3 tests were written before implementation — not after
+- [ ] Tests were run and confirmed to be failing before implementation started
+- [ ] Stage 4 Review 1 checked against the original request — not just against the plan
+- [ ] Stage 4 Review 2 checked for bugs, error handling, security, readability — all four
+- [ ] Issues found in either review were fixed before presenting — not flagged as "things to fix later"
+- [ ] Final output shows what was built, which files were changed, and how to run/test it
+- [ ] CLAUDE.md installation text was offered after activation
+
+---
+
+## Example Trigger Phrases
+
+- "Enable superpowers mode"
+- "Activate superpowers"
+- "Turn on superpowers for this session"
+- "Use the superpowers framework"
+- "Make sure you plan before coding"
+- "I want you to review your work before showing me"
+- "Write tests first this time"
+- "Slow down and plan it out before you start building"
+- "Work on a branch and show me a plan before touching anything"
@@ -0,0 +1,248 @@
+---
+name: context-mode
+description: "Activate output filtering, session logging, and auto-resume to keep Claude Code sessions running for hours without context bloat or memory loss. Use when asked to enable context mode, turn on long session mode, or activate session persistence. Installs a session log at project root, filters verbose command output before it enters context, and auto-resumes after Claude resets."
+---
+
+# Context Mode Skill
+
+Fix the two session killers that end most Claude Code sessions in under 30 minutes: context bloat from raw command output, and memory loss after a reset.
+
+Context Mode runs three systems simultaneously to keep sessions alive:
+
+- **Output Filtering** — strips verbose command output before it enters context
+- **Session Log** — writes a running log of everything that happened
+- **Auto-Resume** — reads the log on reset and picks up exactly where you left off
+
+> **Credit:** Inspired by a skill from Nate Herk's YouTube channel — adapted and extended for this library.
+
+---
+
+## Required Inputs
+
+No inputs required. Context Mode activates on command.
+
+Optional: user can specify a custom log file path if they don't want `session.log` in the project root.
+
+---
+
+## How Context Mode Works
+
+### Part 1 — Output Filtering
+
+The problem: every time Claude Code runs a command, the full raw output enters the context window. A single `npm install` can dump hundreds of lines. A test suite run? Thousands. Within 30 minutes, the context is full of noise and Claude resets.
+
+The fix: before any command output enters context, filter it to the useful summary only.
+
+**What gets kept:**
+- Last 10 lines of stdout
+- Every line containing `error`, `warn`, `fail`, `exception`, `traceback`, or `fatal` (case-insensitive)
+- The exit code
+- A one-line summary of what the command did and whether it succeeded
+
+**What gets discarded:**
+- Middle section of long stdout (replaced with `[... N lines of output truncated ...]`)
+- Progress bars, download indicators, verbose install logs
+- Repeated identical lines (deduplicated)
+
+**Filtering summary format:**
+
+```
+COMMAND: [command run]
+STATUS:  [exit code — success / failed]
+SUMMARY: [one sentence: what happened]
+ERRORS:  [any error/warn lines — or "none"]
+TAIL:    [last 10 lines of stdout]
+```
+
+---
+
+### Part 2 — Session Log
+
+Claude maintains a running log file at `[project root]/session.log`. This file is written after every significant action and is the source of truth for resuming after a reset.
+
+**Session log format:**
+
+```
+SESSION LOG
+===========
+Started:    [timestamp]
+Branch:     [current git branch]
+Directory:  [working directory]
+
+FILES EDITED
+────────────
+[timestamp] [file path] — [one-line description of what changed]
+
+COMMANDS RUN
+────────────
+[timestamp] [command] — [outcome: success / failed — brief reason]
+
+TASKS IN PROGRESS
+─────────────────
+[ ] [Task description — what's been done so far and what's left]
+[x] [Completed task]
+
+LAST USER PROMPT
+────────────────
+[The most recent instruction from the user, verbatim]
+
+LAST ACTION TAKEN
+─────────────────
+[What Claude did last, in one sentence]
+```
+
+**Log update rules:**
+- Write to `session.log` after every file edit
+- Write to `session.log` after every command run
+- Update "Tasks in Progress" when a task is started, progressed, or completed
+- Always overwrite "Last User Prompt" and "Last Action Taken" with the current values — don't append, replace
+
+---
+
+### Part 3 — Resume on Reset
+
+When a new Claude session starts, the first action is:
+
+1. Check for `session.log` in the project root
+2. If found, read it and announce the resume:
+
+```
+Resuming session.
+
+Branch:          [branch]
+Last working on: [last task in progress]
+Files edited:    [list from session log]
+Tasks pending:   [incomplete tasks]
+Last prompt:     "[last user prompt]"
+
+Continuing from where we left off.
+```
+
+3. Continue with the next logical step — don't ask "what should I do?" — check the task list and carry on
+
+If no `session.log` exists, start fresh and initialise the log.
+
+---
+
+## Activation Response
+
+When the user triggers Context Mode, respond with:
+
+```
+Context Mode active.
+
+Session log initialised at: [absolute path to session.log]
+Output filtering:           enabled
+Auto-resume:                enabled
+
+I'll maintain your session state across resets. Long sessions won't lose context.
+```
+
+Then immediately initialise `session.log` with the current timestamp, branch, and directory.
+
+---
+
+## Output Structure
+
+### On activation
+
+```
+Context Mode active.
+Session log initialised at: [path]
+Output filtering: enabled
+Auto-resume: enabled
+I'll maintain your session state across resets. Long sessions won't lose context.
+```
+
+### On command execution (filtered output format)
+
+```
+COMMAND: npm test
+STATUS:  exit 1 — failed
+SUMMARY: 47 tests passed, 3 failed in auth.test.ts
+ERRORS:  Error: Expected 200, received 401 (line 84)
+         Error: Token not found in response (line 112)
+TAIL:
+  ✓ login with valid credentials (23ms)
+  ✓ logout clears session (11ms)
+  ✗ refresh token after expiry
+  ...
+```
+
+### On reset / new session (resume announcement)
+
+```
+Resuming session.
+
+Branch:          feature/auth-refresh
+Last working on: Fixing token refresh logic in auth.service.ts
+Files edited:    src/auth/auth.service.ts, src/auth/auth.test.ts
+Tasks pending:   [ ] Fix failing test on line 112
+                 [ ] Run full test suite once fix is applied
+Last prompt:     "The refresh token test is still failing — look at the 401 handling"
+
+Continuing from where we left off.
+```
+
+---
+
+## CLAUDE.md Installation Text
+
+After activating Context Mode for the session, provide the user with the exact text to add to their `CLAUDE.md` to make it permanent across all sessions:
+
+````
+```
+## Context Mode
+
+Context Mode is always active in this project.
+
+### Output Filtering
+Before any command output enters context, filter it to:
+- Last 10 lines of stdout
+- Any lines containing: error, warn, fail, exception, traceback, fatal (case-insensitive)
+- Exit code
+- One-line summary of what the command did
+
+Use this format for filtered output:
+COMMAND: [command]
+STATUS:  [exit code — success/failed]
+SUMMARY: [one sentence]
+ERRORS:  [error lines or "none"]
+TAIL:    [last 10 lines]
+
+### Session Log
+Maintain a running session log at ./session.log. Write to it after every file edit and every command run. Track: files edited, commands run, tasks in progress, last user prompt, last action taken. Format defined in Context Mode skill.
+
+### Auto-Resume
+At the start of every new session, check for ./session.log. If it exists, read it and announce the resume state. Continue from the last task in progress without asking for instructions.
+```
+````
+
+Tell the user: "Add this to your CLAUDE.md and Context Mode will be active permanently for this project — even after you close and reopen the session."
+
+---
+
+## Quality Checks
+
+- [ ] `session.log` was initialised immediately on activation (not deferred)
+- [ ] Log path shown to user is the absolute path, not relative
+- [ ] Output filtering is applied on the very next command run — not just announced
+- [ ] Filtered output format includes: command, status, summary, errors, and tail — all five fields
+- [ ] Session log tracks all four categories: files edited, commands run, tasks in progress, last prompt
+- [ ] Resume announcement reads the actual log contents — not a generic template
+- [ ] On resume, Claude continues the work without prompting the user for instructions
+- [ ] CLAUDE.md installation text was offered after activation
+- [ ] Log update rule is clear: "Last User Prompt" and "Last Action Taken" replace previous values, not append
+
+---
+
+## Example Trigger Phrases
+
+- "Enable context mode"
+- "Turn on context mode for this session"
+- "Activate long session mode"
+- "I keep losing context — fix it"
+- "Set up session logging"
+- "Keep track of what you've done so you can resume after a reset"
+- "Enable output filtering to save context"
+- "Set up auto-resume so we don't lose our place"