teach-me

A lightweight Codex skill that turns completed technical changes into short, teacher-style explanations—without turning every response into a long tutorial.

teach-me explains:

• what changed;
• how the solution works;
• why that approach was chosen;
• one reusable lesson, when it adds value.

The default debrief is limited to 80 words and adapts to the user's technical level.

Example

After implementing a validation fix, Codex may finish with:

Learning: Validation now runs before submission, so invalid data never reaches the API. The rule lives in one function to avoid duplicated behavior. Centralizing validation makes future changes safer because every caller follows the same rule.

Installation

npm

npm install @archiel/teach-me

Copy the installed package from node_modules/@archiel/teach-me into your Codex skills/teach-me directory. For a direct installation into the Codex skills directory, use Git as shown below.

macOS and Linux

git clone https://github.com/LirielC/teach-me.git ~/.codex/skills/teach-me

Windows PowerShell

git clone https://github.com/LirielC/teach-me.git "$HOME\.codex\skills\teach-me"

If CODEX_HOME points somewhere else, install the repository inside its skills directory instead. Restart Codex after installation if the skill is not discovered immediately.

Usage

Invoke the skill explicitly for predictable activation:

Use $teach-me while fixing this bug.

Refactor this module and use $teach-me to explain the decisions.

It can also activate implicitly when you ask Codex to explain a completed technical change, for example:

Fix this and explain what changed, how it works, and why you chose this approach.

The skill recognizes common learning-oriented requests in English and Portuguese.

Always-on personal preference

To request the debrief after every technical change, add this short instruction to your global Codex guidance:

After completing and verifying technical changes, use `$teach-me` in the final response. Keep its educational debrief concise and omit it when no technical change was made.

Explicit $teach-me invocation remains the most predictable option.

Token-conscious by design

The skill keeps explanations compact by instructing Codex to:

• use at most 80 words by default;
• condense trivial changes into one sentence;
• avoid repeating summaries, diffs, commands, tests, and file lists;
• focus on decisions, cause and effect, and meaningful trade-offs;
• skip line-by-line narration;
• expand only when asked.

How it adapts

| User level | Explanation focus | | --- | --- | | Beginner | One essential concept in plain language | | Intermediate | Decisions and reusable patterns | | Advanced | Non-obvious trade-offs, invariants, and consequences |

Repository structure

teach-me/
├── agents/
│   └── openai.yaml   # Codex UI metadata
├── LICENSE           # MIT license
├── README.md
└── SKILL.md          # Trigger description and behavior

Contributing

Issues and pull requests are welcome. Keep changes concise: this skill is intentionally small so loading it consumes as little context as possible.

When proposing a change, describe:

• which prompts should trigger the skill;
• how the output improves;
• whether the change increases token usage.

License

Released under the MIT License.