learn-skills

A set of agent skills that package evidence-backed pedagogical methodologies (explain-and-check, quiz-me, connect-to-what-you-know, ask-me-questions, learn-by-doing, linked-notes, flashcards) as workflows applied to code. The motivation is anti-cognitive-surrender: closing the comprehension gap that opens between a human and a codebase when an LLM has done the work on the human's behalf.

For the rationale, glossary, and decisions log, read CONTEXT.md. For the user-facing overview, read README.md. For load-bearing decisions, read docs/adr/.

Project structure

README.md            → User-facing overview
CONTEXT.md           → Design rationale, glossary, decisions log
CLAUDE.md            → This file: operating conventions for editing the project
.codex-plugin/       → Codex plugin manifest for installable distribution
.agents/plugins/     → Codex marketplace entry pointing at this repo root
.claude-plugin/      → Claude Code plugin manifest
docs/
  adr/               → Architectural decision records (numbered)
  sources.md         → Canonical verification source policy, bundled into every skill
skills/
  <skill-name>/
    SKILL.md         → Required, ≤ 100 lines
    agents/openai.yaml → Optional Codex UI metadata
    <REFERENCE>.md   → Optional, format-spec / reference content, one level deep
    SOURCES.md       → Generated copy of docs/sources.md for standalone installation

Skills (9 total, two families + two meta)

Meta — start-learn, assess Session methodologies (dialogic) — explain-and-check, quiz-me, connect-to-what-you-know, ask-me-questions Generative methodologies (artefact-producing) — learn-by-doing, linked-notes, flashcards

Bloom and SOLO are editorial concepts, not skills. They appear internally as a chooser and in assess as the output scale; they are not listed in the user-facing README.

Conventions (non-negotiable)

• SKILL.md ≤ 100 lines. Local editorial cap, not a discovery limit. Discovery loads metadata; the body loads on activation. Split overflow into a sibling reference file (UPPER-KEBAB.md). See the portability research for the official guidance.
• YAML frontmatter: name (kebab-case, ≤ 64 char) + description (≤ 1024 char, third person, what + when triggers).
• Reference files one level deep only. SKILL.md → REFERENCE.md is fine. SKILL.md → REFERENCE.md → OTHER.md is forbidden — Claude may not follow the second hop.
• Five operating principles apply to every skill (see CONTEXT.md): (1) agent withholds; (2) student speaks first; (3) artefact is the judge; (4) source fidelity → docs/sources.md; (5) exit is a transfer test. New skills must satisfy all five. Skill entrypoints link their bundled SOURCES.md; edit the canonical policy and regenerate copies with python3 scripts/sync_source_policy.py.
• Anti-patterns use "because Y" — Don't X because Y tends to cause Z. Bare prohibitions are weaker than explained ones.
• English everywhere in files. The agent translates user-facing dialogue at runtime — never write Italian (or any other language) in SKILL.md, REFERENCE.md, or docs.
• Cite, never assert from memory. Every claim about external API / library / framework behaviour requires a verifiable link to an authoritative source (docs/sources.md).

Boundaries (what NOT to do)

• Don't add scheduling methodologies (spaced repetition, interleaving as skill/flag). Rejected in ADR 0002 — temporal state management is a sub-project that would swallow this one.
• Don't add monolithic numeric scores to assess. Discrete Bloom/SOLO levels only. Same ADR.
• The agent auto-selects the methodology (ADR 0004). start-learn detects the goal, declares the chosen skill + a one-line reason, and runs it; the user can redirect. This reverses the older "propose, user decides" rule. Principle 1 still binds content (sessions withhold explanations) — only the meta-choice of methodology is automated.
• Don't write SKILL.md in Italian (or any non-English language). Bilingualism is a runtime behaviour, not a file format.
• Don't promote Bloom or SOLO to invocable skills. They are editorial concepts. See ADR 0001.
• Don't add a new skill without evidence. Methodologies in this repo are evidence-backed (explain-and-check, quiz-me, connect-to-what-you-know are the empirical core). Folk pedagogy doesn't enter.

Authoring workflow

To create or modify a skill, use the write-a-skill skill (/write-a-skill). It enforces the SKILL.md template, line cap, and frontmatter conventions.

After any change to a SKILL.md, verify:

# YAML parsing, line caps, names, local resource closure, policy synchronization,
# optional UI metadata and plugin JSON syntax; Ruby standard library only.
ruby scripts/validate_skills.rb
python3 -m unittest discover -s tests -v

These checks also run in .github/workflows/validate-skills.yml. For discovery or behavioral changes, use the isolated cases in evals/README.md; keep grading criteria out of the agent's input and distinguish preparation from actual model execution.

After any change to Codex plugin packaging, verify:

python3 "$HOME/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py" .
home=/private/tmp/codex-home-learn-skills-test
rm -rf "$home" && mkdir -p "$home"
HOME="$home" codex plugin marketplace add .