feat(spec): add specification for agent skills

Author: amrabed

.vibe/specs/add-skills/design.md

@@ -0,0 +1,88 @@
+# Design: Agent Skills for cur8d Python
+
+## Architecture Overview
+
+```mermaid
+flowchart TD
+    User["Developer Prompt / Issue"] --> Agent["AI Agent (Claude Code, Cursor, Antigravity)"]
+    Agent --> Registry[".agents/skills/ Index"]
+
+    subgraph Skills [".agents/skills/"]
+        M["add-module"]
+        C["add-cli-command"]
+        V["verify-and-fix"]
+    end
+
+    Registry --> M & C & V
+
+    M -->|"Scaffolds"| Domain["project/<module>/<br/>tests/test_<module>.py"]
+    C -->|"Configures"| CLI["project/app.py<br/>pyproject.toml [project.scripts]"]
+    V -->|"Executes"| Tasks["mise run verify (ruff + pyright + pytest)"]
+```
+
+## Directory Structure
+
+Skills will be placed in `.agents/skills/` to ensure immediate compatibility with `skills.sh`, Claude Code, Cursor, and other agent platforms:
+
+```text
+python/
+├── .agents/
+│   └── skills/
+│       ├── add-module/
+│       │   └── SKILL.md
+│       ├── add-cli-command/
+│       │   └── SKILL.md
+│       └── verify-and-fix/
+│           └── SKILL.md
+├── project/
+├── tests/
+├── pyproject.toml
+└── mise.toml
+```
+
+## Skill Definitions
+
+### 1. `add-module`
+- **Frontmatter**:
+  ```yaml
+  ---
+  name: add-module
+  description: Scaffolds a new domain service, model, or utility module adhering to cur8d standards with type annotations, docstrings, and comprehensive pytest tests. Use whenever asked to add, create, or scaffold a module or service.
+  category: coding
+  tags: [python, uv, pyright, pytest, cur8d]
+  ---
+  ```
+- **Rules**:
+  - Full typing support (`pyright` strict typing without `Any` wherever possible).
+  - Docstrings following Google/PEP 257 format.
+  - Test suite in `tests/` verifying nominal cases, edge cases, and exception handling.
+
+### 2. `add-cli-command`
+- **Frontmatter**:
+  ```yaml
+  ---
+  name: add-cli-command
+  description: Adds a new CLI command or subcommand using Click with structured arguments, options, help text, and CliRunner tests. Use whenever asked to add or modify CLI commands.
+  category: coding
+  tags: [python, click, cli, cur8d]
+  ---
+  ```
+- **Rules**:
+  - Leverages Click decorators (`@click.command`, `@click.option`, `@click.argument`).
+  - Registers entry points in `pyproject.toml` under `[project.scripts]`.
+  - Scaffolds tests using `click.testing.CliRunner`.
+
+### 3. `verify-and-fix`
+- **Frontmatter**:
+  ```yaml
+  ---
+  name: verify-and-fix
+  description: Runs repository verification checks (ruff, pyright, pytest, coverage) and iteratively resolves errors and lint warnings. Use whenever asked to verify, check, or fix code quality or test issues.
+  category: coding
+  tags: [python, ruff, pyright, testing, cur8d]
+  ---
+  ```
+- **Rules**:
+  - Executes `mise run verify`.
+  - Runs `uv run ruff check --fix` and `uv run ruff format`.
+  - Reports status and preserves all existing docstrings and comments.

.vibe/specs/add-skills/plan.md

@@ -0,0 +1,35 @@
+# Implementation Plan: Agent Skills for cur8d Python
+
+Establish structured Agent Skills in `cur8d/python` so AI coding agents can reliably build, extend, test, and maintain modern Python projects adhering to `uv`, `ruff`, `pyright`, and `click`.
+
+## Proposed Changes
+
+### Skills Scaffolding
+
+#### [NEW] `.agents/skills/add-module/SKILL.md`
+- Provide actionable instructions for creating new domain modules, models, and services with type annotations, docstrings, and comprehensive pytest unit tests.
+
+#### [NEW] `.agents/skills/add-cli-command/SKILL.md`
+- Provide instructions for adding CLI commands/subcommands via Click, registering entry points in `pyproject.toml`, and testing with `CliRunner`.
+
+#### [NEW] `.agents/skills/verify-and-fix/SKILL.md`
+- Provide automated diagnostic and remediation steps for linting (ruff), type checking (pyright), and testing (pytest).
+
+---
+
+### Documentation & Agents Guidance
+
+#### [MODIFY] `AGENTS.md`
+- Document the newly introduced skills under `.agents/skills/`.
+- Provide guidance on using `npx skills add cur8d/python` or invoking skills directly.
+
+#### [MODIFY] `docs/README.md`
+- Add an "Agent Skills" section explaining how developers and agents can consume the repository's built-in skills.
+
+---
+
+### Verification Plan
+
+#### Automated Verification
+- Run `mise run verify` (linting with ruff, type checks with pyright, and pytest suite execution).
+- Run `npx skills ls` to confirm skills are detected by the skills CLI.

