From 148930ccd9c9b46c284e17f0a77163ee9f3502a1 Mon Sep 17 00:00:00 2001 From: Snehal Raj Date: Fri, 27 Feb 2026 09:39:29 +0100 Subject: [PATCH 1/4] feat: add skills/ directory for Claude Code discovery Claude Code discovers skills by scanning skills//SKILL.md inside plugin directories. Move SKILL.md and reference docs into the canonical skills/skill-issue/ path so the skill is automatically discovered. --- SKILL.md => skills/skill-issue/SKILL.md | 0 {references => skills/skill-issue/references}/challenge-design.md | 0 .../skill-issue/references}/interaction-patterns.md | 0 .../skill-issue/references}/scoring-and-adaptation.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename SKILL.md => skills/skill-issue/SKILL.md (100%) rename {references => skills/skill-issue/references}/challenge-design.md (100%) rename {references => skills/skill-issue/references}/interaction-patterns.md (100%) rename {references => skills/skill-issue/references}/scoring-and-adaptation.md (100%) diff --git a/SKILL.md b/skills/skill-issue/SKILL.md similarity index 100% rename from SKILL.md rename to skills/skill-issue/SKILL.md diff --git a/references/challenge-design.md b/skills/skill-issue/references/challenge-design.md similarity index 100% rename from references/challenge-design.md rename to skills/skill-issue/references/challenge-design.md diff --git a/references/interaction-patterns.md b/skills/skill-issue/references/interaction-patterns.md similarity index 100% rename from references/interaction-patterns.md rename to skills/skill-issue/references/interaction-patterns.md diff --git a/references/scoring-and-adaptation.md b/skills/skill-issue/references/scoring-and-adaptation.md similarity index 100% rename from references/scoring-and-adaptation.md rename to skills/skill-issue/references/scoring-and-adaptation.md From 68ceb08d8453cccf3027a1de3aa727ad16c08df3 Mon Sep 17 00:00:00 2001 From: Snehal Raj Date: Fri, 27 Feb 2026 09:39:53 +0100 Subject: [PATCH 2/4] chore: remove stale SKILL.md from Python package The canonical location is now skills/skill-issue/SKILL.md. The Python wheel no longer bundles SKILL.md as package data. --- pyproject.toml | 3 -- skill_issue/SKILL.md | 106 ------------------------------------------- 2 files changed, 109 deletions(-) delete mode 100644 skill_issue/SKILL.md diff --git a/pyproject.toml b/pyproject.toml index 5c6de14..c4f3f7b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,9 +30,6 @@ include = ["skill_issue*"] [project.optional-dependencies] dev = ["pytest>=7.0"] -[tool.setuptools.package-data] -skill_issue = ["SKILL.md"] - [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] diff --git a/skill_issue/SKILL.md b/skill_issue/SKILL.md deleted file mode 100644 index 17c360e..0000000 --- a/skill_issue/SKILL.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: skill-issue -description: "Gamified active learning system that challenges the human during agentic coding sessions. Embeds spaced-retrieval challenges directly into the workflow at teaching moments. Tracks mastery via a pedagogical knowledge graph (fundamental concepts weighted by reuse frequency). Use whenever performing substantive coding, math, algorithm design, debugging, or architectural decisions โ€” especially in research contexts (quantum computing, ML). Also trigger on: 'my stats', 'challenge me', 'show graph', or any direct reference to skill-issue." -allowed-tools: "Bash(skill-issue *)" ---- - -# skill-issue ๐Ÿง  - -**Core principle:** Challenges must be tied to what was just coded. Target high-reuse fundamentals the human hasn't mastered yet. Never random trivia. - -## Setup (first run) - -```bash -skill-issue init --domain quantum-ml # or: algorithms, ml, python -``` - -Ask user's name + domain if not set. Greet returning users: -> "Welcome back, [name]. Streak: ๐Ÿ”ฅ[N]. Level: [L]. Let's build." - -## When to Challenge - -**ALWAYS:** non-trivial algorithm, math derivation, subtle bug fix, domain-specific concept (parameter shift rule, attention, circuit identity) -**SOMETIMES** (per config): helper function with interesting logic, library/approach tradeoff -**NEVER:** boilerplate, imports, CI, crisis-debugging, focus mode, <8 min since last challenge, 3 consecutive skips - -## Knowledge Graph โ€” Check This First - -Before issuing a challenge: -```bash -skill-issue graph weak --domain --json -``` -If current code maps to a weak high-priority node โ†’ challenge on that concept. -After scoring: `skill-issue graph update --node --score <0-3> --domain ` - -Priority = `reuse_weight ร— (1 - mastery)`. Fundamentals the human hasn't proven yet = highest priority. - -## Challenge Format - -``` -๐Ÿง  SKILL CHECK #[N] โ€” `[topic]` โ€” Difficulty: [Level] - -[1-2 sentences: what was just built/decided] - -โ†’ [The question] - -`answer` `hint` `skip` -``` - -Types: `pen-paper` ๐Ÿ“ | `explain-back` ๐Ÿ—ฃ๏ธ | `predict` ๐Ÿ”ฎ | `spot-bug` ๐Ÿ› | `complexity` โฑ๏ธ | `connect-dots` ๐Ÿ”— -Vary types each session. Details โ†’ `references/challenge-design.md` - -## Scoring - -``` -final_xp = round(base ร— difficulty_mult ร— streak_mult ร— hint_penalty) -``` - -| Score | Meaning | Base XP | Streak | -|---|---|---|---| -| 0 | Wrong/skip | 0 | reset | -| 1 | Partial | 5 | no change | -| 2 | Correct | 12 | +1 | -| 3 | Exceptional | 20 | +1 | - -Difficulty: Apprentice 1ร—, Practitioner 1.5ร—, Expert 2ร—, Master 3ร— -Streak bonus: `min(1.0 + streakร—0.15, 2.5)` | Hint penalty: 0.75ร— - -```bash -skill-issue score --id [N] --score [0-3] --topic [tag] --difficulty [Level] -``` - -Full formula + worked examples โ†’ `references/scoring-and-adaptation.md` - -## Feedback Style - -- Wrong โ†’ what they got right first, then the gap. Never shame. -- Partial โ†’ acknowledge + fill the gap -- Correct โ†’ brief confirmation + one extra insight -- Exceptional โ†’ "That's deeper than I was testing for." - -## User Commands - -| Say | Action | -|---|---| -| `my stats` / `trophy wall` | Show profile / leaderboard | -| `harder` / `easier` | Shift difficulty ยฑ1 | -| `focus mode` / `challenges on` | Toggle off/on | -| `challenge me` | Force challenge now | -| `show graph` | `skill-issue graph show --domain ` | -| `show brain` | `skill-issue graph web --domain ` (D3 viz) | -| `hint` / `skip` | Hint (0.75ร— XP) / skip (score 0) | - -## Session Lifecycle - -**End of session:** `skill-issue report` โ†’ summary + update leaderboard -**After 7+ days away:** start one difficulty level lower for first 2 challenges -**3 consecutive wrong:** "Want me to walk through the last concept before we continue?" - -## Visualization - -```bash -skill-issue graph show --domain quantum-ml # ASCII bar chart in terminal -skill-issue graph web --domain quantum-ml # D3 force-directed graph in browser -``` - -Nodes sized by `reuse_weight`, colored by mastery. Click nodes to see challenge hooks. From 6a0314b361f8e6550890a121e4e14f3949c33fee Mon Sep 17 00:00:00 2001 From: Snehal Raj Date: Fri, 27 Feb 2026 09:40:28 +0100 Subject: [PATCH 3/4] chore: bump versions for skill directory restructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit plugin.json: 1.0.0 โ†’ 1.1.0 (new skills/ layout) pyproject.toml: 1.2.0 โ†’ 1.3.0 (SKILL.md removed from wheel) --- .claude-plugin/plugin.json | 2 +- pyproject.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b445c8d..ff13893 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "skill-issue", "description": "Gamified active learning for agentic coding sessions โ€” bite-sized challenges, XP, streaks, and topic mastery embedded directly into your workflow", - "version": "1.0.0", + "version": "1.1.0", "author": { "name": "Snehal Raj", "github": "SnehalRaj" diff --git a/pyproject.toml b/pyproject.toml index c4f3f7b..b717805 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "skill-issue-cc" -version = "1.2.0" +version = "1.3.0" description = "Gamified active learning system for agentic coding sessions" readme = "README.md" license = { text = "MIT" } From 2f3e8e269b899b1d967c8d030bdb53b46929cf26 Mon Sep 17 00:00:00 2001 From: Snehal Raj Date: Fri, 27 Feb 2026 09:46:52 +0100 Subject: [PATCH 4/4] fix: restore SKILL.md access for CLI via symlink MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CLI's init --claude and init --print commands need to read SKILL.md. Add a symlink at skill_issue/SKILL.md โ†’ ../skills/skill-issue/SKILL.md so the package-relative path works for both pip installs (setuptools follows symlinks when building wheels) and dev mode. Also update _get_skill_md_path() to check skills/skill-issue/SKILL.md as a fallback for dev checkouts where the symlink might not resolve. --- pyproject.toml | 3 +++ skill_issue/SKILL.md | 1 + skill_issue/cli.py | 9 ++++++--- 3 files changed, 10 insertions(+), 3 deletions(-) create mode 120000 skill_issue/SKILL.md diff --git a/pyproject.toml b/pyproject.toml index b717805..7bbca48 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,6 +27,9 @@ skill-issue = "skill_issue.cli:main" where = ["."] include = ["skill_issue*"] +[tool.setuptools.package-data] +skill_issue = ["SKILL.md"] + [project.optional-dependencies] dev = ["pytest>=7.0"] diff --git a/skill_issue/SKILL.md b/skill_issue/SKILL.md new file mode 120000 index 0000000..7783738 --- /dev/null +++ b/skill_issue/SKILL.md @@ -0,0 +1 @@ +../skills/skill-issue/SKILL.md \ No newline at end of file diff --git a/skill_issue/cli.py b/skill_issue/cli.py index d9b8b77..2feb14b 100644 --- a/skill_issue/cli.py +++ b/skill_issue/cli.py @@ -9,10 +9,13 @@ def _get_skill_md_path() -> Path: - """Find SKILL.md - try package-relative first (pip install), then repo root (dev).""" + """Find SKILL.md - try package-relative first (pip install), then skills/ dir (dev).""" + # 1. Package-relative: works for pip install (symlink resolved at build time) skill_md_path = Path(__file__).parent / "SKILL.md" - if not skill_md_path.exists(): - skill_md_path = Path(__file__).parent.parent / "SKILL.md" + if skill_md_path.exists(): + return skill_md_path + # 2. Canonical skills/ directory: works for dev mode (repo checkout) + skill_md_path = Path(__file__).parent.parent / "skills" / "skill-issue" / "SKILL.md" return skill_md_path