Skip to content

borghei/Claude-Skills / engineering/codebase-onboarding

codebase-onboarding

Verified

Gathers facts about a codebase (stack, layers, entry points, setup gaps) and turns them into onboarding docs: architecture overview, file map, setup guide, debugging guide. Use when onboarding engineers or re-documenting after a refactor.

scripts/setup_validator.py

View on GitHub
#!/usr/bin/env python3
"""Validate a project's development setup completeness.

Checks for README, .env.example, Makefile/scripts, required tools,
CI config, and other setup hygiene indicators. Produces a scored
report with pass/warn/fail verdicts and actionable recommendations.
"""

import argparse
import json
import os
import shutil
import subprocess
import sys
from pathlib import Path

# Each check: (id, name, description, severity)
# severity: "critical" (blocks setup), "recommended", "nice-to-have"


def _file_exists(root, *candidates):
    """Return the first matching file path or None."""
    for c in candidates:
        if (Path(root) / c).exists():
            return c
    return None


def _glob_any(root, pattern):
    """Return True if any file matches the glob pattern."""
    return bool(list(Path(root).glob(pattern)))


def _file_has_content(root, filename, min_lines=3):
    """Check if a file exists and has meaningful content."""
    target = Path(root) / filename
    if not target.exists():
        return False
    try:
        lines = [l.strip() for l in open(target, errors="ignore") if l.strip()]
        return len(lines) >= min_lines
    except (OSError, PermissionError):
        return False


def _detect_package_scripts(root):
    """Extract script names from package.json if present."""
    pkg_path = Path(root) / "package.json"
    if not pkg_path.exists():
        return []
    try:
        import json as _json
        data = _json.loads(pkg_path.read_text(errors="ignore"))
        return list(data.get("scripts", {}).keys())
    except (ValueError, OSError):
        return []


def _check_tool_available(tool_name):
    """Check if a CLI tool is available on PATH."""
    return shutil.which(tool_name) is not None


