Add plan-driven execution and react-best-practices skills, register and document them

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).
+<p align="center">Made with ❤️ by <strong>abozezo-dev</strong></p>

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"
+            ]
+        }
+    ]
 }

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.

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.