everything-gemini 0.0.0-stage → 1.0.1

package/skills/api-craftsman/examples/openapi-spec.yaml

@@ -0,0 +1,37 @@
+openapi: 3.1.0
+info:
+  title: Order Management API
+  version: 1.0.0
+  description: High-performance API contract for orders.
+paths:
+  /orders:
+    post:
+      summary: Create new order
+      operationId: createOrder
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [items, customerId]
+              properties:
+                customerId:
+                  type: string
+                  format: uuid
+                items:
+                  type: array
+                  items:
+                    type: object
+                    required: [productId, quantity]
+                    properties:
+                      productId:
+                        type: string
+                      quantity:
+                        type: integer
+                        minimum: 1
+      responses:
+        '201':
+          description: Order created successfully
+        '400':
+          description: Validation failure

package/skills/architecture-designer/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: architecture-designer
+description: >-
+  Creates comprehensive system design architectures, Mermaid diagrams, API contracts, and Architecture Decision Records (ADRs). Use when planning complex software systems or designing net-new components.
+---
+
+# Architecture Designer
+
+This skill structures software design workflows, creating standardized Architecture Decision Records (ADRs) and Mermaid diagrams.
+
+## Design Workflow
+
+### 1. Requirements & Constraint Gathering
+- Clarify functional and non-functional requirements (latency, throughput, availability, consistency).
+- Identify existing tech stack dependencies and constraints.
+
+### 2. High-Level Diagramming with Mermaid
+Always visualize architectures using GitHub-flavored Mermaid blocks:
+- **System Context (C4 Level 1)**
+- **Container / Service Diagram (C4 Level 2)**
+- **Sequence Diagram (Data Flow)**
+
+*Rule*: Quote node labels containing special characters: `id["Service Name (Tech Stack)"]`.
+
+### 3. Architecture Decision Record (ADR)
+Structure decisions in this format:
+- **Title**: `ADR-00X: Short descriptive title`
+- **Status**: Proposed / Accepted / Superseded
+- **Context**: Problem statement and forces at play.
+- **Decision**: The architectural choice and implementation strategy.
+- **Consequences**: Positive outcomes and trade-offs.
+
+For full examples, see [examples/c4-architecture.md](./examples/c4-architecture.md).

package/skills/architecture-designer/examples/c4-architecture.md

@@ -0,0 +1,33 @@
+# C4 Model & Mermaid Diagram Examples
+
+## Example: Microservices Architecture
+```mermaid
+graph TD
+    Client["Web / Mobile Client"] -->|HTTPS / REST| Gateway["API Gateway (Kong / Envoy)"]
+    Gateway -->|gRPC| AuthSvc["Authentication Service (Go)"]
+    Gateway -->|gRPC| OrderSvc["Order Processing Service (Node.js)"]
+    Gateway -->|gRPC| InventorySvc["Inventory Service (Python)"]
+
+    OrderSvc --> DB[(PostgreSQL Primary)]
+    OrderSvc --> Queue["Kafka Event Bus"]
+    Queue --> NotificationSvc["Notification Worker (Go)"]
+```
+
+## Example: Event Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Frontend
+    participant API as API Gateway
+    participant Svc as Payment Service
+    participant Stripe as Stripe API
+
+    User->>Frontend: Click "Pay Now"
+    Frontend->>API: POST /api/checkout
+    API->>Svc: InitiateCheckout(orderId)
+    Svc->>Stripe: CreatePaymentIntent()
+    Stripe-->>Svc: clientSecret
+    Svc-->>Frontend: 200 OK (clientSecret)
+    Frontend->>User: Confirm Payment Modal
+```

package/skills/browser-qa-tester/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: browser-qa-tester
+description: >-
+  Orchestrates automated UI, frontend, and end-to-end testing using Antigravity's native browser subagent with automatic WebP recording. Use when verifying web applications, visual bugs, or UI flows.
+---
+
+# Browser QA Tester
+
+This skill automates visual testing and end-to-end verification of web applications using Antigravity's native `browser_subagent`.
+
+## Why Browser Subagent?
+- **Autonomous Interaction**: Navigates, clicks, fills inputs, and scrolls.
+- **Automatic Recording**: Automatically captures WebP video recordings saved directly into the conversation artifacts directory.
+- **Console & Network Inspection**: Intercepts unhandled errors, failed network requests, and visual layout glitches.
+
+## Verification Procedure
+
+### 1. Ensure Local Server is Running
+Before launching the browser subagent, ensure the web app is running locally:
+```bash
+# Check if port is open
+lsof -i :3000 || lsof -i :5173
+```
+If not running, launch with `run_command` and `IsDaemon: true`:
+```bash
+npm run dev
+```
+
+### 2. Invoke `browser_subagent`
+Formulate a precise task description with explicit stop conditions:
+- Specify target URL (e.g., `http://localhost:3000`).
+- Specify unique element IDs or text labels to click/type.
+- Define what constitutes success (e.g., "Verify dashboard renders after login").
+
+### 3. Review Recording Artifacts
+After the subagent finishes:
+- Embed the generated WebP recording into your summary artifact:
+  ```markdown
+  ![Browser Test Recording](file:///absolute/path/to/artifacts/browser_test_demo.webp)
+  ```
+- Summarize any console warnings or errors detected during the test.
+
+For specialized testing recipes (Responsive testing, Form verification), see [references/browser-recipes.md](./references/browser-recipes.md).