def run_checks(root):
    """Run all setup validation checks and return results."""
    root = str(Path(root).resolve())
    results = []

    # 1. README exists and has content
    readme = _file_exists(root, "README.md", "README.rst", "README.txt", "README")
    results.append({
        "id": "readme",
        "name": "README documentation",
        "severity": "critical",
        "status": "pass" if readme and _file_has_content(root, readme) else (
            "warn" if readme else "fail"
        ),
        "found": readme,
        "recommendation": (
            None if readme and _file_has_content(root, readme)
            else "README exists but is too short" if readme
            else "Add a README.md with project overview, setup steps, and usage examples"
        ),
    })

    # 2. Environment variable template
    env_file = _file_exists(root, ".env.example", ".env.sample", ".env.template", ".env.defaults")
    results.append({
        "id": "env_template",
        "name": "Environment variable template",
        "severity": "critical",
        "status": "pass" if env_file else "fail",
        "found": env_file,
        "recommendation": (
            None if env_file
            else "Add .env.example listing all required environment variables with descriptions"
        ),
    })

    # 3. .env not committed (check .gitignore)
    gitignore_path = Path(root) / ".gitignore"
    env_ignored = False
    if gitignore_path.exists():
        try:
            content = gitignore_path.read_text(errors="ignore")
            env_ignored = any(
                line.strip() in (".env", ".env*", ".env.*", ".env.local")
                for line in content.splitlines()
            )
        except OSError:
            pass
    env_committed = (Path(root) / ".env").exists()
    results.append({
        "id": "env_gitignore",
        "name": ".env excluded from version control",
        "severity": "critical",
        "status": "pass" if env_ignored and not env_committed else (
            "fail" if env_committed and not env_ignored else "warn"
        ),
        "found": ".gitignore has .env pattern" if env_ignored else None,
        "recommendation": (
            None if env_ignored and not env_committed
            else "SECURITY: .env file is committed! Add .env to .gitignore and remove from tracking"
            if env_committed and not env_ignored
            else "Add .env to .gitignore to prevent accidental secret commits"
        ),
    })

    # 4. Build / task runner
    makefile = _file_exists(root, "Makefile", "justfile", "Taskfile.yml")
    pkg_scripts = _detect_package_scripts(root)
    has_runner = makefile is not None or len(pkg_scripts) > 0
    results.append({
        "id": "task_runner",
        "name": "Build/task runner configured",
        "severity": "recommended",
        "status": "pass" if has_runner else "warn",
        "found": makefile or (f"package.json scripts: {', '.join(pkg_scripts[:5])}" if pkg_scripts else None),
        "recommendation": (
            None if has_runner
            else "Add a Makefile or package.json scripts for common tasks (build, test, lint, dev)"
        ),
    })

    # 5. Lock file present
    lock = _file_exists(
        root, "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb",
        "Pipfile.lock", "poetry.lock", "uv.lock",
        "go.sum", "Cargo.lock", "Gemfile.lock", "composer.lock",
    )
    results.append({
        "id": "lockfile",
        "name": "Dependency lock file",
        "severity": "recommended",
        "status": "pass" if lock else "warn",
        "found": lock,
        "recommendation": (
            None if lock
            else "Commit a dependency lock file to ensure reproducible builds"
        ),
    })

    # 6. CI/CD configuration
    ci_found = None
    if (Path(root) / ".github" / "workflows").is_dir():
        workflows = list((Path(root) / ".github" / "workflows").glob("*.yml")) + \
                    list((Path(root) / ".github" / "workflows").glob("*.yaml"))
        if workflows:
            ci_found = f".github/workflows/ ({len(workflows)} workflow(s))"
    if not ci_found:
        ci_file = _file_exists(root, ".gitlab-ci.yml", "Jenkinsfile", ".circleci/config.yml",
                               "bitbucket-pipelines.yml", ".travis.yml")
        if ci_file:
            ci_found = ci_file
    results.append({
        "id": "ci_config",
        "name": "CI/CD configuration",
        "severity": "recommended",
        "status": "pass" if ci_found else "warn",
        "found": ci_found,
        "recommendation": (
            None if ci_found
            else "Add CI/CD configuration to automate testing and deployment"
        ),
    })

    # 7. Linting / formatting config
    lint_config = _file_exists(
        root, ".eslintrc", ".eslintrc.js", ".eslintrc.json", ".eslintrc.yml",
        "eslint.config.js", "eslint.config.mjs",
        ".prettierrc", ".prettierrc.json", "prettier.config.js",
        "biome.json", "biome.jsonc",
        ".flake8", ".pylintrc", "pyproject.toml", "setup.cfg",
        ".rubocop.yml", ".golangci.yml",
    )
    results.append({
        "id": "linter",
        "name": "Linting/formatting configuration",
        "severity": "recommended",
        "status": "pass" if lint_config else "warn",
        "found": lint_config,
        "recommendation": (
            None if lint_config
            else "Add linter/formatter config for consistent code style"
        ),
    })

    # 8. Tests exist
    has_tests = (
        _glob_any(root, "**/*.test.*") or
        _glob_any(root, "**/*.spec.*") or
        _glob_any(root, "**/test_*.py") or
        _glob_any(root, "**/tests/**/*.py") or
        _glob_any(root, "tests/") or
        _glob_any(root, "test/") or
        _glob_any(root, "__tests__/")
    )
    results.append({
        "id": "tests",
        "name": "Test suite present",
        "severity": "recommended",
        "status": "pass" if has_tests else "warn",
        "found": "Test files detected" if has_tests else None,
        "recommendation": (
            None if has_tests
            else "Add tests to verify setup correctness and prevent regressions"
        ),
    })

    # 9. Contributing guide
    contrib = _file_exists(root, "CONTRIBUTING.md", "CONTRIBUTING", "docs/CONTRIBUTING.md")
    results.append({
        "id": "contributing",
        "name": "Contributing guidelines",
        "severity": "nice-to-have",
        "status": "pass" if contrib else "warn",
        "found": contrib,
        "recommendation": (
            None if contrib
            else "Add CONTRIBUTING.md with PR process, coding standards, and review expectations"
        ),
    })

    # 10. License
    lic = _file_exists(root, "LICENSE", "LICENSE.md", "LICENSE.txt", "LICENCE", "COPYING")
    results.append({
        "id": "license",
        "name": "License file",
        "severity": "nice-to-have",
        "status": "pass" if lic else "warn",
        "found": lic,
        "recommendation": (
            None if lic
            else "Add a LICENSE file to clarify usage and contribution terms"
        ),
    })

    # 11. Docker setup (if Dockerfile exists, check docker-compose too)
    dockerfile = _file_exists(root, "Dockerfile")
    compose = _file_exists(root, "docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml")
    if dockerfile:
        results.append({
            "id": "docker_compose",
            "name": "Docker Compose for local infra",
            "severity": "recommended",
            "status": "pass" if compose else "warn",
            "found": compose,
            "recommendation": (
                None if compose
                else "Dockerfile found but no docker-compose. Add docker-compose.yml for local infrastructure"
            ),
        })

    # 12. Editor config
    editor = _file_exists(root, ".editorconfig")
    results.append({
        "id": "editorconfig",
        "name": "EditorConfig for consistent formatting",
        "severity": "nice-to-have",
        "status": "pass" if editor else "warn",
        "found": editor,
        "recommendation": (
            None if editor
            else "Add .editorconfig for consistent indentation across editors"
        ),
    })

    return results


