playbooks

home / skills / ratacat / claude-skills / project-setup

project-setup skill

/skills/project-setup

This skill helps teams bootstrap new projects with strict typing, linting, formatting, and testing across Python, TypeScript, and other languages.

npx playbooks add skill ratacat/claude-skills --skill project-setup

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
1.7 KB
---
name: project-setup
description: Bootstrap new projects with strong typing, linting, formatting, and testing. Supports Python, TypeScript, and other languages with research fallback.
---

# Project Setup

## Core Principles

- **Strong Typing**: Strict mode enabled; types catch bugs at compile time
- **Strong Linting**: Strict rules by default; easier to disable than add later
- **Auto Formatting**: Automated and consistent; no manual formatting
- **Checks at Every Stage**: Pre-commit hooks + CI; catch issues early
- **Co-located Tests**: `foo.ts` → `foo.test.ts`; obvious what's tested
- **Behavior-Focused**: Test what code does, not how; mock only external boundaries

## Workflow

1. Check `reference/` for language guide (Python, TypeScript)
2. If no guide: WebSearch "[language] project setup best practices"
3. Follow setup: typing → linting → formatting → testing → pre-commit → CI
4. For existing projects: migrate incrementally in same order

## Reference Files

- `reference/python.md` - uv, ruff, basedpyright, pytest
- `reference/typescript.md` - pnpm, ESLint, Prettier, Vitest
- `reference/common-patterns.md` - Testing philosophy, CI patterns, security

## Tool Selection

Prefer tools that are: ecosystem standard, actively maintained, strict by default, fast, well-integrated (editor + CI + pre-commit).

## Quality Checklist

- [ ] Typing: Strictest mode, no `any` without justification
- [ ] Linting: Strict rules, warnings as errors
- [ ] Formatting: Auto-format on save + pre-commit
- [ ] Testing: Co-located tests, coverage >80%
- [ ] Pre-commit: Format, lint, type-check
- [ ] CI: Same checks + coverage reporting
- [ ] README: Setup instructions
- [ ] All checks pass on initial commit

Overview

This skill bootstraps new projects with strong typing, strict linting, consistent formatting, and reliable testing. It supports Python and TypeScript out of the box and falls back to researched recommendations for other languages. The goal is to create a development baseline that prevents common errors and scales with team practices. The setup enforces checks locally (pre-commit) and in CI so issues are caught early.

How this skill works

The skill inspects the target language and applies a prescribed pipeline: enable strict typing, add a linter with strict rules, configure an auto-formatter, scaffold co-located tests, and install pre-commit hooks plus CI workflows. For Python and TypeScript it follows curated reference guides; for other languages it runs a research fallback to choose ecosystem-standard tools. Existing projects are migrated incrementally in the same order to minimize disruption.

When to use it

  • Starting a new Python or TypeScript project and you want a production-ready developer experience.
  • Onboarding a team that needs consistent style, types, and automated checks.
  • Modernizing an existing codebase by introducing typing, linting, and pre-commit guards incrementally.
  • Creating a template or mono-repo modules that must share uniform quality standards.

Best practices

  • Apply changes in order: typing → linting → formatting → testing → pre-commit → CI.
  • Prefer ecosystem-standard, actively maintained, and strict-by-default tools.
  • Keep tests co-located with code and focus tests on behavior, not internals.
  • Make lint rules strict by default; relax only with documented exceptions.
  • Enforce formatting automatically via editor integration and pre-commit hooks.

Example use cases

  • Scaffold a TypeScript library with pnpm, strict ESLint, Prettier, Vitest tests, and CI checks.
  • Create a Python service with strict type checking, ruff linting, pytest tests, and pre-commit hooks.
  • Incrementally add typing and linting to a legacy codebase to reduce regressions over time.
  • Generate a starter repo template for new team projects including README and CI config.

FAQ

What if my language is not Python or TypeScript?

The skill performs a research fallback to identify recommended tools and configuration patterns for the language, prioritizing ecosystem standards and strict defaults.

Can I apply the setup incrementally to an existing project?

Yes. Follow the prescribed order (typing → linting → formatting → testing → pre-commit → CI) and migrate gradually to keep the repo stable.