--- name: docker description: Optimize Docker images with multi-stage builds, distroless bases, BuildKit cache mounts, multi-arch builds, compose watch, security hardening (non-root, seccomp, capabilities drop), and vulnerability scanning via docker scout/trivy. Use when user asks to write a Dockerfile, optimize image size, set up docker-compose, debug containers, harden container security, or scan for CVEs. Do NOT use for Kubernetes deployments (use kubernetes), CI/CD pipeline design (use ci-cd), or Terraform (use terraform). license: MIT compatibility: opencode metadata: workflow: infrastructure audience: devops version: "3.0" author: shokunin allowed-tools: Read Bash Write --- # Docker Architect Production-grade Dockerfiles, multi-stage builds, cache optimization, security scanning, and local development. Applies Google's distroless philosophy and Docker BuildKit best practices. ## Decision Framework Before containerizing, answer: - Does the app need process isolation? → Docker - Will it deploy to Kubernetes? → Docker + distroless + non-root - Is it a monolith with simple deployment? → Docker Compose - Is it a static site? → Consider nginx:alpine single-stage - Is the team already using Docker Compose in dev? → Start there, add K8s when needed - Is the app latency-sensitive (sub-ms)? → Bare metal or VM; container overhead matters at extreme scale ## Workflow ### Quick start: `docker init` For new projects, run `docker init` in the project root. It auto-detects the language/framework and generates a Dockerfile, `.dockerignore`, and `compose.yaml` with best-practice defaults. Always review and harden the output — the generated files are a starting point, not production-ready. ### Step 1: Identify stack and choose template | Stack | Base image | Build stage | Runtime | |-------|-----------|-------------|---------| | Node.js | node:22-slim | Full SDK | gcr.io/distroless/nodejs | | Go | golang:1.23-alpine | Full SDK | scratch | | Python | python:3.12-slim | Full SDK | python:3.12-slim | | Rust | rust:1.78-slim | Full SDK | gcr.io/distroless/cc | **Decision**: If the stack is listed above, use the corresponding production Dockerfile below. If not, apply the golden template in Step 2. ### Step 2: Apply golden template Use multi-stage with this exact structure: ``` Stage 1 (deps): COPY lock files → install production deps (--mount=type=cache) Stage 2 (build): COPY source → compile Stage 3 (runtime): minimal base → COPY artifacts from stages 1-2 → USER nonroot → HEALTHCHECK ``` **If the project is a Go binary**, skip Stage 1 (Go has no runtime deps) and go straight to Stage 2. **If the project has native dependencies** (node-gyp, C extensions), use `apt-get` in the builder stage, NOT the runtime stage. ### Step 3: Apply BuildKit optimizations ```dockerfile # syntax=docker/dockerfile:1.4 FROM node:22-slim AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev FRO ...[truncated]
Infrastructure
5 skills--- name: kubernetes description: Deploy, manage, and debug Kubernetes in production — Deployments, Services, Gateway API, Service Mesh (Istio/Linkerd/Cilium), eBPF observability (Cilium Hubble), security hardening (Pod Security Standards, OPA/Kyverno, seccomp, runtime security with Falco/Tetragon), Helm, HPA, PDB, topology spread, and debugging. Use when user asks to write K8s manifests, deploy to a cluster, debug pods, set up Gateway API, configure autoscaling, or harden cluster security. Do NOT use for Dockerfiles (use docker), CI/CD pipeline design (use ci-cd), or Terraform infrastructure (use terraform). license: MIT compatibility: opencode metadata: workflow: infrastructure audience: devops version: "3.0" author: shokunin allowed-tools: Read Bash Write Grep Glob triggers: - k8s - kubernetes - deploy - pod - cluster - helm - kustomize - kubectl - service mesh - istio - linkerd - cilium - gateway api - hpa - network policy - statefulset - daemonset --- # Kubernetes Architect Production-grade Kubernetes: deployments, Gateway API, zero-trust networking, service mesh, eBPF observability, and debugging. Follows NSA/CISA hardening guidelines. ## Decision Framework Before deploying to Kubernetes, answer: - Does the app need horizontal scaling (3+ replicas)? → Kubernetes - Is it a single-instance app with simple needs? → Docker Compose or VPS - Is the team already familiar with Kubernetes? → Proceed. If not, consider managed (EKS, GKE, AKS) - Does the app need advanced networking (service mesh, ingress routing)? → Kubernetes + Gateway API - Is the infrastructure budget tight? → Single-node k3s or Docker Compose for dev - Multiple services with different scaling profiles? → Kubernetes (HPA per service) ## Workflow ### Step 1: Determine deployment type | Type | Kind | Use case | |------|------|----------| | Stateless | Deployment | Web APIs, workers | | Stateful | StatefulSet | Databases, queues (use with caution) | | Batch | Job/CronJob | Migrations, periodic tasks | | Daemon | DaemonSet | Logging, monitoring agents | If uncertain, start with a Deployment. See [assets/deployment-template.yaml](assets/deployment-template.yaml) for the full production template. ### Step 2: Generate manifest Use the scaffold script: ```bash scripts/generate-manifest.sh -n api -i myregistry.com/api:1.0.0 -p 3000 -r 3 -o manifests/ ``` This creates: `deployment.yaml`, `service.yaml`, `hpa.yaml`, `pdb.yaml` with all security contexts, probes, resource requests/limits, and topology spread constraints pre-configured. **If the service expects HTTP traffic**, also create a Gateway API HTTPRoute. ### Template alternatives: Helm and Kustomize The scaffold script above generates raw manifests. For more complex deployments, consider: | Tool | Best for | Pattern | |------|----------|---------| | **Helm** (`helm create`) | Packaging reusable apps, versioned releases, templating | `values.yaml` → Go templates → rendered manifes ...[truncated]
---
name: terraform
description: Design and manage infrastructure as code with Terraform — modules, remote state (S3 + DynamoDB), Stacks (deployments), test framework, preconditions/postconditions, moved/removed blocks, and CI/CD plan/apply separation. Use when user asks to write Terraform config, set up remote state, design modules, manage state, or automate infrastructure. Do NOT use for Kubernetes (use kubernetes), Docker (use docker), or CI/CD pipeline design (use ci-cd).
license: MIT
compatibility: opencode
metadata:
workflow: infrastructure
audience: devops
version: "2.0"
---
# Terraform Architect
Design infrastructure as code with Terraform 1.10+ features: Stacks, test framework, provider-defined functions, and state management.
## Workflow
### Step 1: Determine project structure
| Scale | Structure | State Strategy |
|-------|-----------|---------------|
| Personal | Single `main.tf` | Remote backend, optional workspaces |
| Team (2-5) | `envs/{dev,prod}/modules/` | Directory-per-environment, separate backends |
| Platform team | `infra/{networking,compute,data,iam}/` per repo | Per-component state, `terraform_remote_state` |
### Step 2: Bootstrap remote backend
```hcl
# backend.tf
terraform {
backend "s3" {
bucket = "tf-state-{account}-{region}"
key = "{env}/{component}/terraform.tfstate"
region = "us-east-1"
encrypt = true
dynamodb_table = "tf-state-lock"
}
required_version = ">= 1.10"
required_providers {
aws = { source = "hashicorp/aws", version = "~> 5.0" }
}
}
```
### Step 3: Design modules
Single responsibility: one module = one domain.
```
modules/
├ networking/
│ main.tf, variables.tf, outputs.tf
├ compute/
│ main.tf, variables.tf, outputs.tf
└ database/
main.tf, variables.tf, outputs.tf
environments/
├ prod/
│ backend.tf -> key = "prod/compute/terraform.tfstate"
│ main.tf module "compute" { source = "../../modules/compute" }
│ terraform.tfvars
└ dev/
```
### Step 4: Use preconditions/postconditions
```hcl
resource "aws_db_instance" "main" {
allocated_storage = 100
engine = "postgres"
engine_version = "16.3"
instance_class = "db.r6g.large"
lifecycle {
postcondition {
condition = self.engine == "postgres"
error_message = "Only PostgreSQL is supported"
}
}
}
data "aws_iam_policy_document" "example" {
statement {
actions = ["s3:GetObject"]
condition {
test = "Bool"
variable = "aws:SecureTransport"
values = ["true"]
}
condition {
test = "IpAddress"
variable = "aws:SourceIp"
values = var.allowed_ips
}
}
lifecycle {
precondition {
condition = length(var.allowed_ips) > 0
error_message = "At least one allowed IP must be specified"
}
}
}
```
### Step 5: Use moved and removed blocks for refactoring
```hcl
# Instead of manual state mv, code-review it:
moved {
from = aws_s3_bucket.old
to = m
...[truncated]
--- name: ci-cd description: Design CI/CD pipelines for GitHub Actions, GitLab CI, and CircleCI with matrix builds, test sharding, caching, Docker layer caching, OIDC auth, deployment strategies (rolling, blue-green, canary), auto-rollback, self-hosted runners, and environment protection with manual approvals. Use when user asks to set up CI/CD, write a pipeline, configure GitHub Actions/GitLab CI/CircleCI, automate deployments, or set up build/test/deploy workflows. Do NOT use for Dockerfile authoring (use docker), K8s manifests (use kubernetes), or Terraform config (use terraform). license: MIT compatibility: opencode metadata: workflow: infrastructure audience: devops version: "3.0" author: shokunin allowed-tools: Read Bash Write Grep --- # CI/CD Architect Design fast, reliable, and secure CI/CD pipelines across GitHub Actions, GitLab CI, and CircleCI. Follows Google's DevOps capabilities and DORA metrics. ## Decision Framework Before building a CI/CD pipeline, answer: - Where is the code hosted? → If GitHub, start with GitHub Actions. If GitLab, use GitLab CI. On-prem? Consider self-hosted. - What's the deployment target? → Cloud (use OIDC), on-prem (use self-hosted runner), multi-cloud (use environment-specific jobs) - Is the team size 1-3? → Simple single-workflow. 10+? → Separate build, test, deploy workflows with artifact passing. - Do you need matrix builds (multiple OS/versions)? → Yes for libraries, no for single-platform apps. - Is the deploy target production? → Require manual approval gates. Non-prod: automatic on merge. ## Workflow ### Step 1: Choose platform | Platform | Best for | Config location | |----------|----------|----------------| | GitHub Actions | OSS, GitHub ecosystem | `.github/workflows/*.yml` | | GitLab CI | Self-hosted, monorepos | `.gitlab-ci.yml` | | CircleCI | Performance, Docker | `.circleci/config.yml` | **Decision**: If the project is on GitHub.com, use GitHub Actions. If self-hosted GitLab, use GitLab CI. If maximum performance needed, use CircleCI. ### Step 2: Generate pipeline Use the scaffold script with your platform and stack: ```bash scripts/generate-pipeline.sh --platform github --language node --e2e --docker scripts/generate-pipeline.sh --platform gitlab --language python --docker scripts/generate-pipeline.sh --platform circle --language go --e2e ``` This generates a production-ready pipeline with: - Lint → typecheck → test (sharded) → build → docker → deploy - Caching (npm/pip/go, Docker layers) - OIDC auth (no static secrets) - Environment gates (staging → production) ### Step 3: Configure caching | Cache type | GitHub Actions | GitLab CI | CircleCI | |-----------|---------------|-----------|----------| | npm/pip/go | `actions/cache` with lockfile hash | `cache:key:` with lockfile hash | `save_cache` / `restore_cache` | | Docker layers | `docker/build-push-action` GHA cache | Docker layer caching on self-hosted | Remote Docker engine cache | | Playwright browsers | `npx playwri ...[truncated]
---
name: db-admin
description: PostgreSQL database administration — backup/restore (pg_dump, PITR, WAL archiving), health monitoring (connections, bloat, cache hit ratio, dead tuples), connection pooling (PgBouncer), replication (streaming, logical), vacuum/autovacuum tuning, and scheduled backups with retention. Use when user asks to backup a database, restore from backup, monitor database health, set up replication, or perform DBA tasks. Do NOT use for schema design (use db-sculptor), query optimization (use db-sculptor), or migration planning (use db-sculptor).
license: MIT
compatibility: opencode
metadata:
workflow: operations
audience: devops
version: "3.0"
author: shokunin
allowed-tools: Read Bash Write
---
# Database Administrator
PostgreSQL production operations: backup, restore, monitoring, replication, and maintenance.
## Workflow
### Step 1: Run health check
```powershell
scripts/monitor-db.ps1 -Database myapp
```
Checks 7 metrics:
| Metric | Warning | Fail |
|--------|---------|------|
| Connection count | > 80% of max | > 95% of max |
| Active queries | > 10 | > 20 |
| Long-running (>5m) | Any | > 3 |
| Cache hit ratio | < 99% | < 95% |
| Dead tuple ratio | > 20% | > 40% |
| Index usage (unused) | > 5 | > 10 |
**If any metric is FAIL**: investigate immediately. See [references/postgres-admin.md](references/postgres-admin.md) for diagnosis and fix procedures.
### Step 2: Backup database
```powershell
# Full backup
scripts/backup-db.ps1 -Database myapp
# Custom output directory
scripts/backup-db.ps1 -Database myapp -OutputDir D:\backups
# Exclude large log tables
scripts/backup-db.ps1 -Database myapp -ExcludeTables @("audit_logs", "analytics_events")
```
The script creates: `myapp_2026-05-13_143022.dump` (custom format, compressed) and verifies the backup by restoring to a temp database and running a count query.
### Step 3: Set up scheduled backups
See [assets/backup-schedule-template.ps1](assets/backup-schedule-template.ps1) for the schedule template.
```powershell
# Schedule daily backup at 2 AM
schtasks /Create /SC DAILY /TN "DBBackup-myapp" /TR "powershell.exe -File C:\scripts\backup-schedule.ps1" /ST 02:00
```
**Retention policy:**
- Daily: keep 7
- Weekly: keep 4 (Sundays)
- Monthly: keep 3 (1st of month)
### Step 4: Configure connection pooling
```ini
# pgbouncer.ini for PostgreSQL pooling
[databases]
myapp = host=localhost port=5432 dbname=myapp
[pgbouncer]
listen_port = 6432
listen_addr = 127.0.0.1
auth_type = scram-sha-256
pool_mode = transaction
default_pool_size = 25
max_client_conn = 100
max_db_connections = 50
```
### Step 5: Set up replication (if needed)
See [references/postgres-admin.md](references/postgres-admin.md) for streaming and logical replication setup.
**Decision:**
| Need | Replication type |
|------|-----------------|
| Read scaling + HA | Streaming replication |
| Selective table sync | Logical replication |
| Upgrade with minimal downtime | Logical replication |
| Cross-vers
...[truncated]
Backend
5 skills---
name: api-forge
description: Design REST/GraphQL APIs with OpenAPI 3.1, error handling, pagination, rate limiting, webhooks, and idempotency. Use when user asks to design an API, create endpoints, define REST/GraphQL schema, or generate OpenAPI spec. Do NOT use for database schema design, frontend API integration, or non-HTTP protocols (gRPC, WebSocket, MQTT).
triggers:
- "design an API"
- "create endpoints"
- "REST API"
- "GraphQL schema"
- "OpenAPI spec"
- "rate limiting"
- "webhooks"
- "idempotency"
- "API pagination"
- "API versioning"
- "API security"
negatives:
- "database schema"
- "frontend integration"
- "gRPC"
- "WebSocket"
- "MQTT"
- "database design"
license: MIT
compatibility: opencode
metadata:
workflow: backend
audience: developers
version: "4.0"
author: shokunin
---
# API Forge
Design APIs that developers love. Based on patterns from Stripe, GitHub, Twilio, Slack, and the OpenAPI 3.1 specification.
## Sub-Commands
| Command | Category | Description |
|---------|----------|-------------|
| `design` | Build | Design an API from user requirements. Generate OpenAPI 3.1 spec. |
| `endpoint` | Build | Design a single endpoint with all methods, parameters, responses, and error codes. |
| `audit` | Evaluate | Audit an existing API against design rules, security checklist, and anti-patterns. |
| `document` | Document | Generate API documentation from OpenAPI spec or route handlers. |
| `extract` | Document | Extract OpenAPI spec from existing route handlers. |
| `webhook` | Build | Design webhook delivery, retry, and signature verification. |
## Workflow
### Step 1: Determine API type
| Type | Use Case | Spec |
|------|----------|------|
| REST | CRUD, resource-oriented | OpenAPI 3.1 |
| GraphQL | Complex queries, multiple resources | Schema Definition Language |
| Webhook | Event-driven, async notifications | Standard webhooks (Stripe pattern) |
### Step 2: Define resources and naming
| Pattern | Example | Notes |
|---------|---------|-------|
| Nouns, plural | `/users`, `/orders` | Never verbs |
| Nested (max 2 levels) | `/users/{id}/orders` | Flat preferred over deep nesting |
| Actions as sub-resources | `/orders/{id}/cancel` | Only for non-CRUD operations |
| Query for filters | `/users?role=admin` | Not `/users/admins` |
| kebab-case for paths | `/order-items` | Not `/orderItems` |
| snake_case for fields | `first_name` | Not `firstName` in JSON:API |
### Step 3: Map HTTP methods
| Method | Purpose | Idempotent | Safe | Body |
|--------|---------|:--:|:--:|:--:|
| GET | Read resource | Yes | Yes | No |
| POST | Create resource | No | No | Yes |
| PUT | Full replace | Yes | No | Yes |
| PATCH | Partial update | No | No | Yes |
| DELETE | Remove resource | Yes | No | Optional |
### Step 4: Design response format
Stripe-style standard envelope:
```json
{
"data": {},
"meta": {
"page": 1,
"per_page": 25,
"total": 100
},
"error": null,
"request_id": "req_abc
...[truncated]
---
name: auth-architect
description: Implement authentication and authorization with OWASP Top 10 standards, OAuth 2.0 + OIDC, WebAuthn/Passkeys, session management, and RBAC/ABAC. Use when user asks to implement login, signup, authentication, authorization, JWT, OAuth, SSO, passkeys, MFA, or role-based access. Do NOT use for API key management (use api-forge), encryption at rest, or network-level security (firewalls, WAF).
license: MIT
compatibility: opencode
metadata:
workflow: backend
audience: developers
version: "4.0"
author: shokunin
---
# Auth Architect
Production authentication following OWASP Top 10, NIST SP 800-63B, and patterns from Auth0, AWS Cognito, and the OWASP Cheat Sheet Series.
## Sub-Commands
| Command | Description |
|---------|-------------|
| `implement` | Implement full authentication system (login, signup, sessions, MFA, password reset) |
| `audit` | Audit existing auth against OWASP Top 10 checklist |
| `enforce` | Add missing security measures (rate limiting, CSRF, session rotation) |
| `teach` | Set up auth context file (AUTH.md) with project-specific configuration |
## Workflow
### Step 1: Choose auth method
| Method | Use Case | Security | Complexity |
|--------|----------|:--------:|:----------:|
| Session-based (httpOnly cookies) | Server-rendered web apps | High | Low |
| JWT access + refresh tokens | SPAs, mobile, APIs | High (with proper storage) | Medium |
| OAuth 2.0 + OIDC | Third-party login, SSO | High | High |
| API keys with HMAC | M2M, CLIs, integrations | Medium | Low |
| WebAuthn / Passkeys | Passwordless, high-security | Very High | Medium |
| Magic links / OTP | Low-friction, email-based | Medium | Low |
### Step 2: Implement authentication
#### Password-based auth
```
1. Validate email format + length (< 254 chars)
2. Check against breached passwords (HaveIBeenPwned API k-anonymity)
3. Hash with Argon2id: memory=19456, iterations=2, parallelism=1
OR BCrypt: cost=12 minimum
4. Generate session UUIDv4 via crypto.randomUUID()
5. Store session server-side (Redis, TTL=24h)
6. Set cookie: httpOnly, Secure, SameSite=Strict
7. Return user object (never return password hash)
```
**Password requirements** (NIST SP 800-63B):
- Minimum 12 characters (no max below 64)
- NO composition rules (uppercase, number, symbol required - these weaken security, NIST §5.1.1.2)
- Allow all printable ASCII + Unicode
- Check against HaveIBeenPwned API (k-anonymity, SHA-1 prefix)
- Rate limit: 5 attempts per 15 min per IP + username
#### JWT implementation
```json
{
"iss": "https://api.example.com",
"sub": "user_abc123",
"aud": ["web", "mobile"],
"exp": 900,
"iat": 1700000000,
"jti": "a1b2c3d4e5f6",
"sid": "sess_xyz789"
}
```
**Exact values:**
- Access token: 15 min expiry. Algorithm: RS256 (asymmetric) or HS256 (symmetric, single service).
- Refresh token: 7 day expiry. Rotation on every use.
- Refresh token reuse detection: revoke ALL tokens if a used refresh token is presented (theft i
...[truncated]
--- name: db-sculptor description: Design database schemas with Prisma/Drizzle, PostgreSQL index strategy (B-tree, GIN, GiST, BRIN, Hash), query optimization (EXPLAIN ANALYZE), migration safety (expand/contract, zero-downtime), and sharding/partitioning. Use when user asks to design schema, create migrations, optimize slow queries, add indexes, choose between SQL/NoSQL, or set up Prisma/Drizzle. Do NOT use for data warehouse dimensional modeling, ETL pipeline design, or non-relational (MongoDB, DynamoDB) schema design. license: MIT compatibility: opencode metadata: workflow: backend audience: developers version: "4.0" author: shokunin allowed-tools: Read Bash Write Grep --- # DB Sculptor Design performant database schemas. Model for access patterns first, normalize later. Based on PostgreSQL internals, Prisma/Drizzle best practices, and production patterns from PlanetScale, Neon, and pganalyze. ## Sub-Commands | Command | Description | |---------|-------------| | `design` | Design a schema from access patterns and data volume estimates | | `index` | Analyze queries and recommend/create optimal indexes | | `optimize` | Diagnose slow queries with EXPLAIN ANALYZE and fix them | | `migrate` | Create a safe, zero-downtime migration (expand/contract) | | `audit` | Audit existing schema against best practices and anti-patterns | ## Workflow ### Step 1: Model for access patterns | Question | Determine | |----------|-----------| | Read/write ratio? | How many indexes can the table support | | Data volume? | Current rows, growth rate/month | | Consistency requirements? | ACID vs eventual, read replicas OK? | | Latency budget? | p50 < 5ms, p95 < 50ms, p99 < 200ms | **Decision tree:** - High write volume, simple reads → Normalize (3NF). Minimum indexes. - High read volume, complex joins → Denormalize strategically. Add composite + covering indexes. - Time-series data → Partition by time (monthly). BRIN indexes on timestamp. - Full-text search needed → GIN index with `tsvector` + `tsquery`. - JSON queries → GIN index on JSONB column. ### Step 2: Primary key strategy | PK type | Pros | Cons | When | |---------|------|------|------| | UUIDv7 | Time-sortable, globally unique, no collision risk | Larger than bigint (16 bytes vs 8) | Default for user-facing. Distributed systems. | | UUIDv4 | Random, globally unique | Non-sortable = index fragmentation | Legacy. Avoid for new schemas. | | bigint (auto-increment) | Fast, compact, sequential | Predictable, not globally unique | Internal/analytics tables. Never for user-facing. | | ULID | Time-sortable, URL-safe | 26 chars | When human-readable time ordering matters. | **Default: UUIDv7 for all user-facing tables.** ### Step 3: Add indexes strategically | Index type | Use case | Example | |-----------|----------|---------| | B-tree (default) | Equality, range, sort, ORDER BY | `CREATE INDEX ON users (email)` | | Composite | Multi-column WHERE, ORDER BY | `CREATE INDEX ON orders (user_id, status, ...[truncated]
---
name: error-handler
description: Design error handling, structured logging, and observability with OpenTelemetry (traces, metrics, logs), error classification, recovery patterns (retry with jitter, circuit breaker, bulkhead, timeout), error budgets/SLOs with burn rate alerts, and production incident triage. Use when user asks to implement error handling, logging, monitoring, observability, OpenTelemetry, error boundaries, circuit breakers, retry logic, or SLO tracking. Do NOT use for incident runbooks (use runbook-gen), vendor-specific APM setup (Datadog, Sentry agent config), or K8s debugging.
license: MIT
compatibility: opencode
metadata:
workflow: backend
audience: developers
version: "4.0"
author: shokunin
allowed-tools: Read Bash Write Grep
---
# Error Handler
Observability that makes debugging fast and production predictable. Based on Google SRE (Site Reliability Engineering), OpenTelemetry semantic conventions, and production patterns from Sentry, Honeycomb, and Datadog.
## Sub-Commands
| Command | Description |
|---------|-------------|
| `setup` | Set up OpenTelemetry SDK + instrumentation for a service |
| `classify` | Classify errors by HTTP status, severity, and alert priority |
| `recover` | Implement recovery patterns: retry with jitter, circuit breaker, timeout |
| `slo` | Define error budget, SLO, and burn rate alerts |
| `audit` | Audit existing error handling against best practices |
## The 3 Signals (OpenTelemetry)
| Signal | Purpose | Example |
|--------|---------|---------|
| Traces | Follow a request across services | User request ? API Gateway ? Auth ? DB |
| Metrics | Aggregate measurements over time | Request count, error rate, latency p50/p95/p99 |
| Logs | Discrete events with context | "User login failed: invalid credentials for user_abc123" |
All three signals share `trace_id` + `span_id` for correlation.
## Workflow
### Step 1: Classify errors
| Category | HTTP | Severity | Log level | SLO impact | Alert? |
|----------|------|:--------:|-----------|:----------:|:------:|
| Validation (user error) | 400 | Low | info | No | No |
| Authentication | 401 | Medium | warn | No | Only if spike detected |
| Authorization | 403 | Medium | warn | No | Only if spike detected |
| Not Found | 404 | Low | debug | No | No |
| Conflict | 409 | Medium | info | No | No |
| Rate Limit | 429 | Low | warn | No | No |
| Internal | 500 | High | error | Yes | Yes |
| Downstream failure | 502/503 | High | error | Yes | Yes |
| Timeout | 504 | High | error | Yes | Yes |
### Step 2: Set up OpenTelemetry (exact configuration)
```typescript
import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } from '@opentelemetry/resources'
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
const sdk = new NodeSDK({
resource: new Resource({
[ATTR_SERVICE_NAME]: 'api-service',
'deployment.environment': process.env.NOD
...[truncated]
--- name: neon-postgres description: Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. Use for any Neon-related questions. --- # Neon Serverless Postgres Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres. ## Neon Documentation The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data. ### Fetching Docs as Markdown Any Neon doc page can be fetched as markdown in two ways: 1. **Append `.md` to the URL** (simplest): https://neon.com/docs/introduction/branching.md 2. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching` Both return the same markdown content. Use whichever method your tools support. ### Finding the Right Page The docs index lists every available page with its URL and a short description: ``` https://neon.com/docs/llms.txt ``` Common doc URLs are organized in the topic links below. If you need a page not listed here, search the docs index: https://neon.com/docs/llms.txt — don't guess URLs. ## What Is Neon Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice. Link: https://neon.com/docs/ai/skills/neon-postgres/references/what-is-neon.md ## Getting Started Use this for first-time setup: org/project selection, connection strings, driver installation, optional auth, and initial schema setup. Link: https://neon.com/docs/ai/skills/neon-postgres/references/getting-started.md ## Connection Methods & Drivers Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, long-running). Link: https://neon.com/docs/ai/skills/neon-postgres/references/connection-methods.md ### Serverless Driver Use this for `@neondatabase/serverless` patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations. Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-serverless.md ### Neon JS SDK Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup. Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-js.md ## Developer Tools Use this for local development enablement with `npx neonctl@latest init`, VSCode extension setup, and Neon MCP server configuration. Link: https://neon.com/docs/ai/ski ...[truncated]
Frontend
11 skills---
name: component-forge
description: Build production-grade components for React, Vue 3, and Svelte 5 with all states (loading, empty, error, success, idle), TypeScript strict, WCAG 2.2 accessibility, server components (RSC), and compound component patterns. Includes scaffold script, reference patterns, and template files for React and Vue. Use when user asks to create a UI component, frontend module, or design system component. Do NOT use for page layouts (use landing-craft), routing, or state management architecture (global stores).
license: MIT
compatibility: opencode
metadata:
workflow: frontend
audience: developers
version: "4.0"
author: shokunin
allowed-tools: Read Bash Write Grep Glob
---
# Component Forge
Build components that survive every state, at every screen size, under every edge case. Inspired by Heydon Pickering (Inclusive Components), React core team patterns, and Emil Kowalski's design engineering philosophy.
## Workflow
### Step 1: Determine component type
| Type | Description | Example |
|------|-------------|---------|
| Presentational | Pure rendering, props-driven | Button, Card, Badge |
| Composable | Wraps children with behavior | Modal, Tooltip, Accordion |
| Data-fetching | Reads from API/store | UserProfile, OrderList |
| Layout | Arranges children | Sidebar, Grid, Stack |
| Form | Input + validation | LoginForm, SearchInput |
### Step 2: Scaffold component
```bash
scripts/scaffold-component.sh Button react
scripts/scaffold-component.sh Modal vue
scripts/scaffold-component.sh Accordion svelte
```
> **Windows:** The scaffold script requires Git Bash or WSL. Not compatible with PowerShell or CMD.
Creates:
```
Button/
Button.tsx
Button.types.ts
Button.test.tsx
index.ts
```
### Step 3: Implement states with discriminated union
```tsx
type State<T> =
| { status: 'idle' }
| { status: 'loading' }
| { status: 'empty' }
| { status: 'error'; error: Error }
| { status: 'success'; data: T }
function Profile({ userId }: { userId: string }) {
const [state, setState] = useState<State<User>>({ status: 'idle' })
if (state.status === 'loading') return <LoadingSkeleton />
if (state.status === 'error') return <ErrorState error={state.error} onRetry={fetch} />
if (state.status === 'empty') return <EmptyState message="No user found" />
if (state.status === 'success') return <UserProfile user={state.data} />
return null
}
```
**Every data-fetching component renders all five states.**
### Step 4: Apply accessibility checklist
- [ ] All interactive elements keyboard reachable (Tab ? Enter/Space)
- [ ] ARIA labels on icon-only buttons
- [ ] Focus trap in modals and dialogs
- [ ] Loading state announced via `aria-live="polite"`
- [ ] Error state has `role="alert"`
- [ ] Color is not the only differentiator (add icon/text)
- [ ] Proper heading hierarchy (h1 ? h2 ? h3, no skips)
- [ ] Touch targets = 44-44px
- [ ] `prefers-reduced-motion` respected
See [references/a11y-patterns.md](reference
...[truncated]
---
name: responsive-engine
description: Design multi-device layouts with Container Queries, clamp() fluid typography, :has() selector, subgrid, and modern CSS units (dvh/svh/lvh). Use when user asks to make a layout responsive, handle mobile/tablet/desktop breakpoints, create fluid typography, or use Container Queries. Do NOT use for full-page layouts (use landing-craft), component design (use component-forge), or animation-specific responsive (use motion-craft).
license: MIT
compatibility: opencode
metadata:
workflow: frontend
audience: developers
version: "4.0"
author: shokunin
---
# Responsive Engine
Layouts that work at every screen size without breakpoint spaghetti. Inspired by Ahmad Shadeed (Container Queries), Jen Simmons (Intrinsic Web Design), and the CSS Working Group.
## Core Principle
Responsive design is about containers, not viewports. Use Container Queries first, media queries only for global layout shifts and form factor detection.
---
## Container Queries (preferred over media queries)
```css
.card-grid {
container-type: inline-size;
container-name: card-grid;
}
@container card-grid (min-width: 600px) {
.card {
display: grid;
grid-template-columns: 200px 1fr;
}
}
@container card-grid (min-width: 900px) {
.card {
grid-template-columns: 1fr 1fr 1fr;
}
}
```
### Container query length units
```css
.card {
padding: 10cqw; /* 10% of container width */
font-size: 5cqi; /* 5% of container inline size */
margin-block: 2cqb; /* 2% of container block size */
border-radius: 1cqmin; /* 1% of container smaller side */
}
```
---
## Form Factor Detection
Detect the device type, not just width.
```css
/* Touch vs mouse */
@media (pointer: coarse) {
.button { min-height: 48px; }
}
@media (hover: hover) {
.card:hover { transform: scale(1.02); }
}
@media (hover: none) {
.card:active { transform: scale(0.98); }
}
/* Portrait vs landscape */
@media (orientation: portrait) {
.hero-grid { grid-template-columns: 1fr; }
}
```
---
## Viewport Unit Decision Tree
| Use case | Unit | Why |
|----------|------|-----|
| Full-screen hero | `min-h-[100dvh]` | Adapts to URL bar on mobile. Never `100vh` — iOS Safari viewport jumps. |
| Minimum safe height | `min-height: 100svh` | Small viewport height. Fallback for when URL bar is visible. |
| Large viewport design | `100lvh` | Maximum when URL bar hidden. Only for desktop-like experiences. |
| Width-based | `dvw` | Dynamic viewport width. Avoid on scroll-zooming mobile pages. |
```css
.hero {
height: 100dvh;
min-height: 100svh; /* Fallback: never smaller than smallest viewport */
}
```
### The `h-screen` ban
`h-screen` equals `100vh` which equals disaster on iOS Safari. The URL bar entering/exiting causes catastrophic layout jumps. Always use `min-h-[100dvh]`.
---
## Fluid Typography
```css
:root {
--text-sm: clamp(0.875rem, 0.8rem + 0.25vw, 1rem);
--text-base: clamp(1rem, 0.9rem + 0.35vw, 1.25rem);
--text-lg:
...[truncated]
--- name: motion-craft description: Design GPU-accelerated animations with Web Animations API (WAAPI), Scroll-Driven Animations (ScrollTimeline/ViewTimeline), FLIP technique, easing systems, and accessibility (prefers-reduced-motion). Use when user asks to create animations, transitions, scroll effects, page transitions, or interactive motion for web UIs. Do NOT use for canvas-based animations (Three.js, PixiJS), video editing, or non-web (native mobile) motion design. license: MIT compatibility: opencode metadata: workflow: frontend audience: developers version: "4.0" author: shokunin --- # Motion Craft Animations that communicate, not decorate. Every frame must earn its place. Inspired by Emil Kowalski (Linear, Sonner, Vaul), Paul Lewis (Google Chrome), and the CSS Animation Working Group. ## Workflow ## The Animation Decision Framework Before writing any animation code, answer these four questions in order. ### 1. Should this animate at all? | Frequency | Decision | Reason | |-----------|----------|--------| | 100+ times/day (keyboard shortcuts, command palette, search toggle) | No animation. Ever. | Animation makes frequent actions feel delayed. Raycast has no open/close animation. Optimal. | | Tens of times/day (hover effects, list navigation) | Remove or drastically reduce | Users notice animation latency on repeated interactions | | Occasional (modals, drawers, toasts) | Standard animation | The right place for motion | | Rare / first-time (onboarding, confirmation, celebration) | Add delight | These moments earn longer, richer animations | **Never animate keyboard-initiated actions.** These repeat hundreds of times daily. ### 2. What is the purpose? Every animation must have a clear answer to "why does this animate?" | Purpose | Example | Valid? | |---------|---------|--------| | Spatial consistency | Toast enters and exits from the same direction | ? | | State indication | Button morphs to show "sent" | ? | | Feedback | Button scales down on press, confirming the interface heard the user | ? | | Preventing jarring changes | Elements fading in instead of appearing abruptly | ? | | Explanation | Marketing animation showing how a feature works | ? | | "It looks cool" AND the user sees it often | Gratuitous motion | ? | ### 3. What easing should it use? | Scenario | Easing | CSS | |----------|--------|-----| | Element entering | ease-out (starts fast, feels responsive) | `cubic-bezier(0, 0, 0.2, 1)` | | Element exiting | ease-in (starts slow, grabs attention briefly then accelerates away) | `cubic-bezier(0.4, 0, 1, 1)` | | On-screen movement / morphing | ease-in-out | `cubic-bezier(0.4, 0, 0.2, 1)` | | Hover / color change | ease | `cubic-bezier(0.25, 0.1, 0.25, 1)` | | Constant motion (marquee, progress bar) | linear | `cubic-bezier(0, 0, 1, 1)` | | UI interactions (buttons, tooltips, dropdowns) | strong ease-out | `cubic-bezier(0.23, 1, 0.32, 1)` | **Critical: never use ease-in for UI entering animations.** A dropdow ...[truncated]
--- name: landing-craft description: Build conversion-optimized landing pages with CRO frameworks (Conversion Research, LIFT Model), scroll effects, A/B testing, personalization, form optimization, and Core Web Vitals (INP, LCP, CLS). Use when user asks to create a landing page, sales page, lead generation page, or improve conversion rates. Do NOT use for full product design (use component-forge), animation-specific (use motion-craft), or brand identity (use design). license: MIT compatibility: opencode metadata: workflow: marketing audience: developers version: "4.0" author: shokunin --- # Landing Craft Landing pages that convert. Based on Unbounce (44,000+ A/B tests), GoodUI, CXL Institute, and WiderFunnel LIFT Model. ## Creative Variance Engine Before writing code, select ONE combination based on the brief. This prevents every landing page from looking the same. ### Vibe Archetypes (pick 1) | Archetype | Palette | Typography | Best for | |-----------|---------|------------|----------| | Editorial Luxury | Warm cream (#f5f2ec), deep charcoal, ink-blue accent | Serif display (Cormorant Garamond, Playfair Display) + clean body | B2B, consulting, premium SaaS | | Dark Atmospheric | Deep navy (#080c1a), off-white text, burnt orange accent | Bold condensed display (Cabinet Grotesk, Space Grotesk) | Tech, AI, developer tools | | Soft Structural | White (#ffffff), zinc neutrals, single accent | Grotesk display (Geist, Plus Jakarta Sans) | SaaS, productivity, health | | Minimalist Editorial | Warm bone (#f7f6f3), strict 1px borders, muted pastels | Serif + system sans-serif | Portfolios, indie products | ### Layout Archetypes (pick 1) | Archetype | Structure | Mobile | |-----------|-----------|--------| | Split Screen | 50/50: text left, visual right. Clean alignment, no center. | Stack vertical: text on top, visual below | | Asymmetric Bento | Masonry grid with varying card sizes. `col-span-8` next to `col-span-4`. | Single column. All `col-span` overrides reset to 1 | | Editorial Z-Cascade | Elements overlap with slight rotation (-2deg to 3deg). Depth through stacking. | Remove all rotations and negative margins. Stack vertically. | | Full-Bleed Typography | Hero is pure typography. No image. Text spans viewport width. | Text scales down via clamp(). No overflow. | **Mobile override (universal):** Any asymmetric layout above `md:` (768px) must collapse to single-column (`w-full`, `px-4`, `py-8`) on viewports below `768px`. --- ## Workflow ### Step 1: Select creative archetype Pick one vibe + layout from the Creative Variance Engine. Every page must feel distinct. ### Step 2: Wireframe the sections Block out all 10 sections (Hero through Final CTA). Each section answers: what does the visitor need to hear RIGHT NOW to move forward? ### Step 3: Draft copy Headline under 10 words. One CTA above fold. Social proof near top. Use PAS framework for problem section. ### Step 4: Implement with mobile-first HTML/CSS 8px grid. clamp() for ...[truncated]
---
name: Aesthetic Web Design
description: >
Apply professional, premium UI/UX design standards when building or styling
web interfaces. Use this skill when the user asks to create a website, landing
page, web app, dashboard, UI component, or any visual interface — or when they
ask to make something look better, more professional, or more beautiful. Covers
visual hierarchy, typography, color systems, layout, spacing, motion, dark mode,
responsive design, and conversion patterns. Activate even when the user doesn't
say "design" — if they're building a web frontend, these standards apply.
---
# Aesthetic Web Design
A specific, opinionated design language based on real references. This skill encodes a visual DNA — not generic "make it look good" — but exact fonts, exact palettes, exact CSS values.
## Creative North Star
The default direction is **editorial + atmospheric**.
Core DNA:
- Typography as primary visual element — massive, oversized, bleeding off-screen
- Backgrounds with depth: gradient meshes, grain texture, illustrated scenes
- 3D scroll effects and parallax on hero
- Dark (#080808) OR cream (#f5f2ec) palettes — never generic white
- Serif display for editorial, bold condensed display for tech
- Product screenshots floating at angles, not centered boxes
Anti-identity (absolute bans):
- Flat #fff background with Inter font — wireframe, not finished design
- Purple/indigo gradient on white — the #1 AI cliché
- Generic 3-column centered layout with icon + heading + text cards
- Emoji as icons
- Animations on everything with no purpose
---
## Register Distinction
Every design task is either **Brand** or **Product**.
| Register | Scope | Bar | Approach |
|----------|-------|-----|----------|
| Brand | Marketing, landing pages, campaign surfaces, portfolios, long-form content. Design IS the product. | Distinctiveness. Must stand out from competitors. | Full creative range. Editorial, luxury, brutalist, cinematic — any visual lane. |
| Product | App UI, admin, dashboards, developer tools. Design SERVES the product. | Earned familiarity. Users of Linear, Stripe, Vercel should trust it. | Restrained. Clean. Fast. One palette. Predictable patterns. |
Identify before designing. Priority: (1) task cue ("landing page" vs "dashboard"), (2) surface in focus, (3) project context. First match wins.
---
## 1. Typography — The Main Visual Element
### Display fonts by direction
**Editorial serif** (Structured.money, Cori Corinne, Steep.app):
- Canela (preferred, premium license) — high contrast, editorial
- DM Serif Display (free) — elegant, sharp serifs
- Cormorant Garamond (free) — ultra-high contrast, ultra-luxury
- Playfair Display (free) — classic editorial
- Fraunces (free) — optical-size variable, editorial/vintage
**Bold display sans** (Leonardo.AI, Monopo):
- Neue Haas Grotesk Display — definitive display grotesque
- Cabinet Grotesk (free) — wide, excellent for oversized headlines
- Bebas Neue (free) — all-caps conden
...[truncated]
--- name: ui-ux-pro-max description: "UI/UX design intelligence. 67 styles, 96 palettes, 57 font pairings, 25 charts, 13 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples." --- # UI/UX Pro Max - Design Intelligence Comprehensive design guide for web and mobile applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 13 technology stacks. Searchable database with priority-based recommendations. ## When to Apply Reference these guidelines when: - Designing new UI components or pages - Choosing color palettes and typography - Reviewing code for UX issues - Building landing pages or dashboards - Implementing accessibility requirements ## Workflow 1. **Analyze requirements** — extract product type, style keywords, industry, and technology stack from user request. Default to `html-tailwind` if no stack specified. 2. **Generate design system** — run `python3 scripts/search.py "<query>" --design-system -p "Project Name"` for comprehensive style, color, typography, and effects recommendations. 3. **Supplement with domain searches** — query `style`, `typography`, `ux`, `chart`, or `landing` domains for additional detail on specific areas. 4. **Persist design system for multi-page projects** — use `--persist` to create `design-system/MASTER.md` with page-specific overrides via `--page`. 5. **Apply stack guidelines** — run `--stack <stack>` (default: html-tailwind) for implementation-specific best practices. 6. **Implement with the design system as source of truth** — colors, typography, spacing, and effects all come from the persisted MASTER.md. 7. **Run pre-delivery checklist** — verify visual quality, interaction, light/dark mode, layout, and accessibility before delivering code. ## Rule Categories by Priority | Priority | Category | Impact | Domain | |----------|----------|--------|--------| | 1 | Accessibility | CRITICAL | `ux` | | 2 | Touch & Interaction | CRITICAL | `ux` | | 3 | Performance | HIGH | `ux` | | 4 | Layout & Responsive | HIGH | `ux` | | 5 | Typography & Color | MEDIUM | `typography`, `color` | | 6 | Animation | MEDIUM | `ux` | | 7 | Style Selection | MEDIUM | `style`, `product` | | 8 | Charts & Data | LOW | `chart` | ## Quick Reference ### 1. Accessibility (CRITICAL) - `color-contrast` - Minimum 4.5:1 ratio for ...[truncated]
--- name: emil-design-eng description: Encode Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great. From the creator of Sonner (13M+ weekly npm downloads), Vaul, animations.dev, and Linear's web team. Use when user wants to polish UI, audit animations, review component interactions, add micro-feedback, or elevate motion quality. license: Apache 2.0 (based on emilkowalski/skill) compatibility: opencode metadata: version: "2.0" author: Emil Kowalski, improved by shokunin source: https://github.com/emilkowalski/skill --- # Design Engineering ## Initial Response When this skill is first invoked without a specific question, respond only with: > I'm ready to help you build interfaces that feel right, my knowledge comes from Emil Kowalski's design engineering philosophy — creator of Sonner (13M+ weekly downloads), Vaul, animations.dev, and Linear's web team. If you want to dive even deeper, check out Emil's course: [animations.dev](https://animations.dev/). ## Register Distinction (shokunin improvement) Every design task is **Product** (app UI, dashboard, tool: design SERVES the product) or **Brand** (marketing, landing, campaign: design IS the product). Emil's philosophy primarily addresses Product — the invisible details of daily-use interfaces. | Register | Bar | Focus | |----------|-----|-------| | Product | Earned familiarity. Users of Linear, Raycast, Stripe should trust it. | Tactile feedback, keyboard interactions, invisible correctness | | Brand | Distinctiveness. Must stand out. | Motion as narrative, bolder durations, creative springs | Apply the animation decision framework to both, but Product holds stricter duration limits. ## Core Philosophy ### Taste is trained, not innate Good taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. You develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly. When building UI, don't just make it work. Study why the best interfaces feel the way they do. Reverse engineer animations. Inspect interactions. Be curious. ### Unseen details compound Most details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. That is the goal. > "All those unseen details combine to produce something that's just stunning, like a thousand barely audible voices all singing in tune." — Paul Graham ### Beauty is leverage People select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Beauty is underutilized in software. Use it as leverage to stand out. ## Review Format (Required) When reviewing UI code, you MUST use a markdown table with Before | After | Why columns: | Before | After | Why | |--------| ...[truncated]
--- name: impeccable description: "Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers design systems, anti-pattern detection, brand vs product registers, typography, color (OKLCH), spacing, motion, copy, and accessibility. By Paul Bakaus (ex-Google, ex-Disney, ex-Unity). Full version includes 23 sub-commands, CLI detection, Chrome extension, and E2E test suite: npx skills add pbakaus/impeccable" license: Apache 2.0 (based on pbakaus/impeccable) compatibility: opencode metadata: version: "1.0-lite" author: Paul Bakaus, lite integration by shokunin source: https://github.com/pbakaus/impeccable full_install: npx skills add pbakaus/impeccable --- # Impeccable (Lite) Design and iterate production-grade frontend interfaces. This is a lite integration of Paul Bakaus's Impeccable design language for AI. For the full 23 sub-commands, CLI detection, Chrome extension, and E2E test suite, install: `npx skills add pbakaus/impeccable` ## Quick Start (Lite mode) Skip context gathering for rapid iteration. For full brand/product context, install the full version. ## Shared Design Laws ### Color - Use **OKLCH**. Reduce chroma as lightness approaches 0 or 100. High chroma at extremes looks garish. - Never `#000` or `#fff`. Tint every neutral toward brand hue (chroma 0.005-0.01 is enough). - Pick a **color strategy**: - **Restrained**: tinted neutrals + one accent ≤ 10%. Product default. - **Committed**: one saturated color carries 30-60%. Brand default. - **Full palette**: 3-4 deliberate roles. Brand campaigns. - **Drenched**: the surface IS the color. Brand heroes. ### Dark vs Light Never a default. Write one sentence of physical scene: who, where, under what light, in what mood. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" forces dark. "Editor reading a long-form article on an iPad in morning sunlight" forces light. Run the scene, not the category. ### Typography - Cap body line length at **65-75ch** via `max-width`. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). - No Inter as display font. ### Motion - Don't animate layout properties (`width`, `height`, `top`, `left`). - Ease out with exponential curves. No bounce, no elastic. - UI durations < 300ms. Exit faster than enter. ### Copy - Every word earns its place. No restated headings. - **No em dashes.** Use commas, colons, periods, or parentheses. Also no `--`. - No AI filler: "elevate", "seamless", "unleash", "delve". ## Absolute Bans Match-and-refuse. If you're about to write any of these, rewrite with different structure. | Ban | Why | |-----|-----| | **Side-stripe borders** (`border-left` > 1px as accent) | The #1 AI-dashboard tell | | **Gradient text** (`background-clip: text` + gradient) | Decorative, never meaningful | | **Glassmorphism as default** | Rare and purposef ...[truncated]
--- name: taste description: "Senior UI/UX Engineer. Architect digital interfaces overriding default LLM biases. Enforces metric-based rules, strict component architecture, hardware-accelerated CSS, and balanced design engineering. By Leon Lin & blueemi. Multi-runtime improved by shokunin." license: MIT (based on Leonxlnx/taste-skill) compatibility: opencode metadata: version: "2.0-improved" author: Leon Lin, blueemi, improved by shokunin source: https://github.com/Leonxlnx/taste-skill --- # High-Agency Frontend Skill ## Authority References (shokunin improvement) The rules in this skill are based on patterns observed across: - Linear, Vercel, Stripe, Notion — product UI - Apple Human Interface Guidelines - Material Design 3 - Emil Kowalski's design engineering (Sonner, Vaul, animations.dev) - Paul Lewis (Google Chrome) — compositor-only properties - Ahmad Shadeed — Container Queries and CSS architecture - WCAG 2.2 — Accessibility guidelines - CSS Working Group — modern CSS features ## 1. ACTIVE BASELINE CONFIGURATION - **DESIGN_VARIANCE**: 8 (1=Perfect Symmetry, 10=Artsy Chaos) - **MOTION_INTENSITY**: 6 (1=Static, 10=Cinematic/Magic Physics) - **VISUAL_DENSITY**: 4 (1=Art Gallery/Airy, 10=Pilot Cockpit/Packed Data) These are the standard baselines. ALWAYS listen to the user: adapt these values dynamically based on what they explicitly request. Use these values as global variables driving Sections 3 through 7. ## 2. DEFAULT ARCHITECTURE & CONVENTIONS ### Framework & Interactivity - React or Next.js. Default to Server Components (RSC). - **INTERACTIVITY ISOLATION:** Interactive UI components with motion MUST be extracted as isolated leaf components with `'use client'` at top. - **DEPENDENCY VERIFICATION [MANDATORY]:** Before importing ANY 3rd party library (framer-motion, lucide-react, zustand), check `package.json`. If missing, output `npm install <package>` before code. Never assume. ### Styling - Use Tailwind CSS (v3/v4) for 90% of styling. - **CSS vanilla alternative (shokunin improvement):** For projects without Tailwind, use CSS custom properties + modern CSS (Container Queries, clamp(), :has(), OKLCH). - **TAILWIND VERSION LOCK:** Check `package.json`. No v4 syntax in v3 projects. - **ANTI-EMOJI POLICY:** NEVER use emojis in code, markup, text, or alt text. Replace with Phosphor, Lucide, or clean SVG primitives. ### Responsiveness - **Viewport Stability [CRITICAL]:** NEVER `h-screen`. Always `min-h-[100dvh]` for iOS Safari. - **Grid over Flex-Math:** NEVER `w-[calc(33%-1rem)]`. Always CSS Grid `grid-cols-3 gap-6`. - Standardize breakpoints: sm(640), md(768), lg(1024), xl(1280). ### Icons - `@phosphor-icons/react` or `@radix-ui/react-icons`. Standardize `strokeWidth` (1.5 or 2.0). ## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction) ### Rule 1: Deterministic Typography - **Display/Headlines:** `text-4xl md:text-6xl tracking-tighter leading-none`. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`. NEVER Inter for prem ...[truncated]
--- name: taste-soft description: "High-end visual design like a premium agency. Defines exact fonts, spacing, shadows, card structures, and animations that make a website feel expensive. Blocks common defaults that make AI designs look cheap or generic. Based on taste-skill by Leon Lin & blueemi, improved by shokunin." license: MIT compatibility: opencode metadata: version: "2.0-improved" author: Leon Lin, blueemi, improved by shokunin --- # Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier) Engineering $150k+ agency-level digital experiences. Output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion. NEVER generate the same layout twice. Combine different premium archetypes while adhering to elite "Apple-esque / Linear-tier" design language. ## Authority References (shokunin improvement) Based on: Apple Human Interface Guidelines, Linear Design, Stripe Design, Emil Kowalski (design engineering), Paul Lewis (compositor-only), Ahmad Shadeed (Container Queries), WCAG 2.2. ## 1. THE "ABSOLUTE ZERO" DIRECTIVE (ANTI-PATTERNS) - **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. Use Geist, Clash Display, PP Editorial New, Plus Jakarta Sans. - **Banned Icons:** Standard thick-stroked Lucide, FontAwesome, Material. Use Phosphor Light, Remix Line. - **Banned Borders/Shadows:** Generic 1px solid gray. Harsh `rgba(0,0,0,0.3)`. Use tinted, ultra-diffuse shadows. - **Banned Layouts:** Edge-to-edge sticky nav glued to top. Boring symmetric 3-column grids without massive whitespace. - **Banned Motion:** Standard `linear` or `ease-in-out`. Instant state changes without interpolation. ## 2. THE CREATIVE VARIANCE ENGINE Select ONE combination per project to ensure unique output: ### Vibe & Texture Archetypes (Pick 1) 1. **Ethereal Glass (SaaS/Tech):** OLED black (#050505), radial mesh gradients (glowing purple/emerald orbs). Vantablack cards + `backdrop-blur-2xl` + white/10 hairlines. Wide geometric Grotesk. 2. **Editorial Luxury (Lifestyle/Agency):** Warm creams (#FDFBF7), muted sage, deep espresso. High-contrast Variable Serif for headings. CSS noise/film-grain overlay (`opacity-[0.03]`). 3. **Soft Structuralism (Consumer/Health/Portfolio):** Silver-grey or white backgrounds. Massive bold Grotesk. Airy, floating components with soft, highly diffused ambient shadows. ### Layout Archetypes (Pick 1) 1. **Asymmetrical Bento:** Masonry-like grid of varying card sizes (`col-span-8 row-span-2` next to stacked `col-span-4`). **Mobile:** Single column. All `col-span` overrides reset. 2. **Z-Axis Cascade:** Elements stacked like physical cards, overlapping with subtle `-2deg` or `3deg` rotation. **Mobile:** Remove all rotations and negative margins. Stack vertically. 3. **Editorial Split:** Massive typography on left half (`w-1/2`), interactive horizontal scrollable cards on right. **Mobile:** Full-width vertical stack. **Universal Mobile Override:** Any asymmetric layout ≥ md ...[truncated]
---
name: taste-minimalist
description: "Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows. Based on taste-skill by Leon Lin & blueemi, improved by shokunin."
license: MIT
compatibility: opencode
metadata:
version: "2.0-improved"
author: Leon Lin, blueemi, improved by shokunin
---
# Premium Utilitarian Minimalism & Editorial UI
Protocol for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. Enforces high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous macro-whitespace, bento-grid layouts, and ultra-flat component architecture with deliberate muted pastel accents.
Based on: Apple Notes, Linear, Notion, Basecamp, iA Writer, and premium editorial systems.
## 1. Absolute Negative Constraints (Banned)
- NO Inter, Roboto, or Open Sans typefaces
- NO Lucide, Feather, or standard Heroicons (use Phosphor Bold/Fill)
- NO Tailwind default drop shadows (`shadow-md`, `shadow-lg`, `shadow-xl`)
- NO primary colored backgrounds for sections
- NO gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blur)
- NO `rounded-full` for large containers, cards, or primary buttons
- NO emojis anywhere
- NO "John Doe", "Acme Corp", "Lorem Ipsum" — realistic, contextual content
- NO AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen"
- NO centered Hero sections — left-aligned text
## 2. Typographic Architecture
- **Primary Sans-Serif:** `'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`
- **Editorial Serif (Hero Headings):** `'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif'`. Tight tracking (`-0.02em` to `-0.04em`). Tight line-height (`1.1`).
- **Monospace (Code, Keystrokes):** `'Geist Mono', 'SF Mono', 'JetBrains Mono'`
- **Text Colors:** Never `#000000`. Use off-black (`#111111`, `#2F3437`). Secondary: `#787774`. Line-height `1.6`.
## 3. Color Palette (Warm Monochrome + Muted Pastels)
- **Canvas:** `#FFFFFF` or `#F7F6F3` / `#FBFBFA`
- **Surface (Cards):** `#FFFFFF` or `#F9F9F8`
- **Borders:** `#EAEAEA` or `rgba(0,0,0,0.06)` — exactly 1px solid
- **Accents** (muted pastels only):
- Pale Red: bg `#FDEBEC`, text `#9F2F2D`
- Pale Blue: bg `#E1F3FE`, text `#1F6C9F`
- Pale Green: bg `#EDF3EC`, text `#346538`
- Pale Yellow: bg `#FBF3DB`, text `#956400`
**CSS vanilla alternative (shokunin improvement):** Prefer CSS custom properties over Tailwind for pure editorial projects:
```css
:root {
--canvas: #F7F6F3;
--surface: #FFFFFF;
--border: #EAEAEA;
--text: #111111;
--text-secondary: #787774;
}
```
## 4. Component Specifications
### Bento Box Feature Grids
- Asymmetrical CSS Grid. `border: 1px solid #EAEAEA`. Radius: `8px` to `12px` max.
- Internal padding: `24px` to `40px`.
- Labels placed OUTSIDE and BELOW cards.
### Primary CTAs
- Background `#111111`, text `#FFFFFF`. Radius `4px` to `6p
...[truncated]
Mobile
2 skills--- name: flutter description: Build production Flutter apps with Clean Architecture, Riverpod (preferred over Bloc/Provider), GoRouter navigation, Impeller rendering engine, Dart 3.7+ patterns, platform channels via Pigeon, and App Store/Play Store deployment. triggers: ["create a Flutter app", "set up state management", "design widgets", "implement navigation", "deploy to stores", "flutter clean architecture", "riverpod", "go_router", "build flutter", "mobile app flutter", "pubspec.yaml", "flutter test", "flutter build", "platform channel", "pigeon", "impeller"] negatives: ["React Native", "web-only React", "general mobile design", "SwiftUI", "Jetpack Compose", "Xamarin", "Ionic", "Cordova"] license: MIT compatibility: opencode metadata: workflow: mobile audience: developers version: "4.0" author: shokunin --- # Flutter Architect **Widgets are functions of state. Keep them pure. Compose, don't inherit.** Production Flutter apps with Clean Architecture, Riverpod, GoRouter, Impeller, and platform channels. Based on Flutter docs, Riverpod patterns, and production experience. ## Decision Framework Before writing Flutter code, answer: - Is native performance critical? (animations, camera, maps) → Flutter is a strong fit - Is the team already experienced with Dart? → Proceed. If React/TypeScript, consider react-native skill - Is the app content-heavy with standard platform UI? → Consider native or react-native - Does the app need platform-specific features not available in packages? → Verify pub.dev coverage first ## Workflow 1. **Scaffold**: `dart run flutter_skeleton` or create `lib/core`, `lib/features/*/domain|data|presentation` by hand. Add Riverpod + GoRouter + Freezed deps in `pubspec.yaml`. 2. **Domain first**: Define entities, repository contracts, and use cases. Zero Flutter imports. Pure Dart with `freezed` for sealed unions. 3. **Data layer**: Implement repositories with Dio/retrofit, DTOs with `json_serializable`, and data sources. Wire up in Riverpod with `Provider<AuthRepository>`. 4. **Presentation**: Build screens and widgets with `ConsumerWidget`/`ConsumerStatefulWidget`. Wire `NotifierProvider` for each feature. Keep `ref.watch` at leaf level. 5. **Routing**: Configure GoRouter with auth redirect (`redirect` guard), nested routes per feature, and deep link patterns. 6. **Ship**: Run tests → `flutter build appbundle` / `flutter build ipa` → deploy via Codemagic or GitHub Actions. Enable Impeller on Android in `build.gradle`. ## Sub-Commands | Command | Description | |---------|-------------| | `scaffold` | Create project with folder structure and dependencies | | `feature` | Design a feature with domain/data/presentation layers | | `state` | Set up Riverpod providers for a feature | | `route` | Configure GoRouter with auth guard and deep links | | `test` | Write unit + widget + integration tests | | `ship` | Build and deploy to App Store + Play Store | ## Architecture ``` lib/ ├ core/ │ ├ theme/ # Material ...[truncated]
--- name: react-native description: Build production React Native apps with Expo SDK 53+, Expo Router (file-based navigation), New Architecture (Fabric + TurboModules), FlashList, Reanimated 4, Zustand for state, Hermes, EAS Build, and App Store/Play Store deployment. triggers: - "create a React Native app" - "set up navigation" - "optimize list performance" - "handle deep links" - "configure push notifications" - "deploy to stores" - "Expo Router" - "FlashList" - "Reanimated" - "Zustand" - "React Navigation" - "EAS Build" - "react native" - "expo" - "mobile app" - "iOS" - "Android" - "react-navigation" - "expo router" - "native module" negatives: - "Flutter" - "web-only React" - "PWA" - "mobile web" - "Ionic" - "Cordova" - "Capacitor" - "Xamarin" license: MIT compatibility: opencode metadata: workflow: mobile audience: developers version: "3.0" allowed-tools: - bash - edit - glob - grep - read - write - websearch - webfetch --- # React Native Architect Build production React Native apps with Expo, New Architecture, and modern navigation. ## Workflow 1. **Scaffold** — `npx create-expo-app@latest MyApp --template blank-typescript`, configure SDK 53+ 2. **Navigation** — Choose between Expo Router (greenfield Expo) or React Navigation v7 (bare RN / brownfield). Set up layouts, typed routes, deep linking 3. **State management** — Zustand for local client state, TanStack Query for server state. Avoid Redux unless dealing with massive synchronous state trees 4. **New Architecture** — Ensure Fabric + TurboModules enabled (default in SDK 53+). Verify third-party lib compatibility 5. **Lists** — Replace all FlatLists with FlashList from Shopify. Configure `estimatedItemSize`. Optimize `renderItem` with `React.memo` 6. **Animations** — Reanimated 4 for gesture-driven animations. Use `useSharedValue` + `useAnimatedStyle` instead of `Animated` API 7. **Images** — `expo-image` with cached, resized variants. Never bare `<Image>` without dimensions 8. **Notifications** — `expo-notifications` for push. Handle foreground, background, tap-to-navigate 9. **Performance** — Enable Hermes, lazy-load tab screens, freeze inactive screens via `react-native-screens`, `InteractionManager.runAfterInteractions` for heavy ops 10. **Ship** — `eas build --platform all --profile production`, `eas submit`, configure CI/CD with GitHub Actions ## Navigation Decision | Scenario | Recommended | |----------|------------| | Greenfield Expo app | Expo Router (file-based, typed routes, deep links) | | Bare React Native | React Navigation v7 (imperative, full control) | | Brownfield / native modules | React Navigation v7 | | Web + mobile | Expo Router (SSR, SEO) | ## Expo Router (file-based) ``` app/ ├ _layout.tsx # Root layout (tabs, stack) ├ index.tsx # / ├ (tabs)/ │ ├ _layout.tsx # Tab config │ ├ feed.tsx # /feed │ └ profile.tsx # /profile ├ product/ │ ├ [id].tsx # ...[truncated]
Quality
7 skills
name: test-commander
description: Generate unit, integration, E2E, and visual regression tests following the Testing Trophy methodology (80% integration). Covers Vitest/Jest, Testing Library, Playwright, MSW for API mocking, snapshot strategy, visual regression (Chromatic/Percy/Playwright), test factories with Faker, and CI sharding. Use when user asks to write tests, set up testing framework, mock API/dependencies, improve coverage, or add visual regression. Do NOT use for performance/load testing, production monitoring, or type testing (covered by TypeScript).
license: MIT
compatibility: opencode
metadata:
workflow: quality
audience: developers
version: "4.0"
author: shokunin
allowed-tools: Read Bash Write Grep Glob
---
# Test Commander
Tests that catch real bugs. Following the Testing Trophy (Kent C. Dodds): 80% integration, 10% unit, 10% E2E. Based on patterns from Testing Library, Playwright, MSW, and Chromatic.
## Testing Trophy (visual)
```
/\
/E2E\ ← 2-3 critical flows
/------\
/ Visual \ ← Visual regression on key components
/----------\
/Integration\ ← 80% of tests. Components + API + store.
/--------------\
/ Unit \ ← Pure logic. Utils, helpers, formatters.
/------------------\
Static ← TypeScript + ESLint
```
## Workflow
### Step 1: Determine test level
| What are you testing? | Level | Tool | Speed |
|------------------------|-------|------|:-----:|
| Pure logic (math, format, transform) | Unit | Vitest | < 5ms each |
| Component + API + store together | Integration | Testing Library + MSW | 50-200ms each |
| Critical user flow (checkout, signup) | E2E | Playwright | 2-10s each |
| Visual appearance | Visual | Playwright / Chromatic | 1-5s each |
**Default: Integration.** Catches 80% of bugs with 20% of maintenance cost.
### Step 2: Write integration tests (5 mandatory states)
Every data-fetching component must test ALL five states:
```tsx
describe('UserProfile', () => {
it('shows loading skeleton initially', async () => {
render(<UserProfile userId="123" />)
expect(screen.getByRole('status')).toHaveTextContent('Loading...')
})
it('shows error state with retry button', async () => {
server.use(http.get('/api/users/123', () => new HttpResponse(null, { status: 500 })))
render(<UserProfile userId="123" />)
await waitFor(() => {
expect(screen.getByRole('alert')).toHaveTextContent('Failed to load')
})
expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
})
it('shows empty state when no data', async () => {
server.use(http.get('/api/users/123', () => HttpResponse.json(null)))
render(<UserProfile userId="123" />)
await waitFor(() => {
expect(screen.getByText(/no user found/i)).toBeInTheDocument()
})
})
it('renders user data on success', async () => {
render(<UserProfile userId="123" />)
await screen.findByText('Alice')
expect(screen.getByTe
...[truncated]
---
name: performance-profiler
description: Performance profiling and optimization for web apps — Core Web Vitals (LCP, INP, CLS), Lighthouse audits, bundle analysis, backend profiling (CPU, memory, DB queries), N+1 detection, caching strategies (Redis, CDN, HTTP), and performance budgets. Use when user asks to improve performance, run Lighthouse audit, profile a Node.js app, optimize Core Web Vitals, reduce bundle size, or investigate slow response times. Do NOT use for database schema optimization (use db-sculptor), Docker image optimization (use docker), or CDN configuration.
license: MIT
compatibility: opencode
metadata:
workflow: quality
audience: developers
version: "4.0"
author: shokunin
allowed-tools: Read Bash Write WebFetch
---
# Performance Profiler
Find and fix performance issues from frontend to backend. Based on Google Core Web Vitals, Lighthouse, Chrome DevTools, and production patterns from WebPageTest and clinic.js.
## Sub-Commands
| Command | Description |
|---------|-------------|
| `audit` | Run comprehensive performance audit (frontend + backend) |
| `vitals` | Audit Core Web Vitals specifically (LCP, INP, CLS, TBT) |
| `lcp` | Optimize Largest Contentful Paint |
| `inp` | Fix Interaction to Next Paint (long tasks) |
| `bundle` | Analyze bundle size and split strategy |
| `backend` | Profile Node.js/Python backend performance |
| `budget` | Set and verify performance budgets |
## Workflow
### Step 1: Run Lighthouse audit (exact command)
```bash
npx lighthouse https://example.com --preset=desktop --output=html --output-path=./lighthouse-report.html
npx lighthouse https://example.com --preset=desktop --output=json --output-path=./lighthouse.json
```
Target scores:
| Metric | Target | Severity if missed |
|--------|--------|-------------------|
| Performance | > 90 | Critical |
| LCP (Largest Contentful Paint) | < 2.5s | Critical |
| INP (Interaction to Next Paint) | < 200ms | Critical |
| CLS (Cumulative Layout Shift) | < 0.1 | Critical |
| TBT (Total Blocking Time) | < 200ms | High |
| FCP (First Contentful Paint) | < 1.8s | Medium |
| Speed Index | < 3.4s | Medium |
### Step 2: Fix Core Web Vitals
#### LCP optimization (exact fixes)
```html
<!-- 1. Preload LCP image -->
<link rel="preload" as="image" href="hero.webp" fetchpriority="high">
<!-- 2. LCP image: no lazy loading -->
<img src="hero.webp" width="1200" height="600" fetchpriority="high" alt="">
<!-- 3. Inline critical CSS in <head> -->
<style>
.hero { display: grid; min-height: 100dvh; }
.hero img { width: 100%; height: auto; aspect-ratio: 2/1; }
</style>
<!-- 4. Defer non-critical CSS -->
<link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<!-- 5. Self-host fonts with font-display: swap -->
@font-face {
font-family: 'Geist';
src: url('/fonts/geist.woff2') format('woff2');
font-display: swap;
}
```
**LCP sub-parts breakdown:**
1. TTFB (Time to First Byte): < 800ms. Optimize server response.
...[truncated]
--- name: code-review description: "Review code changes for correctness, security, performance, and code quality. Use when the user asks to review a diff, review code changes, review commits, or perform a code review. Input can be: (1) a text diff pasted directly, (2) one or more git commit hashes to extract the diff from, or (3) a git range like abc123..def456. The user may also provide task description or requirements that motivated the change." metadata: version: 1.0.0 --- # Code Review Expert code reviewer combining rigorous analysis with deep expertise in clarity, consistency, and maintainability. Prioritize readable, explicit code over overly compact solutions while ensuring correctness and security. ## Inputs Accept any combination of: 1. **Text diff** — pasted directly by the user 2. **Git commit hashes** — one or more SHAs; extract the diff with git 3. **Task description / requirements** — context for what the change is supposed to accomplish ## Workflow ### Step 1: Obtain the diff - If the user provided a text diff, use it directly. - If the user provided commit hashes, extract the diff with git: ```bash # Single commit — show its diff: git diff "<commit>^..<commit>" # Two commits — diff between them: git diff "<commit1>..<commit2>" # Range syntax (abc123..def456) — pass directly: git diff "<range>" ``` - If the user provided a range (e.g. `abc..def`), pass it as a single argument. - If neither diff nor commits are provided, ask the user for input. ### Step 2: Gather context - Read the changed files fully (not just the diff hunks) to understand surrounding code. - Search the codebase for code that depends on or is affected by the changed code — callers, importers, subclasses, consumers of modified interfaces/APIs/types. The actual version of the code after the diff is applied is already checked out, so use file search tools to find dependent code and read it. - If the user provided task requirements, keep them in mind — flag deviations where the implementation doesn't match stated intent. ### Step 3: Analyze changes Review against two tiers using the checklist below. #### Priority Levels | Level | Meaning | Action | |-------|---------|--------| | P0 | Critical — security vulnerability, data loss risk, crash | Must fix | | P1 | Major — significant bug, performance regression, broken feature | Must fix | | P2 | Minor — code smell, clarity issue, inconsistency | Nice to fix | | P3 | Suggestion — improvement idea, optional refactor | Optional | #### Critical Issues (P0–P1) **Correctness:** - Logic errors and off-by-one mistakes - Unhandled edge cases (null, empty, boundary values) - Broken control flow (early returns, missing breaks) - Incorrect type conversions or comparisons - State mutation side effects **Security:** - Injection vulnerabilities (SQL, command, XSS) - Exposed secrets, tokens, or credentials - Unsafe deserialization - Missing input validation at system boundaries - Improper access control o ...[truncated]
---
name: comprehensive-review
description: "Comprehensive code review using parallel specialized subagents. If a PR URL is provided, fetches PR details and can post comments. If no PR is provided, reviews the diff between the current branch and its base branch plus any uncommitted changes. CRITICAL: this skill is costly, don't use it unless user explicitly requested to use it."
metadata:
version: 2.1.0
---
# Comprehensive Code Review
Run parallel specialized code reviews via subagents, covering architecture, security, performance, code quality, requirements compliance, and bugs. Merge findings and let the user act on them. Works with both GitHub PRs and local branch diffs.
## Variables
- `{TEMP_DIR}` — the OS temporary directory (e.g. `/tmp` on Unix, `%TEMP%` on Windows). Use it for all intermediate files.
## Workflow
### Step 1: Determine review mode
Check if the user provided a GitHub PR link.
- **PR mode**: A PR URL is provided matching `https://github.com/<OWNER>/<REPO>/pull/<PR_NUMBER>`. Extract owner, repo, and PR number.
- **Local mode**: No PR URL provided. The review will be based on the diff between the current branch and its base branch, plus any uncommitted changes.
### Step 2: Fetch diff and task description via subagent
Call a subagent to gather all change details, save the diff, and checkout the correct branch.
**CRITICAL**: You MUST spawn a subagent for this step. Do NOT perform the diff-gathering, branch detection, or complexity assessment yourself.
Construct the subagent prompt as follows:
```
Gather the code change details for a comprehensive code review.
Mode: <PR mode or Local mode>
<If PR mode: Owner: <OWNER>, Repo: <REPO>, PR Number: <PR_NUMBER>>
Instructions:
- PR mode: Fetch PR details via GitHub API (title, description, diff). Use `gh pr view <PR_NUMBER> --repo <OWNER>/<REPO> --json title,body` for metadata and `gh pr diff <PR_NUMBER> --repo <OWNER>/<REPO>` for the diff. Save diff to {TEMP_DIR}/review-diff-<branch>.patch.
- Local mode: Detect the current branch and its base branch (try main, master, develop). Use `git diff <base>...HEAD` for committed changes and `git diff` for uncommitted changes. Combine into {TEMP_DIR}/review-diff-<branch>.patch.
- Determine complexity: simple (<200 diff lines, single file/module), medium (200-800 lines, 2-5 files), hard (>800 lines, 6+ files, or touches architecture).
- Return: diff file path, diff line count, title, comprehensive task description, and complexity assessment.
```
Use a subagent tool to spawn the subagent. Use a powerful model since this involves complex reasoning to assess complexity.
The subagent will return:
- **Diff file path**: absolute path to the saved diff file (must start with `/`, e.g. `{TEMP_DIR}/review-diff-feature.patch`)
- **Diff line count**: total number of lines in the diff file
- **Title**: the PR title or summary from commits
- **Description**: comprehensive task description with all requirements
- **Complexity**: one of `simple`
...[truncated]
---
name: cross-review
description: Delegate code review to a subagent running a specific model. Use ONLY when user explicitly names a model to review changes ("review with opus", "use sonnet to review", "review with gemini"). The root agent reconstructs changes from conversation history and spawns a subagent with the code-review skill using the specified model. Do NOT use for general code review (use code-review skill instead), for reviewing PRs from git history, or when no model is specified by the user.
license: MIT
compatibility: opencode
metadata:
workflow: review
audience: developers
version: 1.0.0
---
Reconstruct what you changed during this conversation, then delegate the actual review to a single subagent running the `code-review` skill with a user-specified model.
IMPORTANT: Steps 1-2 run in the current agent (the master). Only Step 3 spawns a subagent.
## Workflow
### Step 1: Parse the user request
Extract:
- **Model**: The model ID from user's request. Validate against available models.
- **Review instructions**: Any text after "Review instructions:" — pass verbatim.
- **Change scope**: What should be reviewed. Default: all changes in this conversation.
### Step 2: Gather context from your own changes
Reconstruct the diff from conversation history:
1. Compose a unified diff of all changes (Edit, Write, Bash, etc.). Group by file.
- **If no changes**: Inform user and stop.
2. Read final state of changed files for surrounding context.
3. Check related context:
- Test files related to changed files (skip `node_modules`, `.git`, `dist`, `build`)
- Config changes that affect behavior
- Related type definitions or interfaces
Do NOT show gathered context to user. Use only for the subagent.
### Step 3: Spawn the review subagent
```
spawn_subagent:
skill: "code-review"
model: <model from user request>
prompt: |
Review the changes below using "code-review" skill.
CONSTRAINTS:
- Read-only review. Do NOT edit files.
- All context is provided below. Read files only if clearly incomplete.
- Review independently and objectively.
## Review Instructions
{user's review instructions, verbatim}
## Changes
{reconstructed diff, grouped by file}
## Additional Context
{links to related files, tests, type definitions, requirements}
```
### Step 4: Relay the result — READ-ONLY, NO ACTIONS
CRITICAL: Output the subagent's review AS-IS. Do NOT:
- Summarize, rephrase, reorder, or filter
- Fix, improve, or refactor based on findings
- Add your own commentary or caveats
One-line model attribution is acceptable. You may offer to implement recommendations, but let the user decide.
## Model Mapping
When user says "review with [model name]", map to a valid model ID:
| User says | Model ID |
|-----------|----------|
| opus, claude opus | claude-3-opus |
| sonnet, claude sonnet | claude-3.5-sonnet |
| gpt-4, gpt4 | gpt-4 |
| gpt-4o | gpt-4o |
| gemini | gemini-2.0-flash |
| deepseek
...[truncated]
---
name: zen-review
description: "Expert code reviewer. Analyze PR changes for correctness, security, performance, and quality. Returns findings as JSON. CRITICAL: this skill is costly, don't use it unless user explicitly requested to use it."
metadata:
version: 1.1.0
---
# Code Review
You are an expert code reviewer with deep codebase understanding.
You are running inside the actual repository.
Do NOT clone or fetch — the repo is already checked out.
Do NOT run tests, builds, or modify any files.
Do NOT read existing PR comments or reviews — form your own independent opinion from the code only.
## Workflow
## Your Task
1. Get the diff of changes to review. Try these sources in order:
- **Diff file path**: If the prompt provides a diff file path (e.g., `/tmp/review-diff.patch`), read the diff from that file.
- **Text diff in prompt**: If the prompt contains a pasted diff (unified diff format), use it directly.
- **Git commit hashes**: If the prompt provides commit hashes, extract the diff:
```bash
# Single commit:
git diff "<commit>^..<commit>"
# Two commits or range (abc123..def456):
git diff "<commit1>..<commit2>"
```
- **Current branch changes**: If none of the above are provided, compute the diff from the current branch:
```bash
MERGE_BASE=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null)
if [ -n "$MERGE_BASE" ]; then
git diff "$MERGE_BASE" > /tmp/review-diff.patch
else
git diff HEAD > /tmp/review-diff.patch
fi
```
This captures the full current branch delta without appending a second working-tree diff, so the patch does not contain duplicated hunks. Read the resulting file. If it is empty, inform the user that no changes were found and stop.
2. Process each changed file ONE BY ONE in the order they appear in the diff. For each file, complete ALL steps below before moving to the next file.
## Review Method (per file)
### 1. Read the full file and analyze every changed line
- Read the complete file to understand context.
- For EVERY new or modified line, ask: is this correct?
- Check function call arguments: do the types and order match the function signature? Read the called function's definition to verify.
- Check conditions and comparisons: are they logically correct? Any off-by-one? Any wrong operators (AND vs OR, == vs ===)?
- Check variable usage: is the right variable used? Could names be confused?
- Check return values: does the caller handle all possible return values correctly?
### 2. Check behavioral changes
- What did this code do BEFORE the change? Read the git diff carefully.
- Does this change alter any guarantees? (sync vs async, blocking vs non-blocking, error handling vs ignoring errors)
- Will callers of this code still work correctly with the new behavior?
### 3. Verify type correctness
- For each function call, read the target function's signature.
- Do argument types match p
...[truncated]
--- name: zen-comprehensive-review description: "Orchestrate a multi-model code review: spawn 3 review subagents, merge findings. In PR mode, posts GitHub PR comments with reactions. In local mode, outputs findings directly. CRITICAL: this skill is costly, don't use it unless user explicitly requested to use it." metadata: version: 1.2.1 --- > **Note:** `scripts/post_review_strict.js` is distributed with the full Shokunin tooling. Manual posting to PRs is available without it. # Code Review Orchestrator You are a code review orchestrator. Your job: 1. Determine review mode (PR or Local) 2. Spawn 3 independent review subagents using different models 3. Collect their findings 4. Deduplicate, merge, and verify the findings against actual code 5. In PR mode: post the review on GitHub. In local mode: output findings directly. ## Workflow ## Step 0: Determine Review Mode Check the user's prompt for PR information. - **PR mode**: The prompt contains `Owner/Repo` and `PR Number` (e.g., provided as `Owner/Repo: org/repo` and `PR Number: 123`). Extract these values. In PR mode, the prompt may also include the PR title and description. Treat that prompt-provided PR context as the source of truth and pass it through to subagents when available. - **Local mode**: No PR information provided. The review will be based on the diff between the current branch and its base branch, plus any uncommitted changes. ## Step 0b: Save Diff to File Before spawning subagents, save the diff to `/tmp/review-diff.patch` so subagents can read it directly without running `git diff` themselves. **PR mode:** ```bash git diff $(git merge-base HEAD origin/main) > /tmp/review-diff.patch ``` **Local mode:** ```bash MERGE_BASE=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master) git diff $MERGE_BASE > /tmp/review-diff.patch git diff >> /tmp/review-diff.patch ``` Verify the file was created and is non-empty before proceeding. ## Step 1: Spawn Review Subagents Spawn exactly 3 subagents using the subagent tool. Each should use the `zen-review` skill. **Default models** (use these unless the user's prompt specifies different models): 1. model="opus-4-7-think", skill="zen-review" 2. model="gpt-5-3-codex", skill="zen-review" 3. model="gemini-3-1-pro-preview", skill="zen-review" If the user prompt specifies preferred model names or families (for example claude/codex), follow the user's preference and map it to the closest available model IDs. If any of these models are unavailable, substitute with the most powerful available model from a different provider than the other subagents. If only 1 provider is available, use its most powerful model for all 3. For each subagent, set the prompt to: **PR mode:** "IMPORTANT: Follow the skill instructions STRICTLY and IN ORDER. The diff is saved at /tmp/review-diff.patch. Your FIRST action MUST be to read that file — do NOT run git diff, do NOT read any other files before you have the diff. Use any PR t ...[truncated]
Content & Business
6 skills---
name: communication
description: >
Draft professional emails, feedback (SBI/BID), difficult conversations, meeting
notes, and escalation templates. Covers tone matrix, cross-cultural
communication, Slack/Teams async patterns, and structured notes from raw
transcripts.
Trigger phrases: "write an email", "draft feedback", "difficult conversation",
"meeting notes", "escalate", "compose a message", "corporate email", "feedback
for [person]", "créame un correo", "tone check", "reply to this email", "say
no to a client", "status update to exec", "project delay email", "cold email
to [person]", "async message", "Slack message", "teams message", "follow-up
email", "meeting agenda", "meeting summary".
Negative triggers:
"sales outreach", "cold email sequence", "proposal", "SOW", "pitch deck",
"investor deck" → delegate to business-proposals skill.
"translate", "translation", "localize", "traducir" → delegate to
translate-craft skill.
"blog post", "newsletter", "Twitter thread", "case study", "marketing copy"
→ delegate to content-marketing skill.
license: MIT
compatibility: opencode 1.0+
metadata:
version: "4.0"
workflow: communication
audience: developers
allowed-tools:
- read
- write
- edit
- grep
- glob
- bash
- webfetch
- websearch
- skills
---
# Communication
Professional writing that gets results. Based on Harvard Business Review, Radical Candor (Kim Scott), Crucial Conversations (Patterson et al.), Amazon Working Backwards, and Google Project Aristotle.
## Sub-Commands
| Command | Description |
|---------|-------------|
| `draft` | Draft an email, message, or document from context |
| `polish` | Polish tone, cut filler, strengthen ask |
| `feedback` | Draft feedback using SBI/BID model |
| `notes` | Structure meeting notes from raw transcript or notes |
| `escalate` | Draft escalation with clear facts, impact, and request |
| `reply` | Reply to a message with appropriate tone |
## Workflow
**Step 1 — Identify audience & context**
- Who is the recipient? What is your relationship?
- What is their communication style (direct/indirect, formal/casual)?
- What is the power dynamic (peer, manager, report, client, exec)?
- What has happened before this communication?
**Step 2 — Choose tone from matrix**
| Context | Tone | Salutation | Closing |
|---------|------|------------|---------|
| Internal peer | Casual-direct | "Hi [Name]" | "Thanks" |
| Internal manager | Professional | "Hi [Name]" | "Thanks" |
| Cross-team | Professional | "Hi [Name]" | "Best" |
| Client (established) | Cordial | "Hi [Name]" | "Best regards" |
| Client (new) | Formal-cordial | "Dear [Name]" | "Best regards" |
| Executive / VP+ | Formal | "Dear [Title] [Last]" | "Sincerely" |
| Escalation | Firm, respectful | "Hi [Name]" | "Regards" |
| Complaint | Calm, professional | "Hi [Name]" | "Best regards" |
**Step 3 — Select channel**
| Scenario | Channel |
|----------|---------|
| Simple question, needs q
...[truncated]
--- name: content-marketing description: > Write blogs, newsletters, Twitter threads, case studies, and marketing copy that convert. Covers copywriting frameworks (AIDA, PAS, BAB, FAB), headline formulas, SEO/GEO for 2026 (AI Overviews, SGE), newsletter deliverability, Twitter thread hooks, Cialdini psychology, and cognitive biases. Triggers: write a blog post, newsletter, Twitter thread, case study, marketing copy, landing page copy, ad copy, sales page. Negative triggers: sales outreach (use business-proposals), landing page design (use landing-craft), translation (use translate-craft). license: MIT compatibility: opencode metadata: version: "4.0" workflow: content-marketing audience: developers allowed-tools: [websearch, webfetch, read, write, edit, glob, grep, bash, skill] --- # Content Marketing Content that ranks, converts, and gets shared. Based on Ogilvy, Cialdini, Copyhackers, and modern distribution strategies. ## Sub-Commands | Command | Description | |---------|-------------| | `blog` | Write a blog post (outline → draft → optimize → publish) | | `newsletter` | Write a newsletter issue with subject line + body | | `thread` | Write a Twitter/X thread (hook + value + CTA) | | `case-study` | Write a case study from results data | | `headline` | Generate and score headlines against formulas | | `optimize` | Optimize existing content for SEO + GEO | ## Copywriting Frameworks | Framework | Structure | Best for | |-----------|-----------|----------| | AIDA | Attention → Interest → Desire → Action | Landing pages, emails | | PAS | Problem → Agitate → Solve | Pain-point focused content | | BAB | Before → After → Bridge | Transformational offers | | FAB | Feature → Advantage → Benefit | Product descriptions | | 4Ps | Picture → Promise → Prove → Push | Long-form direct response | ## Headline Formulas | Type | Formula | Example | |------|---------|---------| | Direct benefit | "[Number] [noun] for [audience]" | "10 Email Templates for Busy Founders" | | How-to | "How to [outcome] in [time]" | "How to Double Conversion Rate in 30 Days" | | Pain avoidance | "[Outcome] Without [pain]" | "Get More Leads Without Spending on Ads" | | Contrarian | "Why [common belief] is [wrong]" | "Why 'Write for Skimmers' Is Terrible Advice" | | Personal story | "I [did thing] and [result]" | "I Rewrote One Page and Made $40K" | **Rules:** Under 15 words. Keyword near start. Specific outcome promise. No clickbait. ## Blog Structure ``` Headline → Lead (problem/story/curiosity/data) → H2 sections → Code examples → Conclusion → CTA ``` Lead types: | Type | Formula | |------|---------| | Problem-first | "[Pain]. Here's how to fix it." | | Story-first | "I [did thing] and learned [lesson]." | | Curiosity gap | "[Claim]. Here's why." | | Data-first | "[Stat]. [Why it matters]." | ## SEO + GEO (2026) ### Traditional SEO - Primary keyword in H1, first 100 words, one H2 - Meta description under 155 chars with value prop - URL: kebab-case, n ...[truncated]
--- name: business-proposals description: Generate sales outreach sequences, proposals, SOWs, investor pitch decks, and RFP responses. Covers cold email sequences, proposal structure, pricing tiers (Good-Better-Best), scope of work with exclusions, and 10-slide pitch deck. version: "3.0" triggers: - "write a proposal" - "cold email / outreach sequence" - "pitch deck / investor deck" - "SOW / statement of work" - "sales outreach / prospecting" - "respond to RFP" - "scope of work" - "client proposal" negatives: - general corporate communication (use communication skill) - content marketing / blog posts (use content-marketing skill) - brand design / creative direction (use design skill) - financial models / spreadsheets (use finance skill) - legal contracts / terms of service (use legal-counsel skill) license: MIT compatibility: opencode metadata: workflow: sales audience: consultants, founders, freelancers version: "3.0" --- # Business Proposals v3.0 Win deals and raise funding. Covers the full pipeline: outreach, proposals, and pitch decks. ## Workflow When the user asks for any sales document, follow this process: 1. **Clarify stage**: Outreach (cold) → Proposal (warm) → Pitch deck (investor)? Ask if unclear. 2. **Gather context**: Run discovery questions for the specific stage (sections below). 3. **Select template**: Match the deliverable to the appropriate structure below. 4. **Draft**: Fill template with user-provided info. Use placeholders `[like this]` for unknowns. 5. **Review**: Check against error handling table and production checklist. 6. **Verify anti-patterns**: Scan the anti-patterns table — if any match, fix before delivery. 7. **Output**: Return the completed document in the requested format (text, markdown, email body). ## Sales Outreach ### Required Discovery 1. **Prospect**: Company + person + role 2. **Trigger**: Why now? (funding, product launch, job change) 3. **Value prop**: "We help [X] do [Y] so they can [Z]" 4. **Proof**: Case study, testimonial, data point, mutual connection 5. **Goal**: Reply? Call? Demo? Trial? ### Cold Email Structure 1. **Subject**: Personalized + curiosity gap. 10 words max. 2. **Opening**: Specific reference to them (news, post, achievement) 3. **Value prop**: One sentence. Their benefit, not your features. 4. **Proof**: Social proof or relevant data point. 5. **Ask**: Single, low-friction next step. 6. **Close**: Simple. "Best, [Name]" ### Subject Line Patterns | Pattern | Example | |---------|---------| | Reference | "[Company] + [observation]" | | Question | "Quick question about [situation]" | | Compliment | "Impressed by [achievement]" | | Mutual connection | "[Name] suggested I reach out" | ### Personalization Levels (ALL required) 1. **Company**: Recent news, funding, launch 2. **Person**: Recent post, talk, job change, GitHub activity 3. **Fit**: Why this matters to THEM specifically If you cannot do level 2, do not send the email. ### Sequence L ...[truncated]
---
name: seo-geo
description: SEO + Generative Engine Optimization (GEO) for 2026 — technical SEO, on-page optimization, structured data (JSON-LD, schema.org), Core Web Vitals, citability scoring (llms.txt, entity clarity), AI search engine optimization (ChatGPT, Gemini, Perplexity, Claude, Google AI Overviews), and brand authority building. Use when user asks to optimize a site for search engines, improve SEO, write SEO content, implement structured data, optimize for AI search/GEO, audit a page, or improve Google rankings. Do NOT use for content writing strategy (use content-marketing), performance optimization beyond Core Web Vitals (use performance-profiler), or paid ad strategy.
license: MIT
compatibility: opencode
metadata:
workflow: marketing
audience: developers
version: "4.0"
author: shokunin
allowed-tools: Read Bash Write Grep WebFetch
---
# SEO & GEO Architect
Optimize for traditional search AND AI-powered engines. Based on Google Search Central, Moz, and GEO research (2025-2026).
## Sub-Commands
| Command | Description |
|---------|-------------|
| `audit-seo` | Run full SEO audit (titles, meta, schema, speed, mobile) |
| `audit-geo` | Run GEO audit (llms.txt, entity clarity, AI answer format) |
| `schema` | Generate JSON-LD structured data for any page type |
| `optimize` | Implement priority fixes ranked by impact |
| `llms` | Generate/update llms.txt for AI crawler discovery |
## Workflow
### Step 1: Run SEO audit
Check: title tags (< 60 chars, keyword first), meta descriptions (< 155 chars, value prop), H1 (one per page, keyword), img alt text, OG tags, canonical, robots.txt, sitemap.xml, Core Web Vitals.
Score: 90-100% good. 70-89% fix flagged. < 70% structural issues first.
### Step 2: Run GEO audit
Check: llms.txt presence, ai-plugin.json, FAQ/HowTo schema, entity clarity, brand mention structure, answer format (direct answer in first 2 paragraphs).
### Step 3: Prioritized fixes
| Fix | Impact | Effort |
|-----|:------:|:------:|
| Fix crawl errors (GSC) | High | Low |
| Improve LCP < 2.5s | High | Medium |
| Add structured data (JSON-LD) | High | Medium |
| Create llms.txt | High | Low |
| Fix meta titles/descriptions | Medium | Low |
| Add hreflang (if multilingual) | Medium | Low |
| Improve internal linking | Medium | Medium |
### Step 4: Structured data (must implement)
```json
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Brand Name",
"description": "One sentence. What you do.",
"url": "https://example.com",
"logo": "https://example.com/logo.png",
"sameAs": ["https://twitter.com/handle", "https://github.com/handle"]
}
```
Also: Article, FAQPage, HowTo, Product, BreadcrumbList, LocalBusiness (if applicable).
### Step 5: llms.txt
```
# Brand Name
> One-line description.
## Core pages
- https://example.com/: Home
- https://example.com/about: About
## Docs
- https://docs.example.com/api: API reference
## Blog
- https://example.com/blog/post: Title
```
Place a
...[truncated]
name: translate-craft description: Professional translation and localization for 8 languages (ES, JA, FR, DE, PT, ZH, KO, AR). Covers tone matrix, formality levels, i18n patterns (react-intl, i18next, ICU), RTL layout, cultural adaptation, and locale formatting. Use when user asks to translate text, localize an app, adapt tone, review translations, add i18n, or set up RTL. version: "4.0" license: MIT compatibility: opencode triggers: - translate text from one language to another - localize an app or website for a new market - adapt tone/register for a target audience - review an existing translation for quality - add i18n support to a codebase - set up RTL layout for Arabic or Hebrew - internationalize a React/i18next project - format dates, currencies, numbers per locale negatives: - word-for-word dictionary lookups - raw machine translation without human review - translating code comments or variable names metadata: workflow: communication audience: developers, translators --- # Translate Craft Translation that reads as if originally written in the target language. Based on ATA standards, Mozilla l10n best practices, Airbnb style guide, and Microsoft Language Portal. ## Core Principle Translate **meaning**, not words. If the reader can tell it's a translation, it failed. ## Sub-Commands | Command | Description | |---------|-------------| | `translate` | Translate text with tone, formality, and cultural adaptation | | `localize` | Localize dates, currencies, units, addresses per locale | | `i18n` | Set up i18n framework (react-intl / i18next / ICU) | | `rtl` | Implement RTL layout with CSS logical properties | | `audit` | Review existing translation for quality issues | | `teach` | Create a localization guide for a language pair | ## Language-Specific Rules (8 languages) ### EN → ES (Spanish) - **Formality**: `tú` (internal), `usted` (client/external) - **Gender**: inclusive language. "El usuario" → "La persona usuaria" - **Length**: ~25% longer. Account for UI expansion. - **Passive**: Active preferred. "Se decidió" not "Fue decidido" ### EN → JA (Japanese) - **Politeness**: 3 levels: casual (だ), polite (です), honorific (敬語). Default: polite. - **Subject omission**: Drop subjects when clear from context - **Pronouns**: Minimize 私/あなた. Overuse sounds foreign. ### EN → FR (French) - **Formality**: `vous` (professional), `tu` (casual) - **Gender**: Everything has gender. Ensure agreement across sentences. - **Punctuation**: Non-breaking space before `?`, `!`, `:`, `;` ### EN → DE (German) - **Compound nouns**: "cloud storage" → "Cloud-Speicher" - **Capitalization**: All nouns capitalized - **Formality**: `Sie` (prof), `du` (casual) ### EN → PT (Portuguese) - **Formality**: `você` (general), `o senhor/a senhora` (formal) - **Length**: ~20-25% longer ### EN → ZH (Mandarin) - **Measure words**: 个, 张, 条, 块 — correct classifier per noun - **Tone**: 您 (formal) vs 你 (casual) - **Shortened**: ~15-20% shorter. Mor ...[truncated]
--- name: documentation description: > Generate READMEs, API docs, changelogs, and knowledge base articles. Covers README structure with personality, OpenAPI-based API documentation, changelogs from conventional commits, typedoc patterns, and support KB articles. Triggers: "write a README", "API docs", "API documentation", "changelog", "release notes", "knowledge base", "KB article", "documentation", "project docs", "setup guide". Negatives: do NOT use for API design (use api-forge) or code comments. license: MIT compatibility: opencode metadata: version: "4.0" workflow: documentation audience: developers allowed-tools: [read, write, edit, glob, grep, bash, webfetch] --- # Documentation Write docs that developers actually read. Based on Stripe API docs, Standard Readme, Keep a Changelog, and OpenAPI. ## Sub-Commands | Command | Description | |---------|-------------| | `readme` | Generate a README from project files | | `api` | Generate API docs from OpenAPI spec or route handlers | | `changelog` | Generate changelog from conventional commits | | `kb` | Write a knowledge base article | ## README Structure ``` # Project Name [Badges] > One-line description ## Features (3-6 quantified benefits) ## Quick Start — copy-paste runnable (no placeholders, no omitted imports) ## API Reference — every export in table format ## Examples — 2-3 real-world scenarios ## Configuration — env vars, config file, CLI flags ## Contributing — dev setup commands ## License — SPDX identifier ``` ### The Hook (first paragraph) Answers: what (5 words), who, why. Bad: "A React component library for building modern user interfaces." Good: "Buttons, modals, forms, done right. No design debt. Zero dependencies." ### Quick Start Rules Copy-paste runnable. No omitted imports. No placeholders. No "coming soon". Include expected output. ### Badge Requirements | Badge | Required? | |-------|-----------| | CI (build status) | Yes | | Package version | Yes | | License | Yes | | Coverage | Recommended | ## API Documentation ### Structure per Endpoint ``` ### [METHOD] [Path] **Description**: one sentence **Auth required**: Yes/No [type] **Request**: Headers, Parameters (path/query/body) **Response 200**: Body with example **Error responses**: 400, 401, 404, 500 with descriptions ``` ### Rules per Endpoint - [ ] Request example (curl + one SDK) - [ ] Response example with ALL fields - [ ] Error responses for ALL possible status codes - [ ] Pagination docs (if applicable) - [ ] Rate limit headers documented ## Changelog Format ``` ## [2.1.0] - 2026-05-16 ### Added - New feature (#PR) ### Changed - Behavior change with migration note (#PR) ### Fixed - Bug fix (#PR) ### Deprecated / Removed / Security ``` Rules: Keep a Changelog format. Every entry links to PR. Migration notes for breaking changes. Unreleased section at top. Semantic versioning. Explain WHY not just WHAT. ## Knowledge Base ### Article Format ``` Title: as a question user would ...[truncated]
Productivity
8 skills--- name: git-workflow description: Automate the complete Git development workflow — create feature branches with conventional naming, atomic commits with conventional commit messages, interactive rebase, squash merges, PR body generation from commit history, branch cleanup, and git worktree patterns. Use when user asks to create a branch, commit changes, make a PR, rebase, squash, clean up branches, or follow a Git workflow. Do NOT use for CI/CD pipeline configuration (use ci-cd), code review (use code-review), or GitHub Actions workflows. license: MIT compatibility: opencode metadata: workflow: development audience: developers version: "3.0" author: shokunin allowed-tools: Read Bash Write Grep --- # Git Workflow Automate the development cycle: branch, commit, PR, review, merge, cleanup. Follows conventional commits and trunk-based development. ## Workflow ### Step 1: Create a feature branch ```powershell scripts/create-feature-branch.ps1 -Name "add-user-auth" -Type feat ``` This: 1. Detects default branch (main/master) 2. Fetches and pulls latest 3. Creates `feat/add-user-auth` from base 4. Pushes upstream with tracking **Branch naming:** | Type | Prefix | Example | |------|--------|---------| | Feature | `feat/` | `feat/add-user-auth` | | Fix | `fix/` | `fix/login-redirect` | | Docs | `docs/` | `docs/api-readme` | | Refactor | `refactor/` | `refactor/auth-middleware` | | Chore | `chore/` | `chore/update-deps` | ### Step 2: Make atomic commits ```powershell scripts/auto-commit.ps1 -Scope "auth" -DryRun # Preview first scripts/auto-commit.ps1 -Scope "auth" # Commit ``` The script analyses changed files, generates a conventional commit message, and stages+commits. **Conventional commit format:** ``` <type>(<scope>): <description> [optional body] [optional footer] ``` **Rules:** - One logical change per commit - Description: imperative mood, lowercase, max 72 chars - Scope: the module/area affected - Footer: `BREAKING CHANGE:`, `Closes #123`, `Co-authored-by:` ### Step 3: Prepare for PR ```powershell # Interactive rebase (squash WIP commits) git rebase -i main # Generate PR body from commit history scripts/pr-body.ps1 -Clipboard ``` The PR body script: 1. Detects base branch 2. Extracts commits since fork 3. Groups by conventional commit type 4. Generates ## Summary, ## Changes, ## Testing sections 5. Copies to clipboard **Squash rules:** - Squash `fixup!` and `wip` commits - Keep meaningful commit history - Never squash if commits have different scopes - Use `git rebase -i main` with `fixup` (f) for WIP commits ### Step 4: Create PR ```powershell # Create PR with generated body gh pr create --title "feat(auth): add user authentication" --body "$(Get-Clipboard)" # Or use the file gh pr create --title "feat(auth): add user authentication" --body-file .pr-body.md ``` **PR guidelines:** | Aspect | Rule | |--------|------| | Size | Max 400 lines changed | | Title | Same as conventional commit | | Description | ...[truncated]
--- name: windows-powershell description: Windows 11 system administration with PowerShell — system info reporting, hardware monitoring, package management (winget/scoop), disk cleanup, performance optimization, environment configuration, PowerShell profile setup with aliases and autocomplete, and Task Scheduler automation. Use when user asks to check system info, install tools on Windows, clean up disk space, set up PowerShell profile, or automate Windows tasks. Do NOT use for Linux administration, cross-platform scripting, or network infrastructure management. license: MIT compatibility: opencode metadata: workflow: operations audience: developers version: "3.0" author: shokunin allowed-tools: Read Bash Write --- # Windows PowerShell Windows 11 system administration and automation with PowerShell 7. ## Workflow ### Step 1: System health check ```powershell scripts/system-info.ps1 ``` Outputs: - **OS**: Windows 11 build, edition, install date - **CPU**: Model, cores, current usage % - **RAM**: Total, used, free, usage % - **Disk**: Per drive: total, used, free, usage % - **Top 5 processes** by memory usage - **Network**: Adapters, IP addresses - **Uptime**: Days since last restart - **Windows Updates**: Pending update count **If RAM usage > 80%** or **disk usage > 90%**: proceed to Step 2. ### Step 2: System cleanup ```powershell # Preview what would be cleaned scripts/cleanup-system.ps1 -DryRun # Clean everything scripts/cleanup-system.ps1 ``` Cleans: - Windows temporary files - Recycle Bin - Windows Update cache - npm/yarn/pnpm cache - Docker unused data - Windows.old (if present) - Prefetch files Reports total space recovered. ### Step 3: Install development tools ```powershell # Install everything scripts/install-tools.ps1 # Install specific categories only scripts/install-tools.ps1 -Scope dev # Git, Node, Python, VS Code scripts/install-tools.ps1 -Scope tools # 7-Zip, Windows Terminal, Oh My Posh ``` The script checks if each tool is already installed before attempting. Uses `winget` as primary, falls back to `scoop`. ### Step 4: Set up PowerShell profile Copy the premium profile template: ```powershell # Install the premium profile Copy-Item "~\\.config\\opencode\\skills\\windows-powershell\\assets\\Microsoft.PowerShell_profile.ps1" $PROFILE # Reload profile . $PROFILE ``` The profile includes: - **Oh My Posh** prompt with git status - **PSReadLine** with autocomplete and syntax highlighting - **Git aliases**: `gst` (status), `ga` (add), `gc` (commit), `gp` (push), `gl` (pull), `gb` (branch) - **npm aliases**: `ni` (install), `nrd` (run dev), `nrb` (run build), `nt` (test) - **Docker aliases**: `dps` (ps), `dlog` (logs), `dstop` (stop), `drm` (rm) - **Utils**: `touch`, `which`, `ll` (ls -la), `mkcd` (mkdir + cd), `admin` (runas admin) ### Step 5: Schedule recurring maintenance ```powershell # Weekly cleanup every Sunday at 9 PM schtasks /Create /SC WEEKLY /D SUN /TN "SystemCleanup" /TR "powershell.exe -File ...[truncated]
name: runbook-gen description: Generate operations runbooks and post-mortems for incident response — severity matrix, decision trees, escalation paths, war room setup (Slack/Zoom), status page updates, customer comms templates, and blameless post-mortems with action items. license: MIT compatibility: opencode metadata: workflow: operations audience: sre version: "3.0" triggers: - "create a runbook" - "incident response plan" - "on-call guide" - "SRE procedure" - "escalation path" - "outage playbook" - "post-mortem" - "war room" - "sev1 procedure" negatives: - "Use **documentation** for general project docs, READMEs, API docs" - "Use **error-handler** for error handling patterns, retry logic, circuit breakers" - "Use **error-handler** for logging and tracing configuration" - "Use **ci-cd** for deployment pipeline runbooks" - "Use **db-sculptor** for database-specific recovery procedures" --- # Runbook Generator Operation runbooks that on-call engineers can follow under pressure. Based on Google SRE practices, PagerDuty incident response, and post-mortem culture. ## Workflow Follow these steps in order when generating a runbook: 1. **Discover** — Ask the 5 Required Discovery questions (below) to scope the runbook 2. **Classify** — Map the incident to the Severity Matrix; if unclear start at Sev2 3. **Template** — Instantiate the Runbook Template with service-specific commands, time-boxes, and contacts 4. **War Room** — Configure Slack channel, Zoom bridge, shared doc, status page, and customer comms 5. **Verify** — Run through the Production Checklist before marking complete 6. **Archive** — Store the runbook in the team's on-call repo, test in a drill within the quarter When the ask is a post-mortem (not a runbook), skip steps 3-4 and use the Post-Mortem Template instead. ## 2. Required Discovery 1. **Service/System**: What is the runbook about? (API, database, cache, queue) 2. **Incident types**: What can go wrong? (down, degraded, slow, data loss) 3. **Environment**: Production, staging, or both? 4. **Team structure**: Primary, secondary, escalation contacts 5. **Existing monitoring**: Alerts, dashboards, runbooks ## 3. Severity Matrix | Severity | Definition | Response SLA | |----------|------------|--------------| | Sev1 | Service down, users impacted | Respond within 15 min | | Sev2 | Degraded performance, partial impact | Respond within 1 hour | | Sev3 | Minor issue, no user impact | Next business day | | Sev4 | Internal tooling, non-critical | Per team schedule | ## 4. Runbook Template ``` ## Runbook: [Incident Type] ### Detection How this incident is typically discovered: - Alert: [Prometheus/Grafana/Datadog alert] - User symptom: [what users see or report] - Automated detection: [auto-remediation] ### Initial Response (first 5 min) 1. Acknowledge alert (PagerDuty/Opsgenie). Time: < 2 min 2. Determine severity. Time: < 1 min 3. Assign owner. Create incident channel (#inc-sev1). Time: < 2 ...[truncated]
--- name: strategy description: Run structured brainstorming sessions (divergent/convergent), improve prompts with 7-dimension framework, and apply decision frameworks (RICE, weighted scoring, first principles, pre-mortem). triggers: - brainstorm ideas - run an ideation session - improve a prompt - write a better prompt - make decisions - strategic thinking - how to decide between options - prompt engineering - structured thinking negatives: - creative direction (use design skill) - content strategy (use content-marketing) - personal coaching - simple yes/no decisions without tradeoffs - design feedback or visual critique license: MIT compatibility: opencode metadata: workflow: strategy audience: developers version: "3.0" --- # Strategy Structured thinking for brainstorming, prompt engineering, and decision making. ## Workflow ### Step 1: Intake & Framing Extract the user's core need and classify it into one of three tracks: | Track | Trigger | Output | |-------|---------|--------| | **Decision** | "Should I...", "Which option...", "Help me choose..." | Scored recommendation with rationale and runner-up tradeoff | | **Ideation** | "Brainstorm...", "Generate ideas for...", "What are ways to..." | Prioritized list of ideas with convergent selection | | **Clarity** | "How do I think about...", "Improve this prompt", "Reframe..." | Restructured framing, 7-dimension prompt, or first-principles breakdown | If the user's need spans multiple tracks, run them sequentially: Clarity → Ideation → Decision. ### Step 2: Select Framework For **Decision** track: Choose ICE if speed matters, Impact/Effort matrix if resources are constrained, First Principles if the problem feels stuck or assumed, Pre-Mortem if the decision is high-stakes and irreversible. For **Ideation** track: Start with brainwriting (quantity). If ideas stall, inject SCAMPER or reverse brainstorming. Never open with free association for groups of 3+ — dominant voices take over. For **Clarity** track: Run the 7-dimension prompt diagnosis. Identify which dimensions are weak (0-3 on a 1-10 scale). Rewrite the prompt addressing the weakest dimensions first. ### Step 3: Execute Framework Follow the framework protocol from its dedicated section below. Timebox strictly: - Decision: 20 min (5 min framing, 10 min scoring, 5 min decision) - Ideation: 60 min (divergent 30 min, cluster 10 min, convergent 20 min) - Clarity: 10 min (diagnose 3 min, rewrite 5 min, changelog 2 min) ### Step 4: Document & Deliver Every strategy output must include: - The chosen framework and why it was selected - The raw output (scores, ideas, rewritten prompt) - One recommended action with owner + next step + deadline - One explicitly rejected alternative and the reason ### Step 5: Verify Against Production Checklist Run the Production Checklist before delivering. If any item is unchecked, return to the relevant step. Never deliver a strategy artifact that skips convergent se ...[truncated]
--- name: design description: Generate brand guidelines, design systems with design tokens (W3C format), creative direction (SCAMPER, Design Thinking, TRIZ), and design briefs with scope and success criteria. version: "3.0" license: MIT compatibility: opencode triggers: - "brand guidelines" - "style guide" - "design brief" - "creative brief" - "campaign concept" - "brand identity" - "visual identity" - "design system" - "creative direction" - "brand strategy" negatives: - "UI component design patterns" -> use ui-ux-pro-max - "landing page layout" -> use landing-craft - "responsive design" -> use responsive-engine - "icon set creation" -> use component-forge - "color palette generation" -> use ui-ux-pro-max metadata: workflow: design audience: designers previous_version: "2.0" --- # Design Skill v3.0 Brand identity, design systems, creative direction, and project briefs. --- ## Workflow: Brand / Design System Creation Follow this numbered process. Do not skip steps. | Step | Action | Output | |------|--------|--------| | 1 | Gather inputs: brand story, competitors, audience research, technical constraints | Brief document | | 2 | Define brand strategy: positioning, personality (3-5 adjectives), tone of voice | Brand strategy doc | | 3 | Build color system: primary, neutral, semantic palettes + WCAG AA checks | Color tokens + palette | | 4 | Select typography: headline/body pairing, scale, line-height, responsive sizing | Typography tokens | | 5 | Define spacing, radius, shadow, motion tokens (W3C format) | Design tokens JSON | | 6 | Create logo variations + usage guidelines | Logo guidelines | | 7 | Apply to 3+ touchpoints: web, print, social, or environmental | Application mockups | | 8 | Run design system audit (see checklist below) | Audit report | | 9 | Document anti-patterns and error states | Error + anti-pattern docs | | 10 | Stakeholder review + alignment sign-off | Approved design system v1.0 | --- ## Error Handling | Error | Cause | Fix | |-------|-------|-----| | Color contrast fails WCAG AA | Luminance ratio < 4.5:1 for text | Darken or lighten until ratio passes. Use `contrastRatio` in tokens. | | Token mismatch across platforms | Figma tokens != code tokens | Single source of truth: W3C JSON. Export from design tool. | | Typography scale gaps | Missing intermediate sizes | Build scale with modular scale (1.25 or 1.333 ratio). | | Logo illegible at min size | Too much detail in icon | Use simplified lockup or separate wordmark + icon variants. | | Design brief scope creep | Unclear out-of-scope list | Explicit "what's NOT included" section. Reference during reviews. | | Stakeholder disagreement | No clear decision authority | Identify single approver in brief. Escalate to DRI. | | Campaign fails originality axis | Cliché or derivative idea | Force 5+ directions. Run through SCAMPER/TRIZ. Reference culture, not competitors. | --- ## Brand Guidelines A complete brand system has 9 sections: ...[truncated]
--- name: finance description: >- Personal finance planning — 5-pillar framework (cash flow, net worth, debt, emergency fund, investing), tax optimization, insurance review, retirement planning (FIRE, 4% rule, Mega Backdoor Roth), and document retention. license: MIT compatibility: opencode metadata: workflow: finance audience: personal version: "3.0" triggers: - create a budget - track spending - plan debt payoff - review investments - optimize taxes - organize financial documents - get a financial plan - retirement planning - how much to save - emergency fund - net worth negatives: - stock trading advice - cryptocurrency speculation - day trading strategies - options trading - individual stock picks --- **Disclaimer**: Educational financial planning information. Not professional financial advice. --- ## Workflow Follow in order. Skip pillars already covered. ### 1. Assess Cash Flow 1. Calculate real monthly income (take-home after taxes, insurance, retirement) 2. Track expenses for 30 days 3. Classify into Needs (50%), Wants (30%), Savings (20%) 4. Identify surplus or deficit ### 2. Calculate Net Worth 1. List all assets (cash, investments, property, retirement accounts) 2. List all liabilities (credit cards, loans, mortgage, student debt) 3. Net Worth = Total Assets - Total Liabilities 4. Track monthly — direction matters more than the number ### 3. Eliminate High-Interest Debt 1. List all debts with balance, rate, minimum payment 2. Choose avalanche (highest rate first) or snowball (smallest balance first) 3. Attack with surplus from cash flow 4. Debt is emergency if total > 6 months income OR rate > 10% ### 4. Build Emergency Fund 1. Phase 1: $1,000 or 1 month (starter) 2. Phase 2: 3-6 months of essential expenses (full) 3. Phase 3: 6-12 months (conservative / irregular income) 4. Keep in HYSA only. Never invest it. ### 5. Invest for Retirement 1. 401(k) up to employer match → free money 2. HSA (if eligible) → triple tax-advantaged 3. IRA (Roth or Traditional) → $7,000/yr ($8,000 if 50+) 4. 401(k) up to max ($23,500) 5. Taxable brokerage → no limits --- ## 5-Pillar Framework ``` 1. Cash Flow → Income - Expenses = Surplus 2. Net Worth → Assets - Liabilities = Net Worth 3. Debt → Avalanche or Snowball 4. Emergency → 3-6 months essential expenses in HYSA 5. Invest → Tax-advantaged accounts first ``` ## Pillar 1: Budgeting ### 50/30/20 Rule | Category | % | Includes | |----------|---|----------| | Needs | 50% | Housing, utilities, groceries, insurance, minimum debt, transport | | Wants | 30% | Dining, entertainment, subscriptions, travel, shopping | | Savings | 20% | Emergency fund, retirement, investments, extra debt | ### Budgeting Methods | Method | Best for | |--------|----------| | 50/30/20 | Beginners | | Zero-based | Detail-oriented | | Envelope | Overspenders | | Pay-yourself-first | Savers | ## Pillar 2: Net Worth - Track monthly via spr ...[truncated]
name: legal-counsel description: >- Structured legal reference for GDPR, EU AI Act, DSA/DMA, CCPA/CPRA, HIPAA (2026 updates), ADA/WCAG digital accessibility, DMCA, US state privacy laws (15+ states), and contract review. triggers: - user asks about GDPR compliance, privacy law, cookie consent, data protection - user asks about AI regulation, EU AI Act, AI compliance - user asks about HIPAA, healthcare data, ePHI requirements - user asks about ADA, WCAG, digital accessibility - user asks about DMCA, copyright takedown, safe harbor - user asks about CCPA, CPRA, US state privacy laws - user asks about contract review, DPA, BAA, legal clauses - user asks about DSA, DMA, Digital Services Act, Digital Markets Act negatives: - litigation strategy, courtroom procedure, criminal defense - employment law disputes, labor rights, union matters - immigration law, visa applications, citizenship - tax law, estate planning, family law, real estate transactions - trademark filing, patent prosecution (copyright DMCA is covered) - specific monetary damages calculations for a particular case license: MIT compatibility: opencode metadata: workflow: legal audience: developers version: "3.0" --- **IMPORTANT DISCLAIMER**: Reference information for educational and preliminary analysis. NOT legal advice. No attorney-client relationship. Laws vary by jurisdiction and change frequently. Always consult a qualified attorney. ## Workflow When asked a legal compliance question, follow these steps: | Step | Action | Notes | |------|--------|-------| | 1 | Identify jurisdiction(s) | EU, US federal, US state(s), UK — may overlap | | 2 | Map the Obligation Matrix | Core Analysis Framework (below) | | 3 | Cross-reference enforcement | Fines, private right of action, regulator trends | | 4 | Check effective dates | Phased enforcement is common (AI Act, HIPAA 2026) | | 5 | Return applicable code | Use sub-sections below — do not invent thresholds | | 6 | Append disclaimer | Always close with "verify with qualified attorney" | ### Core Analysis Framework | Lens | What it asks | |------|-------------| | Jurisdiction | Which law applies? (EU, UK, US federal, US state) | | Obligation | What must you do? (mandatory vs recommended) | | Risk | What happens if you don't? (fines, lawsuits, reputation) | | Timeline | When must you comply? (deadlines, phased enforcement) | ## Error Handling | Scenario | What to do | Don't do | |----------|-----------|----------| | User asks "is this legal?" | Frame as checklist — never a yes/no opinion | Give definitive legal judgment | | Jurisdiction unclear | Ask which country/state the business operates in | Assume US or EU by default | | Threshold question (revenue, user count) | Clarify exact figures before answering | Give partial guidance | | Law recently updated | Check effective date; note "proposed/not yet in force" if applicable | Cite outdated text as current | | User asks about pending legislation | ...[truncated]
--- name: whendone-plus description: Automatically notify the user when long-running terminal commands finish (npm test, docker build, git push, etc.). The agent monitors command execution and sends a desktop notification on completion if the command ran longer than threshold (default 10s). Use when user asks to "notify me when done", "desktop notification when command finishes", "alert when done", or "tell me when this completes". Do NOT use for interactive commands (vim, nano, less, htop), commands that always complete in <5s, or streaming commands (tail -f). license: MIT compatibility: opencode metadata: workflow: automation audience: developers version: "3.0" --- # WhenDone Plus Automatically notify when long-running commands complete. ## How It Works 1. User runs a long command (e.g. `npm test`, `docker build`, `git push`) 2. The agent monitors the command execution time 3. If the command runs longer than the threshold (default 10s), the agent notifies the user on completion 4. Exit code is passed through ## Workflow ### Step 1: Detect long-running command Identify commands likely to exceed threshold: - `npm test`, `npm run test`, `npx playwright test` - `docker build`, `docker compose up`, `docker compose down` - `git push`, `git pull`, `git clone` - `pip install`, `npm install`, `pnpm install`, `yarn install` - `cargo build`, `cargo test`, `go build`, `dotnet build` - Custom scripts, database migrations, data processing pipelines - `ffmpeg`, `rsync`, `scp`, large file transfers ### Step 2: Monitor execution Start a background timer when the command begins. Track: - Elapsed wall-clock time - Peak memory usage (if available) - Child process tree (for pipeline awareness) ### Step 3: Notify on completion Basic notification format: ``` ✅ "Command finished: npm test completed in 142s (exit 0)" ❌ "Command finished: docker build failed in 89s (exit 1)" ``` Include: - Command name (first word + key args) - Execution time (rounded to seconds) - Exit code (success/failure) - Optional: memory peak, output file path if redirected ### Step 4: Handle edge cases - Commands completing under 10s: no notification (too fast to matter) - Interactive/TUI commands (vim, nano, htop): skip (user is watching) - Piped commands (e.g. `npm test | grep error`): monitor the pipeline, not the first process - Backgrounded commands (`&`): notify on background process completion - Chained commands (`;`): notify per-segment or in aggregate - Commands killed by signal: notify with signal name (e.g. "killed by SIGTERM") ## Notification Mechanisms ### Windows Toast Notification (PowerShell) ```powershell Add-Type -AssemblyName System.Windows.Forms $balloon = New-Object System.Windows.Forms.NotifyIcon $balloon.Icon = [System.Drawing.SystemIcons]::Information $balloon.BalloonTipTitle = "Command Complete" $balloon.BalloonTipText = "npm test finished in 142s (exit 0)" $balloon.Visible = $true $balloon.ShowBalloonTip(5000) Start-Sleep -Seconds 5 $balloon.Dispo ...[truncated]
Documents
3 skills--- name: kami description: 'Generate PDFs, resumes, CVs, letters, slide decks, portfolios, one-pagers, white papers, and professional documents. Use when user asks to create a PDF, make a resume, write a letter, design slides, format a document, typeset a report, build a portfolio, make a presentation, or create a one-pager. Warm parchment, ink-blue accent, serif-led hierarchy. CN uses TsangerJinKai02, EN uses Charter, JA uses YuMincho (best-effort). Triggers on Chinese: "做 PDF / 排版 / 一页纸 / 白皮书 / 作品集 / 简历 / PPT / slides". Do NOT use for code formatting, data charts, or wireframes.' --- > **Note:** Full Kami distribution includes ~30+ auxiliary files (CHEATSHEET.md, scripts/, references/, assets/diagrams/*.html). The core SKILL.md works standalone; scripts/build.py is required for PDF generation. Check the Shokunin ecosystem root for these. # kami · 紙 **紙 · かみ** - the paper your deliverables land on. Good content deserves good paper. One design language across eight document types: warm parchment canvas, ink-blue accent, serif-led hierarchy, tight editorial rhythm. Part of `Kaku · Waza · Kami` - Kaku writes code, Waza drills habits, **Kami delivers documents**. ## Workflow ## Step 0 · Load brand profile (if exists) Check `~/.config/kami/brand.md` (preferred) or `~/.kami/brand.md` (legacy fallback). If found, read `references/brand-profile.md` for the full four-layer application spec (placeholder substitution, session defaults, visual customization, habit notes) and its six guardrails. If no profile exists, continue without interruption. Key rule: explicit prompt > editorial judgment > habit notes > frontmatter defaults > built-in defaults. Profile fills gaps silently; it never overrides the current conversation. --- ## Step 1 · Decide the language **Match the user's language.** Chinese -> `*.html` / `slides-weasy.html`. English -> `*-en.html` / `slides-weasy-en.html`. Japanese -> CJK path (`.html` / `slides-weasy.html`) as best-effort, JP Mincho first, visual QA before shipping. Reference docs are shared English specs. When ambiguous (e.g. a one-word command like "resume"), ask a one-liner rather than guess. | User language | HTML templates | Slides (PDF default) | Slides (PPTX fallback) | |---|---|---|---| | Chinese (primary) | `*.html` | `slides-weasy.html` | `slides.py` | | English | `*-en.html` | `slides-weasy-en.html` | `slides-en.py` | | Japanese (best-effort) | `*.html` | `slides-weasy.html` | `slides.py` | | Other languages (best-effort) | choose CJK or EN path by script coverage, then verify manually | choose `slides-weasy.html` or `slides-weasy-en.html`, then verify manually | use `slides.py` / `slides-en.py` only if PPTX is required | > Default to the WeasyPrint HTML path; fall back to PPTX (`slides*.py`) only when the user explicitly needs an editable deck. Always use `CHEATSHEET.md` and `references/*.md` for design, writing, production, and diagram guidance. ## Step 1.5 · Intent extraction (silent checklist) Before ...[truncated]
---
name: kagen
description: Convert Kami HTML templates to production-grade PDF via Chromium/Playwright. Complements Kami (design) with PDF rendering. Use when user asks to generate PDF files, render HTML to PDF, or export documents.
---
# kagen · 紙源
**紙源 · かげん** - paper source. PDF generation companion to Kami.
Kami designs, **Kagen ships**. Converts Kami HTML templates to production-grade PDF using Chromium (Playwright), bypassing WeasyPrint's Windows limitations.
## Why Kagen
| Problem | Solution |
|---------|----------|
| WeasyPrint doesn't work on Windows (no GTK) | Kagen uses Playwright/Chromium — works everywhere |
| WeasyPrint cold-start ~630ms per render | Playwright warm ~13ms per render |
| WeasyPrint can't execute JS | Chromium renders fully (charts, dynamic content) |
| wkhtmltopdf is deprecated and unmaintained | Playwright is actively maintained by Microsoft |
Based on benchmarks (pdf4.dev 2026), engineering discussions (HN, Stack Overflow, BrowserStack), and production experience from DocRaptor, customjs.space, and print-css.rocks.
## Prerequisites
- Node.js 20+
- Playwright (`npx playwright` auto-installs on first use)
- Chromium browser installed (`npx playwright install chromium`)
- Kami HTML templates (any valid HTML with print CSS)
## Quick start
```powershell
npx playwright pdf "file:///path/to/doc.html" "output.pdf"
```
Or from Node.js:
```js
const { chromium } = require('playwright');
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('file:///path/to/doc.html', { waitUntil: 'networkidle' });
await page.pdf({
path: 'output.pdf',
format: 'A4',
printBackground: true,
margin: { top: '0', bottom: '0', left: '0', right: '0' }
});
await browser.close();
```
## Production settings (from professional research)
### Page options
```js
await page.pdf({
path: 'output.pdf',
format: 'A4', // or 'Letter', 'A3'
printBackground: true, // always true — renders parchment bg
margin: { top: '0', bottom: '0', left: '0', right: '0' },
// For screen media (not print):
// await page.emulateMedia({ media: 'screen' });
});
```
### Critical CSS rules for reliable PDF output
```css
/* Always include in your HTML template header */
@page {
size: A4;
margin: 24mm 26mm 26mm 26mm;
background: #f5f4ed;
widows: 4;
orphans: 4;
}
/* Force background colors in Chromium */
* {
-webkit-print-color-adjust: exact;
print-color-adjust: exact;
}
/* Avoid orphan text lines — high widows/orphans prevents single-line splits */
body { widows: 4; orphans: 4; }
p { widows: 3; orphans: 3; }
li { widows: 2; orphans: 2; }
/* Page break control — only on chapters with heavy content */
.chapter { }
.chapter.break { break-before: page; }
/* Never let a heading sit alone at page bottom */
h1, h2, h3, h4 { break-after: avoid; }
/* Keep these blocks intact — never split across pages */
table, pre, figure, .callout, .card,
blockquote, .finding-header, .takeaway
...[truncated]
---
name: portfolio-auto
description: Auto-sync GitHub repos to portfolio website. Scans GitHub repos, captures screenshots with Playwright, generates project entries, and updates projects-data.js or Supabase DB. Use when user asks to "update portfolio", "sync projects", "add my repos to portfolio", or "refresh portfolio projects". Do NOT use for one-time project additions — batch sync only.
license: MIT
compatibility: opencode
metadata:
workflow: automation
audience: developers
version: "2.0"
---
> **Note:** `last-sync.json` state file is auto-created on first successful sync. Ignore "missing file" warnings on first run.
# Portfolio Auto-Sync
Automatically sync GitHub repositories to your portfolio website.
## Workflow
### Step 1: Gather configuration
Ask the user:
- **GitHub username**: (default from git config)
- **Portfolio type**: `static` (projects-data.js) or `supabase` (API)
- **Portfolio directory**: Path to portfolio project
- **Filters**: Exclude repos (archived, forks, specific names)
### Step 2: Fetch repos via GitHub API
```
GET /users/{username}/repos?per_page=100&sort=updated&direction=desc
```
Extract: `name`, `description`, `html_url`, `homepage`, `language`, `topics`, `updated_at`
Filter out:
- Forks (unless user opts in)
- Profile repos (`{username}/{username}`)
- Archived repos
### Step 3: Detect changes
Compare against `last-sync.json` (stored in skill directory).
- **New repos**: Not in last sync → full process
- **Updated repos**: `updated_at` changed → re-screenshot
- **Unchanged repos**: Skip
### Step 4: Capture screenshots
For repos with a `homepage` or deploy URL:
```javascript
const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();
```
Save to portfolio's screenshot directory.
### Step 5: Update portfolio data
#### Static (projects-data.js)
```javascript
{
title: '{repo.name}',
description: 'Auto-generated: {description}',
tech: '{language},{topics}',
github_url: '{html_url}',
live_url: '{homepage || ""}',
featured: false
}
```
#### Supabase
```javascript
const res = await fetch('https://your-site.com/api/projects', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
body: JSON.stringify(projectData)
});
```
### Step 6: Save sync state
```json
{
"lastSync": "2026-05-12T18:30:00Z",
"repos": {
"example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
}
}
```
### Step 7: Report results
```
Sync complete:
+ 2 new (Cyberian, Image Enhancer)
+ 1 screenshot captured
+ 1 updated (Portfolio)
- 0 errors
```
## Notes
- Screenshots require Playwright + valid URL. Skip if no homepag
...[truncated]
AI Agents
3 skills--- name: agent-browser description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools. allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*) hidden: true --- # agent-browser Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with accessibility-tree snapshots and compact `@eN` element refs. Install: `npm i -g agent-browser && agent-browser install` ## Workflow ### Step 1: Navigate to a page ```bash agent-browser goto "https://example.com" agent-browser wait @e3 # wait for element to appear agent-browser html # get current DOM snapshot ``` The `goto` command navigates to a URL and waits for the page to load. Use `wait` to ensure specific elements are present before interacting. Always snapshot with `html` after navigation to get fresh `@eN` refs. ### Step 2: Interact with elements ```bash agent-browser click @e5 # click element by accessibility ref agent-browser type @e7 "hello world" # type into input agent-browser select @e9 "option-value" # select dropdown option agent-browser check @e12 # toggle checkbox/radio agent-browser hover @e15 # hover over element agent-browser press Enter # press keyboard key agent-browser scroll down 500 # scroll page by pixels agent-browser drag @e5 @e20 # drag element to target agent-browser upload @e8 "C:\path\to\file.pdf" # file input upload ``` All interactions use accessibility-tree element references (`@eN`). These are stable within a single page snapshot but invalidate after navigation or DOM mutations. ### Step 3: Extract data or capture evidence ```bash agent-browser screenshot page.png # full-page screenshot agent-browser screenshot --element @e5 el.png # element screenshot agent-browser screenshot --full-page false vp.png # viewport-only screenshot agent-browser text # visible text content agent-browser html ...[truncated]
---
name: agent-tools
description: "Run 150+ AI apps via inference.sh CLI - image generation, video creation, LLMs, search, 3D, Twitter automation. Models: FLUX, Veo, Gemini, Grok, Claude, Seedance, OmniHuman, Tavily, Exa, OpenRouter, and many more. Use when running AI apps, generating images/videos, calling LLMs, web search, or automating Twitter. Triggers: inference.sh, infsh, ai model, run ai, serverless ai, ai api, flux, veo, claude api, image generation, video generation, openrouter, tavily, exa search, twitter api, grok"
allowed-tools: Bash(infsh *)
---
# [inference.sh](https://inference.sh)
Run 150+ AI apps in the cloud with a simple CLI. No GPU required.
](https://cloud.inference.sh/app/files/u/4mg21r6ta37mpaz6ktzwtt8krr/01kgjw8atdxgkrsr8a2t5peq7b.jpeg)
## Install CLI
```bash
curl -fsSL https://cli.inference.sh | sh
infsh login
```
> **What does the installer do?** The [install script](https://cli.inference.sh) detects your OS and architecture, downloads the correct binary from `dist.inference.sh`, verifies its SHA-256 checksum, and places it in your PATH. That's it — no elevated permissions, no background processes, no telemetry. If you have [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) installed, the installer also verifies the Sigstore signature automatically.
>
> **Manual install** (if you prefer not to pipe to sh):
> ```bash
> # Download the binary and checksums
> curl -LO https://dist.inference.sh/cli/checksums.txt
> curl -LO $(curl -fsSL https://dist.inference.sh/cli/manifest.json | grep -o '"url":"[^"]*"' | grep $(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') | head -1 | cut -d'"' -f4)
> # Verify checksum
> sha256sum -c checksums.txt --ignore-missing
> # Extract and install
> tar -xzf inferencesh-cli-*.tar.gz
> mv inferencesh-cli-* ~/.local/bin/inferencesh
> ```
## Quick Examples
```bash
# Generate an image
infsh app run falai/flux-dev-lora --input '{"prompt": "a cat astronaut"}'
# Generate a video
infsh app run google/veo-3-1-fast --input '{"prompt": "drone over mountains"}'
# Call Claude
infsh app run openrouter/claude-sonnet-45 --input '{"prompt": "Explain quantum computing"}'
# Web search
infsh app run tavily/search-assistant --input '{"query": "latest AI news"}'
# Post to Twitter
infsh app run x/post-tweet --input '{"text": "Hello from AI!"}'
# Generate 3D model
infsh app run infsh/rodin-3d-generator --input '{"prompt": "a wooden chair"}'
```
## Local File Uploads
The CLI automatically uploads local files when you provide a path instead of a URL:
```bash
# Upscale a local image
infsh app run falai/topaz-image-upscaler --input '{"image": "/path/to/photo.jpg", "upscale_factor": 2}'
# Image-to-video from local file
infsh app run falai/wan-2-5-i2v --input '{"image": "./my-image.png", "prompt": "make it move"}'
# Avatar with local audio and image
infsh app run bytedance/omnihuman-1-5 --input '{"audio": "/path/to/speech.mp
...[truncated]
--- name: skill-creator description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. --- # Skill Creator A skill for creating new skills and iteratively improving them. At a high level, the process of creating a skill goes like this: - Decide what you want the skill to do and roughly how it should do it - Write a draft of the skill - Create a few test prompts and run the skill on them - Help the user evaluate the results both qualitatively and quantitatively - Rewrite the skill based on feedback from the user's evaluation of the results - Repeat until you're satisfied - Expand the test set and try again at larger scale Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat. On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop. Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead. Then after the skill is done (but again, the order is flexible), you can also optimize the description to improve the triggering of the skill. Cool? Cool. ## Communicating with the user The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of LLMs is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate. So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea: - "evaluation" and "benchmark" are borderline, but OK - for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it. --- ## Workflow ### Capture Intent Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/o ...[truncated]
Extras
6 skills--- name: playwright description: "Browser automation, web scraping, E2E testing, and visual regression with Playwright. Covers 30+ patterns: login flows, form testing, responsive design checks, broken link validation, API mocking, data extraction, PDF generation, accessibility audits (axe-core), performance budgets (Lighthouse), visual diffing, multi-browser testing (Chromium/Firefox/WebKit), mobile emulation, infinite scroll, shadow DOM, iframes, file downloads, auth state reuse, cookie consent handling, WebSocket monitoring, console error detection, HAR export, trace viewer, Docker CI, GitHub Actions, and parallel sharding. Use when user asks to test a website, take screenshots, check responsive design, automate a browser task, scrape data, validate forms, check broken links, test login, audit accessibility, or measure page performance. Do NOT use for unit testing, API-only testing, or static analysis. Requires Node.js 18+." license: MIT compatibility: opencode metadata: workflow: testing audience: developers version: 2.1.0 --- # Playwright — Browser Automation Skill Intelligent browser automation executor. Analyzes the user's request, selects the optimal pattern from 30+ built-in templates, generates production-grade Playwright code, and executes it with real-time reporting. ## Setup Playwright must be available in the environment. If not installed: ```bash npm init -y npm install playwright @playwright/test npx playwright install chromium ``` For all 3 browsers: ```bash npx playwright install ``` Check what's installed: ```bash npx playwright install --dry-run ``` ## Trigger Decision Tree When user asks for browser automation, classify the task: ``` User request ├── "screenshot" / "capture" / "take a picture" │ → screenshot template ├── "responsive" / "mobile" / "different sizes" │ → responsive check + per-viewport screenshots ├── "login" / "sign in" / "authenticate" │ → login flow with error detection ├── "form" / "fill" / "submit" / "input" │ → form testing with validation check ├── "broken links" / "check links" / "link validation" │ → broken link scanner ├── "scrape" / "extract" / "get data" / "crawl" │ → data extraction (single page or crawl) ├── "mock" / "intercept" / "stub" / "fake api" │ → API mocking with route interception ├── "accessibility" / "a11y" / "axe" / "wcag" │ → accessibility audit (requires axe-core) ├── "performance" / "lighthouse" / "speed" / "load time" │ → performance audit with budgets ├── "visual" / "visual regression" / "diff" │ → visual comparison screenshots ├── "download" / "file download" │ → file download handler ├── "console" / "errors" / "logs" │ → console error detector ├── "pdf" / "generate pdf" │ → page-to-PDF converter └── else → generic browse + report ``` ## Workflow ### Step 1: Detect the environment Before writing any code, determine what's available: - **Dev servers**: Check common ports (3000, 3001, 5173, 8080, 8000, 4200, 5000, 9000) for running proce ...[truncated]
--- name: Web Security description: > Apply professional-grade security standards to any web application task. Use this skill when writing code that handles authentication, authorization, user input, APIs, file uploads, sessions, secrets, payments, or any data from external sources. Also use when the user asks to review, audit, or assess security of code or a web app. Covers OWASP Top 10 (2025), secure coding, threat modeling, and defensive architecture. Activate even when security is not explicitly mentioned — treat every web feature as a security surface. --- # Web Security — Professional Standards ## Mindset Every input is hostile until proven otherwise. Every privilege is a liability until proven necessary. The average breach goes undetected for 200+ days — not because attacks are sophisticated, but because code assumed the caller was trustworthy. Security is not a feature added at the end. It is a design constraint applied from the first line. --- ## OWASP Top 10 — 2025 Edition Apply these as a mental checklist on every feature you build or review. ### A01 — Broken Access Control (#1 most exploited) The most common and most damaging class of web vulnerability. **Rules:** - Every endpoint must verify the caller has permission for the *specific resource* — not just that they're logged in - Deny by default: if there's no explicit `allow`, the answer is `deny` - Never expose internal IDs directly — use opaque tokens or UUIDs, not sequential integers (IDOR prevention) - Check authorization server-side on every request — never trust client-side state or hidden form fields - Validate CORS: `Access-Control-Allow-Origin: *` is only acceptable for truly public, read-only data - File path inputs must be sanitized — validate against a whitelist and use `path.resolve()` + check prefix **IDOR pattern to enforce:** ``` // Wrong — trusts caller owns the resource GET /api/orders/1234 // Right — verify ownership server-side const order = await getOrder(orderId) if (order.userId !== req.user.id) return 403 ``` ### A02 — Cryptographic Failures **Rules:** - HTTPS everywhere — no exceptions, including internal APIs - Never store passwords in plaintext or with reversible encryption — use bcrypt, Argon2, or scrypt - Never use MD5 or SHA-1 for security purposes — use SHA-256 minimum, SHA-512 preferred - Secrets (API keys, tokens, passwords) never go in source code — use environment variables or secrets managers - Sensitive data at rest must be encrypted — user PII, payment data, health records - Session tokens must be cryptographically random — minimum 128 bits of entropy - Never log sensitive data: passwords, tokens, credit card numbers, SSNs, health info **Secret detection before every commit:** ``` # Patterns that must NEVER appear in source code: # - API keys (sk-*, AIza*, AKIA*, etc.) # - Private keys (-----BEGIN PRIVATE KEY-----) # - Connection strings with passwords # - .env files committed to git ``` ### A03 — Injection (SQL, ...[truncated]
--- name: plan description: "Planning agent for task breakdown and implementation planning. Use via spawn_subagent with skill='plan' when you need to explore a codebase and design an implementation approach before writing code." metadata: version: 1.0.0 disable-model-invocation: false --- Entered plan mode. Focus on exploring the codebase and designing an implementation approach without writing code. In plan mode: 1. Thoroughly explore the codebase to understand existing patterns 2. Identify similar features and architectural approaches 3. Consider multiple approaches and their trade-offs 4. Design a concrete implementation strategy 5. Write the plan and return its path DO NOT write or edit any files yet (except the plan file). This is a read-only exploration and planning phase. ## Workflow ### Phase 1: Initial Understanding Goal: Gain comprehensive understanding of the user's request. **Use only research agents** — no other agent types. 1. Understand the user's request and associated code 2. **Launch research agents in parallel** (single message, multiple calls): - Use `skill: 'research'` for all exploration agents - Use the cheapest model available - 1 agent for isolated tasks with known files - Multiple agents for uncertain scope, multiple codebase areas, or pattern discovery - Max 3 agents — usually 1 is enough 3. Use multiple agents when: - Task touches multiple parts of the codebase - Large refactor or architectural change - Many edge cases to consider - Need to compare different approaches ### Phase 2: Design Goal: Design an implementation approach based on exploration results. Launch 1-3 design agents in parallel: - **Default**: 1 design agent for most tasks - **Skip agents**: Only for trivial tasks (typo fixes, single-line changes, simple renames) - **Multiple agents**: For complex tasks needing different perspectives Example perspectives by task type: - New feature: simplicity vs performance vs maintainability - Bug fix: root cause vs workaround vs prevention - Refactoring: minimal change vs clean architecture For each agent: - Provide comprehensive background from Phase 1 - Describe requirements and constraints - Request a detailed implementation plan ### Phase 3: Review Goal: Review plans and ensure alignment with user's intentions. 1. Read critical files identified by agents 2. Verify plans align with the original request 3. Do NOT call subagents here ### Phase 4: Final Plan Goal: Write the final plan. Include: - Only the recommended approach, not alternatives - Critical file paths to be modified - Verification section (how to test end-to-end) - Concise enough to scan, detailed enough to execute ## Plan Structure Template ``` ## Plan: [Feature Name] ### Summary [1-2 sentence overview of what will be built/changed] ### Files to Modify | File | Change | |------|--------| | path/to/file.ts | [what changes] | ### Implementation Steps 1. [Step 1]: [what to do, why, any gotchas] 2. [Step ...[truncated]
--- name: find-skills description: Search the agent skills ecosystem to discover and install skills that extend AI coding agent capabilities. Use when user asks "how do I do X" (X being a common task), "find a skill for X", "is there a skill that can...", or expresses interest in extending agent capabilities. Triggers on "find a skill", "install a skill", "skill for [task]", "can you do X", "I need help with [domain]", "how do I [task]". Do NOT use when user has explicitly asked to proceed without a skill, or when the task is better handled by agent's built-in capabilities (file operations, git, basic coding). license: MIT compatibility: opencode metadata: workflow: tooling audience: developers --- Help users discover and install skills from the open agent skills ecosystem. ## What is the Skills CLI? The Skills CLI (`npx skills`) is the package manager for agent skills: - `npx skills find [query]` - Search for skills - `npx skills add <package>` - Install from GitHub - `npx skills check` - Check for updates - `npx skills init [name]` - Scaffold a new skill Browse at: https://skills.sh/ ## Workflow ### Step 1: Understand what they need Identify: domain (React, testing, DevOps) → specific task (writing tests, creating animations) → likelihood a skill exists. ### Step 2: Check the leaderboard first Before running CLI: check https://skills.sh/ for well-known skills. Top sources: - `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs) - `anthropics/skills` — Frontend design, document processing (100K+ installs) - `zencoderai/skills` — OSS security, git gate (50K+ installs) ### Step 3: Search ```bash npx skills find [query] ``` Examples: - "how do I make my React app faster" → `npx skills find react performance` - "help with PR reviews" → `npx skills find pr review` - "create a changelog" → `npx skills find changelog` ### Step 4: Verify quality - **Install count**: Prefer 1K+. Be cautious under 100. - **Source reputation**: Official sources (`vercel-labs`, `anthropics`, `microsoft`) over unknown authors. - **GitHub stars**: Source repo < 100 stars → treat with skepticism. ### Step 5: Present options Include: skill name, what it does, install count, source, install command. ``` I found a skill that might help! "react-best-practices" provides React/Next.js performance optimization guidelines from Vercel Engineering. (185K installs) To install: npx skills add vercel-labs/agent-skills@react-best-practices Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices ``` ### Step 6: Install (if user agrees) ```bash npx skills add <owner/repo@skill> -g -y ``` `-g` installs globally, `-y` skips confirmation. ## Common Categories | Category | Example Queries | |----------|----------------| | Web Development | react, nextjs, typescript, css, tailwind | | Testing | testing, jest, playwright, e2e | | DevOps | deploy, docker, kubernetes, ci-cd | | Documentation | docs, readme, changelog, api-docs | | C ...[truncated]
--- name: Efficient Coding description: > Use this skill on every programming task — writing code, fixing bugs, refactoring, explaining code, running tools, or answering technical questions. Apply token-saving and quality-preserving practices throughout. Activate even when the user doesn't explicitly ask for efficiency — this skill is always relevant for software development work. Do not skip this skill for "simple" tasks; the rules apply at every scale. --- # Efficient Coding ## Core Principle Every action has a token cost. The goal is to solve the task with the minimum context needed — not minimum effort, minimum *waste*. Lean context produces faster results and better attention on what matters. --- ## 1. Context — The Biggest Cost Driver Context bloat (sending more than the model needs) is responsible for more wasted tokens than any other cause. Attack it first. **Search before reading:** - Use Grep/Glob to find the exact file and line range before opening anything. - Read only the section you need with `offset` + `limit`, not the whole file. - Never dump entire directories or large files into context speculatively. **Read each file at most once per task:** - If a file is already in context, reuse that knowledge. Don't re-read it. - Exception: re-read only if the file was modified since you last read it. **Phase separation:** - Do discovery (reading, searching, understanding) first, then switch to implementation. - Don't interleave exploration and editing — stale discovery context charges you on every subsequent turn. **Precision over coverage:** - If you only need to understand a function, read that function — not the whole module. - If you only need a type signature, search for it — don't open the file. --- ## 2. Tool Usage — Eliminate Round-Trip Waste **Batch independent calls:** - When multiple files, searches, or commands are needed and don't depend on each other, issue all calls in a single response — not one at a time. - Example: reading 3 unrelated files → one response with 3 Read calls, not 3 sequential responses. **Prefer direct CLI over layered tools:** - A direct shell command (Bash) is cheaper than an MCP tool that wraps it. - Use MCP tools only when they provide genuine capability above the CLI equivalent. **Stop speculative exploration:** - Don't run commands "just to see what happens." Form a hypothesis first, then act. - If the path forward is clear, execute. Don't narrate findings and then ask permission to proceed. --- ## 3. Output — Cut Everything That Doesn't Help **No narration, no preamble, no postamble:** - Don't explain what you're about to do — do it. - Don't summarize what you just did — the result speaks for itself. - Don't add "I hope this helps!" or similar closers. **No unsolicited explanations of code:** - If the user asked for code, write the code. Don't explain it unless asked. - If the user asked for a fix, apply the fix. Don't describe what was wrong unless asked. **No unsolic ...[truncated]
---
name: Senior Engineer Coding
description: >
Apply senior software engineering standards when writing, editing, or refactoring
any code. Use this skill whenever the user asks to write a function, build a feature,
fix a bug, design a module, or improve existing code — even if they don't mention
quality explicitly. The goal is production-grade code: readable, correct, maintainable,
secure, and failure-aware. Always active for any coding task, at any scale.
---
# Senior Engineer Coding
## Mindset
Write code for the next engineer who has to change it at 2am with no context.
Clean code is risk management. Every production incident traces back to unclear,
poorly structured, or hard-to-change code — not missing cleverness.
The standard: a teammate can safely change the code without fear, and explain
what it does after a quick read.
---
## 1. Naming — Highest ROI Habit
Good names eliminate comments, prevent misunderstandings, and make refactoring safe.
**Rules:**
- Name by **intent**, not by type or storage: `emailAddress` not `emailString`
- Use **domain language**: reflect business concepts (`Invoice`, `Subscription`, `Refund`)
- Include **units** in names: `timeoutMs`, `priceCents`, `fileSizeBytes`
- Make **booleans** read as questions: `isEnabled`, `hasAccess`, `shouldRetry`
- Name from the **caller's perspective**: `order.chargePayment()` not `order.process()`
- Be **consistent**: one concept, one word. Never `user` in one place and `customer` in another for the same entity
**Avoid:**
- Noise words: `manager`, `helper`, `data`, `info`, `handler` (unless genuinely descriptive)
- Abbreviations that don't scale: `usrAcctMgr`, `calcDisc`
- Overly generic verbs: `process()`, `handle()`, `doWork()`, `run()`
- Single-letter variables outside tiny loops: `d`, `x`, `tmp` cause real production bugs
---
## 2. Functions — Small, Focused, Predictable
**One function = one job.** If you can't describe it in one sentence, it does too much.
**Guard clauses over nested ifs:**
```
// Wrong — pyramid of doom, hides assumptions
if (user != null) {
if (user.isActive()) {
if (hasAccess(user)) {
process(user)
}
}
}
// Right — early returns, happy path stays flat
if (user == null) return
if (!user.isActive()) return
if (!hasAccess(user)) return
process(user)
```
**Limit parameters:**
- More than 3 parameters → create a request/options object
- Long param lists break silently when order is swapped; objects don't
**Separate computation from I/O:**
- Pure logic (calculation, transformation) → separate from functions that read files, call APIs, write DBs
- Pure functions are easier to test, easier to reason about, and have no hidden side effects
**Command/Query separation:**
- Functions that return data → must not mutate state
- Functions that mutate → return a status/result, not data
---
## 3. No Magic Numbers or Strings
Every hardcoded value with business meaning is a future bug.
```
// Wrong
price * 1.21
if (status === 3)
s
...[truncated]
Ecosystem
3 skills--- name: shokunin-update description: Detect drift, plan updates, and apply changes to the Shokunin AI Ecosystem. Use this when user asks to update, fix, sync, or verify the ecosystem. --- > **Note:** The `shokunin-update.ps1` script lives in `.pack/scripts/` and is deployed to `~/.shokunin/scripts/` by the installer. # Shokunin Update System Maintains the Shokunin ecosystem by detecting drift between the declarative manifest and the actual filesystem state. ## Workflow ### 1. Load the manifest Read `~/.shokunin/shokunin.json`. This is the single source of truth. Every component, path, hash, and template is defined here. ### 2. Check status Run `shokunin-update.ps1 status` to detect drift: - OK: hash matches manifest - MISSING: file doesn't exist but manifest expects it - PROTECTED: data files (chroma_db, sessions) that must never be modified Report results to the user with counts. ### 3. Plan changes Run `shokunin-update.ps1 plan` to see what would change without applying anything. Show the user a clear summary of what will be created, modified, or left alone. ### 4. Apply with confirmation ```powershell & "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" apply -Confirm ``` This automatically: 1. Backs up each file to `~/.shokunin/backups/<timestamp>/` 2. Applies changes 3. Saves update event to ChromaDB 4. Runs `memory-healthcheck.ps1` to verify ### 5. Rollback if needed ```powershell & "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" rollback -Timestamp 20260514-120000 ``` ## When to use this skill - User notices something broken in the ecosystem - User wants to add/remove/modify a component - User asks "is everything up to date?" - Pre-commit or pre-PR verification ## Do NOT - Modify files in `protected` groups (chroma_db, sessions, logs, backups) - Apply changes without user confirmation - Edit the manifest without understanding every field ## Error Handling | Cause | Fix | |-------|-----| | shokunin.json manifest is missing or malformed | Validate JSON syntax with `Test-Json`. If missing, run installer `~/.shokunin/install.ps1` to regenerate from template. Report exact parse error line if malformed. | | File hash mismatch but content is identical | Encoding difference (CRLF vs LF) or trailing whitespace. Normalize line endings with `.pack/scripts/normalize-eol.ps1` before re-checking. | | Backup directory exceeds disk quota | Old backups accumulate over time. Retention policy: keep last 5 backups. Purge older directories with `Remove-Item -Recurse`. | | Protected file group modified by apply | A bug or misconfiguration in the manifest marked a protected path as writable. Abort immediately. Rollback from backup. Fix manifest before retry. | | Rollback target timestamp not found | Backup was purged by retention policy or never created. Cannot recover that point in time. Run `status` to assess current state and manually fix drift. | | Powershell execution policy blocks the script | System execution polic ...[truncated]
---
name: chromadb
description: Manage the ChromaDB vector database that stores the ecosystem's persistent memory. Use when user asks to check memory storage, backup memory, search stored entries, delete entries, or reset the vector database. Do NOT use for general question answering about past sessions (use the memory skill for that).
license: MIT
compatibility: opencode
metadata:
workflow: administration
audience: developers
version: "4.2.2"
---
# chromadb · Memory Storage
**ChromaDB** is the vector database that powers Shokunin's persistent AI memory. It stores embeddings for semantic search across sessions. Built on SQLite with an ONNX embedding model for local-first, offline-capable operation.
## Workflow
### Step 1: Check storage status
```powershell
python ~/.shokunin/scripts/chroma-helper.py count
```
Output: total entries, collection count, disk size on disk, last write timestamp.
```powershell
python ~/.shokunin/scripts/chroma-helper.py stats
```
Output: entries per type (decision, file, command, checkpoint, session_end), per project, per date range.
### Step 2: Search stored entries
```powershell
python ~/.shokunin/scripts/chroma-helper.py search "query text" "project-name" 10
```
Searches via vector similarity + BM25 keyword hybrid. Results sorted by relevance with metadata attached.
```powershell
python ~/.shokunin/scripts/chroma-helper.py search "error handling" "" 20 --type decision
```
Filter by entry type. Leave project empty to search all projects.
### Step 3: List recent entries
```powershell
python ~/.shokunin/scripts/chroma-helper.py recent 10
```
Shows the 10 most recently inserted entries across all projects. Use for quick audit.
```powershell
python ~/.shokunin/scripts/chroma-helper.py recent 50 --project myproject
```
Filter recent entries to a specific project.
### Step 4: Backup the database
```powershell
$backupDir = "$env:USERPROFILE\.shokunin\backups\chroma-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
New-Item -ItemType Directory -Path $backupDir -Force | Out-Null
Compress-Archive -Path "$env:USERPROFILE\.shokunin\memory\chroma_db" -DestinationPath "$backupDir\chroma_db.zip" -Force
```
Also back up session logs:
```powershell
Compress-Archive -Path "$env:USERPROFILE\.shokunin\memory\sessions" -DestinationPath "$backupDir\sessions.zip" -Force
```
Verify backup integrity:
```powershell
Add-Type -AssemblyName System.IO.Compression.FileSystem
[System.IO.Compression.ZipFile]::OpenRead("$backupDir\chroma_db.zip").Entries.Count
```
### Step 5: Delete entries by session prefix
```powershell
python ~/.shokunin/scripts/chroma-helper.py delete "session-prefix"
```
Deletes all entries whose session_id starts with the given prefix. Non-reversible. Backup first.
```powershell
python ~/.shokunin/scripts/chroma-helper.py delete --project "old-project"
```
Delete all entries for a project. Useful when archiving finished projects.
### Step 6: Full reset (requires confirmation)
```powershell
Remove-Item -
...[truncated]
--- name: memory description: Persistent memory across AI sessions using ChromaDB vector database. Stores and retrieves context from past conversations, decisions, and code. Use when user asks to remember something, search past conversations, recall what was done before, save context for later, or find information from previous sessions. Do NOT use for git history or file-based notes. license: MIT compatibility: opencode metadata: workflow: productivity audience: developers version: "1.0" author: shokunin allowed-tools: Read Bash Write --- # Memory Persistent memory across sessions using ChromaDB vector search. Every conversation is stored and retrievable. ## How It Works The memory system uses ChromaDB (local vector database, no server needed) to store conversation context as embeddings. When you start a new session, the agent searches past memory for relevant context. - **Storage**: `~/.shokunin/memory/chroma_db/` (ChromaDB persistent files) - **Sessions**: `~/.shokunin/memory/sessions/` (markdown summaries per session) - **MCP Server**: `~/.shokunin/memory/mcp-server.py` ## Workflow ### Step 1: Start memory server (if not running) The memory MCP server is configured in opencode.json. It starts automatically when OpenCode connects to it. ### Step 2: Save context during session At the end of each significant task, save context: ``` store_context with: text: "Summary of what was done, key decisions, code patterns" tags: ["project-name", "feature", "language"] project: "project-name" session_id: "current-session-id" ``` ### Step 3: Search past memory at session start When starting a new session, search for relevant context: ``` search_context with: query: "what we discussed about auth" project: "current-project" ``` ### Step 4: Get full session summary ``` get_session_summary with: session_id: "session-id" ``` ## Automatic Session Save The agent should automatically: 1. At the end of the session, save a summary of key decisions and context 2. At the start of a new session, search for relevant past context 3. Present relevant past context to the user naturally ## Error Handling | Error | Cause | Fix | |-------|-------|-----| | ChromaDB not found | Not installed | `pip install chromadb` | | Collection not found | First run | Creates automatically on first store | | Slow first query | Downloading ONNX model | First run downloads ~79MB. Subsequent runs are instant. | | Memory not returning results | No data stored yet | Normal on first use. Start by saving something. | | Embedding model fails to download | Network blocked or proxy required | Set `CHROMADB_EMBEDDING_MODEL` env var. Fall back to `all-MiniLM-L6-v2` which is smaller (~23MB). | | Duplicate or stale entries flooding results | Auto-save firing too frequently during rapid iteration | Apply 5-second debounce before storing context. Consolidate entries with `memory_consolidate_memories` periodically. | | Collection corrupted after crash | Write interrup ...[truncated]
Language
3 skills--- name: humanize description: Rewrite AI-generated text to sound natural, remove AI tells, and adjust tone. Use when user asks to make text less robotic, more natural, or humanize AI output. Covers tone matrix, filler words, sentence rhythm, and anti-AI-slop patterns. --- # humanize · 人間 **人間 · にんげん** — "human being". Makes AI-generated text sound like a real person wrote it. Based on research from: Grammarly, MIT Technology Review, GPTZero, QuillBot, Reddit (r/auscorp, r/cybersecurity), Hacker News, Stack Overflow, JustDone, print-css.rocks, BrowserStack, pdf4.dev benchmarks, and professional writing guides (2024–2026). --- ## Core metrics AI detectors measure | Metric | What it means | Human text | AI text | |--------|---------------|------------|---------| | **Perplexity** | How predictable each word is | High — uses unexpected words | Low — always picks the most probable word | | **Burstiness** | Variance in sentence length | High — mixes short/long sentences | Low — uniform sentence length | | **Word frequency** | Rate of common vs rare words | Balanced — uses uncommon terms | Skewed — overuses "the", "it", "is" | | **Repetition** | Recurring patterns | Low — natural variation | High — same structures repeat | Sources: GPTZero, QuillBot, MIT Technology Review, Google Brain research (Ippolito et al. 2020) --- ## The 16 AI tells (how to spot them) ### 1. Overused buzzwords (Grammarly 2026, Reddit) | AI word | Human alternative | |------------|-------------------| | delve into | analyze, explore, dig into | | pivotal | key, decisive, critical | | underscore | highlight, point out, stress | | multifaceted | complex, with several aspects | | landscape | ecosystem, context, situation | | paradigm | model, approach, framework | | robust | solid, reliable, resilient | | leverage | use, harness, take advantage of | | seamless | smooth, frictionless, natural | | transformative | disruptive, profound, radical | ### 2. Mechanical connectors (GPTZero research) - "Moreover", "Furthermore", "Nevertheless", "Consequently" → use "Also", "But", "So" or nothing - "However" every 3 paragraphs → cut half, let it flow - "Nevertheless", "Therefore", "Consequently" → replace with "So", "Then", "That means" ### 3. Perfect symmetrical structure (MIT Tech Review) LLMs generate paragraphs of the same length, same structure: intro → point → example → conclusion. **Fix:** Break the pattern. One-line paragraph. Then a long one. List. Then another short one. ### 4. Low burstiness (QuillBot, pdf4.dev) AI produces sentences of similar length. Humans alternate: - Short sentence. Impact. - Then a longer one that develops the idea with more detail and nuance, adding context. - Another short one. ### 5. Absolute neutrality (r/auscorp, Reddit) AI never takes a position. Sounds like a wiki. **Fix:** Add opinion, judgment, acknowledged bias. "We don't like this", "This is well done", "This is debatable". ### 6. Forced transitions (HN, cybersecurity forums) "I ...[truncated]
--- name: research description: Deep research with web search, source verification, and fact-checking. Runs before humanize + kami in the document pipeline. Use when user asks to research a topic, verify facts, gather sources, or do deep web investigation. Covers source validation, citation, and evidence hierarchy. --- # research · 調査 **調査 · ちょうさ** — "investigation". Source verification and fact-checking for document generation. Pre-loads facts before writing. Runs BEFORE humanize + kami + kagen in the document pipeline. Prevents hallucinated data, fake citations, unverified claims. Based on: CIA Structured Analytic Techniques (Heuer & Pherson), US Government Tradecraft Primer, NPR Training verification guide, Princeton triangulation methodology, OSINT verification tiers (War Intel Hub), journalistic cross-verification research (Godler & Reich), AI hallucination benchmarks (Vectara HHEM 2026), and evidence hierarchy frameworks (NHMRC). --- ## Core principle **Sources before phrasing.** Do not write a claim without verifying it first. Every number, date, name, version, and citation must be traced to a primary or reputable secondary source. --- ## Evidence hierarchy (adapted from NHMRC + intelligence community) Use this hierarchy to determine the weight of each source: | Level | Type | Example | |-------|------|---------| | **1 — Direct primary** | Official document, direct capture, observed data | Real HTTP response, source code, DB dump, screenshot | | **2 — Official primary** | Official statement, public documentation, filing | SEC filing, CVE entry, official changelog, press release | | **3 — Reputable secondary** | Established outlet, peer-reviewed paper, curated database | NVD, Wordfence, OWASP, Reuters, arXiv | | **4 — Multiple independent sources** | 3+ unrelated sources report the same | Cross-reference across tech blogs + forums + docs | | **5 — Single source with evidence** | One verifiable source but no corroboration | Researcher blog with reproducible evidence | | **6 — Unverified** | Unsupported claim, rumor, speculation | Do NOT use as fact in a document | **Rule:** a professional document only uses levels 1–4 for factual claims. Level 5 for context or direct quotes, marked as such. Level 6 is not published. --- ## Source verification protocol (NPR + Princeton triangulation) ### Step 1: The direct knowledge test (before citing) Ask about each source: - **First-hand:** Did the source witness the event, participate directly, or have documentation? → Strong, but requires corroboration - **Second-hand:** Did the source hear it from someone else? → Useful for leads, insufficient to publish - **Third-hand+:** Rumor, hearsay, speculation? → Not publishable as fact ### Step 2: Triangulation (Princeton method) Cross-check each claim against multiple independent sources: ``` Claim: "WordPress 6.7 has vulnerability X" → Source A: official WordPress advisory → Source B: entry in NVD/CVE → Source C: Wordfence or similar a ...[truncated]
--- name: init description: "Use when the user asks to initialize a repo, create AGENTS.md, generate contributor guidelines, or set up agent-oriented documentation for a codebase." disable-model-invocation: true metadata: version: 1.3.0 --- # AGENTS.md Generator Analyze a codebase and generate a concise, accurate `AGENTS.md` contributor guide. **Target:** the current working directory, unless user provided another folder as input. --- ## Gather Information Collect facts about the repository. **Only record what is actually found — never invent information.** These probes are independent — run them in parallel (e.g., dispatch subagents) when the tooling supports it. ### Repository structure Map the repo structure (3 levels deep, excluding .git, node_modules, dist, build, __pycache__, .venv and other autogenerated folders). This is analysis input — the output AGENTS.md should describe non-obvious architecture, not list directories. Focus on the "big picture" that requires reading multiple files to understand. ### Build & dev commands Extract actual command definitions from the project's build system: `package.json` scripts, `Makefile` targets, `pyproject.toml` scripts, `Cargo.toml` bins/workspace members, `go.mod` module path, `docker-compose.yml` services, etc. ### Coding conventions Check for and record key settings of: - Linter configs - Formatter configs - Type checking (note strict mode if applicable) - Agent rules: `.cursorrules`, `.cursor/rules/`, `.github/copilot-instructions.md` - Pre-commit hooks If agent rules files exist, read and extract the important parts — focus on conventions that matter for code generation, not verbatim content. ### Git history Review the last 20 commits to identify commit message conventions and patterns. If this fails (not a git repo or shallow clone), note the limitation and skip. ### Existing documentation - If `README.md` exists, read it for context about the repo's purpose and setup. - If `AGENTS.md` already exists, read it — you'll be improving it rather than starting fresh. - If `CLAUDE.md` exists, read it for additional context. --- ## Generate AGENTS.md ### Document requirements - Title: `# Repository Guidelines` - 200-400 words (exceed only if complexity genuinely demands it) - Direct, instructional tone - No repetition across sections ### Sections to include (omit any that lack evidence) **## Project Structure & Module Organization** Architecture that requires reading multiple files to understand. Omit anything obvious from opening a single file. **## Build, Test, and Development Commands** Actual commands from the build system. Include how to run a single test. **## Coding Style & Naming Conventions** Enforced rules from linter/formatter configs. Include tool names. **## Testing Guidelines** Test framework, how to run tests, coverage requirements if any. **## Commit & Pull Request Guidelines** Commit conventions derived from actual git history. Note any PR templates. Add ...[truncated]