diff --git a/README.md b/README.md index 1ebaaac..aea3afc 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,142 @@ # ๐Ÿ›ก๏ธ Code Quality Skills -A collection of independently installable skills for code cleanup, verification, browser-runtime auditing, and security review. The original `code-verify-and-clean-skill` remains available as an optional orchestration skill that composes the focused skills and manages the two-report workflow. +> **Reusable AI skills for plan-driven implementation, React/Next.js implementation guidance, and code verification, cleanup, runtime auditing, and security-focused review.** -## Install a focused skill +![License](https://img.shields.io/badge/license-MIT-blue.svg) +![Status](https://img.shields.io/badge/status-active-success.svg) + +--- + +## ๐Ÿ“‹ Table of Contents + +- [Purpose](#-purpose) +- [Features](#-features) +- [Getting Started](#-getting-started) +- [Implementation Workflow](#-implementation-workflow) +- [Skills.sh Listing](#-skillssh-listing) +- [Repository Structure](#-repository-structure) +- [Core Principles](#-core-principles) +- [Verification Pipeline](#-verification-pipeline) +- [Reporting Workflow](#-reporting-workflow) +- [License](#-license) + +--- + +## ๐ŸŽฏ Purpose + +These skills empower AI agents to: + +- โœ… **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 +- ๐Ÿงญ **Execute approved plans incrementally** - Implement small, verified changes that follow repository conventions + +--- + +## โœจ Features + +| 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 | + +--- + +## ๐Ÿš€ Getting Started + +### Installation ```bash -# Choose the capability that matches the task. -npx skills add abozezo-dev/Code-Quality-Skill/clean-code -npx skills add abozezo-dev/Code-Quality-Skill/code-verification -npx skills add abozezo-dev/Code-Quality-Skill/runtime-devtools-audit -npx skills add abozezo-dev/Code-Quality-Skill/security-review +npx skills add abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill +npx skills add abozezo-dev/Code-Quality-Skill/execution +npx skills add abozezo-dev/Code-Quality-Skill/react-best-practices ``` +### Quick Start + +1. Install `execution` after an implementation plan has been approved. +2. Ask the agent to implement the plan; it works in small verifiable increments and hands off to `code-verify-and-clean-skill`. +3. For React or Next.js changes, install `react-best-practices` too. `execution` invokes it only for React/Next.js work. +4. Run verification on the target codebase and review the generated report templates in `skills/code-verify-and-clean-skill/assets/`. + +## ๐Ÿงญ Implementation Workflow + +The [`execution`](skills/execution/SKILL.md) skill consumes an **approved** plan, discovers local conventions, +implements one independently verifiable increment at a time, and sends the completed change to +[`code-verify-and-clean-skill`](skills/code-verify-and-clean-skill/SKILL.md) for verification and review. + +For React or Next.js implementation tasks, it has an explicit local dependency on +[`react-best-practices`](skills/react-best-practices/SKILL.md). Install both skills for those projects; no React +guidance is applied to non-React work. + +--- + +## ๐Ÿ”— 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) +- [Implementation Execution](https://skills.sh/abozezo-dev/Code-Quality-Skill/execution) +- [React and Next.js Best Practices](https://skills.sh/abozezo-dev/Code-Quality-Skill/react-best-practices) + +The repository page is customized with [`skills.sh.json`](skills.sh.json), and all skill files live under [`skills/`](skills/) for a clean skills.sh-compatible layout. + +--- + +## ๐Ÿ“ Repository Structure + +``` +Code-Quality-Skill/ +โ”œโ”€โ”€ skills/ +โ”‚ โ””โ”€โ”€ 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 +โ”‚ โ”œโ”€โ”€ execution/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md # Approved-plan implementation workflow +โ”‚ โ””โ”€โ”€ react-best-practices/ +โ”‚ โ””โ”€โ”€ SKILL.md # React and Next.js implementation guidance +โ”œโ”€โ”€ .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! +``` + +--- + +## ๐Ÿง  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 + Install the orchestrator only when a coordinated scan, remediation, verification, and final report are needed: ```bash @@ -58,4 +183,4 @@ When using the orchestration skill, create `SCAN.md` after a read-only assessmen ## License -MIT. See [LICENSE](LICENSE). +

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