.vibe/specs/add-skills/requirements.md

@@ -0,0 +1,45 @@
+# Requirements: Agent Skills for cur8d Python
+
+## Overview
+
+Equip the `cur8d/python` repository with modular Agent Skills following the open standard (compatible with `skills.sh`, Claude Code, Cursor, GitHub Copilot, and Google Antigravity). These skills enable AI agents to autonomously scaffold, extend, test, and maintain modern Python projects adhering to cur8d's standards (uv, ruff, pyright, pytest, and Click).
+
+## User Goals
+
+1. Enable developers and AI agents to quickly scaffold new domain services/modules with type annotations and clean separation of concerns.
+2. Enable agents to add new CLI commands and subcommands with Click and register them in `pyproject.toml`.
+3. Provide an iterative code verification and auto-remediation skill that executes `mise run verify` (or `ruff check --fix`, `ruff format`, `pyright`, and `pytest --cov`).
+4. Support distribution via `npx skills add cur8d/python` and project-level discovery under `.agents/skills/`.
+
+## Functional Requirements
+
+1. **`add-module` Skill**:
+   - Location: `.agents/skills/add-module/SKILL.md`
+   - Instructions for the agent to scaffold a new domain module under `project/<module_name>/`.
+   - Requires full type annotations (`pyright`-compliant) and Google/PEP 257 style docstrings.
+   - Requires matching unit tests under `tests/test_<module_name>.py` with complete test coverage.
+
+2. **`add-cli-command` Skill**:
+   - Location: `.agents/skills/add-cli-command/SKILL.md`
+   - Instructions to add a new CLI command or subcommand using Click in `project/app.py` or `project/cli/`.
+   - Wires CLI parameters, help texts, and error handling.
+   - Registers script entry points under `[project.scripts]` in `pyproject.toml` if creating a standalone binary.
+   - Scaffolds CLI runner tests in `tests/test_cli.py` using Click's `CliRunner`.
+
+3. **`verify-and-fix` Skill**:
+   - Location: `.agents/skills/verify-and-fix/SKILL.md`
+   - Step-by-step diagnostic and auto-repair workflow for Python projects:
+     1. Run `mise run verify` (linting, type checking, security audits, test suite).
+     2. Automatically format and fix mechanical issues using `uv run ruff check --fix` and `uv run ruff format`.
+     3. Diagnose and fix type errors identified by `pyright`.
+     4. Resolve any test failures or coverage drops reported by `pytest`.
+
+4. **Integration & Discoverability**:
+   - Update `AGENTS.md` and `docs/README.md` to document the newly added skills and how to consume them via `npx skills`.
+
+## Non-Functional Requirements
+
+- All skills must include valid YAML frontmatter (`name`, `description`, `category`, `tags`).
+- Descriptions must be trigger-rich and action-oriented for progressive disclosure.
+- Must keep each `SKILL.md` file concise (under 500 lines).
+- Must adhere strictly to existing repository validation (`mise run verify` must pass).

.vibe/specs/add-skills/tasks.md

@@ -0,0 +1,9 @@
+# Tasks: Agent Skills for cur8d Python
+
+- [ ] Create `.agents/skills/add-module/SKILL.md` <!-- id: 0 -->
+- [ ] Create `.agents/skills/add-cli-command/SKILL.md` <!-- id: 1 -->
+- [ ] Create `.agents/skills/verify-and-fix/SKILL.md` <!-- id: 2 -->
+- [ ] Update `AGENTS.md` with skills inventory and triggering instructions <!-- id: 3 -->
+- [ ] Update `docs/README.md` with Agent Skills documentation <!-- id: 4 -->
+- [ ] Run `mise run verify` to ensure tests and linters pass <!-- id: 5 -->
+- [ ] Verify skills discovery with `npx skills` <!-- id: 6 -->