Ask My Repo
A shared, repo-agnostic knowledge skill with three modes. It gives any AI
agent a fast, cited understanding of any codebase — without the agent having
to re-explore the whole tree on every question.
ask-my-repo/
├── SKILL.md (this file — mode selector + shared rules)
└── references/
├── ingest.md (full ingest process)
├── update.md (re-verify + merge process)
└── query.md (answering process + citation rules)
The Prime Directive (applies to all modes)
No claim without evidence. Every statement that lands in a knowledge
file, and every answer given in query mode, carries a file:line
citation, a command you actually ran, or an explicit UNVERIFIED tag.
A convention is only a convention with two or more examples and no
counterexample — otherwise report it as an inconsistency. This is what
makes the knowledge trustworthy enough to skip re-searching.
Mode selection
Resolve the mode from the argument hint, the user's phrasing, and the state
of the target repo. State which mode you picked and why in your first
response line, e.g. Mode: ingest (no AGENTS.md found in ./).
| User says / situation |
Mode |
| "ingest this repo", "onboard", "understand this codebase", "generate AGENTS.md", no knowledge files exist |
ingest |
| "update the docs/knowledge", "refresh AGENTS.md", knowledge files exist but may be stale |
update |
| "how does X work", "where is Y", "explain the architecture", any question about the repo |
query |
| Ambiguous: if knowledge files exist, prefer query; if not, ingest |
|
Target resolution (all modes)
- If a
[project-root] argument is given, treat that path as the repo root.
- Otherwise use the current working directory.
- Never assume a hardcoded path. Always derive the root from the argument or
cwd, and state it explicitly:
Target: /abs/path/to/repo.
- Knowledge files live at
<root>/AGENTS.md and <root>/docs/ARCHITECTURE.md
by default. If the repo already keeps agent knowledge elsewhere
(CLAUDE.md, .cursorrules, docs/ROADMAP.md, …), treat those as the
canonical knowledge set and merge into them — do not create competing files.
Mode: ingest → read references/ingest.md
Build the initial knowledge set from zero. Deep parallel read of the
codebase, extract conventions (2+ examples each), verify build/test/run
commands by running them, follow one real feature end to end, then write
AGENTS.md + docs/ARCHITECTURE.md with every fact cited. Nothing is
deleted. Read the reference for the full 8-step process.
Mode: update → read references/update.md
Existing knowledge files are the starting point, not a blank page. Re-verify
every claim against current code, mark stale ones, merge new findings in
place. Never overwrite — merge. Show the user a diff summary of what
changed. Read the reference for the verify-then-merge process.
Mode: query → read references/query.md
Answer natural-language questions about the repo. Read the knowledge files
first (they exist precisely so you don't re-explore), then drill into code
only when the question isn't fully covered by the docs. Always cite
file:line. If the knowledge files don't exist, offer to run ingest first.
Read the reference for the answering process and citation rules.
Shared rules (all modes)
- Cite or tag.
file:line for code facts, the command for verified
commands, UNVERIFIED for anything you couldn't check. No bare claims.
- Two examples make a convention. One example is an observation; two
with no counterexample is a convention. Report counterexamples as
inconsistencies, not as the rule.
- Run what you write. Build/test/lint commands are only "verified" after
you actually ran them and captured the exit code. Reading a
package.json
script is not verification.
- Merge, don't overwrite. In update mode especially, preserve true
facts and only change what's stale. In ingest mode, merge into any
trivial existing files rather than creating competing ones.
- Nothing destructive. Never delete existing knowledge files or code.
Ingest creates; update edits in place with diffs; query never writes.
- Stay portable. No hardcoded paths, no repo-specific assumptions in
the skill itself. All repo specifics come from reading the actual repo.
Output conventions
- Use
<ref_file file="..."/> and <ref_snippet file="..." lines="..."/>
tags when referencing files so they're clickable.
- For ingest/update, end with a short report: files written/changed, command
verification results, any
UNVERIFIED items, and suggested next steps.
- For query, end with a direct answer plus citations; if the answer is
partial, say what's missing and where to look.
1---2name: ask-my-repo3description: Three-mode repo knowledge skill for ANY codebase: INGEST builds cited knowledge files (AGENTS.md + docs/ARCHITECTURE.md) so any AI agent can understand the codebase without re-searching it; UPDATE re-verifies and merges changes into existing knowledge without overwriting; QUERY answers natural-language questions about the repo by reading the knowledge first, then drilling into code only when needed, with file:line citations. Use whenever the user asks to ingest/onboard/understand a repo, update or refresh repo knowledge/docs, or asks any question about a codebase's architecture, modules, conventions, where things live, or how something works — even if they don't say "ask-my-repo". Works on any repo, no hardcoded paths. Trigger phrases: "ask my repo", "query the codebase", "ingest this repo", "update repo knowledge", "how does X work in this repo", "where is X", "explain the architecture", /ask-my-repo.4license: MIT5---67# Ask My Repo89A shared, repo-agnostic knowledge skill with three modes. It gives any AI10agent a fast, cited understanding of any codebase — without the agent having11to re-explore the whole tree on every question.1213```14ask-my-repo/15├── SKILL.md (this file — mode selector + shared rules)16└── references/17 ├── ingest.md (full ingest process)18 ├── update.md (re-verify + merge process)19 └── query.md (answering process + citation rules)20```2122## The Prime Directive (applies to all modes)2324> **No claim without evidence.** Every statement that lands in a knowledge25> file, and every answer given in query mode, carries a `file:line`26> citation, a command you actually ran, or an explicit `UNVERIFIED` tag.27> A convention is only a convention with **two or more examples and no28> counterexample** — otherwise report it as an inconsistency. This is what29> makes the knowledge trustworthy enough to skip re-searching.3031## Mode selection3233Resolve the mode from the argument hint, the user's phrasing, and the state34of the target repo. State which mode you picked and why in your first35response line, e.g. `Mode: ingest (no AGENTS.md found in ./)`.3637| User says / situation | Mode |38|---|---|39| "ingest this repo", "onboard", "understand this codebase", "generate AGENTS.md", no knowledge files exist | **ingest** |40| "update the docs/knowledge", "refresh AGENTS.md", knowledge files exist but may be stale | **update** |41| "how does X work", "where is Y", "explain the architecture", any question about the repo | **query** |42| Ambiguous: if knowledge files exist, prefer **query**; if not, **ingest** |4344### Target resolution (all modes)4546- If a `[project-root]` argument is given, treat that path as the repo root.47- Otherwise use the current working directory.48- Never assume a hardcoded path. Always derive the root from the argument or49 cwd, and state it explicitly: `Target: /abs/path/to/repo`.50- Knowledge files live at `<root>/AGENTS.md` and `<root>/docs/ARCHITECTURE.md`51 by default. If the repo already keeps agent knowledge elsewhere52 (`CLAUDE.md`, `.cursorrules`, `docs/ROADMAP.md`, …), treat those as the53 canonical knowledge set and merge into them — do not create competing files.5455## Mode: ingest → read `references/ingest.md`5657Build the initial knowledge set from zero. Deep parallel read of the58codebase, extract conventions (2+ examples each), verify build/test/run59commands by running them, follow one real feature end to end, then write60`AGENTS.md` + `docs/ARCHITECTURE.md` with every fact cited. Nothing is61deleted. Read the reference for the full 8-step process.6263## Mode: update → read `references/update.md`6465Existing knowledge files are the starting point, not a blank page. Re-verify66every claim against current code, mark stale ones, merge new findings in67place. Never overwrite — merge. Show the user a diff summary of what68changed. Read the reference for the verify-then-merge process.6970## Mode: query → read `references/query.md`7172Answer natural-language questions about the repo. Read the knowledge files73first (they exist precisely so you don't re-explore), then drill into code74only when the question isn't fully covered by the docs. Always cite75`file:line`. If the knowledge files don't exist, offer to run ingest first.76Read the reference for the answering process and citation rules.7778## Shared rules (all modes)79801. **Cite or tag.** `file:line` for code facts, the command for verified81 commands, `UNVERIFIED` for anything you couldn't check. No bare claims.822. **Two examples make a convention.** One example is an observation; two83 with no counterexample is a convention. Report counterexamples as84 inconsistencies, not as the rule.853. **Run what you write.** Build/test/lint commands are only "verified" after86 you actually ran them and captured the exit code. Reading a `package.json`87 script is not verification.884. **Merge, don't overwrite.** In update mode especially, preserve true89 facts and only change what's stale. In ingest mode, merge into any90 trivial existing files rather than creating competing ones.915. **Nothing destructive.** Never delete existing knowledge files or code.92 Ingest creates; update edits in place with diffs; query never writes.936. **Stay portable.** No hardcoded paths, no repo-specific assumptions in94 the skill itself. All repo specifics come from reading the actual repo.9596## Output conventions9798- Use `<ref_file file="..."/>` and `<ref_snippet file="..." lines="..."/>`99 tags when referencing files so they're clickable.100- For ingest/update, end with a short report: files written/changed, command101 verification results, any `UNVERIFIED` items, and suggested next steps.102- For query, end with a direct answer plus citations; if the answer is103 partial, say what's missing and where to look.
silkyland