Repository Discovery

Explore and document an unfamiliar GitHub repository so future development work can start quickly with a clear understanding of the system architecture, tech...

Security Scan

The skill's instructions, requested resources, and scope are consistent with its stated purpose of exploring and documenting a GitHub repository; nothing requested appears disproportionate or unrelated.

Purpose & Capability

The name/description match the SKILL.md: the instructions focus on scanning repository files (README, package manifests, Dockerfiles, .github configs, etc.) and producing a structured REPO_DISCOVERY.md. No unrelated binaries, installs, or external services are required.

Instruction Scope

Instructions appropriately direct the agent to inspect repository files and metadata. They explicitly include looking for configuration files and .env/.env.example to document required env vars and API endpoints — this is reasonable for repo discovery but means the agent will encounter secrets and credentials if present. The SKILL.md does not instruct the agent to read system-wide files outside the repo or to transmit data to unexpected external endpoints.

Install Mechanism

This is an instruction-only skill with no install spec and no code files, so nothing is written to disk or installed by the skill itself.

Credentials

The skill declares no required environment variables, credentials, or config paths. The only data it asks the agent to inspect is repository-local (dependency files, .env in repo, config directories), which is proportional to its purpose.

Persistence & Privilege

always is false and the skill does not request persistent presence or modify other skills. It relies on normal agent invocation behavior and does not ask for elevated agent-wide privileges.

Assessment

This skill is coherent and appropriate for documenting a repository. Before using it, confirm which repository the agent will access and whether it is allowed to view any private repos. Be aware the agent will look for config and .env files and may encounter secrets; if you do not want secret values recorded or transmitted, either remove/redact them in the repo or instruct the agent (or your agent runtime) to only record variable names and not values. Also review any repository .github/* agent instructions it will prioritize, since those files can change agent behavior.

Repository Discovery Agent

Purpose

Explore and document an unfamiliar GitHub repository so future development work can start quickly with a clear understanding of the system architecture, technologies, and capabilities.

The agent produces a structured overview of the repository including technology stack, dependencies, architecture patterns, and implemented features.

---

When to Use

Use this agent when:

• Starting work on a new or unfamiliar repository
• Preparing for future development work
• Performing technical due diligence on a project
• Building context for AI coding agents
• Creating repository documentation
• Evaluating technology stack and architecture

---

Primary Objectives

1. Identify repository purpose and capabilities
2. Detect technology stack and frameworks
3. Catalogue libraries and dependencies
4. Understand architecture patterns
5. Identify major features and modules
6. Locate developer instructions and conventions
7. Produce a structured repository briefing

---

Exploration Workflow

1. Start With AI/Agent Guidance

Check for repository-specific AI instructions first.

Look for:

.github/copilot-instructions.md .github/agent.md .github/instructions.md

These files often contain:

• coding conventions
• architectural expectations
• testing requirements
• build instructions
• agent workflows

If present, read them before anything else.

---

2. Identify Core Project Metadata

Check for these files in the repository root:

README.md package.json pyproject.toml requirements.txt Cargo.toml go.mod pom.xml build.gradle Makefile Dockerfile docker-compose.yml

Extract:

• project purpose
• primary language
• framework(s)
• build system
• runtime environment
• service architecture

---

3. Detect Technology Stack

Document the following:

Programming Languages

Examples:

• JavaScript / TypeScript
• Python
• Go
• Rust
• Java
• C++

Frameworks

Examples:

• Next.js
• React
• Express
• FastAPI
• Django
• Spring
• Flask
• NestJS

Infrastructure

Look for:

• Docker
• Kubernetes
• Terraform
• Vercel
• AWS SDK usage
• Cloud integrations

Databases

Detect usage of:

• PostgreSQL
• MySQL
• SQLite
• MongoDB
• Redis
• Qdrant
• Elasticsearch

---

4. Identify Libraries and Dependencies

Analyze dependency files such as:

package.json requirements.txt poetry.lock go.mod Cargo.toml

Document:

• core libraries
• AI/ML frameworks
• database clients
• authentication libraries
• API frameworks
• testing libraries

Highlight critical dependencies that shape architecture.

---

5. Understand Project Structure

Map the repository layout.

Example:

/app /components /lib /api /services /scripts /tests /docs

Determine:

• where business logic lives
• where API endpoints exist
• UI components
• background jobs
• configuration layers

Note architectural patterns such as:

• monorepo
• microservices
• layered architecture
• hexagonal architecture
• MVC

---

6. Identify Major Features

From the codebase and documentation, extract the main capabilities of the system.

Examples:

• authentication system
• API gateway
• chatbot
• search engine
• recommendation engine
• analytics pipeline
• background workers
• job queues

Describe each feature briefly.

---

7. Locate Configuration and Environment Requirements

Search for:

.env.example .env config/ settings/

Document:

• required environment variables
• API keys
• service endpoints
• feature flags

---

8. Discover Build and Development Workflow

Identify developer commands such as:

npm install npm run dev pnpm build docker compose up make dev

Document:

• development startup process
• build pipeline
• testing commands
• deployment hints

---

9. Detect Testing Strategy

Look for testing frameworks:

Examples:

• Jest
• Vitest
• Mocha
• PyTest
• Go test
• JUnit

Document:

• test locations
• test strategy
• coverage expectations

---

Output Format

The agent should produce a file:

REPO_DISCOVERY.md

Structure:

Repository Overview

Project Purpose

Technology Stack

Languages

Frameworks

Infrastructure

Dependencies

Architecture

Repository Structure

Key Features

Configuration

Development Workflow

Testing Strategy

Notable Observations

Questions / Unknowns

---

Key Principles

Start With Instructions

Always prioritize:

.github/copilot-instructions.md .github/agent.md

These define how the repository expects AI agents to behave.

---

Be Evidence Based

Only document technologies or features that are confirmed in the codebase.

Avoid speculation.

---

Focus on Developer Value

The goal is to create a briefing that allows another developer or AI agent to:

• understand the project quickly
• start implementing features safely
• navigate the repository efficiently

---

Example Use

User request:

Explore this GitHub repository and document it so we can build features later.

Agent output:

REPO_DISCOVERY.md

A structured overview of the repository's architecture, technologies, and features ready for future development work.