Project Lore: AI Agent Skill for Repository Memory

Project Lore is an AI agent skill for generating .ai/project-lore.md: a concise repository memory that helps coding agents understand a codebase faster.

Use it when you want Claude Code, Codex, Cursor, Copilot-style agents, or any other coding agent to create a first-read onboarding file for a repository: commands, architecture, conventions, setup requirements, generated files, testing notes, and gotchas.

The output is intentionally tool-agnostic Markdown. It is not a replacement for README.md, CLAUDE.md, AGENTS.md, or editor-specific rules. It is the missing "what an agent learns after reading this repo once" file.

Why This Exists

AI coding agents waste time rediscovering the same project facts:

• Which command actually runs one focused test?
• Which directories are generated and should not be hand-edited?
• Where does a request, job, command, or event enter the system?
• Which setup steps are hidden in CI, Makefiles, or old docs?
• Which conventions are real in this repo, not just language defaults?

Project Lore turns that first-read knowledge into .ai/project-lore.md so future agent sessions start with useful context instead of a cold scan.

What It Generates

Example .ai/project-lore.md entries:

## Commands

- Run all tests with `go test ./...`; use `go test ./internal/foo -run TestName -count=1` for focused tests.
- Regenerate API bindings with `make generate`; generated files live under `internal/gen/`.

## Architecture

- HTTP requests enter through `cmd/server/main.go`, register routes in `internal/http`, and delegate business logic to `internal/service`.
- Database migrations live in `migrations/`; application code reads DB config through `internal/config`.

## Gotchas

- Do not edit `internal/gen/` directly; it is overwritten by code generation.
- Integration tests require Postgres on port `5433`, matching `docker-compose.test.yml`.

Good lore is short. Every line should pass this test:

Would removing this line cause an AI agent to make a mistake?

Install

Copy the skill directory into your agent's skills folder.

For Codex-style skills:

mkdir -p ~/.codex/skills
cp -R project-lore ~/.codex/skills/project-lore

For Claude-style skills:

mkdir -p ~/.claude/skills
cp -R project-lore ~/.claude/skills/project-lore

If your agent supports loading a skill by path, point it at:

project-lore/SKILL.md

Usage

Ask your coding agent:

Use project-lore to create .ai/project-lore.md for this repository.

Or:

Refresh the project lore after this refactor.

Or:

Review the existing .ai/project-lore.md and sharpen anything stale or generic.

What The Skill Reads

The skill instructs the agent to inspect evidence such as:

• Project manifests: package.json, go.mod, pyproject.toml, Cargo.toml, Makefile, Taskfile.yml
• README, docs, and contribution guides
• CI workflows and test commands
• Existing AI context files such as AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions
• Entry points, routing, config loading, persistence setup, middleware, generated-code boundaries, and representative source files
• Recent commit messages via git log --oneline -20

It intentionally avoids recursive directory dumps and generic "write clean code" advice.

Keywords

This repository may be useful if you searched for:

• AI agent skill
• coding agent skill
• repository memory
• repo onboarding for AI agents
• .ai/project-lore.md
• Claude Code skill
• Codex skill
• Cursor AI context
• AGENTS.md companion
• AI codebase documentation
• first-read project docs
• agentic coding workflow

Repository Layout

project-lore/
├── README.md
├── LICENSE
└── project-lore/
    ├── SKILL.md
    └── agents/
        └── openai.yaml

The nested project-lore/ directory is the skill folder. The repository root contains packaging and discovery files.

Design Principles

• Evidence first: every output line must be grounded in files or commands the agent inspected.
• Tool-agnostic output: .ai/project-lore.md should help any future coding agent.
• Short beats complete: skip directory listings and obvious language defaults.
• Surgical refreshes: preserve useful existing lore, update stale commands, and remove low-value lines.
• No environment mutation: the skill tells agents not to run install commands or modify setup just to document the repo.

License

MIT