home / skills / joncrangle / .dotfiles / code-style

code-style skill

safe

This skill enforces code style and discovery practices in TypeScript projects, guiding pattern search, type discipline, and test-driven verification.

npx playbooks add skill joncrangle/.dotfiles --skill code-style

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

Files (1)

SKILL.md

961 B

---
name: code-style
description: Discovery, typing, and execution standards.
---

<skill_doc>
# Code Style & Discovery

## 🔍 Discovery Phase (Mandatory)
Before writing any code:
1.  **Search**: Search for existing patterns using the `search_files` tool.
2.  **Read**: Read similar files to match style.
3.  **Types**: Find the TypeScript interfaces/types defined in the project.

## 🛡️ Coding Standards
- **Strict TypeScript**: No `any`. Define interfaces.
- **Error Handling**: Use `try/catch` with specific error logging. No silent failures.
- **Comments**: Comment *why*, not *what*.
- **Imports**: Use absolute imports if project configured (check `tsconfig`).

## 🧪 Verification
- **Test-Driven**: Create/Update tests for every logic change.
- **Lint**: Run linting before reporting success.

## 🛠️ Tooling
- Use `bun tools/hotspots.ts` to find frequently changed files.
- Use `list_files` to explore the directory structure.
</skill_doc>

Overview

This skill defines discovery, typing, and execution standards for TypeScript-based dotfiles and install scripts. It enforces strict typing, explicit error handling, and a mandatory discovery phase to match existing project patterns. The goal is predictable, well-typed code that integrates with the repository's tooling and tests.

How this skill works

Before any change, the skill requires searching and reading existing files to discover established patterns and types. It enforces strict TypeScript without any usage of 'any', requires interface definitions, and mandates explicit try/catch error handling with targeted logging. Developers run project-specific tools to find hotspots, lint, and add or update tests for every logic change.

When to use it

When adding or modifying TypeScript logic in dotfiles, installers, or Neovim config files.
When introducing new shared types or interfaces that other modules will consume.
When fixing bugs in frequently changed files identified by hotspot analysis.
Before submitting a change that could affect configuration loading or install scripts.
When integrating new tools or plugins that require consistent import and typing rules.

Best practices

Run search_files and read similar files first to match naming, imports, and patterns.
Avoid any usage of 'any'; declare precise interfaces and type guards where needed.
Use try/catch around operations that can fail and log errors with context; do not swallow exceptions.
Prefer absolute imports if tsconfig supports them; mirror existing import style found in the repo.
Add or update tests for any logic change and run linting before marking work complete.

Example use cases

Adding a new installer script that reads system state and updates dotfiles—discover existing patterns, define types, add tests.
Refactoring a frequently edited Neovim configuration file identified by hotpots—use hotspot tool, follow established imports and types.
Defining shared interfaces for plugin configuration so multiple modules can safely consume typed data.
Fixing a runtime error in a tool by adding explicit try/catch and richer error logs, plus a regression test.

FAQ

What tools should I run to find frequently changed files?

Run the provided hotspot script (bun tools/hotspots.ts) to list files with high churn, and use list_files to inspect the tree.

Is using 'any' ever acceptable?

No. The standard disallows 'any'. Use concrete interfaces, union types, or type guards to model unknown shapes.