@olegkoval/agent-skills 1.16.0 → 1.18.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/docs-index-keeper/adapters/grok/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:docs-index-keeper",
+  "version": "0.1.0",
+  "description": "Keep a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows.",
+  "skills": "skills/"
+}

package/packages/software-development/docs-index-keeper/adapters/grok/skills/docs-index-keeper/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: docs-index-keeper
+description: Keep a repository's Markdown docs index in sync by installing and running docs-index-keeper in pre-commit hooks, CI, or one-off maintenance flows.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires shell access and Node.js 18+ when installing from npm.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  package: docs-index-keeper
+  tags:
+    - docs
+    - markdown
+    - documentation
+    - pre-commit
+    - ci
+    - index
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# docs-index-keeper
+
+Use this skill when a repository keeps docs under `docs/` and needs a Markdown index table updated automatically as docs are added or changed.
+
+## Trigger phrases
+
+- keep a docs index up to date
+- auto-update `docs/README.md`
+- add a pre-commit hook for docs indexing
+- enforce docs index freshness in CI
+- add a specific `docs/*.md` file into a Markdown index table
+
+## Workflow
+
+1. Confirm the repo has a docs directory and an index table such as `| Doc | Purpose |`.
+2. Install the package if it is not already present:
+
+```bash
+npm install -D docs-index-keeper
+```
+
+3. Initialize the hook:
+
+```bash
+npx docs-index-keeper init
+```
+
+4. For CI enforcement, run:
+
+```bash
+npx docs-index-keeper check
+```
+
+5. For one-off staged maintenance, run:
+
+```bash
+npx docs-index-keeper update
+```
+
+## Notes
+
+- `update` operates on staged Markdown files.
+- `check` exits non-zero when the index is missing entries for staged docs.
+- Purpose text comes from the first Markdown heading when available.
+- New rows are inserted before an archive sentinel row when present.

package/packages/software-development/gh-cli/adapters/grok/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:gh-cli",
+  "version": "0.1.0",
+  "description": "Use the GitHub CLI effectively for repositories, PRs, Actions, releases, and more.",
+  "skills": "skills/"
+}