{"id":49714311,"url":"https://github.com/sebastianelvis/hammer","last_synced_at":"2026-05-08T19:04:18.046Z","repository":{"id":353571751,"uuid":"1219907137","full_name":"SebastianElvis/hammer","owner":"SebastianElvis","description":"AI agent skills for learning — the agent plays tutor, you play learner","archived":false,"fork":false,"pushed_at":"2026-05-02T04:22:13.000Z","size":109,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T04:30:11.752Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SebastianElvis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-24T10:44:27.000Z","updated_at":"2026-05-02T04:22:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SebastianElvis/hammer","commit_stats":null,"previous_names":["sebastianelvis/hammer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SebastianElvis/hammer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebastianElvis%2Fhammer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebastianElvis%2Fhammer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebastianElvis%2Fhammer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebastianElvis%2Fhammer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SebastianElvis","download_url":"https://codeload.github.com/SebastianElvis/hammer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebastianElvis%2Fhammer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32793488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-08T19:04:07.983Z","updated_at":"2026-05-08T19:04:18.037Z","avatar_url":"https://github.com/SebastianElvis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hammer\n\nPersonal agent-skills for learning. The agent plays tutor, you play learner — it refuses to just hand you answers, keeps a persistent profile of what you know and what you've stumbled on, and spaces review of past material across sessions.\n\nCurrently ships one skill: **`teach`**. The repo is named for Richard Hamming, whose *Learning to Learn* is the spine of the approach.\n\n## Install\n\nThe repo is in the [vercel-labs/skills](https://github.com/vercel-labs/skills) format and also carries a Claude Code plugin manifest, so you can install it via whichever path you prefer.\n\n### Via `npx skills` (any supported agent)\n\n```bash\n# install the teach skill globally (available to all projects)\nnpx skills add SebastianElvis/hammer -g\n\n# or scoped to the current project\nnpx skills add SebastianElvis/hammer\n\n# target a specific agent (claude-code, codex, cursor, opencode, …)\nnpx skills add SebastianElvis/hammer -g -a claude-code\n```\n\nSupported agents are listed in the [vercel-labs/skills README](https://github.com/vercel-labs/skills#supported-agents). The CLI auto-detects what you have installed.\n\n### As a Claude Code plugin\n\nThis repo doubles as a Claude Code [plugin marketplace](https://code.claude.com/docs/en/discover-plugins). Add the marketplace, then install the `hammer` plugin:\n\n```bash\n/plugin marketplace add SebastianElvis/hammer\n/plugin install hammer@hammer\n```\n\nAfter installing, run `/reload-plugins` to activate it.\n\n### Manually\n\nClone the repo and symlink `skills/teach/` into your agent's skills directory (e.g., `~/.claude/skills/teach` for Claude Code).\n\n## Usage\n\nOnce installed, just talk to the agent the way you already do. The skill triggers automatically when you ask to *learn* something rather than *get something done*:\n\n- \"teach me SQL window functions\"\n- \"let's learn Rust ownership — don't just explain, walk me through it\"\n- \"quiz me on what we covered last time\"\n- \"I want to understand how a Bloom filter works\"\n\nIt will *not* fire on debugging help, one-shot factual lookups, or task execution — those are not tutoring. See [`skills/teach/SKILL.md`](skills/teach/SKILL.md) for the full trigger definition.\n\n## Where your progress lives\n\nThe skill stores your learner profile outside the skill directory, so reinstalling or updating the skill never touches your data.\n\n- **Default location**: `./.teach/` — the `.teach/` folder in the agent's current working directory. Learner state is scoped per project; `.teach/` is gitignored so it does not get committed.\n- **Override**: set `TEACH_HOME` to any path — useful for a cross-project profile (`TEACH_HOME=~/.teach`) or per-topic folders (`TEACH_HOME=~/.teach/spanish`).\n\nThe folder contains:\n\n```\n./.teach/\n├── learner.md        # your profile — currently studying, goal, known solid, shaky, misconceptions, calibration notes\n├── review.md         # spaced-review queue (new / learning / mastered buckets)\n├── syllabus.md       # ordered arc for a multi-session topic (created only when needed)\n└── sessions/         # one markdown transcript per day\n```\n\nEverything is plain markdown. You can read it, edit it, back it up, sync it via git/Dropbox — it's just text.\n\n## How a session flows\n\nThe lifecycle runs linearly: **calibration → prepare-syllabus → teach loop**. Each upstream phase is either run or skipped based on state; teaching is always last.\n\n```\n┌────────┐   ┌─────────────┐   ┌──────────────────┐   ┌──────────────────┐   ┌────────┐\n│ START  │   │ CALIBRATION │   │ PREPARE-SYLLABUS │   │   TEACH LOOP     │   │  END   │\n│        │──▶│             │──▶│                  │──▶│                  │──▶│        │\n│ read   │   │  skip if    │   │   skip if no     │   │ drill ⇄ socratic │   │ update │\n│ state  │   │  calibrated │   │   arc needed     │   │        ⇅         │   │ state  │\n│        │   │             │   │                  │   │     feynman      │   │        │\n└────────┘   └─────────────┘   └──────────────────┘   └──────────────────┘   └────────┘\n```\n\nInvariant inside the teach loop: answer-protection on the current target question persists across mode switches — a mode switch is not a way out of a stuck Socratic question. See [`references/refusal-rules.md`](skills/teach/references/refusal-rules.md).\n\nStep by step:\n\n1. **Trigger.** Agent matches your intent against [`SKILL.md`](skills/teach/SKILL.md). If it looks like *learning* rather than *getting something done*, the skill activates.\n2. **Bootstrap.** Resolve `$TEACH_HOME`. On first use, seed it from [`assets/`](skills/teach/assets/). Never write back to the skill directory.\n3. **Read state.** Load `learner.md`, `review.md`, and `syllabus.md` (if present).\n4. **Gate 1 — Calibration.** Run [`modes/calibration.md`](skills/teach/modes/calibration.md) if no profile, or the current topic has no relevant calibration. Otherwise skip. Calibrates level *and* motivation.\n5. **Gate 2 — Prepare syllabus.** Run [`modes/prepare-syllabus.md`](skills/teach/modes/prepare-syllabus.md) if this is a new multi-session topic with no arc yet, or the learner asks to replan mid-course. Otherwise skip. Drafts or reshapes the committed arc.\n6. **Teach loop.** Pick whichever tutoring mode fits the learner's state, and switch between them as the session unfolds:\n   - Review queue has items → [`modes/drill.md`](skills/teach/modes/drill.md): short retrieval practice.\n   - New material → [`modes/socratic.md`](skills/teach/modes/socratic.md): default, question-driven. Answer-protection enforced by [`references/refusal-rules.md`](skills/teach/references/refusal-rules.md).\n   - Consolidating familiar material → [`modes/feynman.md`](skills/teach/modes/feynman.md): you explain it back, the tutor probes for gaps.\n7. **Session end.** State files updated per [`references/state-editing-protocol.md`](skills/teach/references/state-editing-protocol.md) — strict rules that prevent profile corruption over time.\n\n## Repo layout\n\n```\nhammer/\n├── .claude-plugin/\n│   └── marketplace.json        # Claude Code plugin manifest\n├── skills/\n│   └── teach/\n│       ├── SKILL.md            # trigger + orchestration (deliberately thin)\n│       ├── modes/              # one file per teaching mode, loaded on demand\n│       ├── references/         # policy: refusal, evaluation, review buckets, state protocol\n│       └── assets/             # seeds copied to ./.teach/ on first run\n└── evals/                      # eval harness for the skill (dev-only, not shipped)\n```\n\n## Evals\n\nThe skill ships markdown rules (\"don't state the answer\", \"category-3 right-answer-wrong-reasoning\"); `evals/` is what actually checks those rules hold under pressure. It runs the skill against scripted multi-turn scenarios and grades each trial with a mix of code-based and LLM-judge graders. Uses the Claude CLI — no API key required.\n\n```bash\npython evals/run.py refusal --trials 3            # run the refusal pack\npython evals/regrade.py \u003ctask\u003e \u003ctranscript\u003e --k 5 # check judge stability on a frozen transcript\n```\n\nMethodology follows Anthropic's [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents). See [`evals/README.md`](evals/README.md) for layout, how to add tasks, fixtures, and graders, and the cost note.\n\n---\n\n## The principles behind the skill\n\n### 1. Hamming's lens — *learning to learn* is the master skill, and taste decides what is worth learning\n\nHamming's contribution is not a technique but an orientation. *Learning to learn* is the skill that makes every other skill compound: if you cannot get better at acquiring new understanding, you plateau. And the specific *what* you choose to learn matters as much as the *how* — a tutor who only answers \"what are you studying?\" is a less useful tutor than one who, gently and occasionally, also asks \"and why this, and why now?\"\n\nThis is why the skill has a calibration mode at the start of every new topic (of motivation, not just level), and why session-end reflections ask what the learner wants to be able to do next time.\n\n**Sources**:\n- Hamming, R. W. (1997). *The Art of Doing Science and Engineering: Learning to Learn.* Gordon and Breach. Republished by Stripe Press (2020) with a foreword by Bret Victor. The subtitle is this skill's founding premise; Chapter 1 (\"Orientation\") is the clearest statement of why meta-learning is the master skill.\n- Hamming, R. W. (1986). *You and Your Research* (Bell Communications Research Colloquium Seminar, March 7, 1986). In: Kaiser, J. F. (Ed.) (1986). *Transactions of the Bell Communications Research Colloquium Seminar.* The \"important problems\" heuristic: \"What are the important problems in my field? What am I working on? Why aren't they the same thing?\" — the single most load-bearing quote in the skill's design.\n\n**Where applied**: [`modes/calibration.md`](skills/teach/modes/calibration.md), session-end reflection in [`SKILL.md`](skills/teach/SKILL.md).\n\n### 2. Productive struggle — the learner must produce the answer\n\nThe act of producing the answer is what creates understanding. Receiving the answer produces the feeling of learning without the substance. A tutor who removes the friction removes the learning.\n\nThis principle covers the entire Socratic tradition (questions that force the learner to produce their own answer) as well as twentieth-century cognitive science showing that the *effort* of retrieval and reasoning is what produces durable memory, even when it feels less productive than being told.\n\n**Sources**:\n- Plato. *Meno* (c. 380 BCE). Translated by G.M.A. Grube (1976), Hackett Publishing. 82b–85b — Socrates teaches a slave boy geometry by asking only questions.\n- Moore, R. L. (the \"Moore method\"). Documented in: Parker, J. (2005). *R. L. Moore: Mathematician and Teacher.* MAA. Moore refused to let students read the textbook — they had to prove every theorem themselves.\n- Pólya, G. (1945). *How to Solve It.* Princeton University Press. The four-stage framework (understand → plan → execute → look back) gives the principle a practical shape.\n- Bjork, R. A., \u0026 Bjork, E. L. (2011). *Making things hard on oneself, but in a desirable way.* In M. A. Gernsbacher et al. (Eds.), *Psychology and the real world.* Worth Publishers. \"Desirable difficulties\": effort, spacing, interleaving, and generation improve long-term retention by making short-term performance harder.\n- Roediger, H. L., \u0026 Karpicke, J. D. (2006). \"Test-enhanced learning.\" *Psychological Science*, 17(3), 249–255. The testing effect — retrieval outperforms rereading.\n\n**Where applied**: [`modes/socratic.md`](skills/teach/modes/socratic.md), [`references/refusal-rules.md`](skills/teach/references/refusal-rules.md).\n\n*Calibration mechanics — Vygotsky's \"zone of proximal development\" and Bloom's two-sigma finding — back the calibration mode empirically; they're not the philosophical spine, but they're what makes individualized Socratic teaching as effective as the data shows.*\n\n### 3. Understanding is tested by explanation — and the learner is the easiest person to fool\n\nA learner who can recite a definition but cannot recognize the concept when shown it does not understand it. A correct answer produced by bad reasoning is worse than a wrong one, because it hides the gap. The tutor's job is not just to ask — it is to listen for self-deception and surface it, gently, without letting it pass.\n\nThis is why the skill treats \"right answer, wrong reasoning\" as a separate evaluation category rather than collapsing it into \"correct.\"\n\n**Sources**:\n- Feynman, R. P., Leighton, R. B., \u0026 Sands, M. (1963). *The Feynman Lectures on Physics*, Vol. 1, Preface. Addison-Wesley. The preface frames the lectures as Feynman explaining physics to *himself* — the test of understanding is the ability to teach.\n- Feynman, R. P. (1985). *\"Surely You're Joking, Mr. Feynman!\"*. Norton. See \"O Americano, Outra Vez!\" — case study of students who could recite the definition of polarized light but could not recognize it physically.\n- Feynman, R. P. (1974). *Cargo Cult Science* (Caltech commencement address, reprinted in *Surely You're Joking* and elsewhere). \"The first principle is that you must not fool yourself — and you are the easiest person to fool.\"\n\n**Where applied**: [`modes/feynman.md`](skills/teach/modes/feynman.md), [`references/evaluation-rubric.md`](skills/teach/references/evaluation-rubric.md).\n\n### 4. Retention requires retrieval over time\n\nUnderstanding at the end of a session is not the same as knowing the thing a week later. Without retrieval across a gap, knowledge decays on a predictable curve. The cure is spaced retrieval practice.\n\n**Sources**:\n- Ebbinghaus, H. (1885). *Über das Gedächtnis: Untersuchungen zur experimentellen Psychologie* (*Memory: A Contribution to Experimental Psychology*). The original forgetting curve.\n- Karpicke, J. D., \u0026 Roediger, H. L. (2008). \"The critical importance of retrieval for learning.\" *Science*, 319(5865), 966–968. *Retrieval*, not repeated study, is what produces long-term retention. Learners who study-study-study-study perform worse one week out than learners who study-test-test-test — even though the second group feels less confident at the time.\n- Wozniak, P. (1990). *Optimization of learning* (Master's thesis, Poznan University of Technology). The SuperMemo SM-2 algorithm. This skill uses a simplified three-bucket variant rather than date-based intervals, because date math is fragile in an LLM-driven substrate.\n\n**Where applied**: [`modes/drill.md`](skills/teach/modes/drill.md), [`references/review-buckets.md`](skills/teach/references/review-buckets.md).\n\n## License\n\n[MIT](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastianelvis%2Fhammer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebastianelvis%2Fhammer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastianelvis%2Fhammer/lists"}