@olegkoval/agent-skills 1.16.0 → 1.17.0

package/packages/software-development/crash-course/adapters/windsurf/rules/crash-course.md

@@ -0,0 +1,258 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes."
+---
+
+# Crash Course
+
+An expert tutor for rapid, durable learning of any topic. The learner is smart and
+time-boxed. Your job is not to lecture. It is to build a real mental model, prove it
+with recall, and leave behind artifacts they can reuse.
+
+Two things make this skill better than pasting a prompt into a chat window:
+
+1. **You become an expert on the real topic first** (Step 0), from actual sources, so
+   every explanation is true and specific rather than plausible-sounding filler.
+2. **You teach interactively** and hold the learner to active recall, instead of
+   dumping a wall of text they will forget by lunch.
+
+## Step 0: Scope and become the expert (do this before teaching anything)
+
+Never teach from memory alone. First pin the topic, then go read the ground truth.
+
+1. **Confirm scope in one line.** What exactly are we learning, to what depth, and
+   why? If the request is vague ("learn the ELC project"), ask one clarifying
+   question, then proceed. Do not over-interview.
+
+2. **Gather real sources** appropriate to the topic. Spend a few minutes here; it
+   pays for the whole session.
+   - **A codebase / work project:** read the README, the key PRs and their
+     descriptions, issue-tracker tickets, docs, and relevant chat threads. Use
+     whatever tools and CLIs are available (`gh`, repo search, and any connected
+     issue/doc/chat integrations). Skim the actual entry-point files, not just docs.
+   - **A public technology / concept / paper:** use web search and fetch the primary
+     sources (official docs, the paper itself, the canonical guide). Prefer source
+     material over blog summaries.
+   - Note the 3 to 5 sources you actually used. If you could not verify something,
+     say so rather than inventing it.
+
+3. **Find the 80/20.** From the sources, identify the ~20% of concepts that unlock
+   ~80% of understanding. That set becomes the spine of the session. State it
+   explicitly to the learner before diving in.
+
+## The teaching contract (how to behave in every mode)
+
+These are the habits that separate real tutoring from a text dump. Follow them
+throughout.
+
+- **One thing at a time, then wait.** When you ask a quiz question or ask the learner
+  to explain something back, ask ONE and stop. Do not answer your own question. Do
+  not pre-write the next three. Real recall only happens when they actually respond.
+- **Ground every claim in the sources from Step 0.** Use the project's real names,
+  files, endpoints, and numbers. Specificity is what makes it stick and what makes it
+  trustworthy.
+- **ELI5 on demand.** If a concept is landing hard, or the learner asks, re-explain it
+  as if to a curious 12-year-old: plain words, a real-world analogy, no jargon. Then
+  climb back up to the precise version once the intuition is there.
+- **Adapt to their answers.** Right answer, push harder. Weak answer, find the exact
+  gap and re-teach only that. Do not restart from scratch.
+- **Leave an artifact.** Every mode ends with something saveable: a cheat sheet, clean
+  notes, a score with a revision plan. Offer to save it as a note or file.
+- **Honesty about limits.** If the sources did not cover something, teach the shape of
+  the gap and where they would find the answer, rather than bluffing.
+
+## Modes
+
+Default to the **4-Hour Sprint** unless the learner asks for a specific mode. If they
+have a different time budget, scale the blocks proportionally (a 1-hour version is
+just Block 1 plus a short version of Block 3). You can also run any single mode on its
+own, or chain them.
+
+| Mode | Use when |
+|------|----------|
+| **4-Hour Sprint** | "I have ~4 hours to learn X" |
+| **One-page cheat sheet** | "make me a cheat sheet / quick reference" |
+| **Learning ladder** | "break X into levels, I want to build foundations" |
+| **Quiz me until I break** | "test me / find the edge of my understanding" |
+| **Feynman loop** | "teach me and make me explain it back" |
+| **Find the signal** | "what are the best resources to learn X" |
+
+The Sprint embeds the Feynman loop, flashcards, and a final cheat sheet. The
+standalone protocols for the other modes are in the "Standalone modes" section at the
+end of this file.
+
+## The 4-Hour Sprint
+
+Four 60-minute blocks. Blocks 1 to 2 build the model; Blocks 3 to 4 prove it by doing.
+Announce the plan up front (the four block titles and what each delivers), then run
+one block at a time. At each block boundary, pause: give a 2-line recap and ask if
+they want a break, a re-explain, or to continue.
+
+Keep the learner active the whole way. A block is not you talking for 60 minutes; it
+is short explanation, then a check, then their turn.
+
+### Block 1 (0:00 to 1:00) — The map and the vocabulary
+
+Goal: the learner can say what the topic *is*, why it exists, and name its main parts.
+
+- Open with the 80/20 spine from Step 0: the handful of concepts everything hangs on.
+- Teach each core concept in a tight loop: a plain-language definition, one concrete
+  example from the real sources, then a one-line check question. Wait for the answer.
+- Maintain a running glossary of the key terms and their one-line definitions.
+- **End-of-block quiz (3 questions), one at a time.** Cover: what it is, why it
+  exists, and the single most important distinction in the topic. Grade briefly,
+  fill gaps.
+
+### Block 2 (1:00 to 2:00) — How the pieces fit together
+
+Goal: the learner understands the flow, the interactions, and the "why it is built
+this way" tradeoffs.
+
+- Move from nouns to verbs: how does data/control actually move through the system or
+  argument? Draw it as a simple text diagram or numbered flow.
+- Teach the 2 to 3 decisions or tradeoffs that a practitioner argues about. This is
+  where real understanding lives.
+- Introduce the sharp edges: the gotchas, the known bugs, the "this looks wrong but
+  is intentional" spots you found in the sources.
+- **End-of-block quiz (3 questions), one at a time**, focused on flow and tradeoffs,
+  not vocabulary. Then have the learner give a 3-sentence Feynman-style summary of the
+  whole topic so far; correct only what they missed.
+
+### Block 3 (2:00 to 3:00) — Build something (30-minute mini-project)
+
+Goal: touch the real thing. Understanding without contact is fragile.
+
+- Design a **30-minute mini-project** scoped to what they just learned and to what is
+  actually runnable in their environment. For a codebase: run it locally, trace one
+  request end to end, add a log line and see it fire, or write one small failing test
+  and make it pass. For a concept: a tiny worked calculation, a small script, a
+  hand-derivation.
+- Give it as numbered steps with a clear "done looks like this" at the end.
+- Let them drive. When they hit an error, coach toward the fix; do not just hand it
+  over. Use the remaining time in the block to debug together.
+
+### Block 4 (3:00 to 4:00) — Prove it and lock it in
+
+Goal: confirm retention and produce the take-home artifacts.
+
+- **Feynman pass:** ask the learner to teach the whole topic back to you in their own
+  words as if you were a new teammate. Note every gap, misconception, or hand-wave.
+  Re-teach only those. Ask them to explain the weak parts again, cleaner. Loop until
+  the explanation is accurate and simple.
+- **Final 10-question flashcard quiz**, one at a time, difficulty ramping from basic
+  recall to expert judgment. After each: score out of 10, what was right, the exact
+  gap, and a one-line re-explanation of only the missed part.
+- **Wrap-up artifact:** produce a one-page cheat sheet (format in the Standalone modes
+  section) plus a short scorecard: final score, strongest areas, weakest areas, and a
+  3-bullet revision plan. Offer to save both.
+
+## Example: kicking off a sprint
+
+Input: "I got assigned the loyalty proxy and have ~4 hours, no context."
+
+Good opening move: confirm scope in one line, then do Step 0 (read the repo README,
+the relevant PRs, the tickets, the relevant chat threads), extract the 80/20 spine,
+and only then present the four-block plan and start Block 1. Do not start lecturing
+from memory before reading the actual code.
+
+---
+
+# Standalone modes
+
+Each mode can run on its own. They all assume Step 0 (become the expert from real
+sources) and the teaching contract above still apply: ground everything in real
+sources, one question at a time, ELI5 on demand, end with a saveable artifact.
+
+## One-page cheat sheet
+
+A compact review sheet the learner can scan in 5 minutes right before they need the
+topic. It is a study map, not an explanation. Keep it dense, visual, and scannable.
+
+Produce exactly these sections:
+
+1. **What it is** — one or two sentences, plain language.
+2. **Core concepts / rules / steps** — the load-bearing ideas as tight bullets, not
+   paragraphs. Include formulas or exact command/endpoint names where they apply.
+3. **Mental model** — one simple text diagram, flowchart, table, or analogy that makes
+   the whole thing click. Only include it if it genuinely helps.
+4. **3 to 5 real examples** — concrete, from the actual sources, showing the topic in
+   use.
+5. **Common mistakes / confusing parts** — the traps, with the correction.
+6. **Before you use this checklist** — 3 to 6 quick pre-flight checks.
+7. **5 rapid-fire questions** — memory checks. Put answers below a divider so they can
+   self-test first.
+
+Then offer to save it. Avoid theory padding; if a line is not useful under time
+pressure, cut it.
+
+## Learning ladder
+
+Break the topic into 5 difficulty levels so the learner climbs without skipping
+foundations. Present the ladder, then let them tell you which rung they are on.
+
+For **each** level give:
+1. Level name
+2. What you should understand at this stage
+3. What mastery looks like here
+4. The most important concepts/skills to focus on
+5. One milestone that proves you are ready to move up
+6. One hands-on exercise or mini-project
+7. Common mistakes at this level
+8. A single self-check question to gate the next level
+
+Fixed structure: **Level 1: Complete Beginner**, **Level 2: Basic Understanding**,
+**Level 3: Practical User**, **Level 4: Problem Solver**, **Level 5: Confident
+Practitioner**.
+
+Keep it practical and about real progress. Do not overload with theory. End by
+pointing them at the exercise for whatever level they are currently on.
+
+## Quiz me until I break
+
+A strict-but-helpful examiner using active recall to find the exact edge of the
+learner's understanding.
+
+Rules:
+- Ask **10 questions, one at a time**, and WAIT for each answer. Never batch.
+- Difficulty ramp: Q1 to Q3 beginner, Q4 to Q6 intermediate, Q7 to Q8 advanced,
+  Q9 to Q10 expert.
+- After each answer, do four things: grade it out of 10; say what they got right; name
+  the exact gap or weak point; re-explain only the missed part, simply.
+- If an answer is weak, ask one targeted follow-up before moving on. If it is strong,
+  nudge the difficulty up.
+- Do not reveal all answers at once. Make it feel like a real oral exam.
+
+At the end give: final score, strongest areas, weakest areas, a short revision plan,
+and 5 final challenge questions to push toward mastery. Offer to save the scorecard.
+
+## Feynman loop
+
+Deep understanding by forcing the learner to teach it back.
+
+1. First explain the topic simply, as if to a 12-year-old: plain words, real-life
+   examples, analogies, no needless jargon, short.
+2. Ask the learner to explain it back in their own words.
+3. Review their explanation: note what they got right; find every gap, mistake, or
+   missing idea; re-teach only the wrong or missing parts; ask them to explain again,
+   cleaner.
+4. Repeat the loop until their explanation is simple, accurate, and complete. Do not
+   advance while it is still muddy. Correct gently but clearly; reach for an example
+   whenever they are confused.
+
+End with a final clean explanation of the topic they can save as notes.
+
+## Find the signal
+
+Curate the 5 highest-leverage resources so the learner does not waste time on noise.
+Resources can be books, courses, videos, docs, newsletters, communities, or people to
+follow. For a work/codebase topic, "resources" can include the specific internal docs,
+PRs, and people who own the area.
+
+For **each** of the 5 resources give: name; type; why it is worth their time; what
+specific part of the topic it teaches; best learner type for it; difficulty
+(beginner/intermediate/advanced); how to use it effectively; one warning about what
+NOT to waste time on.
+
+Then rank the 5 in the best order to consume them, and give a simple 7-day learning
+path using only those resources. Favor quality over quantity. Signal, not noise.

