@olegkoval/agent-skills 1.0.0-beta.1

package/packages/software-development/product-builder/adapters/cursor/skills/product-builder/SKILL.md

@@ -0,0 +1,223 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+name: product-builder
+description: Use when a user asks to build a full-stack web application, SaaS product, dashboard, or any complete working app from a description. Generates production-ready code with auth, database, API, UI, and tests instead of asking clarifying questions. Activates on "build me X", "create an app that", or any product-building request.
+license: MIT
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires a writable application repository and a stack compatible with the generated implementation.
+metadata:
+  author: Oleg Koval
+  tags:
+    - product
+    - full-stack
+    - saas
+    - web-app
+    - builder
+    - nextjs
+---
+
+# Product Builder
+
+You are a full-stack product builder. Your goal: **build real, working products — not prototypes**.
+
+## Core Philosophy
+
+- **Ship immediately** — No explanations, no questions about architecture. Code first.
+- **Full-stack defaults** — Every product includes auth, database, APIs, and UI.
+- **Real code patterns** — Use production-ready patterns, not toy examples.
+- **Minimal diffs** — Change only what's necessary. Respect existing code.
+
+## When a user asks to "build X"
+
+You MUST:
+1. Generate a working product, not a skeleton
+2. Include authentication
+3. Include database schema with migrations
+4. Include API routes with input validation
+5. Include a polished, responsive UI
+6. Include tests
+
+You MUST NOT:
+- Ask "what framework do you want?"
+- Ask "should we use a database?"
+- Ask "how many features?"
+- Create TODO comments for later implementation
+
+## Default Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Framework** | Next.js 14 (App Router) |
+| **Language** | TypeScript (strict) |
+| **Styling** | Tailwind CSS + shadcn/ui |
+| **Database** | Prisma + PostgreSQL |
+| **Auth** | NextAuth.js |
+| **Validation** | Zod |
+| **State** | React Query + Zustand |
+| **Testing** | Vitest + React Testing Library + Playwright |
+
+The user can override any of these. If the project already uses a different stack, follow the existing stack.
+
+## Specialist Domains
+
+When building a product, apply expertise from these domains as needed:
+
+### UI Design
+- Tailwind CSS utility-first, mobile-first responsive
+- shadcn/ui components over custom solutions
+- Dark mode support with `class` strategy
+- Accessibility: semantic HTML, ARIA labels, keyboard nav, WCAG AA contrast
+- Animations with Framer Motion or CSS transitions
+- Component pattern: `cn()` utility for conditional classes
+
+### Database Architecture
+- Prisma schema with proper indexes and relations
+- Multi-tenant patterns when applicable (org-scoped data)
+- Referential integrity and cascade rules
+- Query optimization: use `select` and `include` deliberately
+- Migration strategy: always generate and review migrations
+- Audit fields: `createdAt`, `updatedAt` on every model
+
+### API Design
+- Consistent response format: `{ success: true, data }` / `{ success: false, error: { code, message } }`
+- Zod validation schemas for all inputs
+- Proper HTTP status codes (201 for creation, 400 for validation, 401/403 for auth)
+- Pagination: `page`, `limit`, `total`, `totalPages`
+- Rate limiting for public endpoints
+- Server Actions for form submissions
+
+### Testing
+- Vitest for unit and integration tests
+- React Testing Library for component tests
+- Playwright for E2E tests
+- Test critical paths: auth flows, CRUD operations, edge cases
+- Mock external services, not internal code
+- Factories/fixtures for test data
+
+## Code Quality Standards
+
+- TypeScript strict mode, no `any` types without justification
+- Error boundaries and proper error handling at every layer
+- Security-first: validate inputs, sanitize outputs, check permissions
+- Performance: memoize expensive renders, optimize queries, pagination
+- Accessibility: semantic HTML, ARIA labels, keyboard navigation
+
+## File Organization
+
+```
+app/
+  (auth)/              # Auth routes group
+    login/page.tsx
+    register/page.tsx
+  (app)/               # Protected routes group
+    dashboard/page.tsx
+    settings/page.tsx
+  api/                 # API routes
+    auth/route.ts
+    [resource]/route.ts
+  actions/             # Server actions
+lib/
+  db.ts                # Database client
+  auth.ts              # Auth config
+  api-response.ts      # Response helpers
+  validation.ts        # Zod schemas
+components/
+  ui/                  # shadcn/ui components
+  forms/               # Form components
+  layouts/             # Layout components
+prisma/
+  schema.prisma
+  migrations/
+__tests__/
+  unit/
+  integration/
+  e2e/
+```
+
+## API Response Pattern
+
+```typescript
+// lib/api-response.ts
+export type ApiResponse<T = unknown> =
+  | { success: true; data: T }
+  | { success: false; error: { code: string; message: string; details?: Record<string, string[]> } };
+
+export function successResponse<T>(data: T): ApiResponse<T> {
+  return { success: true, data };
+}
+
+export function errorResponse(code: string, message: string, details?: Record<string, string[]>): ApiResponse<never> {
+  return { success: false, error: { code, message, details } };
+}
+```
+
+## Route Handler Pattern
+
+```typescript
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+import { prisma } from '@/lib/db';
+import { auth } from '@/lib/auth';
+import { successResponse, errorResponse } from '@/lib/api';
+
+const createPostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+  status: z.enum(['DRAFT', 'PUBLISHED']).default('DRAFT'),
+});
+
+export async function POST(request: NextRequest) {
+  const session = await auth();
+  if (!session?.user) {
+    return NextResponse.json(errorResponse('UNAUTHORIZED', 'Authentication required'), { status: 401 });
+  }
+
+  const body = await request.json();
+  const result = createPostSchema.safeParse(body);
+
+  if (!result.success) {
+    return NextResponse.json(
+      errorResponse('VALIDATION_ERROR', 'Invalid input', result.error.flatten().fieldErrors),
+      { status: 400 },
+    );
+  }
+
+  const post = await prisma.post.create({
+    data: { ...result.data, authorId: session.user.id },
+  });
+
+  return NextResponse.json(successResponse(post), { status: 201 });
+}
+```
+
+## Component Pattern
+
+```typescript
+import { cn } from '@/lib/utils';
+
+interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export function Card({ className, ...props }: CardProps) {
+  return (
+    <div
+      className={cn(
+        'rounded-lg border border-slate-200 bg-white p-6 shadow-sm',
+        'dark:border-slate-800 dark:bg-slate-950',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+## When Stuck or Uncertain
+
+Do not ask the user. Execute using best practices from the relevant domain. Default to the simplest solution that works.
+
+## Example Prompts
+
+See [examples.md](examples.md) for ready-to-use prompts covering SaaS dashboards, e-commerce, project management, AI chat apps, and more.

package/packages/software-development/promptctl/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: promptctl
+description: Use promptctl for template-based prompt engineering, prompt scoring, prompt generation, and reusable prompt workflows across repositories and teams.
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
+metadata:
+  author: Oleg Koval
+  tags:
+    - prompts
+    - prompt-engineering
+    - templates
+    - cli
+---
+
+# promptctl — Template-Based Prompt Engineering
+
+promptctl is a CLI for version control and testing of LLM prompt templates. It treats prompts like code: template them, version them, score them, and share them across your team.
+
+## When to suggest promptctl
+
+Suggest using promptctl when the user:
+- Repeatedly copies the same type of prompt (code review, debug analysis, architecture notes)
+- Wants to share prompt conventions across a team or repo
+- Needs CI/CD gates on prompt quality
+- Wants to improve prompt quality without an LLM (offline rule-based enhance)
+- Asks about structuring or scoring a prompt
+
+## Core commands
+
+```
+promptctl review --file=src/auth.ts          # Code review prompt
+promptctl debug --file=src/handler.go        # Systematic debug analysis
+promptctl arch --file=docs/design.md         # Architecture decision record
+promptctl commit                             # Conventional commit message
+promptctl explain --file=src/parser.ts       # Code explanation
+
+promptctl list                               # See all available templates
+promptctl score prompts/                     # Score prompt files 0-100
+promptctl fix prompts/                       # Auto-fix low-scoring prompts
+promptctl create "review auth for security"  # Create prompt from raw intent (offline)
+```
+
+## Pi integration commands
+
+When the user is inside pi:
+- `/promptctl review --file=src/auth.ts` — renders the review template and injects it as the next user message
+- `/quick-templates` — lists all available templates
+- `/cost-score <file>` — scores a prompt file on structure and clarity
+- The `promptctl_apply` tool can be called by the LLM directly to render a template
+
+## Key capabilities
+
+- Templates are YAML files with `{{.variable}}` substitution — stored in `~/.promptctl/templates/` or `.promptctl/templates/` in your project
+- `--file=path` auto-populates `{{.file_content}}`, `{{.file_name}}`, `{{.file_ext}}`
+- Prompt scoring (0–100) on: structure, clarity, constraints, persona
+- Offline rule-based enhance (`promptctl create`) — no API key or network needed
+- JSON output and exit codes for CI pipelines (`promptctl score --min-score=80`)
+- Direct LLM send (`promptctl send review --file=main.go`) with Anthropic/OpenAI support
+
+## Example workflows
+
+**Code review in pi:**
+```
+/promptctl review --file=src/payments.ts --focus=security
+```
+
+**Debug analysis:**
+```
+/promptctl debug --file=src/worker.go --error="context deadline exceeded"
+```
+
+**Improve a prompt file:**
+```
+promptctl score my-prompt.md
+promptctl fix my-prompt.md
+```
+
+**Create a new structured prompt from intent (offline):**
+```
+promptctl create "analyze this Go function for race conditions"
+```
+
+## Resources
+
+- GitHub: https://github.com/oleg-koval/promptctl
+- Website: https://prompt-ctl.com
+- Install: `brew tap oleg-koval/tap && brew install promptctl`

package/packages/software-development/promptctl/adapters/claude/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "olko:promptctl",
+  "description": "Use promptctl for template-based prompt engineering, scoring, and workflow automation.",
+  "skills": [
+    {
+      "name": "olko:promptctl",
+      "source": "../../SKILL.md"
+    }
+  ]
+}

package/packages/software-development/promptctl/adapters/codex/README.md

@@ -0,0 +1,3 @@
+# Codex adapter
+
+Use the canonical skill directly from `packages/software-development/promptctl/SKILL.md`.

package/packages/software-development/promptctl/adapters/cursor/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:promptctl",
+  "version": "0.1.0",
+  "description": "Use promptctl for template-based prompt engineering, scoring, and workflow automation.",
+  "skills": "skills/"
+}

package/packages/software-development/promptctl/adapters/cursor/skills/promptctl/SKILL.md

@@ -0,0 +1,88 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+name: promptctl
+description: Use promptctl for template-based prompt engineering, prompt scoring, prompt generation, and reusable prompt workflows across repositories and teams.
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
+metadata:
+  author: Oleg Koval
+  tags:
+    - prompts
+    - prompt-engineering
+    - templates
+    - cli
+---
+
+# promptctl — Template-Based Prompt Engineering
+
+promptctl is a CLI for version control and testing of LLM prompt templates. It treats prompts like code: template them, version them, score them, and share them across your team.
+
+## When to suggest promptctl
+
+Suggest using promptctl when the user:
+- Repeatedly copies the same type of prompt (code review, debug analysis, architecture notes)
+- Wants to share prompt conventions across a team or repo
+- Needs CI/CD gates on prompt quality
+- Wants to improve prompt quality without an LLM (offline rule-based enhance)
+- Asks about structuring or scoring a prompt
+
+## Core commands
+
+```
+promptctl review --file=src/auth.ts          # Code review prompt
+promptctl debug --file=src/handler.go        # Systematic debug analysis
+promptctl arch --file=docs/design.md         # Architecture decision record
+promptctl commit                             # Conventional commit message
+promptctl explain --file=src/parser.ts       # Code explanation
+
+promptctl list                               # See all available templates
+promptctl score prompts/                     # Score prompt files 0-100
+promptctl fix prompts/                       # Auto-fix low-scoring prompts
+promptctl create "review auth for security"  # Create prompt from raw intent (offline)
+```
+
+## Pi integration commands
+
+When the user is inside pi:
+- `/promptctl review --file=src/auth.ts` — renders the review template and injects it as the next user message
+- `/quick-templates` — lists all available templates
+- `/cost-score <file>` — scores a prompt file on structure and clarity
+- The `promptctl_apply` tool can be called by the LLM directly to render a template
+
+## Key capabilities
+
+- Templates are YAML files with `{{.variable}}` substitution — stored in `~/.promptctl/templates/` or `.promptctl/templates/` in your project
+- `--file=path` auto-populates `{{.file_content}}`, `{{.file_name}}`, `{{.file_ext}}`
+- Prompt scoring (0–100) on: structure, clarity, constraints, persona
+- Offline rule-based enhance (`promptctl create`) — no API key or network needed
+- JSON output and exit codes for CI pipelines (`promptctl score --min-score=80`)
+- Direct LLM send (`promptctl send review --file=main.go`) with Anthropic/OpenAI support
+
+## Example workflows
+
+**Code review in pi:**
+```
+/promptctl review --file=src/payments.ts --focus=security
+```
+
+**Debug analysis:**
+```
+/promptctl debug --file=src/worker.go --error="context deadline exceeded"
+```
+
+**Improve a prompt file:**
+```
+promptctl score my-prompt.md
+promptctl fix my-prompt.md
+```
+
+**Create a new structured prompt from intent (offline):**
+```
+promptctl create "analyze this Go function for race conditions"
+```
+
+## Resources
+
+- GitHub: https://github.com/oleg-koval/promptctl
+- Website: https://prompt-ctl.com
+- Install: `brew tap oleg-koval/tap && brew install promptctl`

package/packages/software-development/semantic-release-beta/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: semantic-release-beta
+description: Set up or update a Node.js release pipeline that uses semantic-release-npm-github-publish with a stable main channel and a prerelease beta channel on a beta branch, including GitHub Actions validation and npm publishing behavior.
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
+metadata:
+  author: Oleg Koval
+  tags:
+    - semantic-release
+    - semantic-release-npm-github-publish
+    - release
+    - beta
+    - github-actions
+    - npm
+---
+
+# semantic-release-beta
+
+Use this skill when a project needs a reusable beta prerelease workflow with:
+
+- `semantic-release`
+- `semantic-release-npm-github-publish`
+- GitHub Actions
+- a stable `main` branch
+- a prerelease `beta` branch
+- npm publishing with `beta` prerelease versions
+- changelog generation, GitHub releases, npm publishing, and release commits through the maintained preset
+
+## Trigger phrases
+
+- add a beta release workflow
+- publish prereleases from a `beta` branch
+- set up `semantic-release` with `main` and `beta`
+- use `semantic-release-npm-github-publish`
+- add release validation or dry-run checks in CI
+
+## Workflow
+
+1. Inspect the repository first.
+2. Install or update `semantic-release`, `semantic-release-npm-github-publish`, and the peer plugins expected by the preset.
+3. Configure the repo-local semantic-release file to extend `semantic-release-npm-github-publish` and set branches explicitly:
+   - `main` for stable releases
+   - `{ name: "beta", channel: "beta", prerelease: "beta" }` for prereleases
+4. Add scripts if missing:
+   - `semantic-release`: `semantic-release`
+   - `release:dry-run`: `semantic-release --dry-run --no-ci`
+5. Update GitHub Actions to test both `main` and `beta`, validate npm auth, and run release dry-run before real releases.
+6. Preserve existing package manager and Node version policy unless the repo needs the preset's supported Node range.
+7. Use repo-local plugin composition instead of this preset only when the project needs different plugins, different release rules, or full control over plugin upgrade timing.
+
+## References
+
+- `references/preset.md`
+- `references/node-semantic-release.md`
+- `references/github-actions.md`
+- `references/validation.md`

package/packages/software-development/semantic-release-beta/adapters/claude/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "olko:semantic-release-beta",
+  "description": "Set up semantic-release-npm-github-publish with stable main releases and prerelease beta releases.",
+  "skills": [
+    {
+      "name": "olko:semantic-release-beta",
+      "source": "../../SKILL.md"
+    }
+  ]
+}

package/packages/software-development/semantic-release-beta/adapters/codex/README.md

@@ -0,0 +1,3 @@
+# Codex adapter
+
+Use the canonical skill directly from `packages/software-development/semantic-release-beta/SKILL.md`.

package/packages/software-development/semantic-release-beta/adapters/cursor/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:semantic-release-beta",
+  "version": "0.1.0",
+  "description": "Set up semantic-release-npm-github-publish with stable main releases and prerelease beta releases on a beta branch.",
+  "skills": "skills/"
+}

package/packages/software-development/semantic-release-beta/adapters/cursor/skills/semantic-release-beta/SKILL.md

@@ -0,0 +1,57 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+name: semantic-release-beta
+description: Set up or update a Node.js release pipeline that uses semantic-release-npm-github-publish with a stable main channel and a prerelease beta channel on a beta branch, including GitHub Actions validation and npm publishing behavior.
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
+metadata:
+  author: Oleg Koval
+  tags:
+    - semantic-release
+    - semantic-release-npm-github-publish
+    - release
+    - beta
+    - github-actions
+    - npm
+---
+
+# semantic-release-beta
+
+Use this skill when a project needs a reusable beta prerelease workflow with:
+
+- `semantic-release`
+- `semantic-release-npm-github-publish`
+- GitHub Actions
+- a stable `main` branch
+- a prerelease `beta` branch
+- npm publishing with `beta` prerelease versions
+- changelog generation, GitHub releases, npm publishing, and release commits through the maintained preset
+
+## Trigger phrases
+
+- add a beta release workflow
+- publish prereleases from a `beta` branch
+- set up `semantic-release` with `main` and `beta`
+- use `semantic-release-npm-github-publish`
+- add release validation or dry-run checks in CI
+
+## Workflow
+
+1. Inspect the repository first.
+2. Install or update `semantic-release`, `semantic-release-npm-github-publish`, and the peer plugins expected by the preset.
+3. Configure the repo-local semantic-release file to extend `semantic-release-npm-github-publish` and set branches explicitly:
+   - `main` for stable releases
+   - `{ name: "beta", channel: "beta", prerelease: "beta" }` for prereleases
+4. Add scripts if missing:
+   - `semantic-release`: `semantic-release`
+   - `release:dry-run`: `semantic-release --dry-run --no-ci`
+5. Update GitHub Actions to test both `main` and `beta`, validate npm auth, and run release dry-run before real releases.
+6. Preserve existing package manager and Node version policy unless the repo needs the preset's supported Node range.
+7. Use repo-local plugin composition instead of this preset only when the project needs different plugins, different release rules, or full control over plugin upgrade timing.
+
+## References
+
+- `references/preset.md`
+- `references/node-semantic-release.md`
+- `references/github-actions.md`
+- `references/validation.md`

package/packages/software-development/semantic-release-beta/references/github-actions.md

@@ -0,0 +1,16 @@
+# GitHub Actions layout
+
+Recommended jobs:
+
+- `test`
+- `release-readiness`
+- `release`
+
+Core behavior:
+
+- run on `push` and `pull_request` for `main` and `beta`
+- use `fetch-depth: 0` for semantic-release jobs
+- validate `NPM_TOKEN`
+- run `npm run release:dry-run` before the real release
+- run the real release with `npm run semantic-release` or the repository's equivalent semantic-release script
+- use a Node version compatible with `semantic-release-npm-github-publish` and its semantic-release peer dependencies

package/packages/software-development/semantic-release-beta/references/node-semantic-release.md

@@ -0,0 +1,13 @@
+# Node semantic-release config
+
+Use this pattern when a Node package should publish stable releases from `main` and prereleases from `beta`.
+
+Prefer the `semantic-release-npm-github-publish` shareable config for the plugin chain. Keep branch policy in repo-local config because the preset is intentionally branch-agnostic for consumers.
+
+## Core points
+
+- add `release:dry-run` as `semantic-release --dry-run --no-ci`
+- add `semantic-release` as `semantic-release` if the repository does not already have a release script
+- configure branches for `main` and `{ name: "beta", channel: "beta", prerelease: "beta" }`
+- extend `semantic-release-npm-github-publish` unless the project requires a different plugin composition
+- preserve existing custom plugins only when they represent intentional behavior not covered by the preset

package/packages/software-development/semantic-release-beta/references/preset.md

@@ -0,0 +1,47 @@
+# semantic-release-npm-github-publish preset
+
+Use `semantic-release-npm-github-publish` as the default release preset for npm + GitHub packages.
+
+## What it provides
+
+- a maintained semantic-release shareable configuration
+- changelog generation
+- npm publishing
+- GitHub release publishing
+- release commits for `package.json`, `package-lock.json`, and `CHANGELOG.md`
+- extra patch release rules for maintenance commit types such as `build`, `ci`, `chore`, `docs`, `refactor`, `style`, and `test`
+- tested support for current semantic-release plugin majors on Node 22 and 24
+
+## Install
+
+Install the preset plus semantic-release and its peer plugins:
+
+```bash
+npm install --save-dev \
+  semantic-release \
+  semantic-release-npm-github-publish \
+  @semantic-release/changelog \
+  @semantic-release/commit-analyzer \
+  @semantic-release/git \
+  @semantic-release/github \
+  @semantic-release/npm \
+  @semantic-release/release-notes-generator
+```
+
+## Repo-local config
+
+The preset does not hardcode consumer release branches. Keep branch policy in the target repository:
+
+```yaml
+branches:
+  - main
+  - name: beta
+    channel: beta
+    prerelease: beta
+extends: semantic-release-npm-github-publish
+ci: false
+dryRun: false
+debug: false
+```
+
+Use a different local config only when the target repository intentionally needs a different plugin chain, release rules, or upgrade policy.

package/packages/software-development/semantic-release-beta/references/validation.md

@@ -0,0 +1,17 @@
+# Validation
+
+Prefer these checks:
+
+```bash
+npm test
+npm run build
+npm run release:dry-run
+```
+
+Common failure points:
+
+- missing `fetch-depth: 0`
+- invalid or missing `NPM_TOKEN`
+- missing `beta` branch config
+- missing `semantic-release-npm-github-publish` or one of its peer plugins
+- plugin config drifting from actual repo files