scriptoriumadmin/claude-skills
1
0
Fork 0
mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-08 22:21:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
claude-skills/engineering/skills/codebase-onboarding/SKILL.md
Claude d3c822a517
fix(v2.6.1): expand validator trigger patterns + fix 10 placeholder descriptions 
Follow-up to v2.6.0. Uses the audit_skills.py tool (shipped in #646) to identify
real bugs vs validator false-positives across 298 repo skills, then fixes both.

Three coordinated changes:

1. Validator trigger pattern expansion (write-a-skill internal tools)
- Old: only "Use when", "Use for", "Invoke when", "Trigger when" recognized
- New: + "Use before/during/after/while", "Invoke before/after", "Apply when",
  "Run when/before"
- Why: 11 legacy skills had semantically-valid triggers (e.g., gdpr-audit-prep
  says "Use before annual GDPR review") that the v2.6.0 validator wrongly
  flagged as missing. Natural English variants now accepted.
- Impact: 30 skills reclassified from FAIL → WARN/PASS automatically.
- Karpathy complexity: 100/100 (PASS) on both modified validators.

2. Ten placeholder descriptions fixed in engineering/skills/
The audit revealed 21 skills (~7% of repo) with broken descriptions that
were literally just the skill name (e.g., description: "Migration Architect").
These were real bugs from a v2.0.0 batch import where the description field
was never filled in. Top-10 fixed in this PR (POWERFUL-tier, high-visibility):
- migration-architect: zero-downtime migration planning + rollback strategy
- dependency-auditor: vulnerabilities + license + safe-upgrade audit
- codebase-onboarding: codebase analysis + onboarding doc generation
- ci-cd-pipeline-builder: pragmatic CI/CD from project stack signals
- mcp-server-builder: MCP servers from OpenAPI contracts (Python + TS)
- observability-designer: metrics + logs + traces + SLI/SLO design
- api-design-reviewer: REST design review + breaking-change detection
- performance-profiler: Node/Python/Go profiling + flamegraphs + load tests
- changelog-generator: Conventional Commits → release notes automation
- runbook-generator: operational runbooks from service name + templates

Each new description: ≤1024 chars, third person, action verb in first
sentence, "Use when ..." trigger in second sentence per Matt Pocock's rule.
Remaining 11 placeholder descriptions tracked for v2.6.2.

3. Quality-gates reference updated (Option C: legacy advisory)
quality_gates_for_skills.md now explicitly documents the binding-for-new
vs advisory-for-legacy split. The 6-item checklist remains BLOCKING for
post-v2.6.0 skills and ADVISORY for the 298 legacy SKILL.md files. Audit
report drift is tracked separately; PASS count is the metric to grow, not
a force-march-to-Friday deadline.

Aggregate audit improvement (against the 298 real-skill cohort):
- PASS:  4 (1%) → 7 (2%)
- WARN:  111 (37%) → 134 (45%)
- FAIL:  183 (61%) → 157 (53%)
- "Missing trigger" failures: 119 (39%) → 79 (26%)

26 skills total lifted from FAIL → WARN/PASS in this PR. Highest-leverage
fix per hour of any v2.6.x cleanup since the v2.6.0 release.

https://claude.ai/code/session_01VFreMf7XLBqMgjsrG4wSYe
2026-05-14 04:52:51 +00:00

2.5 KiB
Raw Permalink Blame History

name description
codebase-onboarding Analyze a codebase and generate onboarding documentation for engineers, tech leads, and contractors. Fast fact-gathering and repeatable onboarding outputs. Use when onboarding a new engineer, writing architecture-overview docs for a new project, or producing tech-lead briefings for unfamiliar repos.

Codebase Onboarding

Tier: POWERFUL
Category: Engineering
Domain: Documentation / Developer Experience

Overview

Analyze a codebase and generate onboarding documentation for engineers, tech leads, and contractors. This skill is optimized for fast fact-gathering and repeatable onboarding outputs.

Core Capabilities

  • Architecture and stack discovery from repository signals
  • Key file and config inventory for new contributors
  • Local setup and common-task guidance generation
  • Audience-aware documentation framing
  • Debugging and contribution checklist scaffolding

When to Use

  • Onboarding a new team member or contractor
  • Rebuilding stale project docs after large refactors
  • Preparing internal handoff documentation
  • Creating a standardized onboarding packet for services

Quick Start

# 1) Gather codebase facts
python3 scripts/codebase_analyzer.py /path/to/repo

# 2) Export machine-readable output
python3 scripts/codebase_analyzer.py /path/to/repo --json

# 3) Use the template to draft onboarding docs
# See references/onboarding-template.md

Recommended Workflow

  1. Run scripts/codebase_analyzer.py against the target repository.
  2. Capture key signals: file counts, detected languages, config files, top-level structure.
  3. Fill the onboarding template in references/onboarding-template.md.
  4. Tailor output depth by audience:
    • Junior: setup + guardrails
    • Senior: architecture + operational concerns
    • Contractor: scoped ownership + integration boundaries

Onboarding Document Template

Detailed template and section examples live in:

  • references/onboarding-template.md
  • references/output-format-templates.md

Common Pitfalls

  • Writing docs without validating setup commands on a clean environment
  • Mixing architecture deep-dives into contractor-oriented docs
  • Omitting troubleshooting and verification steps
  • Letting onboarding docs drift from current repo state

Best Practices

  1. Keep setup instructions executable and time-bounded.
  2. Document the "why" for key architectural decisions.
  3. Update docs in the same PR as behavior changes.
  4. Treat onboarding docs as living operational assets, not one-time deliverables.