| name | coding-standard-writer |
| description | Write a coding standards document for a project using the coding styles inferred from provided file(s) or folder(s). |
| license | MIT |
Skill Name: coding-standard-writer
Dynamically generate a coding standards document based on the existing syntax, formatting, and conventions found in provided file(s) or folder(s).
Core Process
- Ingest Targets: Read the contents of the target
<file-path> or <folder-path>.
- Analyze Syntax: Parse indentation, variable naming (
camelCase, snake_case), commenting styles, block nesting, and string quotation formats.
- Identify Majority Rules: Tally occurrences of different styles; establish the majority as the standard.
- Handle Inconsistencies: Report formatting inconsistencies and optionally fix them only when explicitly requested by the user; always verify changes using project-specific linting tools.
- Format Document: Use a "minimal" or "verbose" template structure to compose the guidelines.
- Output Generation: Write the result to a new file (e.g.,
CONTRIBUTING.md, STYLE.md) or inject it into the README.md.
Core Principles
- Empirical Inference: Standards must be derived strictly from existing code, not assumed.
- Template Adaptation: Use "verbose" for comprehensive style guides and "minimal" for concise rule summaries.
- Contextual Insertion: When appending to
README.md, locate the most logical insertion point (e.g., at the end or under a "Contributing" heading).
WHEN TO USE
- When tasked with creating coding guidelines from existing code.
- To detect and fix formatting inconsistencies across multiple files.
- When generating
CONTRIBUTING.md, STYLE.md, or STYLEGUIDE.md.
WHEN NOT TO USE
- When the project already has an explicit, well-documented
CONTRIBUTING.md or .editorconfig that should not be overwritten.
- To enforce rules that contradict the organization's global engineering standards.
- When generating general project documentation unrelated to coding style (use
docs-writer).
Common Pitfalls
- Ignoring Edge Cases: Establishing a "majority rule" based on a single small file, leading to a standard that conflicts with the rest of the massive codebase.
- Overwriting Existing Rules: Blindly generating a new
STYLE.md that overrides a carefully curated, existing style guide without asking the user.
- Opinionated Hallucinations: Injecting Python conventions (like PEP 8) into a JavaScript project just because the LLM prefers them, rather than strictly empirical inference.
Quick Start
- Identify the reference file or folder.
- Read the source contents to infer formatting patterns.
- Generate the coding standard using a minimal or verbose markdown template.
- Write to the designated output location.
Diagnostics and Troubleshooting
- If file styles are extremely chaotic, prompt the user to choose a baseline reference file before generating the standard.
Best Practices
- Fetch external style guides as supplemental reference only when explicitly requested, and do not let them override the codebase's existing majority conventions.
- If requested, generate a companion test file to enforce the newly defined standards.
What to Avoid
- Overwriting existing documented standards without confirmation.
- Injecting subjective preferences that contradict the codebase's existing majority style.
Coding Standards Templates
"m", "minimal"
```markdown
## 1. Introduction
* **Purpose:** Briefly explain why the coding standards are being established (e.g., to improve code quality, maintainability, and team collaboration).
* **Scope:** Define which languages, projects, or modules this specification applies to.
## 2. Naming Conventions
* **Variables:** `camelCase`
* **Functions/Methods:** `PascalCase` or `camelCase`.
* **Classes/Structs:** `PascalCase`.
* **Constants:** `UPPER_SNAKE_CASE`.
## 3. Formatting and Style
* **Indentation:** Use 4 spaces per indent (or tabs).
* **Line Length:** Limit lines to a maximum of 80 or 120 characters.
* **Braces:** Use the "K&R" style (opening brace on the same line) or the "Allman" style (opening brace on a new line).
* **Blank Lines:** Specify how many blank lines to use for separating logical blocks of code.
## 4. Commenting
* **Docstrings/Function Comments:** Describe the function's purpose, parameters, and return values.
* **Inline Comments:** Explain complex or non-obvious logic.
* **File Headers:** Specify what information should be included in a file header, such as author, date, and file description.
## 5. Error Handling
* **General:** How to handle and log errors.
* **Specifics:** Which exception types to use, and what information to include in error messages.
## 6. Best Practices and Anti-Patterns
* **General:** List common anti-patterns to avoid (e.g., global variables, magic numbers).
* **Language-specific:** Specific recommendations based on the project's programming language.
## 7. Examples
* Provide a small code example demonstrating the correct application of the rules.
* Provide a small code example of an incorrect implementation and how to fix it.
## 8. Contribution and Enforcement
* Explain how the standards are to be enforced (e.g., via code reviews).
* Provide a guide for contributing to the standards document itself.
```
"v", verbose"
```markdown
# Style Guide
This document defines the style and conventions used in this project.
All contributions should follow these rules unless otherwise noted.
## 1. General Code Style
- Favor clarity over brevity.
- Keep functions and methods small and focused.
- Avoid repeating logic; prefer shared helpers/utilities.
- Remove unused variables, imports, code paths, and files.
## 2. Naming Conventions
Use descriptive names. Avoid abbreviations unless well-known.
| Item | Convention | Example |
|-----------------|----------------------|--------------------|
| Variables | `lower_snake_case` | `buffer_size` |
| Functions | `lower_snake_case()` | `read_file()` |
| Constants | `UPPER_SNAKE_CASE` | `MAX_RETRIES` |
| Types/Structs | `PascalCase` | `FileHeader` |
| File Names | `lower_snake_case` | `file_reader.c` |
## 3. Formatting Rules
- Indentation: **4 spaces**
- Line length: **max 100 characters**
- Encoding: **UTF-8**, no BOM
- End files with a newline
### Braces (example in C, adjust for your language)
```c
if (condition) {
do_something();
} else {
do_something_else();
}
```
### Spacing
- One space after keywords: `if (x)`, not `if(x)`
- One blank line between top-level functions
## 4. Comments & Documentation
- Explain *why*, not *what*, unless intent is unclear.
- Keep comments up-to-date as code changes.
- Public functions should include a short description of purpose and parameters.
Recommended tags:
```text
TODO: follow-up work
FIXME: known incorrect behavior
NOTE: non-obvious design decision
```
## 5. Error Handling
- Handle error conditions explicitly.
- Avoid silent failures; either return errors or log them appropriately.
- Clean up resources (files, memory, handles) before returning on failure.
## 6. Commit & Review Practices
### Commits
- One logical change per commit.
- Write clear commit messages:
```text
Short summary (max ~50 chars)
Optional longer explanation of context and rationale.
```
### Reviews
- Keep pull requests reasonably small.
- Be respectful and constructive in review discussions.
- Address requested changes or explain if you disagree.
## 7. Tests
- Write tests for new functionality.
- Tests should be deterministic (no randomness without seeding).
- Prefer readable test cases over complex test abstraction.
## 8. Changes to This Guide
Style evolves.
Propose improvements by opening an issue or sending a patch updating this document.
```
References
Related Skills
- docs-writer: You MUST load this skill when writing or updating READMEs and Architectural Decision Records.
