not-matthias/learn-codebase

<!-- Source: https://github.com/HazAT/pi-config/blob/main/skills/learn-codebase/SKILL.md -->

Learn Codebase Conventions

Scan the current project for agent instruction files from various tools, summarize the conventions, and optionally register discovered skills in .pi/settings.json.

Step 1: Scan for Convention Files

Search the project root for these files and directories:

# Agent instruction files (root-level)
for f in CLAUDE.md AGENTS.md COPILOT.md .cursorrules .clinerules; do
  [ -f "$f" ] && echo "FOUND: $f"
done

# Agent config directories
for d in .claude .cursor .github .pi; do
  [ -d "$d" ] && echo "FOUND DIR: $d/"
done

# Deeper convention files
[ -f ".github/copilot-instructions.md" ] && echo "FOUND: .github/copilot-instructions.md"

# Claude Code rules, skills, and commands
[ -d ".claude/rules" ] && echo "FOUND: .claude/rules/"
[ -d ".claude/skills" ] && echo "FOUND: .claude/skills/"
[ -d ".claude/commands" ] && echo "FOUND: .claude/commands/"

# Cursor rules
[ -d ".cursor/rules" ] && echo "FOUND: .cursor/rules/"

# Pi project skills
[ -d ".pi/skills" ] && echo "FOUND: .pi/skills/"

Step 2: Read and Summarize

For each discovered file, read its contents and extract key conventions:

1. Root instruction files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) — read fully, these are the primary project rules
2. Rule directories (.claude/rules/, .cursor/rules/) — read each rule file
3. Commands (.claude/commands/) — read each command file. These are reusable prompt workflows from Claude Code (e.g., PR creation, release scripts, review checklists). Summarize what each command does.
4. Skills directories (.claude/skills/, .cursor/skills/) — list available skills and read their descriptions
5. Settings files (.claude/settings.json) — note permissions and configuration

Present a structured summary to the user:

## Project Conventions Summary

### Build & Run
- Package manager: [npm/pnpm/yarn/bun]
- Dev command: [command]
- Test command: [command]

### Code Style
- [Key style rules]

### Architecture
- [Key patterns, structure]

### Agent-Specific Rules
- [Any rules targeted at AI agents]

### Available Commands (from .claude/commands/)
- [command-name] — [what it does]

### Available Skills (from other tools)
- [List skills found in .claude/skills, .cursor/skills]

Focus on actionable information. Skip boilerplate and obvious conventions.

Step 3: Register External Skills

If .claude/skills/ or other skill directories exist, suggest registering them in .pi/settings.json so pi can use them too:

{
  "skills": ["../.claude/skills"]
}

Ask the user if they want to create or update .pi/settings.json with the discovered skill paths. Only do this if skills were actually found.

Step 4: Note What to Remember

After summarizing, highlight the top 3-5 things to keep in mind while working in this project. These are the conventions most likely to be violated if forgotten — things like:

• Specific commit message formats
• Required co-author lines
• Mandatory test patterns
• Forbidden patterns or anti-patterns
• Package manager preferences (don't use npm when pnpm is required)

Step 5: Security & Smell Sweep

Scan the codebase for things that look shady, fishy, or dangerous. This isn't a full audit — it's a quick sweep to surface anything the user should be aware of. Flag real concerns, not hypotheticals.

What to Scan

Run these checks and report anything suspicious:

Hardcoded Secrets & Credentials

# Look for hardcoded secrets, API keys, tokens, passwords
rg -i --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  '(api[_-]?key|secret|token|password|credential|auth)\s*[:=]\s*["\x27][^"\x27]{8,}' \
  --type-not binary -l 2>/dev/null | head -20

# .env files committed to repo (should be gitignored)
git ls-files --cached | grep -iE '\.env($|\.)' 2>/dev/null

Insecure Code Patterns

# eval(), exec(), dangerouslySetInnerHTML, innerHTML assignments, shell injection vectors
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e '\beval\s*\(' -e '\bexec\s*\(' -e 'dangerouslySetInnerHTML' \
  -e '\.innerHTML\s*=' -e 'child_process' -e '\$\(.*\$\{' \
  --type-not binary -l 2>/dev/null | head -20

# Unparameterized SQL (string concatenation in queries)
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e 'query\s*\(\s*[`"'"'"'].*\$\{' -e 'execute\s*\(\s*[`"'"'"'].*\+' \
  --type-not binary -l 2>/dev/null | head -20

Suspicious Dependencies

# Check for install/postinstall scripts in dependencies (supply chain risk)
[ -f package.json ] && cat package.json | grep -E '"(pre|post)install"' 2>/dev/null

# Look for wildcard or git dependencies (unpinned)
[ -f package.json ] && rg '"[*]"|"git[+:]|"github:' package.json 2>/dev/null

# Very outdated lock file vs package.json mismatch
[ -f package-lock.json ] && [ package.json -nt package-lock.json ] && echo "WARN: package.json newer than lockfile"
[ -f pnpm-lock.yaml ] && [ package.json -nt pnpm-lock.yaml ] && echo "WARN: package.json newer than lockfile"

Overly Permissive Configurations

# CORS wildcards, disabled security headers, permissive CSP
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e "origin:\s*['\"]?\*" -e 'Access-Control-Allow-Origin.*\*' \
  -e "cors.*true" -e 'unsafe-inline' -e 'unsafe-eval' \
  --type-not binary -l 2>/dev/null | head -10

# Disabled TLS verification, insecure flags
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e 'NODE_TLS_REJECT_UNAUTHORIZED.*0' -e 'rejectUnauthorized.*false' \
  -e 'verify.*false' -e 'insecure.*true' \
  --type-not binary -l 2>/dev/null | head -10

File Permissions & Sensitive Files

# Private keys, certificates, or database files in repo
git ls-files --cached 2>/dev/null | grep -iE '\.(pem|key|p12|pfx|jks|keystore|sqlite|db)$' | head -10

# Check .gitignore exists and covers basics
if [ -f .gitignore ]; then
  for pattern in '.env' 'node_modules' '.DS_Store'; do
    grep -q "$pattern" .gitignore || echo "WARN: .gitignore missing $pattern"
  done
else
  echo "WARN: No .gitignore file found"
fi

How to Report

Present findings in a dedicated section with severity tags. Be direct — no sugarcoating, but also no false alarms.

## Security & Code Smell Findings

### [P0] Hardcoded API key in src/config.ts
Line 42 has a Stripe secret key directly in source code.
This should be in an environment variable, not committed.

### [P1] .env file tracked by git
`.env.production` is committed and contains database credentials.
Add to `.gitignore` and rotate the exposed credentials.

### [P2] eval() usage in src/utils/parser.ts
Used to parse user-supplied expressions. Consider a safe parser
like `JSON.parse()` or a sandboxed evaluator instead.

### Nothing Concerning
[If sweep is clean, say so explicitly — don't manufacture findings.]

Severity guide:

• [P0] — Actively dangerous. Exposed secrets, SQL injection, RCE vectors. Fix now.
• [P1] — Genuine risk. Someone will get bitten by this. Should fix soon.
• [P2] — Worth knowing about. Not urgent, but the user should be aware.

Do NOT flag:

• Test files using eval/exec for testing purposes
• Known development-only insecure configs (like localhost CORS in dev servers)
• Theoretical issues with no concrete exploit path in this codebase
• Dependencies that are simply old (that's not a security finding without a known CVE)