def compute_score(results):
    """Compute an overall setup health score."""
    weights = {"critical": 3, "recommended": 2, "nice-to-have": 1}
    total = 0
    earned = 0
    for r in results:
        w = weights.get(r["severity"], 1)
        total += w
        if r["status"] == "pass":
            earned += w
        elif r["status"] == "warn":
            earned += w * 0.5
    return round((earned / total) * 100) if total > 0 else 0


def format_human(results, score, project_path):
    """Format results as human-readable text."""
    lines = []
    lines.append(f"{'=' * 60}")
    lines.append(f"  SETUP VALIDATION: {Path(project_path).name}")
    lines.append(f"{'=' * 60}")
    lines.append(f"\nProject: {project_path}")
    lines.append(f"Score:   {score}/100\n")

    status_icons = {"pass": "[PASS]", "warn": "[WARN]", "fail": "[FAIL]"}
    severity_order = {"critical": 0, "recommended": 1, "nice-to-have": 2}
    sorted_results = sorted(results, key=lambda r: (severity_order.get(r["severity"], 9), r["status"] != "fail"))

    for r in sorted_results:
        icon = status_icons.get(r["status"], "[????]")
        lines.append(f"  {icon}  {r['name']} ({r['severity']})")
        if r["found"]:
            lines.append(f"         Found: {r['found']}")
        if r["recommendation"]:
            lines.append(f"         -> {r['recommendation']}")
        lines.append("")

    pass_count = sum(1 for r in results if r["status"] == "pass")
    warn_count = sum(1 for r in results if r["status"] == "warn")
    fail_count = sum(1 for r in results if r["status"] == "fail")
    lines.append(f"--- Summary ---")
    lines.append(f"  Passed: {pass_count}  |  Warnings: {warn_count}  |  Failed: {fail_count}")
    lines.append(f"  Health Score: {score}/100")

    if score >= 80:
        lines.append("\n  Verdict: Setup is well-configured for onboarding.")
    elif score >= 50:
        lines.append("\n  Verdict: Setup needs improvement. Address failed checks first.")
    else:
        lines.append("\n  Verdict: Setup has significant gaps. New developers will struggle.")

    lines.append(f"\n{'=' * 60}")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Validate a project's development setup completeness.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "Examples:\n"
            "  %(prog)s /path/to/project\n"
            "  %(prog)s . --json\n"
            "  %(prog)s ~/my-app --json | jq '.results[] | select(.status==\"fail\")'\n"
        ),
    )
    parser.add_argument(
        "directory",
        nargs="?",
        default=".",
        help="Project directory to validate (default: current directory)",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        dest="json_output",
        help="Output results as JSON instead of human-readable format",
    )
    args = parser.parse_args()

    target = Path(args.directory).resolve()
    if not target.is_dir():
        print(f"Error: '{args.directory}' is not a valid directory.", file=sys.stderr)
        sys.exit(2)

    results = run_checks(str(target))
    score = compute_score(results)

    if args.json_output:
        output = {
            "project_name": target.name,
            "project_path": str(target),
            "score": score,
            "total_checks": len(results),
            "passed": sum(1 for r in results if r["status"] == "pass"),
            "warnings": sum(1 for r in results if r["status"] == "warn"),
            "failed": sum(1 for r in results if r["status"] == "fail"),
            "results": results,
        }
        print(json.dumps(output, indent=2))
    else:
        print(format_human(results, score, str(target)))


if __name__ == "__main__":
    main()
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall