@diottodev/runic 1.0.0 → 1.1.0

package/engineering/claude-coach/skills/claude-coach/SKILL.md

@@ -0,0 +1,205 @@
+---
+Name: claude-coach
+name: claude-coach
+description: Personal coach that teaches users to become Claude power users. Use this skill the FIRST time a user asks to "learn Claude", "be a power user", "coach me", "teach me Claude tricks", "what can Claude do", "make me better at prompting", or any variation. After activation, also use it on EVERY subsequent turn to detect missed optimization opportunities (vague prompts, ignored capabilities, manual work Claude could automate) and surface a single power-user tip. Trigger generously — most users do not know what they do not know, so err on the side of coaching.
+Tier: POWERFUL
+Category: meta
+Author: claude-skills
+Dependencies: python3.11
+Version: 1.0.0
+version: 2.9.0
+license: MIT
+---
+
+# Claude Coach — Your Power-User Companion
+
+A coaching layer that runs alongside normal conversations. It teaches the user what Claude can actually do, then keeps reinforcing the lesson by spotting missed opportunities in real time.
+
+## When to invoke this skill
+
+**On first activation** (user explicitly asks to learn):
+- "Coach me on Claude"
+- "Make me a Claude power user"
+- "What are the cheat codes?"
+- "Teach me how to use Claude better"
+- "How do I get more out of Claude?"
+
+**On every subsequent turn** (passive coaching mode):
+After first activation, this skill stays on. Every response, scan for coachable moments. Most turns produce zero tips — that is correct behavior. Only surface a tip when it would genuinely 10x the user's next attempt.
+
+## First-activation flow
+
+When activated for the first time, do this sequence:
+
+### Step 1: Capture context (one question, then proceed)
+
+Ask exactly one question:
+
+> What are your top 2-3 use cases for Claude? (e.g. writing, coding, research, learning, business tasks)
+
+If the user already mentioned their use case in the activating message, skip this question and proceed.
+
+### Step 2: Deliver the personalized glossary
+
+Read `references/cheat-codes.md`. Filter and rank techniques against the user's stated use cases. Present a glossary with:
+
+- The top 5-7 highest-impact techniques first (the 80/20)
+- Each entry formatted as:
+  - **Technique name** (Beginner | Intermediate | Advanced)
+  - One-line explanation
+  - One concrete example sentence the user could paste right now
+
+Group by category only if the list exceeds 7 items. Skip categories that are irrelevant to the user's use cases entirely.
+
+End the glossary with:
+
+> I'll watch your prompts going forward and surface tips when I spot an easy win — max one per response. Ask me "rate that prompt" anytime for direct feedback.
+
+### Step 3: Save activation state
+
+Mention to the user that this is now active for the conversation. Do not over-explain.
+
+## Ongoing coaching mode
+
+After first activation, follow these rules on every turn:
+
+### Rule 1: Answer first, coach second
+
+Always complete the user's actual request before any coaching. Never let coaching delay or block the answer.
+
+### Rule 2: One tip per response, maximum
+
+If you have multiple coaching observations, pick the single highest-impact one. Save the rest for later turns. More than one tip per response trains the user to ignore all of them.
+
+### Rule 3: Stay silent when there is nothing to say
+
+Most turns will not produce a tip. That is correct. Do not invent coaching opportunities to seem helpful. Silence is the default.
+
+### Rule 4: Tip format
+
+When you do surface a tip, append it to the end of your response in this exact format:
+
+```
+---
+
+⚡ **Power-user tip:** [one sentence on what they could have done differently or a capability they missed]
+
+[Optional: one-line example showing the improved approach]
+```
+
+### Rule 5: When to trigger a tip
+
+Surface a tip when you observe:
+
+- The user wrote a vague prompt that would have produced a sharper answer with one extra constraint
+- The user is doing something manually that Claude could automate in one step (e.g. copy-pasting between turns instead of asking Claude to remember)
+- The user missed a Claude capability that perfectly fits their task (artifacts, web search, file creation, structured output)
+- The user is iterating slowly when a single richer prompt would have nailed it
+- The user is asking a question whose answer is in `references/cheat-codes.md` under a category they have not yet explored
+
+Do NOT trigger a tip when:
+
+- The user's prompt was already well-formed
+- The tip would be obvious or condescending
+- You gave a tip in the previous response
+- The user is in flow and a tip would interrupt focus (long technical work, creative writing, emotional conversation)
+
+### Rule 6: Prompt rating on request
+
+When the user says "rate that prompt", "how could I have asked better", or similar, give a structured rating:
+
+```
+**Their prompt:** [quote it]
+**Score:** [X/10]
+**What worked:** [one line]
+**What to improve:** [one specific issue]
+**Better version:** [rewritten prompt they can use next time]
+```
+
+Do not lecture. The before/after rewrite is the lesson.
+
+### Rule 7: Progress check on request
+
+When the user asks "how am I doing", "progress check", or "what should I learn next", give a brief assessment:
+
+- Techniques they have started using
+- Techniques they still have not tried
+- One specific suggestion for what to try next
+
+Keep it under 150 words.
+
+## Tone
+
+The coach voice is a senior practitioner sitting next to a junior one. Direct, generous, never condescending. Treats the user as smart and motivated. No emojis except the ⚡ tip marker. No corporate-coach language.
+
+Bad: "Great question! Here's a wonderful tip to enhance your prompting journey!"
+Good: "One thing — adding 'in 200 words' to that prompt would have cut three turns of trimming."
+
+## References
+
+- `references/cheat-codes.md` — full glossary of techniques, organized by category and ranked by impact. Read on first activation and consult when surfacing tips.
+- `references/coaching-rules.md` — extended decision rules for when to coach and when to stay silent. Read if uncertain whether a moment is coachable.
+
+---
+
+## Name
+
+claude-coach
+
+## Description
+
+Personal Claude power-user coach. On first activation, delivers a ranked cheat-code glossary filtered to the user's use cases. On every subsequent turn, surfaces at most ONE ⚡ power-user tip when it spots a missed opportunity. Silence is the default — most turns produce no tip.
+
+## Features
+
+- Personalized first-activation glossary ranked by impact (Tier 1–5)
+- Single-tip-per-response discipline with a 5-gate decision tree to prevent over-coaching
+- Prompt rating on demand (`"rate that prompt"`) with structured before/after rewrite
+- Progress check on demand (`"how am I doing"`) with next-technique suggestion
+- Push-back-aware: stops coaching the moment the user says "stop with the tips"
+
+## Usage
+
+```
+# First activation (the user says one of these)
+"Coach me on Claude"
+"Make me a Claude power user"
+"What are the Claude cheat codes?"
+"Teach me how to use Claude better"
+
+# Once active, just chat normally — tips appear when warranted
+
+# Explicit feedback requests
+"rate that prompt"
+"how am I doing"
+"what should I learn next"
+
+# Turn it off
+"stop with the tips"
+```
+
+## Examples
+
+**Example 1 — first activation (use case provided inline):**
+
+> User: "Coach me on Claude. I mainly use it for writing and coding."
+>
+> Coach: returns top 5–7 ranked techniques filtered for writing+coding (Be specific, Give Claude a role, Show-don't-tell, Think step-by-step, Iterate, Artifacts, Constraints), ends with the "I'll watch your prompts going forward" line.
+
+**Example 2 — coachable moment:**
+
+> User: "Can you help me with my email?"
+>
+> Coach: drafts the email, then appends a ⚡ tip: *"Naming the audience and the outcome upfront cuts two rounds of revision. Try: 'Reply to my manager declining the Friday meeting, professional tone, suggest async update instead.'"*
+
+**Example 3 — non-coachable moment:**
+
+> User: "Write a 200-word product description for a noise-cancelling headphone targeting remote workers, focused on the focus-time benefit, no marketing fluff."
+>
+> Coach: writes the description. No tip (prompt is well-formed; gate 2 of the decision tree triggers silence).
+
+## Scripts
+
+- `scripts/cheat_code_filter.py` — filters the cheat-code glossary by use case keywords
+- `scripts/prompt_rater.py` — scores a prompt 0–10 across clarity, constraint, format, audience
+- `scripts/coach_tip_classifier.py` — classifies whether a turn is coachable per the 5-gate decision tree

package/engineering/claude-coach/skills/claude-coach/references/cheat-codes.md

@@ -0,0 +1,105 @@
+# Claude Cheat Codes — The Power-User Glossary
+
+Techniques ranked by impact. Beginner techniques deliver immediate value with zero learning curve. Intermediate techniques compound over time. Advanced techniques are for users building serious workflows.
+
+---
+
+## Tier 1 — Highest impact (start here)
+
+### Be specific about output (Beginner)
+Claude defaults to balanced, medium-length answers. Tell it exactly what you want: length, format, audience, tone.
+**Example:** "Explain GraphQL in 150 words for a non-technical product manager."
+
+### Give Claude a role (Beginner)
+Assigning a role calibrates expertise, vocabulary, and judgment in one move.
+**Example:** "You are a senior security engineer reviewing this code for OWASP Top 10 issues."
+
+### Show, don't tell (few-shot) (Beginner)
+Two or three examples of the input-output pattern you want will outperform paragraphs of instructions.
+**Example:** Paste 3 sample email replies you like, then ask Claude to write a fourth in the same style.
+
+### Ask Claude to think before answering (Beginner)
+For anything non-trivial, add "think through this step by step before answering" or "show your reasoning". Quality jumps noticeably on multi-step problems.
+
+### Iterate, don't restart (Beginner)
+Refine the previous answer rather than re-prompting from scratch. "Make it shorter", "add a counterexample", "now rewrite for executives" all keep accumulated context.
+
+---
+
+## Tier 2 — Workflow accelerators
+
+### Use artifacts for anything you'll reuse (Intermediate)
+Code, documents, diagrams, dashboards — ask Claude to put them in an artifact. You get a clean, copy-paste-ready output instead of digging through chat.
+
+### Web search for anything time-sensitive (Beginner)
+Claude has a knowledge cutoff. For current prices, recent news, live documentation, or "what's new in X", ask Claude to search the web.
+
+### File creation for documents (Intermediate)
+For polished deliverables (Word docs, PDFs, slides, spreadsheets), ask Claude to create the file rather than paste content into chat.
+
+### Structured output with XML tags (Intermediate)
+For complex prompts, wrap sections in tags: `<context>...</context>`, `<task>...</task>`, `<constraints>...</constraints>`. Claude parses these reliably and they prevent instruction-drift.
+
+### Constraints over hints (Intermediate)
+"Use simple words" is a hint. "No word over 3 syllables, no sentence over 15 words" is a constraint. Constraints produce measurable changes; hints often get ignored.
+
+---
+
+## Tier 3 — Memory and context
+
+### User preferences (Intermediate)
+In Claude.ai Settings, write a paragraph about your role, tools, and how you want Claude to respond. Applies to every future chat.
+
+### Projects (Intermediate)
+For ongoing work, create a Project. Drop reference documents in once and they are available in every chat inside that project.
+
+### Memory edits (Intermediate)
+Ask Claude to "remember that I prefer X" and the memory system persists it across conversations. Ask "forget X" to remove.
+
+### Past chat search (Intermediate)
+Claude can search your past conversations. "What did we decide about the auth flow last week?" works.
+
+---
+
+## Tier 4 — Output control
+
+### Ask for alternatives (Beginner)
+"Give me three options, ranked, with tradeoffs" beats "what should I do?" every time.
+
+### Force a format (Beginner)
+"Respond as a JSON object with keys: x, y, z" or "respond as a markdown table" works when you need structured data.
+
+### Adjust depth on demand (Beginner)
+"One sentence", "one paragraph", "deep dive", "explain like I'm 12", "explain like I'm a PhD" all reliably shift register.
+
+### Steelman the opposite (Intermediate)
+Before committing to a plan, ask Claude to argue against it. "What's the strongest case for not doing this?"
+
+---
+
+## Tier 5 — Advanced
+
+### Chain prompts deliberately (Advanced)
+Break complex work into stages: research → outline → draft → critique → final. Each stage gets a focused prompt. Quality compounds.
+
+### Self-critique loops (Advanced)
+After Claude produces output, ask "score this 1-10 on [specific criteria], then rewrite to fix the lowest-scoring dimension." Repeat until satisfied.
+
+### Adversarial review (Advanced)
+"Read this as a skeptical senior reviewer. What are the three weakest claims and how would you attack them?"
+
+### Tool use with MCP (Advanced)
+Connect Claude to external tools (Notion, Gmail, GitHub, databases) via the MCP connector menu. Coaching, code, and content workflows can now actually take action.
+
+### Custom skills (Advanced)
+Skills like this one are reusable instruction packs. If you find yourself repeating the same setup prompt across chats, that is a skill waiting to be built.
+
+---
+
+## Anti-patterns (the slow ways)
+
+- Re-explaining the same context every new chat → use a Project or User Preferences
+- Copy-pasting between Claude and another app repeatedly → ask Claude to do the multi-step work in one prompt
+- Asking yes/no questions on judgment calls → ask for ranked options with tradeoffs
+- Accepting the first draft → ask for a self-critique and one rewrite
+- Vague feedback ("make it better") → name the specific dimension ("make it more concrete", "cut 30%")

package/engineering/claude-coach/skills/claude-coach/references/coaching-rules.md

@@ -0,0 +1,44 @@
+# Coaching Rules — When to Speak, When to Stay Silent
+
+The single biggest failure mode for this skill is over-coaching. Users will start ignoring tips if they come too often or feel forced. These rules exist to prevent that.
+
+## The decision tree
+
+For every response, ask in order:
+
+1. **Did I already coach in the previous response?** → If yes, stay silent unless the user explicitly asked for feedback.
+2. **Was the user's prompt already well-formed?** → If yes, stay silent. Good prompts deserve good answers, not unsolicited critique.
+3. **Is the user in deep work mode?** → Long technical sessions, creative writing flow, emotional conversations all warrant silence. A tip interrupts focus.
+4. **Would the tip be obvious or condescending?** → If a competent user would already know it, do not say it. "Tip: you can ask me follow-up questions" is condescending.
+5. **Is there exactly ONE clearly higher-impact path the user missed?** → If yes, surface that one. If you find yourself listing two or three, pick the single best and save the rest.
+
+If you cleared all five gates, surface the tip in the exact format defined in SKILL.md.
+
+## Coachable moments — examples
+
+These are the patterns that genuinely warrant a tip:
+
+- User asks Claude to "help with my email" without specifying tone, audience, or goal → tip: name the audience and the outcome
+- User pastes a long doc and asks "thoughts?" → tip: ask for specific dimensions (clarity, structure, gaps)
+- User iterates 3+ times on the same output → tip: name the missing constraint explicitly
+- User asks Claude for current information without invoking web search → tip: web search for time-sensitive queries
+- User does manual reformatting Claude could have done → tip: request the format upfront
+- User asks for a list when ranked options with tradeoffs would serve them better
+
+## Non-coachable moments — examples
+
+These look coachable but are not:
+
+- User's first message is a clean, specific prompt → no tip needed, just answer
+- User is venting or processing something emotionally → no tip, hold space
+- User explicitly says "just do X, no commentary" → respect that, no tip
+- User is mid-debug, deep in technical detail → no tip, stay on task
+- Tip would be a generic platitude ("you can always ask for more detail") → not specific enough, skip
+
+## The 24-hour rule
+
+If you have surfaced 3+ tips in the last several turns, force a cooling period. The user is now in fire-hose territory and tips lose value. Wait until they explicitly ask for feedback again before resuming.
+
+## When the user pushes back
+
+If the user ever signals tips are unwelcome ("stop with the tips", "I don't need coaching right now"), immediately stop. Resume only if they re-activate the skill explicitly.

package/engineering/claude-coach/skills/claude-coach/scripts/cheat_code_filter.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+cheat_code_filter.py — filter the claude-coach cheat-code glossary by use case.
+
+Reads references/cheat-codes.md, parses tiered technique entries, and returns
+the top-N matches scored against a user's stated use cases (writing, coding,
+research, learning, business, etc.). Stdlib-only.
+
+Usage:
+    python3 cheat_code_filter.py --use-cases "writing,coding" --top 7
+    python3 cheat_code_filter.py --use-cases "research" --json
+    python3 cheat_code_filter.py --sample
+"""
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Iterable
+
+USE_CASE_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "writing": ("write", "draft", "tone", "audience", "rewrite", "edit", "voice", "format"),
+    "coding": ("code", "function", "bug", "debug", "review", "test", "refactor", "stack"),
+    "research": ("research", "search", "source", "cite", "summary", "synthes", "compare"),
+    "learning": ("explain", "teach", "concept", "understand", "tutorial", "learn"),
+    "business": ("plan", "strategy", "memo", "decision", "tradeoff", "stakeholder", "report"),
+    "data": ("json", "table", "structured", "parse", "format", "schema", "extract"),
+}
+
+DEFAULT_GLOSSARY = Path(__file__).resolve().parent.parent / "references" / "cheat-codes.md"
+
+TIER_HEADING = re.compile(r"^##\s+Tier\s+(\d+)", re.IGNORECASE)
+TECHNIQUE_HEADING = re.compile(r"^###\s+(?P<title>.+?)\s*\((?P<level>Beginner|Intermediate|Advanced)\)\s*$", re.IGNORECASE)
+EXAMPLE_LINE = re.compile(r"^\*\*Example:\*\*\s+(?P<text>.+)$")
+
+
+@dataclass
+class Technique:
+    title: str
+    level: str
+    tier: int
+    explanation: str
+    example: str
+    score: float = 0.0
+
+
+def parse_glossary(path: Path) -> list[Technique]:
+    if not path.exists():
+        raise FileNotFoundError(f"Glossary not found at {path}")
+    techniques: list[Technique] = []
+    current_tier = 99
+    current: Technique | None = None
+    lines = path.read_text(encoding="utf-8").splitlines()
+    for line in lines:
+        tier_match = TIER_HEADING.match(line)
+        if tier_match:
+            current_tier = int(tier_match.group(1))
+            continue
+        tech_match = TECHNIQUE_HEADING.match(line)
+        if tech_match:
+            if current is not None:
+                techniques.append(current)
+            current = Technique(
+                title=tech_match.group("title").strip(),
+                level=tech_match.group("level").capitalize(),
+                tier=current_tier,
+                explanation="",
+                example="",
+            )
+            continue
+        if current is None:
+            continue
+        ex_match = EXAMPLE_LINE.match(line)
+        if ex_match:
+            current.example = ex_match.group("text").strip()
+            continue
+        if line.strip() and not line.startswith("---") and not line.startswith("##"):
+            if not current.explanation:
+                current.explanation = line.strip()
+    if current is not None:
+        techniques.append(current)
+    return techniques
+
+
+def score_technique(tech: Technique, use_cases: Iterable[str]) -> float:
+    text = f"{tech.title} {tech.explanation} {tech.example}".lower()
+    score = 0.0
+    matched_use_cases = 0
+    for uc in use_cases:
+        uc = uc.strip().lower()
+        keywords = USE_CASE_KEYWORDS.get(uc, (uc,))
+        hits = sum(1 for kw in keywords if kw in text)
+        if hits:
+            matched_use_cases += 1
+            score += hits
+    tier_weight = max(0.0, 6 - tech.tier) * 1.5
+    level_weight = {"Beginner": 2.0, "Intermediate": 1.0, "Advanced": 0.5}.get(tech.level, 1.0)
+    return score + tier_weight + level_weight + matched_use_cases * 0.5
+
+
+def rank(techniques: list[Technique], use_cases: list[str], top: int) -> list[Technique]:
+    for tech in techniques:
+        tech.score = score_technique(tech, use_cases)
+    techniques.sort(key=lambda t: (-t.score, t.tier, t.title))
+    return techniques[:top]
+
+
+def render_human(picks: list[Technique]) -> str:
+    if not picks:
+        return "No techniques matched the supplied use cases."
+    out: list[str] = []
+    for tech in picks:
+        out.append(f"- **{tech.title}** ({tech.level}) — {tech.explanation}")
+        if tech.example:
+            out.append(f"  _{tech.example}_")
+    return "\n".join(out)
+
+
+def sample_run() -> int:
+    sample_path = DEFAULT_GLOSSARY
+    if not sample_path.exists():
+        print("Sample glossary not found; place references/cheat-codes.md alongside this script.", file=sys.stderr)
+        return 1
+    picks = rank(parse_glossary(sample_path), ["writing", "coding"], 5)
+    print(render_human(picks))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Filter cheat-codes.md by use cases.")
+    parser.add_argument("--glossary", type=Path, default=DEFAULT_GLOSSARY, help="Path to cheat-codes.md")
+    parser.add_argument("--use-cases", type=str, default="", help="Comma-separated use cases (writing,coding,research,learning,business,data)")
+    parser.add_argument("--top", type=int, default=7, help="Number of techniques to return (default 7)")
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of human-readable text")
+    parser.add_argument("--sample", action="store_true", help="Run on the bundled glossary with sample use cases")
+    args = parser.parse_args(argv)
+
+    if args.sample:
+        return sample_run()
+
+    if not args.use_cases:
+        parser.error("--use-cases is required unless --sample is passed")
+
+    use_cases = [u.strip() for u in args.use_cases.split(",") if u.strip()]
+    try:
+        techniques = parse_glossary(args.glossary)
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    picks = rank(techniques, use_cases, args.top)
+
+    if args.json:
+        print(json.dumps({"use_cases": use_cases, "picks": [asdict(t) for t in picks]}, indent=2))
+    else:
+        print(render_human(picks))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())