codebase-context

Gather architectural context about an internal system from code and documentation across the organization — use when asked to understand a system's architecture, find its repos, or get an overview before working on it.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Codebase Context

Gather comprehensive architectural context about an internal system by searching code and documentation across the organization.

Determine the system name from the user's request. If not specified, ask before proceeding.

Core Principles

Breadth before depth: Find all relevant pieces before diving deep
Docs + code: Both tell important parts of the story
Be skeptical: Not every search result is relevant context
Freshness matters: Stale docs can mislead

Process

Phase 1: Find the Code

Search for the system's codebase across all repositories:

code_search "[system] main OR core updated:past_month"
code_search "[system] service handler"

Look for:

Main entry points and core modules
API definitions (REST, gRPC, GraphQL)
Key data structures and models

Phase 2: Find the Documentation

Search for architecture and design docs:

search "[system] architecture OR design doc"
search "[system] RFC OR proposal"
search "[system] runbook OR playbook"

Phase 3: Identify Key Contributors

Find who's actively working on this system:

code_search "[system] owner:* updated:past_month"

Cross-reference with employee_search for contact info.

Phase 4: Vet All Content

For each piece of content, evaluate:

Test	✅ Include	⚠️ Note	❌ Reject
Relevance	Core component, directly relevant	Mentions system but not central	Keyword coincidence
Currency	<6 months, matches code	6-12 months	12+ months with no activity
Authority	Approved RFC, design doc, official runbook	Team wiki, notes, drafts	Outdated proposals, abandoned work
Doc/Code consistency	Docs reflect current state	Note discrepancy, prefer code	Doc significantly wrong — warn user

Repository Health:

✅ ACTIVE: Commits in past month
⚠️ SLOWING: Last commit 1-6 months ago
❌ STALE: No commits in 6+ months

Phase 5: Generate Vetted Context Report

# Codebase Context: [System Name]

## Freshness Check
| Component | Last Updated | Status |
|-----------|--------------|--------|
| Main repo | [date] | Active / Slowing / Stale |
| Design doc | [date] | Current / Aging / Outdated |

## Overview
[1-2 paragraph summary synthesized from current docs — note age of sources]

## Key Repositories
| Repository | Purpose | Last Active | Status |
|------------|---------|-------------|--------|
| [repo] | [what it does] | [date] | Active / Stale |

## Architecture Highlights
[Only include if from recent/authoritative sources]
- **API Layer**: [description] (source: [doc], updated [date])
- **Data Model**: [description]
- **Key Dependencies**: [list]

## Documentation (Vetted)

### Current & Authoritative
| Doc | Type | Updated | Summary |
|-----|------|---------|---------|
| [Title] | RFC | [date] | [summary] |

### Use With Caution (Aging)
| Doc | Type | Updated | Caveat |
|-----|------|---------|--------|
| [Title] | Design doc | [date] | May not reflect current implementation |

## Key Contributors
| Name | Role | Last Active | Contact |
|------|------|-------------|---------|
| [Name] | [Title] | [date] | [email] |

## Related Systems
- **Upstream**: [systems that call this one]
- **Downstream**: [systems this one calls]

## Warnings
- [ ] [Any concerns about the system's state]

If Limited Context Found

# Codebase Context: [System Name]

## Limited Context Available

Found limited authoritative information about this system.

**What was found:** [code/docs summary]
**Gaps:** No recent design documentation, no clear architectural overview

**Suggested next steps:**
1. Check with [suggested team/person]
2. Explore the code directly: [suggested entry points]

Troubleshooting

No Results Found

Try alternative system names or acronyms
Search for related technologies
Check if the system might be in a private repo

Conflicting Information

Note the discrepancy clearly
Prefer code as source of truth for current state
Reference doc dates to identify which might be outdated

Repository: gleanwork/claude-plugins
Path: plugins/glean/skills/codebase-context/SKILL.md
Commit: a549de6

Last updated: 5 days ago
First committed: 4 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.