Metadata-Version: 2.4
Name: skill-issue-cc
Version: 1.0.0
Summary: Gamified active learning system for agentic coding sessions
License: MIT
Keywords: claude,claude-code,ai,learning,gamification,spaced-repetition
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# skill-issue 🧠

> *You're not bad at coding. You just have a skill issue.*

Your AI writes the code. But do **you** actually understand it?

**skill-issue** embeds bite-sized challenges directly into your Claude Code / Cursor / Copilot workflow — at the exact moment you'd otherwise just accept and move on. Earn XP. Build streaks. Actually learn.

---

## Install

**Claude Code** (native, one-time):
```
/plugin marketplace add SnehalRaj/skill-issue-marketplace
/plugin install skill-issue@skill-issue-marketplace
```

**Cursor:**
```
/plugin-add skill-issue
```

**Codex / anything else:**
```bash
pip install skill-issue && skill-issue init
```

Open a session. skill-issue is live.

---

## Demo

![skill-issue in action](assets/demo/skill-issue-demo.gif)

---

## How It Works

The agent codes as normal. When it does something non-trivial — fixes a subtle bug, implements an algorithm, makes an architectural tradeoff — it pauses and challenges you:

```
🧠 SKILL CHECK #23 — `algorithms` — Difficulty: Practitioner

I just wrote a two-pointer function to find all pairs summing to K.

→ What's the time and space complexity? Could it be done better?

`[answer]`  `[hint]`  `[skip]`
```

You answer. It evaluates, gives feedback, awards XP. Coding resumes.

**It never interrupts boilerplate.** Only teaching moments.

---

## Challenge Types

| | Type | Example trigger |
|---|---|---|
| 📝 | Pen & Paper | "What's the output of this function for input [3, 1, 4]?" |
| 🗣️ | Explain Back | "In 2 sentences: why does memoization fix this?" |
| 🔮 | Predict | "What does this regex match on 'hello world'?" |
| 🐛 | Spot the Bug | Show a slightly broken version — find what's wrong |
| ⏱️ | Complexity | "What's the Big-O of what I just wrote? Is there a better way?" |
| 🔗 | Connect | "How does this relate to what we built last session?" |

---

## XP & Progression

```
XP = base × difficulty × streak_multiplier
```

- Streak bonus: up to **2.5×** for consecutive correct answers
- Per-topic mastery: Apprentice → Practitioner → Expert → Master
- Auto-adapts difficulty based on your rolling performance
- Trophy wall in `~/.skill-issue/leaderboard.md`

---

## Commands

Say these to the agent at any time:

```
my stats       → XP, level, streak
harder         → bump difficulty
focus mode     → pause all challenges
challenge me   → force one right now
trophy wall    → show leaderboard
```

---

## Why This Exists

AI coding tools are incredible. They're also making it easy to ship code you don't understand.

Not because you're lazy — because the workflow doesn't give you a reason to engage. You're in flow, the code looks right, you move on.

skill-issue adds that reason. It's the difference between watching someone solve a puzzle and solving it yourself.

---

## Contributing

The challenge banks (in `references/challenge-design.md`) are just markdown — easy to extend for your domain. PRs welcome.

**MIT license.**

---

*Works with Claude Code, Cursor, GitHub Copilot, and any agent that reads a system prompt.*
