platformio-mcp: Skill for Claude Code

House Style Documentation

Enforce a specific set of documentation and style standards for TypeScript files in this repository.

High-Level Standards

1. Module Headers: Every file must have a brief JSDoc header describing its purpose.
2. Function/Method Documentation: All exported functions, methods, and classes must have JSDoc-style comments.
3. Variable/Constant Documentation: Important configuration or global objects should be documented with JSDoc or clear block comments.
4. Error Handling: Utilize Custom Error classes (e.g., PlatformIOError) extending from the base error structure, instead of throwing raw Error objects where appropriate.
5. Naming Conventions: File names MUST strictly use kebab-case. Types, Interfaces, Classes, and Zod schemas MUST be PascalCase. Variables and functions MUST be camelCase.
6. Formatting/Linting: The codebase utilizes ESLint, Prettier, and stricter TypeScript configurations (strict: true, noUnusedLocals, etc.). Ensure code is clean and handles types properly. Zod is used for parsing JSON data.
7. Implementation Plans: All implementation plans must be reviewed for house style (Goal, Review Required, Proposed Changes, Verification).

1. Module Headers

Every TypeScript file MUST start with a brief JSDoc header describing the module's overall responsibility. Do not include large proprietary or C++ style copyright blocks, but DO include a one-line summary of the functions and constants that the module provides.

Format:

/**
 * [Brief descriptive title of the file/module]
 * [Optional detailed multi-line description of the module's responsibility]
 *
 * Provides:
 * - [FunctionName]: [One-line summary]
 * - [CONSTANT_NAME]: [One-line summary]
 */

[!IMPORTANT] While TypeScript handles exports implicitly, providing this one-line summary list in the header allows developers to quickly see the services offered by the module without reading the whole file.