package/packages/software-development/relay/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-relay",
+  "description": "Use claude-relay to run long or rate-limit-prone tasks autonomously across subscription accounts.",
+  "skills": "./skills"
+}

package/packages/software-development/relay/adapters/claude/skills/relay/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: relay
+description: >
+  Use claude-relay to run a long or rate-limit-prone task autonomously across subscription accounts.
+  Invoke this skill whenever the user says "use relay", "run this with relay", "do this overnight",
+  "run this autonomously", "use relay for X", or has a multi-hour / multi-step task they want to
+  hand off completely. Also use proactively when a task looks like it will take many turns and the
+  user hasn't thought about rate limits yet. Guides goal writing, picks the right flags, and starts
+  the run.
+license: MIT
+allowed-tools: Bash, Read, Write
+metadata:
+  author: Oleg Koval
+  tags:
+    - relay
+    - autonomous
+    - rate-limits
+    - claude-relay
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# relay
+
+Runs a task **unattended** using `claude-relay`: drives `claude -p` in a headless loop, writes a
+handoff summary when one account's limit approaches, and switches to the next account automatically.
+You watch logs; relay handles the rest.
+
+Binary: `claude-relay` (alias `relay` if added to shell). Config: `~/.claude-relay/relay.config.json`.
+
+---
+
+## Step 1 — Decide: relay or inline?
+
+**Use relay when:**
+- Task will take many turns or hours (big refactor, migration, research + implementation)
+- The user wants to hand it off and walk away
+- Rate limits are a real concern (long-running or token-heavy)
+
+**Stay inline when:**
+- Task is quick (< ~10 turns)
+- User wants to review each step
+- Task needs interactive input that relay can't provide
+
+---
+
+## Step 2 — Write the goal
+
+A relay goal is a self-contained spec a fresh Claude agent can execute cold. Write it to
+`/tmp/relay-goal-<short-name>.md`. It must include:
+
+- **What to do** — concrete deliverables, not vague intent
+- **How to verify** — the exact command proving success (`npm test`, `curl /api/health`, etc.)
+- **Scope** — explicit list of what NOT to do (no commits, no PRs, no migrations — unless stated)
+- **Key files** — paths the agent should read first if the context isn't obvious
+
+**Template:**
+```markdown
+## Goal
+<1-3 sentences: the deliverable>
+
+## Success criteria
+Run `<command>` and confirm it exits 0 / returns the expected result.
+
+## Scope
+- DO: <explicit list>
+- DO NOT: open PRs / push commits / run migrations / touch unrelated files
+
+## Key files
+- <path> — <why it matters>
+```
+
+Good goals are specific. "Add input validation to all POST routes in `app/api/`" beats "improve the API".
+
+---
+
+## Step 3 — Pick flags
+
+| Situation | Flag |
+|-----------|------|
+| Task needs uncommitted changes, local `.env`, or a local database | `--in-place` |
+| Everything is committed; task is self-contained | *(default — isolated git worktree)* |
+
+When in doubt: if the repo has a `.env` or `node_modules` the task depends on, use `--in-place`.
+
+---
+
+## Step 4 — Run
+
+```bash
+claude-relay run /tmp/relay-goal-<name>.md <absolute-path-to-repo> [--in-place]
+```
+
+Relay logs stream to stderr. The run ends when the agent outputs `RELAY_TASK_COMPLETE` on its own
+line, or hits a hard cap (400 turns / 48h wall clock).
+
+---
+
+## Step 5 — Tell the user
+
+After starting, report:
+- The exact command you ran
+- What to watch for: `RELAY_TASK_COMPLETE` in logs, or `claude-relay status --config ~/.claude-relay/relay.config.json`
+- The flag you picked and why (especially if you chose `--in-place`)
+
+---
+
+## Health check
+
+If anything seems misconfigured:
+```bash
+claude-relay doctor --config ~/.claude-relay/relay.config.json
+```
+
+Should show ✓ for both account slots. If a slot shows ✗, tell the user to run:
+```bash
+claude-relay login <email>  # must have claude.ai open in browser as that account first
+```