From 8a3dfeb71e232aab44b0904272f938ec84cfdd74 Mon Sep 17 00:00:00 2001 From: abozezo-dev Date: Fri, 17 Jul 2026 23:04:57 +0300 Subject: [PATCH] Add plan-driven execution skills --- README.md | 41 +++++++++----- skills.sh.json | 6 +- skills/execution/SKILL.md | 82 ++++++++++++++++++++++++++++ skills/react-best-practices/SKILL.md | 39 +++++++++++++ 4 files changed, 151 insertions(+), 17 deletions(-) create mode 100644 skills/execution/SKILL.md create mode 100644 skills/react-best-practices/SKILL.md diff --git a/README.md b/README.md index 72c2041..9212b34 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.** +> **Reusable AI skills for plan-driven implementation, React/Next.js implementation guidance, and code verification, cleanup, runtime auditing, and security-focused review.** ![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) @@ -12,6 +12,7 @@ - [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) @@ -23,7 +24,7 @@ ## ๐ŸŽฏ Purpose -This skill empowers AI agents to: +These skills empower AI agents to: - โœ… **Verify code correctness** - Ensure logic works as intended - ๐Ÿงน **Remove dead code & duplication** - Keep codebases lean and maintainable @@ -31,6 +32,7 @@ This skill empowers AI agents to: - ๐Ÿ”’ **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 --- @@ -52,23 +54,26 @@ This skill empowers AI agents to: ```bash 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. 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/` +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/`. ---- - -## ๐Ÿ”— Skills.sh Listing +## ๐Ÿงญ Implementation Workflow -View this skill on skills.sh: - -- [Code Verification & Cleaning Skill](https://skills.sh/abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill) +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. -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. +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. --- @@ -77,8 +82,10 @@ The repository page is customized with [`skills.sh.json`](skills.sh.json), and t 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), which groups this skill under **Code Quality** for easier discovery. +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. --- @@ -101,6 +108,10 @@ Code-Quality-Skill/ โ”‚ โ”œโ”€โ”€ 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 @@ -217,4 +228,4 @@ SOFTWARE. --- -

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

\ No newline at end of file +

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

diff --git a/skills.sh.json b/skills.sh.json index 66be6f0..d74a7b8 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -4,9 +4,11 @@ "groupings": [ { "title": "Code Quality", - "description": "Code verification, cleanup, runtime auditing, and security review skills.", + "description": "Plan-driven implementation, React/Next.js guidance, verification, cleanup, runtime auditing, and security review skills.", "skills": [ - "code-verify-and-clean-skill" + "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.