From d6f3876055c54f21d0f5aab54208ddef1fff7931 Mon Sep 17 00:00:00 2001 From: abozezo-dev Date: Fri, 17 Jul 2026 23:05:00 +0300 Subject: [PATCH] Document modular code quality skills --- README.md | 235 +++++++++++++++++++++--------------------------------- 1 file changed, 89 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 72c2041..7a16ac1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# ๐Ÿ›ก๏ธ Code Verification & Cleaning Skill +# ๐Ÿ›ก๏ธ Code Quality Skills -> **A reusable AI skill for code verification, cleanup, runtime auditing, and security-focused review, organized under `skills/code-verify-and-clean-skill/` for skills.sh discovery.** +> **A modular collection of AI sub-skills for verifying, cleaning, auditing, and securing code.** Install only the focused capability your task needs, or install the optional bundle for the complete workflow. ![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) @@ -10,211 +10,154 @@ ## ๐Ÿ“‹ Table of Contents - [Purpose](#-purpose) -- [Features](#-features) -- [Getting Started](#-getting-started) -- [Skills.sh Listing](#-skillssh-listing) +- [Sub-skills](#-sub-skills) +- [Installation](#-installation) - [Repository Structure](#-repository-structure) - [Core Principles](#-core-principles) -- [Verification Pipeline](#-verification-pipeline) -- [Reporting Workflow](#-reporting-workflow) +- [Workflow](#-workflow) +- [Resources](#-resources) - [License](#-license) --- ## ๐ŸŽฏ Purpose -This skill empowers AI agents to: +Code Quality Skills separates code-quality work into small, composable sub-skills. Choose a targeted skill when you need one type of review, or use the all-in-one bundle when a change needs the entire verification-and-cleaning workflow. -- โœ… **Verify code correctness** - Ensure logic works as intended -- ๐Ÿงน **Remove dead code & duplication** - Keep codebases lean and maintainable -- ๐Ÿ” **Audit runtime behavior** - Browser-based verification with DevTools -- ๐Ÿ”’ **Check security issues** - Identify vulnerabilities and exposure risks -- ๐Ÿ—๏ธ **Enforce clean architecture** - Maintain modular, single-responsibility design -- ๐Ÿงช **Validate builds, tests & linting** - Automated quality gates +| Need | Owning sub-skill | +|------|------------------| +| Remove dead code, duplication, and unnecessary complexity | [Clean Code](skills/clean-code/SKILL.md) | +| Run builds, tests, linters, and formatting checks | [Code Verification](skills/code-verification/SKILL.md) | +| Inspect a running frontend with browser DevTools | [Runtime Auditing](skills/runtime-auditing/SKILL.md) | +| Review injection risks, exposed tokens, and client-side security issues | [Security Review](skills/security-review/SKILL.md) | +| Perform the complete scan, cleanup, verification, and reporting workflow | [Code Verification & Cleaning bundle](skills/code-verify-and-clean-skill/SKILL.md) | --- -## โœจ Features +## ๐Ÿงฉ Sub-skills -| Feature | Description | -|---------|-------------| -| **Static Analysis** | Automated linting, formatting, and compilation checks | -| **Runtime Auditing** | Live browser testing with console & network inspection | -| **Code Sanitization** | Remove unused imports, variables, and technical debt | -| **Security Scanning** | Detect injection points, token exposure, and client-side risks | -| **Architecture Review** | Enforce modularity and reusability patterns | +- **[Clean Code](skills/clean-code/SKILL.md)** โ€” owns dead-code removal, duplicate-code reduction, simplification, and modularity improvements. +- **[Code Verification](skills/code-verification/SKILL.md)** โ€” owns compilation, tests, linting, formatting, and other automated quality gates. +- **[Runtime Auditing](skills/runtime-auditing/SKILL.md)** โ€” owns browser-based validation, console inspection, network checks, and UI runtime diagnostics. +- **[Security Review](skills/security-review/SKILL.md)** โ€” owns security-focused review for injection points, credential exposure, and client-side risks. +- **[Code Verification & Cleaning](skills/code-verify-and-clean-skill/SKILL.md)** โ€” the optional bundle that combines every sub-skill and coordinates the end-to-end reporting workflow. --- -## ๐Ÿš€ Getting Started +## ๐Ÿš€ Installation -### Installation +Install the smallest sub-skill that covers the task. For example, install **Clean Code** by itself: ```bash -npx skills add abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill +npx skills add abozezo-dev/Code-Quality-Skill/clean-code ``` -### Quick Start - -1. Add the skill to your AI agent configuration -2. Run verification on your target codebase -3. Review the generated report templates in `skills/code-verify-and-clean-skill/assets/` - ---- - -## ๐Ÿ”— Skills.sh Listing - -View this skill on skills.sh: - -- [Code Verification & Cleaning Skill](https://skills.sh/abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill) - -The repository page is customized with [`skills.sh.json`](skills.sh.json), and the skill files live under [`skills/code-verify-and-clean-skill/`](skills/code-verify-and-clean-skill/) for a clean skills.sh-compatible layout. +Install any other individual sub-skill as needed: ---- +```bash +# Automated builds, tests, linting, and formatting +npx skills add abozezo-dev/Code-Quality-Skill/code-verification -## ๐Ÿ”— Skills.sh Listing +# Browser and DevTools runtime checks +npx skills add abozezo-dev/Code-Quality-Skill/runtime-auditing -View this skill on skills.sh: +# Security-focused code review +npx skills add abozezo-dev/Code-Quality-Skill/security-review +``` -- [Code Verification & Cleaning Skill](https://skills.sh/abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill) +Or install the optional all-in-one bundle for the complete code-quality workflow: -The repository page is customized with [`skills.sh.json`](skills.sh.json), which groups this skill under **Code Quality** for easier discovery. +```bash +npx skills add abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill +``` --- ## ๐Ÿ“ Repository Structure -``` +```text Code-Quality-Skill/ โ”œโ”€โ”€ skills/ +โ”‚ โ”œโ”€โ”€ clean-code/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md # Cleanup, deduplication, and modularity +โ”‚ โ”œโ”€โ”€ code-verification/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md # Builds, tests, linting, and formatting +โ”‚ โ”œโ”€โ”€ runtime-auditing/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md # Browser and DevTools validation +โ”‚ โ”œโ”€โ”€ security-review/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md # Security-focused review โ”‚ โ””โ”€โ”€ code-verify-and-clean-skill/ -โ”‚ โ”œโ”€โ”€ assets/ -โ”‚ โ”‚ โ”œโ”€โ”€ report-template.md # Post-modification report template -โ”‚ โ”‚ โ”œโ”€โ”€ review-template.md # Template for code reviews -โ”‚ โ”‚ โ”œโ”€โ”€ scan-template.md # Pre-modification scan template -โ”‚ โ”‚ โ””โ”€โ”€ verification-checklist.md # Comprehensive checklist -โ”‚ โ”œโ”€โ”€ reference/ -โ”‚ โ”‚ โ”œโ”€โ”€ code-cleaning-universal.md # Cleaning standards & patterns -โ”‚ โ”‚ โ”œโ”€โ”€ devtools-verification.md # Browser audit workflows -โ”‚ โ”‚ โ”œโ”€โ”€ reporting-workflow.md # SCAN.md and REPORT.md workflow -โ”‚ โ”‚ โ””โ”€โ”€ security-verification.md # Security check guidelines -โ”‚ โ”œโ”€โ”€ scripts/ -โ”‚ โ”‚ โ””โ”€โ”€ verify-pipeline.sh # Automated verification script -โ”‚ โ””โ”€โ”€ SKILL.md # Full skill specification -โ”œโ”€โ”€ .github/ -โ”‚ โ””โ”€โ”€ workflows/ -โ”‚ โ””โ”€โ”€ ci.yml # CI/CD pipeline -โ”œโ”€โ”€ .gitignore # Local and generated file exclusions -โ”œโ”€โ”€ skills.sh.json # skills.sh repository page customization -โ”œโ”€โ”€ LICENSE # MIT License -โ””โ”€โ”€ README.md # You are here! +โ”‚ โ”œโ”€โ”€ assets/ # Bundle report and review templates +โ”‚ โ”œโ”€โ”€ reference/ # Bundle workflow guides +โ”‚ โ”œโ”€โ”€ scripts/ # Bundle automation +โ”‚ โ””โ”€โ”€ SKILL.md # All-in-one workflow +โ”œโ”€โ”€ .github/workflows/ci.yml # CI checks +โ”œโ”€โ”€ skills.sh.json # skills.sh repository configuration +โ”œโ”€โ”€ LICENSE # MIT license +โ””โ”€โ”€ README.md # You are here ``` +Each directory above links to its own `SKILL.md`: [Clean Code](skills/clean-code/SKILL.md), [Code Verification](skills/code-verification/SKILL.md), [Runtime Auditing](skills/runtime-auditing/SKILL.md), [Security Review](skills/security-review/SKILL.md), and the [all-in-one bundle](skills/code-verify-and-clean-skill/SKILL.md). + --- ## ๐Ÿง  Core Principles -### 1. Trust But Verify -Never assume code works just because it looks correct. Always: -- **Execute** - Boot servers, compile modules, run interpreters -- **Observe** - Use browser tools to catch visual/architectural breaks -- **Isolate** - Capture stack traces and system warnings - -### 2. Radical Code Cleaning -Keep code lean, modern, and maintainable: -- ๐Ÿ—‘๏ธ Prune unused components, imports, and variables -- ๐Ÿ”„ Refactor complex logic into explicit early returns -- โ™ป๏ธ Reuse global utilities instead of reinventing logic +### 1. Trust But Verify โ€” Code Verification and Runtime Auditing -### 3. Severity Tiers +Do not treat code that looks correct as code that is correct. **Code Verification** executes builds, tests, and static checks; **Runtime Auditing** validates the running application, including browser console output and network activity. -| Marker | Meaning | Action | -|--------|---------|--------| -| ๐Ÿ”ด `[breaking-error]` | Code crashes or breaks workflows | **Blocks merge** | -| ๐ŸŸก `[code-smell]` | Works but introduces technical debt | Schedule refactor | -| ๐ŸŸข `[refactored]` | Auto-cleaned by agent | Already resolved | +### 2. Keep Code Lean โ€” Clean Code ---- +**Clean Code** keeps codebases maintainable by pruning unused components, imports, and variables; reducing duplication; and simplifying complex logic into explicit, reusable modules. -## โš™๏ธ Verification Pipeline +### 3. Treat Security Findings as First-Class โ€” Security Review -### Phase 1: Static Analysis -```bash -# Run native linters and formatters -npm run lint -npm run format +**Security Review** identifies injection opportunities, exposed tokens, and client-side exposure risks before they become production issues. -# Execute pre-checks -./skills/code-verify-and-clean-skill/scripts/verify-pipeline.sh -``` +### 4. Use Clear Severity Tiers โ€” All-in-One Bundle -### Phase 2: Structural Review -- Check modular breakdown (single responsibility) -- Audit for code duplication across modules -- Validate reusability patterns +The **Code Verification & Cleaning** bundle uses consistent markers when coordinating multiple sub-skills: -### Phase 3: Live Browser Audits *(Frontend)* -1. Start local preview server -2. Open browser DevTools -3. Inspect console for errors/warnings -4. Trace network requests (no 400/500 errors) +| Marker | Meaning | Action | +|--------|---------|--------| +| ๐Ÿ”ด `[breaking-error]` | Code crashes, fails checks, or breaks a workflow | **Blocks merge** | +| ๐ŸŸก `[code-smell]` | Code works but adds debt or avoidable complexity | Schedule remediation | +| ๐ŸŸข `[refactored]` | A cleanup was applied and verified | Already resolved | --- -## ๐Ÿ“ Reporting Workflow - -The verification and cleaning workflow produces two application reports: +## โš™๏ธ Workflow -| Report | When Generated | Purpose | -|--------|----------------|---------| -| `SCAN.md` | Before modifications | Read-only scan report covering pre-modification verification, cleaning, and security findings. No application files may be modified during this stage. | -| `REPORT.md` | After modifications | Final application report documenting what changed, what was verified, remaining risks, and the final security/cleaning status. | - -Use `SCAN.md` to establish the baseline state of the application before edits, then use `REPORT.md` to summarize the completed remediation and post-change validation. See `skills/code-verify-and-clean-skill/reference/reporting-workflow.md` for the full workflow and use `skills/code-verify-and-clean-skill/assets/scan-template.md` and `skills/code-verify-and-clean-skill/assets/report-template.md` as starting points for consistent reports. +1. **Clean Code** removes obvious dead code, duplication, and structural bloat. +2. **Code Verification** runs the repository's native build, test, lint, and formatting commands. +3. **Runtime Auditing** validates changed frontend behavior in a live browser when applicable. +4. **Security Review** checks the changed surface for security risks. +5. The **all-in-one bundle** coordinates the full workflow and records the pre-change `SCAN.md` and post-change `REPORT.md` when comprehensive reporting is required. --- -## ๐Ÿ“š Additional Resources +## ๐Ÿ“š Resources + +The optional bundle supplies shared workflow resources; use the indicated sub-skill for the capability each resource supports. -- [DevTools Verification Guide](skills/code-verify-and-clean-skill/reference/devtools-verification.md) -- [Code Cleaning Standards](skills/code-verify-and-clean-skill/reference/code-cleaning-universal.md) -- [Security Verification](skills/code-verify-and-clean-skill/reference/security-verification.md) -- [Reporting Workflow Guide](skills/code-verify-and-clean-skill/reference/reporting-workflow.md) -- [SCAN.md Template](skills/code-verify-and-clean-skill/assets/scan-template.md) -- [REPORT.md Template](skills/code-verify-and-clean-skill/assets/report-template.md) -- [Review Template](skills/code-verify-and-clean-skill/assets/review-template.md) -- [Verification Checklist](skills/code-verify-and-clean-skill/assets/verification-checklist.md) +| Resource | Capability owner | Description | +|----------|------------------|-------------| +| [Code Cleaning Standards](skills/code-verify-and-clean-skill/reference/code-cleaning-universal.md) | [Clean Code](skills/clean-code/SKILL.md) | Cleaning standards and patterns for reducing technical debt. | +| [DevTools Verification Guide](skills/code-verify-and-clean-skill/reference/devtools-verification.md) | [Runtime Auditing](skills/runtime-auditing/SKILL.md) | Browser, layout, console, and network-audit guidance. | +| [Security Verification Guide](skills/code-verify-and-clean-skill/reference/security-verification.md) | [Security Review](skills/security-review/SKILL.md) | Security checks for injection and client-side exposure. | +| [Reporting Workflow Guide](skills/code-verify-and-clean-skill/reference/reporting-workflow.md) | [Code Verification & Cleaning bundle](skills/code-verify-and-clean-skill/SKILL.md) | `SCAN.md` and `REPORT.md` workflow and evidence standards. | +| [Verification Checklist](skills/code-verify-and-clean-skill/assets/verification-checklist.md) | [Code Verification](skills/code-verification/SKILL.md) | Checklist for automated verification gates. | +| [Review Template](skills/code-verify-and-clean-skill/assets/review-template.md) | [Security Review](skills/security-review/SKILL.md) | Consistent review findings and remediation notes. | +| [SCAN.md Template](skills/code-verify-and-clean-skill/assets/scan-template.md) | [Code Verification & Cleaning bundle](skills/code-verify-and-clean-skill/SKILL.md) | Baseline report template before modifications. | +| [REPORT.md Template](skills/code-verify-and-clean-skill/assets/report-template.md) | [Code Verification & Cleaning bundle](skills/code-verify-and-clean-skill/SKILL.md) | Final report template after remediation and validation. | --- ## ๐Ÿ“„ License -This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. - -``` -MIT License - -Copyright (c) 2026 abozezo-dev - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` +This project is licensed under the [MIT License](LICENSE). --- -

Made with โค๏ธ by abozezo-dev

\ No newline at end of file +

Made with โค๏ธ by abozezo-dev