discover-repo

Files (3)

• SKILL.md
• example-publisher-claude-md.md · references/
• template.md · references/

SKILL.md (first lines)

# Discover Repo

Generate a high-quality AGENTS.md that serves as an index and architecture guide for the current repository, with a CLAUDE.md symlink for Claude Code compatibility.

## Output

- `AGENTS.md` at the current directory root (primary artifact)
- `CLAUDE.md` symlink pointing to `AGENTS.md`
- If `AGENTS.md` already exists: write to `AGENTS.discovery.md` and symlink `CLAUDE.discovery.md` to it (never overwrite)

## Process

### Phase 1 - Parallel Discovery

Dispatch 5 Agent subagents simultaneously using `subagent_type: "Explore"`. All 5 MUST be dispatched in a single message for parallel execution.

Replace `{cwd}` with the actual current working directory in each prompt.

**Structure Agent:**
```
Explore the repository at {cwd}. Map the directory structure.

Report in clean markdown:

1. DIRECTORY TREE - Annotated tree of the repo showing key files/directories with one-line descriptions.
   - 3 levels deep for all directories, up to 5 levels for src/, lib/, core/, and other source directories
   - Annotate each significant file with a one-line description
   - Skip node_modules/, target/, build/, dist/, .git/, __pycache__/, vendor/

2. LANGUAGES & BUILD SYSTEM - Languages used, build tool (Cargo, npm, Make, etc.), key config files

3. FILE COUNTS - Approximate source file count by language/extension

Cite exact file paths. Be thorough but concise.
Flag anything uncertain with [NEEDS VERIFICATION].
```

**Core Code Agent:**
```
Explore the repository at {cwd}. Understand the core code architecture.

Report in clean markdown:

1. ENTRYPOINTS - Main/entrypoint files (main.rs, main.go, index.ts, etc.). What each does.

2. KEY COMPONENTS TABLE - For each major module/component/service:
   | Component | File(s) | Responsibility |
   Include specific method/function names that define the component's behavior.

3. DATA FLOW - How data moves through the system. Trace the main happy path from input to output.

4. EXECUTION FLOW - Step-by-step: what happens when the main operation runs.

5. KEY ABSTRACTIONS - Core types, traits/interfaces, data structures. Name, file, one-line description.

6. IF APPLICABLE (include only if found):
   - API routes/endpoints table (HTTP, RPC, WebSocket) with method, path, handler, description
   - Wire protocol or message types table (tags, payload types, directions)

Cite exact file paths and line numbers. Focus on architecture, not implementation details.
Flag anything uncertain with [NEEDS VERIFICATION].
```

**Docs Agent:**
```
Explore the repository at {cwd}. Extract the project's purpose and existing documentation.

Report in clean markdown:

1. PURPOSE - What does this project do? Why does it exist? Synthesize from README, doc comments, and code.

2. KEY CAPABILITIES - Bullet list of what the system can do.

3. EXISTING DOCS - List all documentation files with a one-line summary of each.

4. PROTOCOL/DOMAIN CONTEXT - If domain-specific: terminology, external system interactions.

5. NOTEWORTHY COMMENTS - Significant code comments explaining architectural decisions (grep for TODO, HACK, NOTE, IMPORTANT, SAFETY, INVARIANT).

6. CROSS-REPO CONTEXT (if applicable) - How this repo relates to sibling repos, external services, or a broader system. Import/dependency relationships with other repos.

7. HARD-WON RULES (if applicable) - Look for lessons-learned files, "do not" comments, removed-code notes, or operational rules embedded in docs/comments. These encode negative knowledge (what NOT to do).

Cite exact file paths. Prefer direct quotes over paraphrasing.
Flag anything uncertain with [NEEDS VERIFICATION].
```

**Tests Agent:**
```
Explore the repository at {cwd}. Understand the test infrastructure.

Report in clean markdown:

1. TEST FILES TABLE:
   | File/Directory | Tests (approx) | What it tests |

2. TESTING APPROACH - Unit? Integration? E2E? Frameworks? Test utilities/helpers?

3. CI CONFIGURATION - Read CI configs (.github/workflows/, etc.). What runs, what gates merges.

4. TEST COMMANDS - How to run tests.

Cite exact file paths. Count test functions where possible.
Flag anything uncertain with [NEEDS VERIFICATION].
```

**Config Agent:**
```
Explore the repository at {cwd}. Understand configuration, dependencies, and deployment.

Report in clean markdown:

1. BUILD COMMANDS - How to build, test, lint, format. Check Makefile, justfile, package.json scripts, etc.

2. CONFIGURATION - Config files, environment variables, .env templates.

3. DEPENDENCIES - Top 10-15 most important dependencies and their purpose.

4. DEPLOYMENT - Dockerfile, docker-compose, K8s manifests. Deployment targets.

From kyzooghost/skills, MIT.

More from kyzooghost/skills