IsmailAzzouzIsmailAzzouz/Work-With-Me-Skill/skills/learn-project/SKILL.md

learn-project

Skill0 starsChanged 27 days agoMITView on GitHub

Build and maintain project-root agent-journal/: machine-only notes (architecture, stack, product, philosophy, gotchas, map), graph-first when graphify is available. Caveman-ultra token-cheap prose ok. Use when learning a new project, onboarding, "learn this repo", refreshing agent context, or before non-trivial work when agent-journal/ is missing or stale.

3 other projects use a version of this.

Adopted by

Most recently taken up by

luiseiman/dotforgetheir own version, first seen Oct 13, 2026
allroad88888888/learn-projecttheir own version, first seen Aug 19, 2026
Fozikio/cortex-enginetheir own version, first seen Mar 16, 2026

Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
Fozikio/cortex-engine★ 51same name
luiseiman/dotforge★ 8same name
allroad88888888/learn-project★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- templates/AGENTS.mdAGENTS.md
- work-with-meSkill

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 4 are distinctive, and 8 are very specific to this project.

0
Common
Most of the 3 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Create + maintain agent-journal/ at the project root.
line 14
Very specific:
After learn: cold agent opens agent-journal/index.md → picks 1–3 notes via summaries → enough context to work without re-discovering …
line 27
Very specific:
If agent-journal/ exists: read index.md, check note dates/summaries, decide refresh vs full rebuild.
line 54
Very specific:
If graphify available and graphify-out/ missing or stale → run graphify on project (or --update).
line 56
Distinctive:
add other notes only if they earn a summary slot (auth, domain model, etc.)
line 70
Distinctive:
Use graph reports and queries to navigate.
line 72
Very specific:
Every note: title + one-line summary (summary = decide-to-open signal).
line 77
Distinctive:
No secrets (tokens, passwords).
line 79
Very specific:
If subfolders appear later, each gets index.md.
line 85
Very specific:
after large features land (merge key learnings.
line 94
Very specific:
Update only stale notes. Keep summaries honest.
line 96
Distinctive:
If gap → investigate code/graph → write back into journal (compounding knowledge)
line 103

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Learn Project

Create + maintain agent-journal/ at the project root. Audience = agents only. Humans never the target. Token-cheap writing ok (caveman ultra): drop fluff, articles, punctuation if meaning stays clear. Keep paths, symbols, APIs, package names exact.

Companion skills (optional)

Skill	Use	Fallback if not installed
`graphify`	Build/query project knowledge graph; prefer `graphify-out/` + `query` before raw sprawl	Scan manifests, entrypoints, imports, top dirs by hand
`knowledge-base-builder`	Keep `agent-journal/` navigable: every note `summary` frontmatter + `index.md` tree	Follow conventions.md directly

Also align with work-with-me: knowledge retrieval should read this journal first when it exists.

Goal

After learn: cold agent opens agent-journal/index.md → picks 1–3 notes via summaries → enough context to work without re-discovering stack/architecture/product from scratch.

Layout

agent-journal/
  index.md              # nav protocol + map (machine)
  architecture.md
  stack.md
  product.md
  philosophy.md
  map.md                # entrypoints, key dirs, god nodes
  gotchas.md
  services.md           # optional mono/multi-service
  workflows.md          # optional build/test/deploy
  glossary.md           # optional project terms
  ...                   # agent may add more notes as needed

Agent chooses links ([[wikilinks]], relative md links, or bare paths). Consistency inside one journal > matching human docs style.

Full note schemas: conventions.md.

Workflow

1. Assess

If agent-journal/ exists: read index.md, check note dates/summaries, decide refresh vs full rebuild.
Scan repo: README, agent instructions file (AGENTS.md or harness equivalent), package manifests, docker/compose, CI, top dirs.
If graphify available and graphify-out/ missing or stale → run graphify on project (or --update). Prefer graph queries for architecture/map over reading everything.

Tell user briefly: found X / will create or refresh journal. Then proceed (do not wait unless destructive moves needed; journal is additive).

2. Extract (graph-first when available)

Pull facts into notes:

architecture: components, boundaries, data flow, critical paths
stack: languages, frameworks, datastores, infra, versions if known
product: what it does, users, non-goals
philosophy: conventions, patterns the codebase already follows, "how we build here"
map: entrypoints, important dirs, god modules (from graphify when available)
gotchas: traps, footguns, "do not"
add other notes only if they earn a summary slot (auth, domain model, etc.)

Use graph reports and queries to navigate. Verify conclusions against current code and configuration; when sources disagree, current implementation takes precedence over generated graphs or descriptive documentation. Record intended behavior separately when it differs.

3. Write machine notes

Caveman ultra ok in body. Frontmatter still structured (YAML) so indexes work.
Every note: title + one-line summary (summary = decide-to-open signal).
Link heavily between notes; point to real repo paths.
No secrets (tokens, passwords). Point to secret locations only.

4. Index

Apply knowledge-base-builder conventions (or conventions.md) to agent-journal/.
Root index.md = navigation protocol + list of notes with summaries.
If subfolders appear later, each gets index.md.

5. Maintain

Refresh when:

user says learn/refresh
stack or architecture clearly drifted
agent repeatedly rediscovers facts not in journal
after large features land (merge key learnings; leave session detail in working-sessions/)

Update only stale notes. Keep summaries honest. Re-run graphify --update when structure shifted.

Read protocol (any agent)

Open agent-journal/index.md
Pick notes by summary
Open only those
If gap → investigate code/graph → write back into journal (compounding knowledge)

Anti-patterns

Human-polished essays / marketing tone
Dumping whole files into journal
Duplicating working-sessions/ task logs here (promote only durable project truth)
Skipping index/summaries
Inventing architecture not evidenced in repo

Additional resources

Note schemas + style: conventions.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free