package/skills/browser-qa-tester/references/browser-recipes.md

@@ -0,0 +1,21 @@
+# Browser Testing Recipes
+
+## Recipe 1: Form Fill and Submit Flow
+```text
+Task: Navigate to http://localhost:3000/contact.
+Locate input with id '#name' and type 'Test User'.
+Locate input with id '#email' and type 'test@example.com'.
+Locate button with text 'Send Message' and click it.
+Verify that the success message 'Thank you for contacting us' appears on screen.
+Stop condition: Success message is visible or error banner appears.
+```
+
+## Recipe 2: Responsive Layout Check
+```text
+Task: Open http://localhost:3000.
+Resize browser window to 375x812 (mobile iPhone viewport).
+Verify that the mobile hamburger navigation toggle is visible.
+Click the hamburger icon and verify the drawer menu slides in.
+Resize back to 1440x900 (desktop viewport) and verify desktop navigation links return.
+Stop condition: Both mobile and desktop nav states verified.
+```

package/skills/cloudflare-workers/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: cloudflare-workers
+description: >-
+  Use this skill when developing Cloudflare Workers, configuring Wrangler v3, integrating Cloudflare D1 SQL or KV storage, or deploying global edge APIs.
+---
+
+# Cloudflare Workers & Edge Infrastructure
+
+## Overview
+Cloudflare Workers execute on V8 isolates across 300+ edge locations worldwide. This skill provides architectural patterns for ultra-low latency serverless APIs, D1 relational databases, KV storage, and Wrangler configuration.
+
+## Procedural Workflow
+
+### 1. Project Scaffolding & Wrangler Config
+Structure `wrangler.jsonc` or `wrangler.toml` with strict environment bindings:
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "edge-api",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-09-23",
+  "compatibility_flags": ["nodejs_compat"],
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "prod-db",
+      "database_id": "xxxx-xxxx"
+    }
+  ],
+  "kv_namespaces": [
+    {
+      "binding": "CACHE",
+      "id": "yyyy-yyyy"
+    }
+  ]
+}
+```
+
+### 2. Edge Request Handling
+Use typed `Env` interfaces and native `fetch` handlers:
+```typescript
+export interface Env {
+  DB: D1Database;
+  CACHE: KVNamespace;
+  API_SECRET: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+    if (request.method === "OPTIONS") {
+      return handleCors(request);
+    }
+    // Execution context for background tasks that shouldn't block response
+    ctx.waitUntil(logAnalytics(request, env));
+    return new Response(JSON.stringify({ status: "ok" }), {
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+};
+```
+
+### 3. Edge Storage Patterns
+- **Cloudflare KV**: High-read, low-write caching (eventually consistent). Ideal for session tokens, feature flags, and redirect maps.
+- **Cloudflare D1**: Serverless SQLite at the edge. Always use parameterized queries (`env.DB.prepare("SELECT * FROM users WHERE id = ?").bind(id).first()`).
+- **Cloudflare R2**: Zero-egress S3-compatible object storage.
+
+## Verification Checklist
+- [ ] `compatibility_date` pinned to a modern version
+- [ ] Secrets managed via `wrangler secret put`, never hardcoded
+- [ ] Background telemetry wrapped in `ctx.waitUntil`
+- [ ] D1 queries use parameterized bindings to prevent SQL injection

package/skills/context-caching/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: context-caching
+description: >-
+  Use this skill when managing large-context Gemini operations (1M-2M tokens), architecting prefix-cached repository indexes, optimizing prompt structures for cost and latency, or structuring session memory for long-running agent workflows.
+---
+
+# Gemini Context Caching & Large-Context Optimization
+
+## Overview
+Gemini's 1M-to-2M token context window combined with explicit and implicit Context Caching allows agents to ingest entire codebases, documentation sets, and transaction logs. This skill outlines architectural strategies to maximize caching efficiency, cut API token costs by up to 75%, and minimize time-to-first-token (TTFT).
+
+## Context Architecture: Prefix Optimization
+
+Gemini caching relies on **deterministic prefix matching**. To ensure cache hits across agent invocations:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ 1. STATIC PREFIX (Cached - High Hit Rate)                    │
+│    - System Instructions & Repository Rules (GEMINI.md)     │
+│    - Architecture Specs & Database Schemas                  │
+│    - Base Codebase Index / AST Dump                         │
+├─────────────────────────────────────────────────────────────┤
+│ 2. DYNAMIC SUFFIX (Uncached - Fast Processing)              │
+│    - Current User Prompt / Incremental Task Diff            │
+│    - Recent Terminal Command Output                         │
+│    - Real-Time Conversation Turn                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Golden Rules for Caching
+1. **Never mutate the prefix**: Avoid injecting dynamic timestamps, random IDs, or changing session metadata at the beginning of the context.
+2. **Cluster Static Assets**: Place unchanging documentation, API contracts, and core schemas at the very top of context assemblies.
+3. **Chunking Thresholds**: Context caching provides optimal return on investment when static context exceeds 32k tokens.
+
+## Progressive Ingestion Strategies
+
+1. **Skeleton First**: Ingest file tree maps and interface definitions before pulling full function implementations.
+2. **Selective Hydration**: Ingest full source files only for components identified during initial skeleton mapping.
+3. **Session Compaction**: When conversation histories grow long, trigger the `Stop` or `PostInvocation` summarizer to compress intermediate thoughts into high-density Knowledge Items (KI).
+
+## Cost & Latency Economics
+- **Cached Input Cost**: ~75% cheaper than non-cached input tokens.
+- **Cache Hit Latency**: Reduces initial TTFT from seconds to milliseconds on large contexts.
+
+## Verification Checklist
+- [ ] Static instructions positioned consistently at the head of context
+- [ ] No variable timestamps or nonces in the static prefix block
+- [ ] Cache hit rates monitored during multi-turn batch workflows

package/skills/continuous-learning/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: continuous-learning
+description: >-
+  Extracts architectural lessons, developer corrections, and project conventions from the current session and records them into permanent rules or Knowledge Items. Activate when the user runs /learn or after resolving a complex issue.
+---
+
+# Continuous Learning & Instinct Recording
+
+This skill enables Antigravity to retain lessons and developer feedback so mistakes are never repeated.
+
+## Learning Workflow
+
+### 1. Identify the Core Insight
+Determine what was learned:
+- **Correction**: Did the user correct a style, framework version, or tool choice?
+- **Bug Fix**: Was an obscure bug or configuration issue solved after debugging?
+- **Workflow**: Was an optimal command sequence identified for building/testing?
+
+### 2. Format the Instinct
+Formulate a concise, imperative rule:
+- *Bad*: "We had an issue with Docker not starting on port 8080."
+- *Good*: "Always map Docker container port 8080 to host 8081 to avoid conflicting with local proxy."
+
+### 3. Persist to `.agents/rules/instincts.md`
+Append the new instinct under the appropriate section in `.agents/rules/instincts.md`:
+```markdown
+- **Topic Name**: Concrete rule statement.
+```
+
+### 4. For Major Architectural Changes: Create Knowledge Item
+If the insight affects the broader repository architecture, write a dedicated Knowledge Item in `<appDataDir>/knowledge` with `metadata.json` and artifact details.

package/skills/database-architect/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: database-architect
+description: >-
+  Designs relational and document database schemas, crafts zero-downtime database migrations, optimizes complex queries, and configures ORMs (Prisma, Drizzle, SQLAlchemy).
+---
+
+# Database Architect
+
+This skill guides data modeling, schema evolution, index tuning, and zero-downtime migration workflows.
+
+## Core Directives
+
+### 1. Schema Design Standards
+- **Primary Keys**: Use UUIDv7 or ULIDs for distributed systems, or identity integers for internal lookups.
+- **Foreign Keys**: Always define explicit foreign key constraints with appropriate `ON DELETE` behavior (`CASCADE`, `RESTRICT`, or `SET NULL`).
+- **Timestamps**: Every table must have `created_at TIMESTAMPTZ DEFAULT now()` and `updated_at TIMESTAMPTZ DEFAULT now()`.
+
+### 2. Zero-Downtime Migrations (Expand/Contract Pattern)
+- **Never rename or delete a column in a single migration**:
+  1. *Phase 1 (Expand)*: Add the new column as nullable or with a default. Deploy code that writes to both columns.
+  2. *Phase 2 (Backfill)*: Backfill existing records asynchronously.
+  3. *Phase 3 (Switch)*: Deploy code that reads from the new column only.
+  4. *Phase 4 (Contract)*: Remove the old column.
+- **Safe Index Creation**: In PostgreSQL, always use `CREATE INDEX CONCURRENTLY` to avoid blocking read/write queries.
+
+For the zero-downtime migration checklist, see [references/migration-checklist.md](./references/migration-checklist.md).

package/skills/database-architect/references/migration-checklist.md

@@ -0,0 +1,9 @@
+# Zero-Downtime Migration Checklist
+
+Before applying any migration to staging or production:
+
+- [ ] **No Exclusive Table Locks**: Are you adding a column with a non-constant default on older Postgres versions?
+- [ ] **Concurrent Indexes**: Are all new indexes declared with `CONCURRENTLY` (or equivalent in your database engine)?
+- [ ] **Reversible / Down Migrations**: Is there a verified `down` migration script in case a rollback is required?
+- [ ] **Idempotent Execution**: Can the migration be safely re-run if interrupted?
+- [ ] **Query Performance Impact**: Has `EXPLAIN (ANALYZE, BUFFERS)` been verified for queries hitting the modified tables?

package/skills/devops-pipeline/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: devops-pipeline
+description: >-
+  Architects and configures Docker containers, multi-stage Dockerfiles, GitHub Actions CI/CD workflows, and infrastructure automation. Use when building or tuning deployment pipelines.
+---
+
+# DevOps Pipeline Engineering
+
+This skill structures Docker containerization, caching, security scanning, and CI/CD automation.
+
+## Core Directives
+
+### 1. Minimal Multi-Stage Dockerfiles
+- Use multi-stage builds (`AS builder` and `AS runner`) to keep final image sizes minimal (< 100MB).
+- Run applications as a non-root user (`USER node` or `USER appuser`) for defense-in-depth.
+- Order commands to maximize Docker layer cache hits (copy `package.json` / `requirements.txt` before copying source code).
+
+### 2. GitHub Actions CI/CD Best Practices
+- Cache dependencies (`actions/cache` or `actions/setup-node` with `cache: 'npm'`).
+- Run linting, typechecking, and unit tests concurrently using GitHub Actions job matrix.
+- Enforce status checks before permitting branch merges into `main`.
+
+For complete production CI/CD workflow templates, see [templates/github-ci.yml](./templates/github-ci.yml).

package/skills/devops-pipeline/templates/github-ci.yml

@@ -0,0 +1,31 @@
+name: CI Suite
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck --if-present
+
+      - name: Lint
+        run: npm run lint --if-present
+
+      - name: Run Test Suite
+        run: npm test

package/skills/fullstack-nextjs/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: fullstack-nextjs
+description: >-
+  Specialized engineering workflow for Next.js App Router, React Server Components (RSC), Server Actions, and API routes. Use when building or debugging modern Next.js applications.
+---
+
+# Fullstack Next.js Engineering
+
+This skill provides patterns for Next.js (App Router), React Server Components (RSC), and Server Actions.
+
+## Core Directives
+
+### 1. Server vs. Client Components
+- **Default to Server Components**: Fetch data directly on the server without `useEffect` or client-side fetch.
+- **`'use client'` Boundary**: Only mark components with `'use client'` when they require browser event listeners (`onClick`, `onChange`), React state (`useState`, `useReducer`), or browser APIs.
+- **Push Client Boundaries Down**: Keep client components at the leaves of the component tree to maximize server-side rendering performance.
+
+### 2. Server Actions & Mutations
+- Use `'use server'` functions for mutations.
+- Always validate input arguments using Zod schemas inside Server Actions before performing database queries.
+- Revalidate cache paths using `revalidatePath()` or `revalidateTag()` after data mutations.
+
+### 3. Hydration Bug Prevention
+- Avoid accessing `window`, `localStorage`, or `navigator` during initial render.
+- Ensure identical HTML output between SSR and hydration (e.g. avoid rendering random IDs or localized date strings on initial render without a client wrapper).
+
+For architectural layouts and route handler patterns, see [references/app-router-patterns.md](./references/app-router-patterns.md).

package/skills/fullstack-nextjs/references/app-router-patterns.md

@@ -0,0 +1,46 @@
+# Next.js App Router Architecture & Patterns
+
+## 1. Safe Server Action Pattern with Zod
+```typescript
+'use server';
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const CreateTodoSchema = z.object({
+  title: z.string().min(1).max(100),
+});
+
+export async function createTodo(formData: FormData) {
+  const parsed = CreateTodoSchema.safeParse({
+    title: formData.get('title'),
+  });
+
+  if (!parsed.success) {
+    return { error: 'Invalid input', issues: parsed.error.issues };
+  }
+
+  // Database insert
+  // await db.todos.create({ data: { title: parsed.data.title } });
+
+  revalidatePath('/todos');
+  return { success: true };
+}
+```
+
+## 2. Suspense & Streaming Data Fetching
+```tsx
+import { Suspense } from 'react';
+import { UserProfileSkeleton, UserProfile } from './UserProfile';
+
+export default function DashboardPage() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-bold">Dashboard</h1>
+      <Suspense fallback={<UserProfileSkeleton />}>
+        <UserProfile />
+      </Suspense>
+    </main>
+  );
+}
+```

package/skills/gemini-grounding/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gemini-grounding
+description: >-
+  Use this skill when verifying dynamic facts, researching live documentation, fact-checking technical claims, or integrating Google Search grounding into Gemini agent reasoning workflows.
+---
+
+# Gemini Search Grounding & Dynamic Fact Verification
+
+## Overview
+Gemini frontier models feature native **Google Search Grounding**, enabling agents to supplement static training weights with real-time web citations, current API documentation, and package release notes. This skill outlines best practices for search grounding, citation verification, and hallucination elimination.
+
+## Procedural Workflow
+
+### 1. Identify Grounding Triggers
+Activate search grounding when:
+- Querying rapidly evolving SDKs, library APIs, or breaking versions released after model cutoffs.
+- Verifying deployment status, cloud service outages, or public CVE advisories.
+- Researching latest framework releases (e.g., Next.js canary features, Tailwind v4, React 19).
+
+### 2. Search Query Formulation
+Formulate targeted search queries:
+- **Exact Syntax Match**: Use quotes for exact error strings or function signatures.
+- **Official Domain Prioritization**: Target authoritative documentation:
+  - `site:github.com` for issue threads and release tags.
+  - `site:npmjs.com` or `site:pypi.org` for version numbers and dependencies.
+  - Official vendor docs (`docs.antigravity.google`, `developer.mozilla.org`).
+
+### 3. Verification & Citation Attribution
+When incorporating search findings into code:
+1. **Cross-Check with Active Code**: Never assume an external snippet works as-is; inspect local types and configurations first.
+2. **Clickable Links**: Link external references using markdown links in documentation and artifacts.
+3. **Zero-Trust Validation**: Verify any third-party code against local linters (`npm test` or typecheckers).
+
+## Verification Checklist
+- [ ] Claims backed by verifiable, recent documentation
+- [ ] No hallucinated imports or deprecated APIs
+- [ ] External references properly attributed

package/skills/gemini-multimodal/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gemini-multimodal
+description: >-
+  Use this skill when analyzing visual mockups, inspecting UI screenshots, converting wireframes to frontend code, extracting architecture from diagrams, or performing visual QA regression checks using Gemini's native multimodal capabilities.
+---
+
+# Gemini Multimodal Engineering
+
+## Overview
+Gemini 1.5/3.8 models feature native multimodal grounding across images, diagrams, video frames, and audio tokens. This skill guides the agent on how to effectively extract structured specifications from visual assets and translate them into production code.
+
+## Procedural Workflow
+
+### 1. Visual Intake & Pre-Processing
+- **Aspect Ratio & Resolution**: Gemini processes visual inputs with native resolution preservation.
+- **Reference Assets**: When inspecting diagrams or UI mockups, identify layout hierarchy:
+  - Header / Navigation bars
+  - Main grid or flex container arrangements
+  - Typography weights, line heights, and color hex values
+  - Interactive elements (buttons, inputs, carousels, modals)
+
+### 2. Mockup-to-Code Translation Pattern
+When converting a visual mockup into web components:
+1. **Layout First**: Implement semantic HTML scaffolding matching visual hierarchy.
+2. **Design Tokens**: Extract exact color palettes, border radiuses, and shadow elevations into CSS variables.
+3. **Responsive Breakpoints**: Infer desktop, tablet, and mobile reflow logic from the visual layout.
+4. **Interactive States**: Emulate hover, focus-visible, and active states visible in the UI.
+
+### 3. Diagram & Flowchart Extraction
+When given an architectural whiteboard photo or flowchart:
+1. Transcribe nodes and connections into clean **Mermaid.js** diagrams.
+2. Extract data models, sequence flows, and component boundaries into typed interfaces.
+
+### 4. Visual QA & Regression Diffing
+1. Capture screenshots of the rendered application using `browser_subagent`.
+2. Inspect layout anomalies: overlapping text, clipped containers, misalignment across viewports.
+3. Apply surgical CSS adjustments without affecting sibling components.
+
+## Verification Checklist
+- [ ] Visual hierarchy precisely reflects the reference asset
+- [ ] No placeholder assets or mock text left in production components
+- [ ] CSS uses fluid units (`rem`, `ch`, `%`) and CSS grid/flexbox
+- [ ] Visual artifacts verified via browser inspection or recording

package/skills/git-craftsman/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: git-craftsman
+description: >-
+  Guides atomic commits, conventional commit formatting, clean branch strategies, and pull request walkthrough generation. Use when staging, committing, or preparing a PR.
+---
+
+# Git Craftsman
+
+This skill enforces clean version control habits, atomic commits, and structured pull request walkthroughs.
+
+## Atomic Commit Workflow
+
+### 1. Inspect Staged & Unstaged Diff
+Always review changes before staging:
+```bash
+git status -s
+git diff
+```
+
+### 2. Craft Conventional Commit Messages
+Format commit messages strictly following the Conventional Commits specification:
+```text
+<type>(<scope>): <short imperative summary>
+
+[optional detailed body explaining WHY, not just WHAT]
+
+[optional breaking changes or issue references]
+```
+
+**Permitted Types**:
+- `feat`: New feature or user-facing functionality.
+- `fix`: Bug fix.
+- `refactor`: Code change that neither fixes a bug nor adds a feature.
+- `perf`: Performance improvement.
+- `test`: Adding or correcting tests.
+- `docs`: Documentation only changes.
+- `chore`: Build system, configuration, or dependency updates.
+
+### 3. Pull Request Walkthrough Format
+When authoring a pull request summary, include:
+- **High-Level Objective**: What problem this PR solves.
+- **Key Changes**: Bulleted list of modified modules with clickable file links.
+- **Verification Performed**: Exact commands run (`npm test`, `cargo test`) and results.