code-ingest

Files (1)

• SKILL.md

SKILL.md (first lines)

# code-ingest — add a repository to the Obsidian Code library

Turns a repo into a **map you can read in 2 minutes and instantly recall how the
code is organized and where to look to change something** — without duplicating
the source. The code itself stays in git / on the server; these notes are the index.

## When to use
- The user hands you a repo URL or path and says "add to the code library" / "разбери репо".
- A project starts depending on external code that has no `Code/<repo>/` folder yet.
- Before heavily editing an unfamiliar repo (build the map first).

## When NOT to use
- The repo is already in `Code/<repo>/` and unchanged → just read it. Re-run only to refresh after large upstream changes.
- For per-project edits/diffs → those go in the **project hub card** `## Код` section, not here (see [[code-library]]).

## Where it lives
Vault (the lab tree): `${OBSIDIAN_VAULT}/personal/code-library/`
One folder per repo: `personal/code-library/<repo-slug>/`. The slug is the repo name, kebab-case.

## Output structure (always)
```
Code/<repo>/
  <repo>.md          ← CANONICAL OVERVIEW. Always this exact name. Read this first.
  architecture.md    ← entrypoint, control/data flow, how a run executes end-to-end
  <module>.md        ← one note per major module/package (group tiny files)
  ...
```
- The overview `<repo>.md` is mandatory and always named after the folder, so any agent knows which file to open first.
- Split into module notes when the repo is large; for a tiny repo a single `<repo>.md` is fine.
- Update `Code/README.md` (the library index) with a one-line entry for the new repo.

## Procedure
1. **Get the source.** Prefer reading a local clone or the server copy if one exists (ask / check the project card). Otherwise fetch file listing + key files from GitHub (raw URLs / `gh`). Note the canonical git URL and default branch.
2. **Map the layout.** List top-level dirs and the role of each. Identify: entrypoint(s), config system, the main loop, the factory/registry or dispatch points (where names map to classes), data path, outputs/checkpoints.
3. **Trace one full run** end-to-end (what `main` does, in order) — this becomes `architecture.md`.
4. **Write module notes** using the template below. For each module: what it's for, key files with **GitHub permalinks and line anchors**, key classes/functions, and an explicit **"where to edit to change X"** list. Do not paste code bodies — cite `path:line` + a one-line description.
5. **Write the overview `<repo>.md`** using its template.
6. **Index it** in `Code/README.md`.
7. Tell the user what was created and link the overview.

## Overview template (`<repo>.md`)
```markdown
---
tags: [code, <repo-slug>]
repo: <git url>
default_branch: <branch>
created: DD-MM-YYYY
---
# <repo> — code map

One-paragraph: what this repo is and what you use it for.

## At a glance
- **Entrypoint:** `path` (`func`)
- **Config:** how runs are parametrized (flags / yaml / hydra)
- **Run a job:** the minimal command
- **Data:** where data lives / how it's loaded
- **Outputs:** where checkpoints / logs / metrics go
- **Dispatch points:** where a name (optimizer/model/dataset) maps to a class

## Directory map
| path | role | note |
|------|------|------|
| ... | ... | [[architecture]] / [[<module>]] |

## Where to look to change X
- change the model arch → [[models]] (`...`)
- add an optimizer → [[optimizers]] (`...`)
- change the schedule → ...
- change data → ...

## Notes
- [[architecture]] · [[optimizers]] · [[models]] · [[data]] · ...

## Used by projects
- [[<направление>/<тема>/<работа>/README|<работа>]] — <fork/branch + what's changed>
```

## Module note template (`<module>.md`)
```markdown
# <module>

What this module is responsible for, in 2-3 sentences.

## Key files
- `path/to/file.py` — role. [GitHub](permalink)
  - `ClassOrFunc` (`file.py:LINE`) — what it does.

## How it fits the run
Where this is called from (link [[architecture]]), inputs/outputs.

## Where to edit to change X
- ... → `file.py:LINE`
```

## Rules
- **Never copy large code blocks.** Cite `path:line` + GitHub permalink + a sentence. The notes are a map, not a mirror.
- Keep each note focused; 200-400 lines max, split if larger.
- Pin permalinks to the analyzed commit/branch so line anchors stay valid; note the branch.
- Use Obsidian wikilinks between the overview and module notes.
- After ingesting, remind the user to add a `## Код` section to the relevant project hub card (see [[code-library]]).

From Vepricov/claude-brainlab, MIT.

More from Vepricov/claude-brainlab