@g3nomaly/g3n-skills 0.1.4 → 0.1.6

package/.claude-plugin/marketplace.json

@@ -56,6 +56,20 @@
         "./decisions"
       ]
     },
+    {
+      "name": "teach",
+      "source": "./skills/teach",
+      "description": "Teach through real work: build, explain, dive deep, decide architecture, debug and review while the user learns the reasoning.",
+      "skills": [
+        "./teaching",
+        "./learn-by-building",
+        "./explain",
+        "./deep-dive",
+        "./architecture",
+        "./guided-debugging",
+        "./guided-review"
+      ]
+    },
     {
       "name": "using-hooks",
       "source": "./skills/using-hooks",

package/README.md

@@ -1,6 +1,6 @@
 # @g3nomaly/g3n-skills
 
-The g3n skills for Claude Code and Codex: 31 skills in 8 groups. This package holds the skills and has no CLI. Install them with [`@g3nomaly/skills`](https://www.npmjs.com/package/@g3nomaly/skills), which reads this package as its built-in source, or read it as a Claude Code plugin marketplace.
+The g3n skills for Claude Code and Codex: 38 skills in 9 groups. This package holds the skills and has no CLI. Install them with [`@g3nomaly/skills`](https://www.npmjs.com/package/@g3nomaly/skills), which reads this package as its built-in source, or read it as a Claude Code plugin marketplace.
 
 Some skills carry their own hooks. A hook is a TypeScript file in the skill's `hooks/` folder, and the agent runs it with `bun`. The task-manager hooks keep plans, phases and tasks as Markdown files that the agent reaches only through those hooks. The workflow hooks decide when a step of a phase is finished.
 
@@ -65,6 +65,13 @@ Skills marked _manual_ run only when you type their command, such as `/grill-me`
 | `speech` | `no-questions` | Replies end without questions or offers; a Stop hook refuses a reply that asks one |
 | `task-manager` | `task-manager` | Query plans, phases and tasks and change their status through hooks |
 | `task-manager` | `decisions` | Record and look up a plan's decisions as numbered files inside the plan |
+| `teach` | `teaching` | The teaching principles every teach skill follows: real work, causality, mental models and guidance per concept |
+| `teach` | `learn-by-building` | Learn a subject while completing a real task on the user's own system |
+| `teach` | `explain` | Explain existing material through its purpose, mental model, flow and failure modes |
+| `teach` | `deep-dive` | Trace the layers beneath an abstraction, only as deep as the question needs |
+| `teach` | `architecture` | Reason from forces and options to an architecture decision and its consequences |
+| `teach` | `guided-debugging` | Find a failure's root cause through hypotheses and small experiments, teaching the method |
+| `teach` | `guided-review` | Review work by consequence and explain the principle behind each finding |
 | `using-hooks` | `hook-pre-tool-use` | _Manual._ Writing a `PreToolUse` hook, which can allow, deny or escalate a tool call |
 | `using-hooks` | `hook-post-tool-use` | _Manual._ Writing a `PostToolUse` hook, which reacts to a finished tool call |
 | `using-hooks` | `hook-stop` | _Manual._ Writing a `Stop` hook, which can refuse to let the agent end its turn |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/g3n-skills",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The g3n skills, each with its own hooks: a skill source for @g3nomaly/skills and a Claude Code plugin marketplace.",
   "type": "module",
   "files": [
@@ -15,7 +15,7 @@
     "test:clean": "CLEAN_TMP=1 bun test"
   },
   "devDependencies": {
-    "@g3nomaly/core": "^0.3.3",
+    "@g3nomaly/core": "^0.3.5",
     "@types/bun": "^1.4.0",
     "typescript": "~7.0.2",
     "zod": "^4.4.3"

package/skills/coding/code/SKILL.md

@@ -9,7 +9,7 @@ disable-model-invocation: false
 Apply SOLID principles, DRY, and KISS. Use descriptive names for variables, functions, and classes.
 
 - **One domain per file**: schemas, selectors and business logic live in separate files. Split god objects.
-- **Strict typing**: per the language reference. Python passes `mypy` or `pyright`.
+- **Strict typing**: per the language reference.
 - **Production grade**: handle errors explicitly, validate external input at the boundary, leave no dead code.
 - **No shims**: on a rename or refactor, update every call site. Leave no aliases.
 - **Config from the environment**: read configuration from environment variables through a schema.
@@ -26,3 +26,6 @@ Each language has a reference that names its toolchain, its commands and its rul
 | Language | Reference | Files |
 |---|---|---|
 | TypeScript | [`references/typescript.md`](references/typescript.md) | `.ts` `.tsx` |
+| Python | [`references/python.md`](references/python.md) | `.py` |
+| C++ | [`references/cpp.md`](references/cpp.md) | `.cpp` `.cc` `.hpp` `.h` |
+| Rust | [`references/rust.md`](references/rust.md) | `.rs` |

package/skills/coding/code/references/cpp.md

@@ -0,0 +1,43 @@
+# C++
+
+CMake configures and builds with clang. vcpkg supplies dependencies in manifest mode, from `vcpkg.json`. Run commands from inside the project directory, where `CMakeLists.txt` lives.
+
+| Task | Command |
+|---|---|
+| Configure | `cmake --preset <preset>` when `CMakePresets.json` exists, otherwise `cmake -S . -B build -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON` |
+| Add a dependency | `vcpkg add port <pkg>`, then `find_package` and `target_link_libraries` in `CMakeLists.txt` |
+| Build | `cmake --build build` |
+| Run | the target's binary under `build/` |
+
+## Checks
+
+| Check | Command | When |
+|---|---|---|
+| Build | `cmake --build build` | always |
+| Format | `clang-format --dry-run --Werror <files>`, or `clang-format -i <files>` to fix | always |
+| Lint | see [clang-tidy](#clang-tidy) | always |
+| Test | `ctest --test-dir build --output-on-failure` | when the project has tests |
+
+## clang-tidy
+
+Its output is long enough to be cut off in a tool result, and it exits `0` on warnings. Never judge it from the terminal output.
+
+1. Run it in the foreground, all output to a log:
+
+   ```bash
+   clang-tidy -p build --quiet --warnings-as-errors='*' <files> > build/clang-tidy.log 2>&1; echo "exit $?"
+   ```
+
+2. Count the findings: `grep -cE ':[0-9]+:[0-9]+: (warning|error):' build/clang-tidy.log`.
+3. List them: `grep -nE ':[0-9]+:[0-9]+: (warning|error):' build/clang-tidy.log`. When the list itself is long, page through it with `sed -n '1,100p'`, then the next 100, until the line count matches step 2.
+
+The check passes only when the exit code is `0` **and** the count is `0`. Never pipe clang-tidy into `head` or `tail`, and never run it in the background.
+
+## Rules
+
+- Never install libraries with `apt` or vendor them by hand. vcpkg owns dependencies.
+- `.clang-format` and `.clang-tidy` at the project root set the style. Fix the code, not the config, to pass a check.
+- The C++ standard is set once in `CMakeLists.txt`. Do not raise it without asking.
+- Targets compile with `-Wall -Wextra -Wpedantic -Werror`.
+- RAII for every resource. Ownership goes through `std::unique_ptr` or `std::shared_ptr`, never a raw `new` or `delete`.
+- External input is parsed into typed objects at the boundary.

package/skills/coding/code/references/python.md

@@ -0,0 +1,28 @@
+# Python
+
+uv handles install, run and build. Run commands from inside the project directory, where `pyproject.toml` lives.
+
+| Task | Command |
+|---|---|
+| Install | `uv sync` |
+| Add a dependency | `uv add <pkg>`, or `uv add --dev <pkg>` for dev |
+| Run a file | `uv run <file>` |
+| Run a tool once | `uvx <tool>` |
+| Build | `uv build` |
+
+## Checks
+
+| Check | Command | When |
+|---|---|---|
+| Typecheck | `uv run ty check` | always |
+| Lint | `uv run ruff check --fix`, then fix what remains by hand | always |
+| Format | `uv run ruff format --check`, or `uv run ruff format` to fix | always |
+| Test | `uv run pytest` | when the project has tests |
+
+## Rules
+
+- Never `pip`, `python -m venv` or `poetry`. uv owns the environment.
+- Ruff and ty read their settings from `pyproject.toml`. Fix the code, not the config, to pass a check.
+- Every function signature has type hints, including the return type.
+- `object` and narrowing in place of `Any`.
+- External input is parsed into typed objects at the boundary.

package/skills/coding/code/references/rust.md

@@ -0,0 +1,26 @@
+# Rust
+
+Cargo handles install, run, test and build. Run commands from inside the crate or workspace directory, where `Cargo.toml` lives.
+
+| Task | Command |
+|---|---|
+| Install | `cargo fetch`, or let `cargo build` fetch |
+| Add a dependency | `cargo add <crate>`, or `cargo add --dev <crate>` for dev |
+| Run | `cargo run` |
+| Build | `cargo build`, or `cargo build --release` |
+
+## Checks
+
+| Check | Command | When |
+|---|---|---|
+| Typecheck | `cargo check` | always |
+| Lint | `cargo clippy --all-targets -- -D warnings` | always |
+| Format | `cargo fmt --check`, or `cargo fmt` to fix | always |
+| Test | `cargo test` | when the crate has tests |
+
+## Rules
+
+- Fix the code, not the lint config, to pass a check. No `#[allow(...)]` to silence clippy.
+- Errors return as `Result` and travel with `?`. No `unwrap` or `expect` outside tests.
+- No `unsafe` without asking.
+- External input is parsed into typed structs at the boundary, e.g. with `serde`.

package/skills/coding/document/SKILL.md

@@ -54,3 +54,13 @@ A decision is a choice **the user** made, with its _why_, never the _how_. A cho
 The syntax for each language:
 
 - TypeScript: [`references/typescript.md`](references/typescript.md)
+- Python: [`references/python.md`](references/python.md)
+- C++: [`references/cpp.md`](references/cpp.md)
+- Rust: [`references/rust.md`](references/rust.md)
+
+## Editor highlighting
+
+Only when the user asks for docstring highlighting in VS Code. `<document-dir>` is the folder holding this `SKILL.md`.
+
+1. **Install**: `bun <document-dir>/hooks/install-highlighting.ts`. It installs the extension in `vscode/`, which colours Rust doc sections and Python docstring sections like JSDoc tags, and turns off rust-analyzer's comment tokens that would cover them. On exit `1`, report its message.
+2. **Reload**: tell the user to run `Developer: Reload Window`. Done when they see the colours.

package/skills/coding/document/hooks/install-highlighting.ts

@@ -0,0 +1,136 @@
+// packages/g3n-skills/skills/coding/document/hooks/install-highlighting.ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** The editor setting that lets rust-analyzer paint over every grammar inside comments. */
+const RUST_COMMENT_TOKENS = "rust-analyzer.semanticHighlighting.comments.enable";
+
+/** Folder of the grammar-only extension this hook installs. */
+const EXTENSION_DIR = path.join(import.meta.dir, "..", "vscode");
+
+/**
+ * @brief Identity of the extension, read from its `package.json`.
+ *
+ * @property id - `publisher.name`, e.g. `g3nomaly.g3n-doc-tags`.
+ * @property version - Version from `package.json`, e.g. `0.1.0`.
+ */
+type Extension = { id: string; version: string };
+
+/**
+ * @brief Reads the id and version of the extension in `EXTENSION_DIR`.
+ *
+ * @returns The extension's identity.
+ * @throws Error when `package.json` lacks `publisher`, `name` or `version`.
+ */
+function readExtension(): Extension {
+  const manifest: unknown = JSON.parse(fs.readFileSync(path.join(EXTENSION_DIR, "package.json"), "utf8"));
+  if (typeof manifest !== "object" || manifest === null) throw new Error("vscode/package.json is not an object");
+  const { publisher, name, version } = manifest as Record<string, unknown>;
+  if (typeof publisher !== "string" || typeof name !== "string" || typeof version !== "string") {
+    throw new Error("vscode/package.json needs publisher, name and version");
+  }
+  return { id: `${publisher}.${name}`, version };
+}
+
+/**
+ * @brief Runs a command and fails with its output when it exits non-zero.
+ *
+ * @param command - Program and arguments, e.g. `["code", "--install-extension", "x.vsix"]`.
+ * @param cwd - Working directory of the command.
+ * @throws Error with the command's stderr when it exits non-zero.
+ */
+function run(command: string[], cwd: string): void {
+  const result = Bun.spawnSync(command, { cwd, stdout: "pipe", stderr: "pipe" });
+  if (result.exitCode !== 0) {
+    throw new Error(`${command.join(" ")} failed:\n${result.stderr.toString() || result.stdout.toString()}`);
+  }
+}
+
+/**
+ * @brief Packages the extension into a `.vsix` in a fresh temporary folder, so the skill folder stays untouched.
+ *
+ * @param extension - Identity of the extension, which names the file.
+ * @returns Absolute path of the `.vsix`.
+ */
+function packageExtension(extension: Extension): string {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "g3n-doc-tags-"));
+  const source = path.join(work, "extension");
+  fs.cpSync(EXTENSION_DIR, source, { recursive: true });
+
+  const vsix = path.join(work, `${extension.id}-${extension.version}.vsix`);
+  run(["bunx", "@vscode/vsce@3", "package", "--no-dependencies", "--skip-license", "--allow-missing-repository", "--out", vsix], source);
+  return vsix;
+}
+
+/**
+ * @brief Finds the settings file VS Code reads on this machine: the WSL machine settings when a VS Code server
+ * runs here, otherwise the user settings.
+ *
+ * @returns Absolute path of the settings file, which may not exist yet.
+ */
+function settingsPath(): string {
+  const home = os.homedir();
+  if (fs.existsSync(path.join(home, ".vscode-server"))) return path.join(home, ".vscode-server", "data", "Machine", "settings.json");
+  if (process.platform === "darwin") return path.join(home, "Library", "Application Support", "Code", "User", "settings.json");
+  return path.join(home, ".config", "Code", "User", "settings.json");
+}
+
+/**
+ * @brief Turns off rust-analyzer's comment tokens in `file`, so the extension's colours show. Writes the file
+ * only when the setting is not already `false`.
+ *
+ * @param file - Absolute path of a VS Code settings file.
+ * @returns True when the file was written.
+ * @throws Error when the file is not plain JSON, such as a file with comments, naming the setting to add by hand.
+ */
+function disableRustCommentTokens(file: string): boolean {
+  const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "{}";
+  let settings: unknown;
+  try {
+    settings = JSON.parse(text.trim() === "" ? "{}" : text);
+  } catch {
+    settings = null;
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    throw new Error(`${file} is not plain JSON. Add by hand: "${RUST_COMMENT_TOKENS}": false`);
+  }
+
+  const record = settings as Record<string, unknown>;
+  if (record[RUST_COMMENT_TOKENS] === false) return false;
+  record[RUST_COMMENT_TOKENS] = false;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+  return true;
+}
+
+/**
+ * @brief Installs the doc tag highlighting: packages the extension, installs it with VS Code's `code` command,
+ * and turns off rust-analyzer's comment tokens in the VS Code settings. Writes the settings file.
+ *
+ * @param argv - Arguments of the hook. `--pretty` indents the JSON.
+ * @throws Error when `code` is not on the PATH, packaging or installing fails, or the settings are not plain JSON.
+ */
+function main(argv: readonly string[]): void {
+  const code = Bun.which("code");
+  if (code === null) throw new Error("VS Code's `code` command is not on the PATH. Run this from a VS Code terminal.");
+
+  const extension = readExtension();
+  const vsix = packageExtension(extension);
+  run([code, "--install-extension", vsix, "--force"], path.dirname(vsix));
+  fs.rmSync(path.dirname(vsix), { recursive: true, force: true });
+
+  const settings = settingsPath();
+  const settingsChanged = disableRustCommentTokens(settings);
+
+  const result = { extension: `${extension.id}@${extension.version}`, settings, settingsChanged };
+  console.log(JSON.stringify(result, null, argv.includes("--pretty") ? 2 : undefined));
+  console.error("Run `Developer: Reload Window` in VS Code to load the highlighting.");
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/skills/coding/document/references/cpp.md

@@ -0,0 +1,105 @@
+# C++
+
+Doxygen: a `/** */` block directly above the declaration, in the header.
+
+- **Line 1**: `// src/users/user_store.hpp`, the relative path. No `@file` block.
+- **Declarations with a docstring**: functions, classes, structs, enums, type aliases and concepts. The header declaration carries it; the definition in the `.cpp` does not repeat it.
+- **Summary**: `/** Adds two numbers. */` on one line. A longer block opens with `@brief` and the summary.
+- **Tags**: `@param name text`, `@return text`, `@throws Type When ...`, and for the members of a class, struct or enum `@property name text`. Any other tag that fits is fine: `@tparam T text`, `@example`, `@see`, `@deprecated`, `@since`.
+- **Throws**: a function that can throw has one `@throws` tag per exception type, with its full name, e.g. `std::filesystem::filesystem_error`.
+- **Example**: `@example` with the code on the lines below it. Not `@code` ... `@endcode`, which analyze does not read.
+
+```cpp
+/** Adds two numbers. */
+[[nodiscard]] int add(int a, int b);
+
+/**
+ * @brief Retrieves a user by id.
+ *
+ * @param user_id Surrogate key from the `users` table, not the auth provider's id.
+ * @return Custom User class used by the authentication service, or `std::nullopt` when no row matches.
+ */
+[[nodiscard]] std::optional<User> get_user(std::int64_t user_id);
+
+/**
+ * @brief Reads a file and checks it against its schema.
+ *
+ * @param path Absolute path of the file, e.g. `/home/me/app/docs/auth.md`.
+ * @return Custom Tree struct with one node per section of the file.
+ * @throws FileValidationError When a field does not match the schema.
+ * @throws std::filesystem::filesystem_error When the file cannot be read.
+ */
+[[nodiscard]] Tree parse_file(const std::filesystem::path& path);
+
+/**
+ * @brief Error for a file on disk that does not match its schema.
+ *
+ * Holds the path of the file and one issue per rejected field, and `what()`
+ * lists them all. Thrown by `parse_file` and by the readers in `filetree/`,
+ * `decisions/` and `vocabulary/` that check a file's layout by hand. Callers
+ * tell it apart from other errors with `catch (const FileValidationError&)`.
+ *
+ * @property file Absolute path of the file that failed, e.g. `/home/me/app/docs/auth.md`.
+ * @property issues Rejected fields, e.g. `{ "phases.0.status", "is required" }`.
+ *
+ * @example
+ * throw FileValidationError("/home/me/app/docs/auth.md", {{"status", "is \"done\""}});
+ */
+class FileValidationError : public std::runtime_error {
+public:
+    /** Builds the message from the file path and every issue. */
+    FileValidationError(std::filesystem::path file, std::vector<FileValidationIssue> issues);
+
+    const std::filesystem::path file;
+    const std::vector<FileValidationIssue> issues;
+};
+
+/**
+ * @brief Entries a set of requests resolved to, and the requests that did not resolve.
+ *
+ * @property entries Resolved entries by key, e.g. `emphasise`.
+ * @property unknown Requests no source offers, e.g. `ghost@mine`.
+ * @property notes Why an entry nobody named is in the set, e.g. `{ "vocabulary", "dep of plan" }`.
+ */
+struct Resolution {
+    std::unordered_map<std::string, SourceOffer> entries;
+    std::vector<std::string> unknown;
+    std::unordered_map<std::string, std::string> notes;
+};
+```
+
+## Bad
+
+Each one next to what is wrong with it. The examples above show the fix.
+
+```cpp
+struct Resolution {
+    std::vector<std::string> unknown; ///< Requests no source offers.
+};
+```
+A trailing `///<` docstring on a member. Members go in the struct's docstring as `@property` tags.
+
+```cpp
+// Retrieves a user by id.
+std::optional<User> get_user(std::int64_t user_id);
+```
+A plain `//` comment in place of a docstring. Doxygen and clangd only read `/** */`.
+
+```cpp
+/**
+ * @brief Reads a file and checks it against its schema.
+ *
+ * @return The parsed tree. Throws when the file is invalid.
+ */
+[[nodiscard]] Tree parse_file(const std::filesystem::path& path);
+```
+The exception is prose inside `@return`, with no type. Each exception gets its own `@throws` tag, as in `parse_file` above.
+
+```cpp
+/**
+ * Resolves the dependencies of one entry against every offer.
+ *
+ * @param preferred Source to take a key from when several offer it.
+ */
+```
+More than one line without `@brief`. It opens with `@brief Resolves the dependencies...`.

package/skills/coding/document/references/python.md

@@ -0,0 +1,95 @@
+# Python
+
+Google-style docstrings: a `"""` block as the first statement inside the declaration.
+
+- **Line 1**: `# src/app/users.py`, the relative path. No module docstring, so ruff's `D100` and `D104` stay off.
+- **Declarations with a docstring**: functions, methods, classes, dataclasses, `TypedDict`s, `Protocol`s and enums.
+- **Summary**: `"""Adds two numbers."""` on one line. The first line is the `@brief`: a longer block opens with the summary, then a blank line.
+- **Tags**: sections `Args:`, `Returns:`, `Raises:` and `Example:`. The fields of a class, dataclass, `TypedDict` or enum go under `Attributes:` in its docstring.
+
+```python
+def add(a: int, b: int) -> int:
+    """Adds two numbers."""
+    return a + b
+
+
+async def get_user(user_id: int) -> User | None:
+    """Retrieves a user by id.
+
+    Args:
+        user_id: Surrogate key from the `users` table, not the auth provider's id.
+
+    Returns:
+        Custom User class used by the authentication service, or `None` when no row matches.
+    """
+    ...
+
+
+class FileValidationError(Exception):
+    """Error for a file on disk that does not match its schema.
+
+    Holds the path of the file and one issue per rejected field, and its message
+    lists them all. Raised by `parse_file` and by the readers in `filetree/`,
+    `decisions/` and `vocabulary/` that check a file's layout by hand. Callers
+    tell it apart from other errors with `except FileValidationError`.
+
+    Attributes:
+        file: Absolute path of the file that failed, e.g. `/home/me/app/docs/auth.md`.
+        issues: Rejected fields, e.g. `FileValidationIssue(field="phases.0.status", message="is required")`.
+
+    Example:
+        raise FileValidationError("/home/me/app/docs/auth.md", [
+            FileValidationIssue(field="status", message='is "done"'),
+        ])
+    """
+
+    def __init__(self, file: str, issues: list[FileValidationIssue]) -> None:
+        """Builds the message from the file path and every issue."""
+        ...
+
+
+@dataclass(frozen=True)
+class Resolution:
+    """Entries a set of requests resolved to, and the requests that did not resolve.
+
+    Attributes:
+        entries: Resolved entries by key, e.g. `emphasise`.
+        unknown: Requests no source offers, e.g. `ghost@mine`.
+        notes: Why an entry nobody named is in the set, e.g. `{"vocabulary": "dep of plan"}`.
+    """
+
+    entries: dict[str, SourceOffer]
+    unknown: list[str]
+    notes: dict[str, str]
+```
+
+`__init__` gets a summary only when the class docstring already tags its arguments as attributes.
+
+## Bad
+
+Each one next to what is wrong with it. The examples above show the fix.
+
+```python
+@dataclass
+class Resolution:
+    """Entries a set of requests resolved to."""
+
+    entries: dict[str, SourceOffer]
+    """Resolved entries by key."""
+```
+A docstring on a field. Fields go in the class docstring under `Attributes:`.
+
+```python
+def get_user(user_id: int) -> User | None:
+    # Looks the user up by surrogate key.
+    """Retrieves a user by id."""
+```
+A comment that says what a tag can say. It goes under `Args:`.
+
+```python
+def matches(request: EntryRequest, offers: Sequence[SourceOffer]) -> Match:
+    """
+    Finds the entries one request names.
+    """
+```
+The summary starts on line 2, and the custom types `EntryRequest`, `SourceOffer` and `Match` have no `Args:` or `Returns:` entry.

package/skills/coding/document/references/rust.md

@@ -0,0 +1,122 @@
+# Rust
+
+Rustdoc: a `/** */` block directly above the item, written in Markdown. Never `///`.
+
+- **Line 1**: `// src/users/store.rs`, the relative path. No `//!` or `/*! */` module or crate docs.
+- **Declarations with a docstring**: functions, methods, structs, enums, traits and type aliases.
+- **Summary**: `/** Adds two numbers. */` on one line. The first line is the `@brief`: a longer block opens with the summary, then a blank ` *` line.
+- **Tags**: Markdown sections `# Arguments`, `# Returns`, `# Errors`, `# Panics` and `# Examples`. Arguments are a list of `` * `name` - text ``.
+- **Fields and variants**: Rust has no field tag, so this is the one exception to the owner rule. Each struct field and enum variant gets its own one-line `/** */`. Rustdoc and analyze both read it from there.
+- **Examples**: a fenced block under `# Examples`. `cargo test` compiles and runs it, so it must build. Setup lines start with `# `, which hides them from the rendered docs.
+
+```rust
+/** Adds two numbers. */
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+
+/**
+ * Retrieves a user by id.
+ *
+ * # Arguments
+ *
+ * * `user_id` - Surrogate key from the `users` table, not the auth provider's id.
+ *
+ * # Returns
+ *
+ * Custom User struct used by the authentication service, or `None` when no row matches.
+ *
+ * # Errors
+ *
+ * `StoreError::Connection` when the database is unreachable.
+ */
+pub async fn get_user(user_id: i64) -> Result<Option<User>, StoreError> {
+    // ...
+}
+
+/**
+ * Error for a file on disk that does not match its schema.
+ *
+ * Holds the path of the file and one issue per rejected field, and its
+ * `Display` lists them all. Returned by `parse_file` and by the readers in
+ * `filetree/`, `decisions/` and `vocabulary/` that check a file's layout by
+ * hand. Callers tell it apart from other errors by matching on the type.
+ *
+ * # Examples
+ *
+ * ```
+ * # use harbor::{FileValidationError, FileValidationIssue};
+ * let error = FileValidationError {
+ *     file: "/home/me/app/docs/auth.md".into(),
+ *     issues: vec![FileValidationIssue { field: "status".into(), message: r#"is "done""#.into() }],
+ * };
+ * ```
+ */
+#[derive(Debug)]
+pub struct FileValidationError {
+    /** Absolute path of the file that failed, e.g. `/home/me/app/docs/auth.md`. */
+    pub file: PathBuf,
+    /** Rejected fields, e.g. `FileValidationIssue { field: "phases.0.status".into(), message: "is required".into() }`. */
+    pub issues: Vec<FileValidationIssue>,
+}
+
+/** Entries a set of requests resolved to, and the requests that did not resolve. */
+pub struct Resolution {
+    /** Resolved entries by key, e.g. `emphasise`. */
+    pub entries: HashMap<String, SourceOffer>,
+    /** Requests no source offers, e.g. `ghost@mine`. */
+    pub unknown: Vec<String>,
+    /** Why an entry nobody named is in the set, e.g. `("vocabulary", "dep of plan")`. */
+    pub notes: HashMap<String, String>,
+}
+```
+
+`harbor` in the example stands for the crate's own name. Doctests use the crate from outside, so `crate::` does not work there.
+
+A function that returns `Result` always has `# Errors`. One that can panic always has `# Panics`.
+
+## Bad
+
+Each one next to what is wrong with it. The examples above show the fix.
+
+```rust
+/// Adds two numbers.
+pub fn add(a: i32, b: i32) -> i32
+```
+A `///` comment. Use `/** Adds two numbers. */`.
+
+```rust
+/**
+ * Entries a set of requests resolved to.
+ *
+ * # Fields
+ *
+ * * `entries` - Resolved entries by key.
+ */
+pub struct Resolution {
+    pub entries: HashMap<String, SourceOffer>,
+}
+```
+Fields listed in the struct's docstring. Neither rustdoc nor analyze reads them there. The `/** */` goes on the field.
+
+```rust
+/** Parses a file. */
+pub fn parse_file(path: &Path) -> Result<Tree, FileValidationError>
+```
+Returns `Result` with no `# Errors` section.
+
+```rust
+/**
+ * # Examples
+ *
+ * ```
+ * let error = FileValidationError::new(path, vec![issue]);
+ * ```
+ */
+```
+`path` and `issue` are never defined and the type is never imported, so `cargo test` fails on it.
+
+```rust
+/*! User storage. */
+```
+A module docstring. Line 1 is the path comment, and the items carry the docs.

package/skills/coding/document/vscode/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "g3n-doc-tags",
+  "displayName": "g3n Doc Tags",
+  "description": "Colours the sections and argument names of Rust doc comments and Python docstrings like JSDoc tags.",
+  "publisher": "g3nomaly",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "engines": {
+    "vscode": "^1.80.0"
+  },
+  "categories": [
+    "Programming Languages"
+  ],
+  "contributes": {
+    "grammars": [
+      {
+        "scopeName": "g3n.doc-tags.rust",
+        "path": "./syntaxes/rust.json",
+        "injectTo": ["source.rust", "text.html.markdown"]
+      },
+      {
+        "scopeName": "g3n.doc-tags.python",
+        "path": "./syntaxes/python.json",
+        "injectTo": ["source.python", "text.html.markdown"]
+      }
+    ]
+  }
+}

package/skills/coding/document/vscode/syntaxes/python.json

@@ -0,0 +1,56 @@
+{
+  "scopeName": "g3n.doc-tags.python",
+  "injectionSelector": "L:string.quoted.docstring.multi.python, L:string.quoted.docstring.raw.multi.python",
+  "patterns": [
+    { "include": "#named-section" },
+    { "include": "#raises-section" },
+    { "include": "#plain-section" }
+  ],
+  "repository": {
+    "named-section": {
+      "comment": "`Args:` or `Attributes:` and the `name (type):` items under it. The section ends at the first line that is not indented deeper, or at the closing quotes.",
+      "begin": "^(\\s*)(Args|Arguments|Attributes|Keyword Args|Keyword Arguments|Other Parameters)(:)\\s*$",
+      "end": "(?=\"\"\"|''')|^(?!\\1\\s+\\S|\\s*$)",
+      "beginCaptures": {
+        "2": { "name": "storage.type.class.jsdoc" },
+        "3": { "name": "punctuation.separator.jsdoc" }
+      },
+      "patterns": [
+        {
+          "match": "^\\s+(\\*{0,2}[A-Za-z_]\\w*)(?:\\s*\\(([^)]*)\\))?(:)(?=\\s|$)",
+          "captures": {
+            "1": { "name": "variable.other.jsdoc" },
+            "2": { "name": "entity.name.type.instance.jsdoc" },
+            "3": { "name": "punctuation.separator.jsdoc" }
+          }
+        }
+      ]
+    },
+    "raises-section": {
+      "comment": "`Raises:` and the `ErrorType:` items under it.",
+      "begin": "^(\\s*)(Raises)(:)\\s*$",
+      "end": "(?=\"\"\"|''')|^(?!\\1\\s+\\S|\\s*$)",
+      "beginCaptures": {
+        "2": { "name": "storage.type.class.jsdoc" },
+        "3": { "name": "punctuation.separator.jsdoc" }
+      },
+      "patterns": [
+        {
+          "match": "^\\s+([A-Za-z_][\\w.]*)(:)(?=\\s|$)",
+          "captures": {
+            "1": { "name": "entity.name.type.instance.jsdoc" },
+            "2": { "name": "punctuation.separator.jsdoc" }
+          }
+        }
+      ]
+    },
+    "plain-section": {
+      "comment": "Sections whose body is prose or code, such as `Returns:` and `Example:`. Only the heading is coloured.",
+      "match": "^\\s*(Returns|Yields|Example|Examples|Note|Notes|Warning|Warnings|See Also|Todo)(:)\\s*$",
+      "captures": {
+        "1": { "name": "storage.type.class.jsdoc" },
+        "2": { "name": "punctuation.separator.jsdoc" }
+      }
+    }
+  }
+}

package/skills/coding/document/vscode/syntaxes/rust.json

@@ -0,0 +1,25 @@
+{
+  "scopeName": "g3n.doc-tags.rust",
+  "injectionSelector": "L:comment.block.documentation.rust",
+  "patterns": [
+    { "include": "#section" },
+    { "include": "#argument" }
+  ],
+  "repository": {
+    "section": {
+      "comment": "A section heading such as ` * # Errors`. Only known names, so a hidden doctest line such as `# use harbor::Tree;` stays plain.",
+      "match": "^\\s*\\*?\\s*(#)\\s+(Arguments|Returns|Errors|Panics|Safety|Examples)\\s*$",
+      "captures": {
+        "1": { "name": "punctuation.definition.block.tag.jsdoc" },
+        "2": { "name": "storage.type.class.jsdoc" }
+      }
+    },
+    "argument": {
+      "comment": "An item of the Arguments list: ` * * `user_id` - text`.",
+      "match": "^\\s*\\*?\\s*[*-]\\s+(`)([A-Za-z_]\\w*)(`)\\s+(-)(?=\\s)",
+      "captures": {
+        "2": { "name": "variable.other.jsdoc" }
+      }
+    }
+  }
+}

package/skills/teach/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "teach",
+  "description": "Teach through real work: build, explain, dive deep, decide architecture, debug and review while the user learns the reasoning.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "skills": ["./teaching", "./learn-by-building", "./explain", "./deep-dive", "./architecture", "./guided-debugging", "./guided-review"]
+}

package/skills/teach/architecture/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: architecture
+description: Use when the user is deciding or wants to understand an architecture choice, such as system boundaries, ownership, dependencies, state, data flow, consistency, integration or deployment.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Reason from the problem to the decision, and teach the user to reason the same way. Follow the `/teaching` skill throughout. A _pattern name_ describes a solution once the forces justify it. It is never the starting point.
+
+## Steps
+
+1. **Define the decision** and its scope in neutral terms, with no pattern name. Done when the user agrees it is the question.
+2. **Gather the forces**: requirements, constraints, invariants and who owns them, failures to contain, parts that change independently, and what the team must operate. Done when each force traces to the system or the request, not to an imagined future.
+3. **List the options**: the few credible ones, always including the simplest that works. Keep logical, runtime, deployment and data boundaries apart.
+4. **Compare** the options on the forces that could change the decision. Drop an option whose cost solves a problem nobody has.
+5. **Recommend** one, with your confidence and assumptions. When evidence is weak, prefer the option easiest to reverse.
+6. **State the consequences**: new responsibilities, risks, migration cost, and the evidence that would reopen the choice. Done when the user could explain why the other options lost.
+
+For worked cases, such as wrapping a provider SDK or splitting out a worker, read [`references/examples.md`](references/examples.md).

package/skills/teach/architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Architecture"
+  short_description: "Reason from forces to an architecture decision and its consequences"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/architecture/references/examples.md

@@ -0,0 +1,16 @@
+# Architecture examples
+
+## Call the storage SDK directly, or put a boundary in front of it?
+
+Check whether the application has storage operations of its own, more than one provider, migration plans, special retry or authorization rules, or testing needs. For a small adapter over stable provider semantics, calling the SDK directly may be simplest. A boundary earns its place when it owns real application operations and contains provider-specific behavior. That provider replacement is _imaginable_ is no reason to add one.
+
+## Should this worker be a microservice?
+
+Separate logical ownership from deployment. Independent scaling, failure isolation, runtime needs, release cadence and team ownership can justify another process. Being called a "worker" does not.
+
+## Failure modes
+
+- _Hypothetical scale._ Paying permanent complexity for demand nobody has shown.
+- _Boundary confusion._ Treating modules, processes, services and deployments as interchangeable.
+- _Provider-shaped abstraction._ Re-exporting every provider concept through a new interface without reducing coupling.
+- _Operation blindness._ Choosing a design without accounting for deployment, monitoring, recovery and team capacity.

package/skills/teach/deep-dive/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: deep-dive
+description: Use when the user asks how a runtime, protocol, database, framework, operating-system feature, network operation or other abstraction works underneath.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Build a model of the layers under an abstraction the user already uses. Follow the `/teaching` skill throughout, and go only as deep as the question, decision or bug needs.
+
+## Steps
+
+1. **Name the operation** being traced and why the user needs the depth. Done when you know where to stop: the layer past which detail no longer changes what the user can predict or do.
+2. **Map the whole path** in a compact diagram before expanding any layer.
+3. **Expand one layer at a time**: its input, responsible component, state change, output and where it fails. Explain the handoff to the next layer, not only the component's name.
+4. **Label each detail** as _concept_ (stable mechanism), _implementation_ (how one system does it) or _platform_ (varies by OS, runtime, version or configuration). When the system or version is unknown, say so instead of inventing detail.
+5. **Check at each boundary** whether more depth helps, and reconnect to the original operation. Offer a deeper branch rather than forcing it in.
+6. **Finish with a compact model** the user can use to predict the behavior.
+
+For worked cases, such as a Docker Compose connection or a `fetch()` call, read [`references/examples.md`](references/examples.md).

package/skills/teach/deep-dive/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Deep Dive"
+  short_description: "Trace the layers beneath an abstraction, only as deep as useful"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/deep-dive/references/examples.md

@@ -0,0 +1,15 @@
+# Deep-dive examples
+
+## What happens when `api` connects to `postgres:5432` in Docker Compose?
+
+Start with the path:
+
+```text
+service name → Docker DNS → container-network IP → TCP connection → PostgreSQL listener
+```
+
+Compose provides service discovery on the shared network. DNS resolves the service name to a reachable container address, and TCP connects to the process listening on port 5432. Go into Linux network namespaces afterwards, and only if the user needs to explain why `localhost` behaves differently.
+
+## What happens when JavaScript calls `fetch()`?
+
+Map URL resolution, connection setup, TLS, the HTTP exchange, runtime scheduling and application handling. Expand DNS or transport internals only when they serve the user's question.

package/skills/teach/explain/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: explain
+description: Use when the user asks to understand existing code, types, queries, configuration, workflows, tests, protocols or infrastructure.
+registryDependencies: [teaching, deep-dive]
+disable-model-invocation: false
+---
+
+Explain why the important parts exist and how they interact, so the user can reason about the material later. Follow the `/teaching` skill throughout. Never paraphrase line by line.
+
+## Steps
+
+1. **Read the neighbors**: the callers, consumers, state and effects that give the material its meaning. Done when you can state its purpose in the larger system. Never invent an intent the evidence does not support.
+2. **Give the smallest mental model** that explains its behavior.
+3. **Trace the flow** that matters: data, control, ownership or lifecycle.
+4. **Spend attention unevenly.** Focus on what preserves information, enforces a boundary or encodes a design choice, and explain each non-obvious choice by the constraint it serves. Skip boilerplate and syntax unless it changes meaning.
+5. **Cover failure**: the invariants downstream code depends on, and how the material breaks.
+6. **Stop** when more depth no longer improves the model. If a lower layer would help, offer it through the `/deep-dive` skill.
+
+For worked cases, such as a `readonly` array type or a multi-stage Dockerfile, read [`references/examples.md`](references/examples.md).

package/skills/teach/explain/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Explain"
+  short_description: "Explain existing material through purpose, model, flow and failure"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/explain/references/examples.md

@@ -0,0 +1,9 @@
+# Explain examples
+
+## `export type QueryOutput = readonly QueryEntry[];`
+
+Do not stop at "a readonly array". An ordered list of entries can hold duplicate keys, such as two `tag` values, which a `Record<string, string>` cannot. `readonly` tells consumers not to mutate the canonical encoded form in place.
+
+## A multi-stage Dockerfile
+
+Explain the build and runtime stages as separate environments with separate jobs. Trace how dependency layers are cached, how the production artifact moves between stages, and why the build tooling is absent from the runtime image. Cover single instructions only where they affect those mechanisms.

package/skills/teach/guided-debugging/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: guided-debugging
+description: Use when the user brings an error, regression, failing test, broken deployment, wrong result or other observable failure and wants to learn how to find the cause, not a list of guesses.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Fix a real failure and teach a repeatable method for finding causes. Follow the `/teaching` skill throughout. Keep three levels apart:
+
+- **Symptom**: the visible failure.
+- **Cause**: the condition that directly produces it.
+- **Root cause**: the deeper condition that let the cause exist or recur.
+
+## Steps
+
+1. **Capture the symptom** exactly: error text, timing, scope and how to reproduce it. Name the component that produced the evidence, which may not be the one that displayed it.
+2. **Inspect before changing.** Read the relevant state and keep the diagnostic evidence.
+3. **List a few hypotheses** drawn from the observations, each with what it predicts, ranked by likelihood, risk and what a test would tell you. Never offer a pile of unrelated fixes.
+4. **Run one small experiment** that separates the leading hypotheses: cheap, safe, reversible, one variable at a time where practical. Say beforehand what it can and cannot show.
+5. **Interpret the result**: which hypothesis gained or lost support, and why. Repeat from step 3 until evidence supports both the cause and the root cause. When the investigation spans several experiments, keep the record in [`references/debugging-loop.md`](references/debugging-loop.md).
+6. **Fix the root cause** with the smallest change that does not hide the symptom.
+7. **Verify** by reproducing the original scenario, not a convenient proxy. Done when the original path works.
+8. **Add prevention** when recurrence or impact justifies it: validation, types, tests, health checks or monitoring.
+
+For worked cases, such as a container that cannot reach its database or a test that fails only in the full suite, read [`references/examples.md`](references/examples.md).

package/skills/teach/guided-debugging/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Guided Debugging"
+  short_description: "Find a failure's root cause through hypotheses and small experiments"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/guided-debugging/references/debugging-loop.md

@@ -0,0 +1,18 @@
+# Debugging evidence loop
+
+Keep this record when an investigation has several plausible hypotheses or spans several experiments.
+
+| Field | Record |
+| --- | --- |
+| Exact symptom | Error, wrong result, timing and reproduction boundary |
+| Producer and stage | Component that produced the evidence, and where it failed |
+| Relevant state | Configuration, inputs, dependencies and environment |
+| Hypothesis | A testable causal explanation |
+| Prediction | The result expected if the hypothesis is right |
+| Experiment | A small, safe action that tells the likely explanations apart |
+| Observation | The result of the experiment, uninterpreted |
+| Interpretation | Hypotheses strengthened, weakened or eliminated |
+
+Update the hypothesis set after each experiment instead of piling up unrelated fixes.
+
+Finish by recording the supported cause, the root cause, the fix, how the original failure path was verified, and any prevention that recurrence or impact justifies.

package/skills/teach/guided-debugging/references/examples.md

@@ -0,0 +1,24 @@
+# Guided-debugging examples
+
+## A containerized API cannot connect to PostgreSQL
+
+Before editing configuration, inspect the database host the API process actually uses, and the Compose network. If the API uses `127.0.0.1:5432`, test the hypothesis that it targets its own network namespace.
+
+```text
+symptom:    connection refused
+cause:      the API connects to its own loopback interface
+root cause: the configuration assumes the API and database share a network namespace
+```
+
+The fix is to use the database service name on the shared network. Prevention may be environment validation and an integration health check.
+
+## A test passes alone but fails in the full suite
+
+Compare order, shared state, time and resource ownership. Prefer an experiment that changes only execution order or isolation, then use the result to tell leaked state apart from timing or resource contention.
+
+## Failure modes
+
+- _Producer confusion._ Debugging the component that displayed an error instead of the one that produced it.
+- _State destruction._ Changing several variables at once and losing the ability to attribute the result.
+- _Symptom patching._ Suppressing the visible error while its cause stays.
+- _Premature root cause._ Stopping at the immediate bad value without explaining why it was possible.

package/skills/teach/guided-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: guided-review
+description: Use when the user wants feedback on code, a pull request, configuration, tests or a design and wants to learn the judgment behind the findings.
+registryDependencies: [teaching]
+disable-model-invocation: false
+---
+
+Find the defects and risks that matter, and explain the principle behind each one so the judgment carries over. Follow the `/teaching` skill throughout. A few high-value findings beat an exhaustive list.
+
+## Steps
+
+1. **Establish the intent**: what the change is for, its scope, and the boundaries that carry risk.
+2. **Read beyond the diff**: the contracts, callers, state and tests around it.
+3. **Trace the risky paths**: authorization, data mutation, failure, concurrency and cleanup, as they apply.
+4. **Try to disprove each candidate finding.** Keep only those with a concrete execution path, violated invariant or reproducible condition.
+5. **Rank** by consequence and likelihood, roughly: correctness, security, data integrity, concurrency, failure handling, architecture, maintainability, testing, performance, style.
+6. **Write each finding** at the narrowest location: the observation, why it matters, the principle, the possible consequence and a recommended direction, not a rewrite. Label each one _required_, _optional_ or _open question_. A preference is never a defect.
+7. **Close with the scope**: what you could not verify, such as behavior you only read and never ran. With no confirmed findings, say so.
+
+For a worked finding, a tenant check missing from a query, read [`references/examples.md`](references/examples.md).

package/skills/teach/guided-review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Guided Review"
+  short_description: "Review work by consequence and teach the principle behind each finding"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/guided-review/references/examples.md

@@ -0,0 +1,18 @@
+# Guided-review examples
+
+## A tenant check missing from a query
+
+- **Observation**: `tenantId` comes from the request and scopes a query, with no check that the user belongs to that tenant.
+- **Why it matters**: the tenant boundary exists only in input the client controls.
+- **Principle**: enforce authorization at the protected data boundary.
+- **Possible consequence**: a modified request reads another tenant's records.
+- **Recommended direction**: derive the tenant from the authenticated request, or check membership before any tenant-scoped query. Naming and method extraction wait until the authorization boundary is right.
+
+An optional finding in the same review: a repeated mapping block could be extracted. Label it _optional_ when it creates no current correctness or consistency risk.
+
+## Failure modes
+
+- _Style flood._ Many low-value comments that hide the risk.
+- _Scope blindness._ Reviewing a function without the contracts or boundaries that decide its correctness.
+- _Severity inflation._ Urgent labels on ordinary maintainability choices.
+- _Patch takeover._ Replacing the author's design instead of naming the violated principle.

package/skills/teach/learn-by-building/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: learn-by-building
+description: Use when the user wants to learn a subject by building, integrating, deploying, configuring or migrating a real system, such as learning Docker by containerizing their API.
+registryDependencies: [teaching, guided-debugging]
+disable-model-invocation: false
+---
+
+Finish the real task so that it leaves the user with understanding they can reuse. Follow the `/teaching` skill throughout.
+
+## Steps
+
+1. **Inspect the real system**: code, configuration, environment and constraints. Done when you can state the goal and what a successful result looks like.
+2. **Pick the few concepts** that control the outcome.
+3. **Draw the system map** and place the current step on it. Never hand over a large implementation before the map.
+4. **Take one meaningful step.** Say what it advances in the work and what it should teach.
+5. **Inspect the result** instead of assuming success, and explain what it confirms. When a step fails, debug it with the `/guided-debugging` skill, then come back.
+6. **Recap the mental model at each milestone.** Repeat from step 4. Done when the real task is complete and the user has shown they understand each concept from step 2.
+
+For worked cases, such as learning CI/CD through a deployment or Redis through caching, read [`references/examples.md`](references/examples.md).

package/skills/teach/learn-by-building/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Learn by Building"
+  short_description: "Learn a subject while completing a real task"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/learn-by-building/references/examples.md

@@ -0,0 +1,15 @@
+# Learn-by-building examples
+
+## "Teach me CI/CD while deploying this NestJS API with GitHub Actions, Docker, GHCR and a Linux VM"
+
+Begin with the deployment map:
+
+```text
+source → verified build → image → registry → VM → container → user
+```
+
+Start by producing a reliable artifact, because a deployment cannot be reasoned about until the deployable unit is explicit. Connect building the image to immutability, the registry to distribution, and container startup to runtime configuration.
+
+## "Teach me Redis by adding caching to this endpoint"
+
+Inspect the endpoint's correctness and where its data changes first. Teach cache key identity, freshness, invalidation and failure behavior through the actual feature, not by starting from Redis command syntax.

package/skills/teach/teaching/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: teaching
+description: Use when teaching the user a technical subject through real work, or when another skill needs the teaching principles.
+disable-model-invocation: false
+---
+
+Teach through the user's real work, and leave them with _mental models_ they can reason with. Sound like a competent peer: precise, direct and proportionate to the task.
+
+## Principles
+
+- **Use the real system.** Teach through the user's own code, bug, deployment or design. A simplified example earns its place only when it isolates a mechanism the real system hides.
+- **Teach what matters.** Sort what comes up into must-understand, useful context and trivia, and spend attention in that order. Group routine mechanics instead of lecturing on them.
+- **Explain causality.** Say "A causes B because C", never "it is best practice". Each non-trivial recommendation names its force: an invariant, failure mode, cost, boundary or operational need.
+- **Cover the trade-offs that can change the decision**, and when another choice would win. Skip the rest.
+- **Build models, not rules.** "Never use localhost between containers" breaks in the next case. "Each container has its own network namespace" lets the user derive the answer. Use an analogy only to lighten the load, then return to the mechanism.
+- **Adapt per concept, not per person.** Reduce support for each concept as evidence of understanding grows. Read [`references/learning-model.md`](references/learning-model.md) when deciding how much to explain.
+- **Treat results as evidence.** After a success, explain the mechanism it confirms. After an error, find the exact error, what produced it, the stage and the failed assumption before changing anything. Say what a result confirms and what it does not.
+- **Ask few questions.** Ask only when the answer changes the path or exercises reasoning worth practicing. Ask for a prediction to test a model, never to make the user rediscover a fact.
+- **Recap the model at milestones**: what the user can now distinguish or predict, not which commands ran.
+- **State uncertainty.** Keep observation apart from inference, and requirement apart from advice.
+
+Never withhold information, split trivial work or hide a solution to simulate discovery. Leave out praise, hype, motivational filler and labels such as _beginner_ or _junior_.

package/skills/teach/teaching/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Teaching"
+  short_description: "Teach through real work: causality, mental models, guidance per concept"
+policy:
+  allow_implicit_invocation: true

package/skills/teach/teaching/references/learning-model.md

@@ -0,0 +1,24 @@
+# Learning model
+
+Track understanding per concept, never as one level for the whole person. A user may have demonstrated TypeScript generics and still show no evidence yet for Linux namespaces.
+
+| State | Evidence | Guidance |
+| --- | --- | --- |
+| Unknown | None yet. Unobserved, not incapable | Explain directly, and demonstrate before expecting independent use |
+| Partial | Part of the model, with a gap or misconception | Keep what is right and repair only the missing connection |
+| Understood | Explains or reasons correctly with some support | Stop re-explaining; let the user reason through the next decision worth practicing |
+| Demonstrated | Applies it alone in real work and reads the result correctly | Step back; step in only for risk, new constraints or contradicting evidence |
+
+## Evidence
+
+A state is a working hypothesis, and it moves either way as evidence comes in. Count:
+
+- a correct prediction with causal reasoning
+- an implementation choice and its explanation
+- a diagnostic hypothesis drawn from observations
+- a concept carried into a new context
+- a misconception recognized and corrected
+
+A finished task proves nothing when you made every decision. A wrong answer points at a specific gap, not at the user.
+
+Infer states from the work already happening; never quiz the user to assign one. Track only the concepts the current task needs, and keep no profile of the user beyond them.