diff --git a/skills.sh.json b/skills.sh.json index 9fba13a..d74a7b8 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -1,17 +1,15 @@ { - "$schema": "https://skills.sh/schemas/skills.sh.schema.json", - "notGrouped": "bottom", - "groupings": [ - { - "title": "Code Quality", - "description": "Focused code cleanup, verification, runtime auditing, and security review skills.", - "skills": [ - "clean-code", - "code-verification", - "runtime-devtools-audit", - "security-review", - "code-verify-and-clean-skill" - ] - } - ] + "$schema": "https://skills.sh/schemas/skills.sh.schema.json", + "notGrouped": "bottom", + "groupings": [ + { + "title": "Code Quality", + "description": "Plan-driven implementation, React/Next.js guidance, verification, cleanup, runtime auditing, and security review skills.", + "skills": [ + "code-verify-and-clean-skill", + "execution", + "react-best-practices" + ] + } + ] } diff --git a/skills/execution/SKILL.md b/skills/execution/SKILL.md new file mode 100644 index 0000000..49abdac --- /dev/null +++ b/skills/execution/SKILL.md @@ -0,0 +1,82 @@ +--- +name: execution +description: | + Implements an approved software plan in small, verifiable increments while preserving the target + repository's conventions. Hands completed work to verification and review. + Use when: an implementation plan has been approved and code, configuration, tests, or documentation + must be changed. +allowed-tools: + - Read + - Write + - Grep + - Glob + - Bash +--- + +# Implementation Execution + +## Prerequisite + +Start only after the implementation plan is approved. Treat the approved plan as the source of truth for +scope, acceptance criteria, and ordering. If it is absent, incomplete, or conflicts with the repository, +surface the discrepancy and request a clarified plan rather than silently expanding scope. + +## Workflow + +### 1. Establish the implementation baseline + +1. Read the approved plan and restate the current plan item, its acceptance criteria, and its dependencies. +2. Inspect the affected code, neighboring modules, tests, build scripts, and repository guidance before editing. +3. Identify established conventions for naming, module boundaries, error handling, types, formatting, tests, + documentation, and package tooling. +4. Check the working tree so unrelated changes are not overwritten or folded into the task. + +### 2. Implement one small increment at a time + +For each plan item, make the smallest coherent change that can be checked independently: + +1. Implement only the behavior required by that increment. +2. Update or add the nearest appropriate test, fixture, type, or documentation needed to express its contract. +3. Run the narrowest relevant check immediately (for example, a focused test, type check, formatter, or build + target). +4. Inspect the diff and correct regressions before starting the next increment. +5. Record any failed check, decision, or deviation from the plan so it can be reported accurately. + +Do not batch unrelated refactors with feature work. Preserve public interfaces and backward compatibility unless +the approved plan explicitly changes them. Prefer existing project utilities, components, patterns, and commands +over introducing parallel abstractions or dependencies. + +### 3. Apply framework-specific guidance only when needed + +For repositories containing React or Next.js code affected by this work, read and follow the local +[`react-best-practices`](../react-best-practices/SKILL.md) skill before editing UI, hooks, components, routes, +or client/server boundaries. Apply it only to React/Next.js implementation work; this skill remains +framework-neutral for every other stack. + +### 4. Preserve project conventions + +- Use the repository's package manager, task runner, formatter, linter, test framework, and directory layout. +- Match existing naming, import ordering, typing, accessibility, logging, and error-handling conventions. +- Keep changes focused, readable, and reversible; avoid drive-by formatting or generated-file edits unless required. +- Add tests at the same layer and in the same style as adjacent tests. +- Never conceal failures by weakening assertions, disabling checks, swallowing errors, or adding broad exceptions. + +### 5. Finish and hand off + +After all plan items are implemented: + +1. Re-read the approved acceptance criteria and confirm each is covered by the implementation and tests. +2. Run the repository's relevant aggregate checks in addition to the increment-level checks. +3. Prepare a concise handoff for verification and review containing: + - changed files and the behavior delivered; + - checks run and their results; + - known limitations, skipped checks, and follow-up risks; + - any intentional plan deviations and their rationale. +4. Hand the change to the verification and review workflow. In this repository, use + [`code-verify-and-clean-skill`](../code-verify-and-clean-skill/SKILL.md) for the final validation and review. + +## Completion Criteria + +Implementation is complete only when every approved plan item is addressed, each increment has been checked, +repository conventions are preserved, and the verification/review handoff includes sufficient evidence to assess +the change independently. diff --git a/skills/react-best-practices/SKILL.md b/skills/react-best-practices/SKILL.md new file mode 100644 index 0000000..0b7973c --- /dev/null +++ b/skills/react-best-practices/SKILL.md @@ -0,0 +1,39 @@ +--- +name: react-best-practices +description: | + Provides focused implementation guidance for React and Next.js changes, including component boundaries, + hooks, accessibility, and client/server rendering behavior. + Use when: implementing or modifying React components, hooks, Next.js routes, or React client/server boundaries. +allowed-tools: + - Read + - Write + - Grep + - Glob + - Bash +--- + +# React and Next.js Best Practices + +Use this skill only for React or Next.js work. It supplements the repository's conventions; local project +patterns and documented framework configuration take precedence. + +## Implementation Guidance + +- Reuse existing components, design-system primitives, data-access helpers, and route conventions before adding new ones. +- Keep components focused. Extract a component or hook only when it has a clear responsibility and matches local patterns. +- Follow the existing state-management approach. Keep derived values derived instead of duplicating them in state. +- Use hooks at the top level, give effects complete dependency lists, and include cleanup for subscriptions, timers, + and other side effects. +- Preserve accessible semantics: use native controls where appropriate, labels for form inputs, keyboard support, + visible focus behavior, and meaningful loading/error states. +- For Next.js, respect the existing server/client component boundary. Add `'use client'` only when browser APIs, + client state, event handlers, or client-only hooks require it; keep data fetching and secrets on the server. +- Avoid hydration mismatches by keeping server and initial client output deterministic and by using established + project patterns for browser-only values. +- Test user-visible behavior and important loading, empty, and failure states using the repository's existing test tools. + +## Before Handoff + +Check the changed routes and components for console warnings, accessibility regressions, unnecessary client-side +work, and broken loading or error paths. Then return to the execution skill for the standard verification and +review handoff.