aj-geddes/code-reading
skills/code-reading/SKILL.md
Strategic code comprehension protocol for navigating existing codebases. ALWAYS trigger on "understand this code", "how does this work", "refactor", "before changing", "legacy code", "code review", "what does this do", "explain this codebase", "walk me through", "unfamiliar code", "read through". Use when exploring unfamiliar code, preparing to modify legacy systems, debugging complex issues, or conducting code reviews. Different from pattern-transfer which maps known solutions across domains -- this skill builds accurate mental models of existing code.
$ install --global
skillsauthnpx skillsauth add aj-geddes/unicorn-team code-readingInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 25, 2026, 4:41 PM54.2s3 files scanned
SKILL.md
- name:
- code-reading
- description:
- >-
<!-- Last reviewed: 2026-03 -->
Code Reading
Strategic Reading Protocol
1. Entry Points First
Start where execution begins. Never read alphabetically.
# Find entry points
grep -r "app.run\|app.listen\|@app.route\|def main\|if __name__" --include="*.py" --include="*.js"
Read order: Main entry -> route definitions -> request handlers -> business logic -> data layer -> utilities
2. Data Flow Tracing
Follow: INPUT -> VALIDATION -> PROCESSING -> STORAGE -> OUTPUT
At each step ask: Where does data enter? What validations? How transformed? Where stored? What side effects?
3. Error Path Mapping
grep -r "try:\|except\|catch\|raise\|throw" --include="*.py" --include="*.js"
Map: What fails? How detected? How handled (retry/fallback/propagate)? What messages returned? Errors logged with context?
4. Integration Points
Identify system boundaries (high-risk areas): APIs, databases, message queues, file systems, external services.
Document for each: expected format, return format, failure modes, retry logic, timeouts.
Comprehension Levels
| Level | Question | Technique |
|-------|----------|-----------|
| L1: Behavior | What does it DO? (inputs, outputs, side effects) | Read signature + docstring + tests |
| L2: Mechanics | HOW does it work? (algorithm, data structures, steps) | Read implementation |
| L3: Design | WHY this way? (tradeoffs, constraints, optimization target) | Comments, git log/blame, issue tracker |
| L4: Impact | What ELSE affected? (callers, dependencies, blast radius) | grep -r "function_name", check tests |
Legacy Code Protocol
- Run existing tests -- verify current behavior is captured
- Add characterization tests -- document current behavior (even if "wrong")
- Map dependency graph -- who calls this? what does this call?
- Identify load-bearing walls -- critical code that MUST NOT break
- Find seams -- safe change points (object, preprocessing, link seams)
See references/legacy-code-protocol.md for detailed steps and seam patterns.
Reading Techniques
| Technique | Purpose | |-----------|---------| | Follow happy path first | Understand main flow before edge cases | | Map side effects | Find hidden consequences (DB writes, API calls, emails) | | Identify invariants | Assumptions that must ALWAYS hold | | Note coupling points | High coupling = high risk areas |
See references/reading-techniques.md for detailed guidance and examples.
Reading Checklist
Starting a new codebase:
- [ ] Find entry points (main, routes, handlers)
- [ ] Trace data flow for one request/feature
- [ ] Map error handling and failure modes
- [ ] Identify external dependencies
- [ ] Run existing tests
- [ ] Locate critical business logic
- [ ] Note high coupling points
- [ ] Document in 1-page architecture diagram
Before Changing Legacy Code
- [ ] Run existing tests (capture baseline)
- [ ] Add characterization tests (document current behavior)
- [ ] Map dependency graph (who calls this? what does this call?)
- [ ] Identify load-bearing walls (critical paths)
- [ ] Find seams (safe change points)
- [ ] Make smallest change possible
- [ ] Verify behavior unchanged (tests pass)
Common Patterns to Recognize
Predict structure without reading every line:
- Model-View-Controller -- separation of concerns
- Repository Pattern -- data access abstraction
- Strategy Pattern -- algorithm selection
- Observer Pattern -- event notification
- Factory Pattern -- object creation
- Decorator Pattern -- behavior extension
- Adapter Pattern -- interface translation
Related Skills
aj-geddes/testing
development
VerifiedTrustedCommunity
Guides the user through test-first development and test strategy decisions. ALWAYS trigger on "write tests", "TDD", "test coverage", "mock", "test fails", "flaky test", "how to test", "unit test", "integration test", "e2e test", "test structure", "what to test", "test organization", "coverage report", "testing strategy", "arrange act assert". Use when writing new tests, choosing test types, setting up mocking, debugging flaky tests, improving coverage, or designing testable code. Different from qa-security agent which focuses on code review and security audits rather than test authoring.
7SKILL.mdUpdated Apr 25, 2026
aj-geddes/technical-debt
development
VerifiedTrustedCommunity
Guides deliberate management of technical debt: recognition, tracking, prioritization, and paydown. ALWAYS trigger on "technical debt", "code shortcut", "pay down debt", "debt tracking", "just for now", "temporary hack", "hardcoded value", "copy-paste code", "missing tests", "TODO cleanup", "refactor plan", "debt priority", "interest cost", "boy scout rule", "code quality backlog". Use when taking a shortcut, discovering suboptimal code, planning debt paydown, or quantifying ongoing cost of compromises.
7SKILL.mdUpdated Apr 25, 2026
aj-geddes/self-verification
development
VerifiedTrustedCommunity
Guides the user through systematic pre-commit quality verification. ALWAYS trigger on "review my code", "check my work", "before commit", "self-review", "quality check", "am I ready to commit", "pre-commit review", "code quality", "verify my changes", "sanity check", "review before merge", "is this ready". Use before any commit, merge, or code review submission.
7SKILL.mdUpdated Apr 25, 2026
aj-geddes/security
development
VerifiedTrustedCommunity
Guides secure development using defense-in-depth and attacker's mindset. ALWAYS trigger on "security review", "vulnerability", "authentication", "authorization", "input validation", "XSS", "SQL injection", "CSRF", "secrets management", "OWASP", "threat model", "security scan", "path traversal", "mass assignment", "privilege escalation", "security headers", "bandit", "dependency audit", "hardening". Use when implementing auth, handling user input, storing secrets, reviewing code for vulnerabilities, or preparing for production deployment. Different from devops skill which covers infrastructure; this covers application-level security patterns.
7SKILL.mdUpdated Apr 25, 2026