Editor Integration Skills

AI Agent Skills

在 AI 编辑器（Cursor、Windsurf）中使用这些技能文档，让 AI 掌握 Kest Flow 编写、执行以及前端开发规范

Kest Flow & Testing Skills

编写和执行 Kest Flow 测试、API 文档生成的技能规范

Kest Flow Writing (kest-flow-writing)

Write structured, chained API tests using Kest Flow (.flow.md) with ```step/```flow/```edge blocks, exec steps, variable chaining, and assertions.

---
name: kest-flow-writing
description: Expert guide for writing Kest Flow tests (v0.7.0)
---

# Kest Flow Writing Skill

## Two Syntax Variants

### New Syntax (Recommended): step/flow/edge blocks
```step
@id login
@name Login
@retry 2
POST /api/v1/login
{ "username": "admin", "password": "123" }

[Captures]
token = data.access_token

[Asserts]
status == 200
duration < 500
```

### Exec Steps (shell commands)
```step
@id gen-sig
@type exec
echo -n "{{ts}}" | openssl dgst -sha256
[Captures]
signature = $line.0
```

### Legacy Syntax (still supported)
```kest blocks with Markdown headings

## Key Rules
- New: ```step with @id/@name
- Captures use = : var = path
- Built-in vars: {{$randomInt}}, {{$timestamp}}

Kest API Testing (kest-testing)

High-velocity API testing with Kest CLI v0.7.0: AI commands, REST/gRPC/SSE, mock server, snapshot testing, watch mode, variable chaining, replay & diff.

---
name: kest-testing
description: Kest CLI v0.7.0 for high-velocity API testing
---

# Kest API Testing Skill

## Core Commands
- REST: kest get|post|put|delete /path
- Capture: -c "token=data.access_token"
- Assert: -a "status==200"
- AI: kest why · kest suggest · kest gen
- Mock: kest mock --port 8080
- Snap: kest snap /api/users --verify
- Watch: kest watch login.flow.md
- Replay: kest replay last --diff
- Stream: kest post /chat --stream
- gRPC: kest grpc host service/Method

## AI-Powered
kest why          # Diagnose last failure
kest suggest      # AI suggests next call
kest gen "desc"   # Generate .flow.md

API Documentation Generation (api-doc-gen)

Generate hallucination-free API docs from Go source code with Kest CLI, including Mermaid diagrams and permission analysis.

---
name: api-doc-gen
description: Generate API docs from source code using Kest CLI
---

# API Documentation Generation

## Core Principles
1. Strict Schema Adherence
2. Zero Hallucination
3. Visual Clarity (Mermaid diagrams)
4. Security First (permission docs)

## Commands
kest doc <path> -o <output> --ai
kest doc <path> -o <output> -m <module> --ai

## Anti-Hallucination Rules
- No Ghost Wrapping
- No field renaming
- No missing fields

Frontend Development Skills

前端项目开发规范、状态管理、主题系统等技能文档

Environment Configuration (environment-config)

Strict rules for environment variable management using Zod validation and src/config/env.ts

---
name: environment-config
description: Strict rules for environment variable management
---

# environment-config

## Guidelines

### 1. Single Source of Truth
All environment variables MUST be defined in `src/config/env.ts`.

❌ DO NOT:
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

✅ DO:
import { env } from '@/config/env';
const apiUrl = env.NEXT_PUBLIC_API_URL;

### 2. Validation (Zod)
Use zod to validate at runtime...

Data State Management (data-state-management)

Zustand stores, React Query hooks, and Service-Hook-Type pattern specifications

---
name: data-state-management
description: Zustand stores, React Query hooks, Service-Hook-Type pattern
---

# data-state-management

## State Categories
- Auth State: src/store/auth-store.ts (Zustand + persist)
- UI State: src/store/ui-store.ts (Zustand)
- Server State: React Query for API data

## Service-Hook-Type Pattern
Layer 1: Types (src/types/*.ts)
Layer 2: Services (src/services/*.ts)
Layer 3: Hooks (src/hooks/*.ts)...

UI Styling Guide (ui-styling-guide)

shadcn/ui components, OKLCH theme system, and styling specifications

---
name: ui-styling-guide
description: shadcn/ui primitives, components, OKLCH theme system
---

# ui-styling-guide

## Theme System (OKLCH & CSS Variables)
- Primitives: src/themes/primitives.css
- Semantic Tokens: light.css / dark.css
  - Backgrounds: bg-canvas, bg-surface, bg-subtle
  - Foregrounds: text-main, text-subtle, text-muted
  - Borders: border-main, border-subtle, border-strong

Example:
<div className="bg-bg-surface text-text-main border-border-subtle">
  <h1 className="text-brand">Heading</h1>
</div>...

API Error Handling (api-error-handling)

Standardized error format, code clusters, and API client usage standards

---
name: api-error-handling
description: Standardized error format, error codes, API client usage
---

# api-error-handling

## Error Response Format
{
  "code": "AUTH_001",
  "message": "Invalid credentials",
  "details": { "field": "password" }
}

## Error Code Clusters
- AUTH_xxx: Authentication errors
- VALIDATION_xxx: Input validation
- RESOURCE_xxx: Resource not found
- PERMISSION_xxx: Authorization errors...

Internationalization (i18n-handler)

Guidelines for managing i18n using next-intl and unified translation patterns

---
name: i18n-handler
description: Managing i18n using next-intl and unified translation patterns
---

# i18n-handler

## Guidelines

### 1. Use the useT Hook
import { useT } from '@/i18n/use-t';
const { t, formatDate } = useT();

<h1>{t('welcome')}</h1>

### 2. Translation Files Structure
src/i18n/messages/
  - zh.json
  - en.json...

如何使用

1. 在 Cursor/Windsurf 中添加规则

点击上方的"复制技能文档"按钮，将内容粘贴到编辑器的 .cursorrules 或 .windsurfrules 文件中

项目根目录/.cursorrules

2. AI 将自动遵循规范

配置完成后，AI 助手在生成代码时会自动遵循项目的编码规范、设计模式和最佳实践

3. 保持规则更新

项目规范更新时，重新访问本页面获取最新的技能文档