@mandujs/skills 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,85 @@
+{
+  "name": "mandu-skills",
+  "description": "Claude Code plugin for Mandu Framework - architecture skills, guard hooks, MCP integration, and scaffolding workflows for agent-native fullstack development.",
+  "version": "1.0.0",
+  "author": "konamgil",
+  "homepage": "https://github.com/konamgil/mandu",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git",
+    "directory": "packages/skills"
+  },
+  "license": "MPL-2.0",
+  "skills": [
+    {
+      "name": "mandu-create-feature",
+      "path": "../skills/mandu-create-feature/SKILL.md",
+      "description": "Feature scaffolding - pages, API routes, Islands via MCP negotiate/generate pipeline"
+    },
+    {
+      "name": "mandu-create-api",
+      "path": "../skills/mandu-create-api/SKILL.md",
+      "description": "REST API generation - CRUD endpoints, auth, file upload with contracts and tests"
+    },
+    {
+      "name": "mandu-debug",
+      "path": "../skills/mandu-debug/SKILL.md",
+      "description": "Error diagnosis and repair - build failures, white screens, Island issues, API errors"
+    },
+    {
+      "name": "mandu-explain",
+      "path": "../skills/mandu-explain/SKILL.md",
+      "description": "Mandu concept reference - Island, Filling, Guard, Contract, Slot, SSR, ISR explanations"
+    },
+    {
+      "name": "mandu-guard-guide",
+      "path": "../skills/mandu-guard-guide/SKILL.md",
+      "description": "Guard architecture guide - presets, violation fixes, layer rules"
+    },
+    {
+      "name": "mandu-deploy",
+      "path": "../skills/mandu-deploy/SKILL.md",
+      "description": "Production deployment pipeline - Docker, CI/CD, nginx configuration"
+    },
+    {
+      "name": "mandu-slot",
+      "path": "../skills/mandu-slot/SKILL.md",
+      "description": "Filling API reference - ctx methods, lifecycle hooks, middleware chains"
+    },
+    {
+      "name": "mandu-fs-routes",
+      "path": "../skills/mandu-fs-routes/SKILL.md",
+      "description": "File-system routing - pages, API routes, layouts, dynamic params"
+    },
+    {
+      "name": "mandu-hydration",
+      "path": "../skills/mandu-hydration/SKILL.md",
+      "description": "Island hydration - partial hydration, client hooks, import rules"
+    }
+  ],
+  "templates": {
+    ".mcp.json": "../templates/.mcp.json",
+    ".claude/settings.json": "../templates/.claude/settings.json"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "description": "Validate architecture guard rules before file modifications"
+      }
+    ]
+  },
+  "requires": {
+    "mcpServers": ["mandu"]
+  },
+  "keywords": [
+    "mandu",
+    "framework",
+    "fullstack",
+    "bun",
+    "typescript",
+    "react",
+    "island-architecture",
+    "agent-native"
+  ]
+}

package/README.md

@@ -0,0 +1,77 @@
+# @mandujs/skills
+
+Claude Code plugin for the Mandu Framework. Provides 9 architecture skills, guard validation hooks, MCP integration, and development environment setup for agent-native fullstack development.
+
+## 9 Skills
+
+| Skill | Description |
+|-------|-------------|
+| **mandu-create-feature** | Feature scaffolding via MCP negotiate/generate pipeline |
+| **mandu-create-api** | REST API generation with contracts and tests |
+| **mandu-debug** | Error diagnosis and repair (8-category triage) |
+| **mandu-explain** | Mandu concept reference (18 concepts) |
+| **mandu-guard-guide** | Guard architecture guide (6 presets) |
+| **mandu-deploy** | Production deployment (Docker, CI/CD, nginx) |
+| **mandu-slot** | Filling API reference (ctx methods, lifecycle, middleware) |
+| **mandu-fs-routes** | File-system routing rules and layout constraints |
+| **mandu-hydration** | Island hydration and client import rules |
+
+## Installation
+
+### Via `mandu init` (Recommended)
+
+```bash
+bunx mandu init my-app
+```
+
+Skills are automatically installed during project creation.
+
+### Manual Installation
+
+```bash
+bun add -D @mandujs/skills
+bunx mandu-skills install
+```
+
+### Existing Project Upgrade
+
+```bash
+bunx mandu-skills install --force
+```
+
+## What Gets Installed
+
+```
+.claude/
+  skills/
+    mandu-create-feature.md
+    mandu-create-api.md
+    mandu-debug.md
+    mandu-explain.md
+    mandu-guard-guide.md
+    mandu-deploy.md
+    mandu-slot.md
+    mandu-fs-routes.md
+    mandu-hydration.md
+  settings.json
+.mcp.json
+```
+
+## CLI
+
+```bash
+mandu-skills install              # Install all skills
+mandu-skills install --force      # Overwrite existing
+mandu-skills install --dry-run    # Preview changes
+mandu-skills list                 # List available skills
+```
+
+## Version Compatibility
+
+| @mandujs/skills | @mandujs/core | @mandujs/mcp |
+|-----------------|---------------|--------------|
+| 1.0.x | >= 0.19.0 | >= 0.18.10 |
+
+## License
+
+MPL-2.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mandujs/skills",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Claude Code skills and plugin for Mandu framework",
+  "license": "MPL-2.0",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./init-integration": "./src/init-integration.ts"
+  },
+  "bin": {
+    "mandu-skills": "./src/cli.ts"
+  },
+  "files": [
+    "src/**/*",
+    "skills/**/*",
+    "templates/**/*",
+    ".claude-plugin/**/*",
+    "README.md"
+  ],
+  "keywords": [
+    "mandu",
+    "claude-code",
+    "skills",
+    "plugin",
+    "ai",
+    "agent",
+    "architecture",
+    "guard"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git",
+    "directory": "packages/skills"
+  },
+  "author": "konamgil",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "@mandujs/core": ">=0.19.0"
+  },
+  "peerDependenciesMeta": {
+    "@mandujs/core": {
+      "optional": true
+    }
+  }
+}

package/skills/mandu-create-api/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: mandu-create-api
+description: |
+  REST API 생성. CRUD/인증/업로드 엔드포인트. 'API', 'endpoint', 'CRUD' 시 자동 호출
+---
+
+# Mandu Create API
+
+REST API 엔드포인트를 생성하는 워크플로우.
+Route + Contract + Slot + Test 파이프라인으로 완전한 API를 스캐폴딩합니다.
+
+## Workflow: Route -> Contract -> Slot -> Test
+
+### Step 1: Route 생성
+
+```typescript
+// app/api/posts/route.ts
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get((ctx) => ctx.ok({ posts: [] }))
+  .post(async (ctx) => {
+    const body = await ctx.body<CreatePostInput>();
+    return ctx.created({ post: body });
+  });
+```
+
+### Step 2: Contract 정의
+
+```typescript
+// src/shared/contracts/post.contract.ts
+import { z } from "zod";
+
+export const CreatePostInput = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+  tags: z.array(z.string()).optional(),
+});
+
+export const PostResponse = z.object({
+  id: z.string(),
+  title: z.string(),
+  content: z.string(),
+  createdAt: z.string().datetime(),
+});
+
+export type CreatePostInput = z.infer<typeof CreatePostInput>;
+export type PostResponse = z.infer<typeof PostResponse>;
+```
+
+### Step 3: Slot (서버 데이터 로더)
+
+```typescript
+// spec/slots/posts.slot.ts
+import { Mandu } from "@mandujs/core";
+import { CreatePostInput } from "@/shared/contracts/post.contract";
+
+export default Mandu.filling()
+  .guard(async (ctx) => {
+    const token = ctx.headers.get("authorization");
+    if (!token) return ctx.error(401, "Unauthorized");
+    ctx.set("userId", await verifyToken(token));
+  })
+  .post(async (ctx) => {
+    const body = await ctx.body<CreatePostInput>();
+    const validated = CreatePostInput.parse(body);
+    const post = await db.posts.create({ ...validated, userId: ctx.get("userId") });
+    return ctx.created({ post });
+  });
+```
+
+### Step 4: Test 작성
+
+```typescript
+// tests/api/posts.test.ts
+import { describe, test, expect } from "bun:test";
+
+describe("POST /api/posts", () => {
+  test("creates a post with valid input", async () => {
+    const res = await fetch("http://localhost:3333/api/posts", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Bearer test-token",
+      },
+      body: JSON.stringify({ title: "Test", content: "Hello" }),
+    });
+    expect(res.status).toBe(201);
+    const data = await res.json();
+    expect(data.post.title).toBe("Test");
+  });
+
+  test("returns 401 without auth", async () => {
+    const res = await fetch("http://localhost:3333/api/posts", {
+      method: "POST",
+      body: JSON.stringify({ title: "Test", content: "Hello" }),
+    });
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+## CRUD Pattern
+
+```
+app/api/{resource}/route.ts          GET (list), POST (create)
+app/api/{resource}/[id]/route.ts     GET (read), PATCH (update), DELETE (remove)
+src/shared/contracts/{resource}.contract.ts
+spec/slots/{resource}.slot.ts
+tests/api/{resource}.test.ts
+```
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mandu_add_route` | Create route file at correct path |
+| `mandu_create_contract` | Generate Zod contract schema |
+| `mandu_negotiate` | Analyze API requirements |
+| `mandu_generate` | Full scaffold generation |
+
+## Auth Patterns
+
+```typescript
+// Bearer token guard
+.guard(async (ctx) => {
+  const token = ctx.headers.get("authorization")?.replace("Bearer ", "");
+  if (!token) return ctx.error(401, "Missing token");
+  ctx.set("user", await verifyToken(token));
+})
+
+// API key guard
+.guard((ctx) => {
+  const key = ctx.headers.get("x-api-key");
+  if (key !== process.env.API_KEY) return ctx.error(403, "Invalid API key");
+})
+```
+
+## Key Rules
+
+1. 모든 API route는 `Mandu.filling()` 체인으로 export
+2. 반드시 Contract를 먼저 정의하고 validation에 사용
+3. `.guard()`로 인증/인가 처리 (인라인 체크 금지)
+4. 에러는 `ctx.error(status, message)` 사용
+5. `ctx.body()`는 반드시 await

package/skills/mandu-create-feature/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: mandu-create-feature
+description: |
+  Mandu 피처 생성. 페이지/API/Island 스캐폴딩. '만들어줘', 'create', 'add page' 시 자동 호출
+---
+
+# Mandu Create Feature
+
+Mandu 프로젝트에 새 피처를 생성하는 5단계 워크플로우.
+MCP 도구 파이프라인을 통해 페이지, API, Island을 자동 스캐폴딩합니다.
+
+## 5-Phase Workflow
+
+### Phase 1: Negotiate (요구사항 분석)
+
+MCP 도구 `mandu_negotiate`를 호출하여 피처 요구사항을 분석합니다.
+
+```
+mandu_negotiate({ description: "사용자 프로필 페이지와 편집 기능" })
+```
+
+결과: 필요한 라우트, 컴포넌트, API 엔드포인트 목록이 반환됩니다.
+
+### Phase 2: Add Routes (라우트 생성)
+
+분석 결과를 바탕으로 `mandu_add_route`로 라우트를 생성합니다.
+
+```
+mandu_add_route({ path: "/users/[id]", type: "page" })
+mandu_add_route({ path: "/api/users/[id]", type: "api" })
+```
+
+파일 생성 규칙:
+- Page: `app/users/[id]/page.tsx`
+- API: `app/api/users/[id]/route.ts`
+- Layout: `app/users/layout.tsx`
+
+### Phase 3: Create Contracts (타입 계약)
+
+`mandu_create_contract`로 API 계약을 정의합니다.
+
+```
+mandu_create_contract({
+  name: "user",
+  methods: ["get", "patch"],
+  fields: { name: "string", email: "string", avatar: "string?" }
+})
+```
+
+생성 위치: `src/shared/contracts/user.contract.ts`
+
+### Phase 4: Generate Scaffold (코드 생성)
+
+`mandu_generate`로 전체 스캐폴드를 생성합니다.
+
+```
+mandu_generate({ spec: negotiateResult })
+```
+
+생성되는 파일:
+- `.mandu/generated/server/` - 서버 코드
+- `.mandu/generated/web/` - 클라이언트 코드
+- `spec/slots/*.slot.ts` - 서버 데이터 로더
+- `app/**/*.island.tsx` - Island 컴포넌트
+
+### Phase 5: Guard Heal (아키텍처 검증)
+
+`mandu_guard_heal`로 생성된 코드의 아키텍처 규칙 준수를 검증합니다.
+
+```
+mandu_guard_heal({ autofix: true })
+```
+
+위반 사항이 있으면 자동 수정을 시도합니다.
+
+## Quick Recipes
+
+### 새 페이지 추가
+```
+negotiate → add_route(page) → generate
+```
+
+### 새 API + 페이지
+```
+negotiate → add_route(page) → add_route(api) → create_contract → generate → guard_heal
+```
+
+### Island 추가
+```
+negotiate → add_route(page) → generate → island 파일에 "use client" 확인
+```
+
+## Key Rules
+
+1. 항상 `mandu_negotiate`부터 시작 (분석 없이 직접 생성하지 않기)
+2. API 엔드포인트에는 반드시 contract 생성
+3. 생성 후 `mandu_guard_heal`로 검증
+4. Layout에 `<html>/<head>/<body>` 태그 사용 금지
+5. Island 파일은 `@mandujs/core/client`에서 import

package/skills/mandu-debug/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: mandu-debug
+description: |
+  에러 진단+수정. 빌드실패/하얀화면/Island안됨/API에러/CSS깨짐 시 자동 호출
+---
+
+# Mandu Debug
+
+Mandu 프로젝트의 에러를 진단하고 수정하는 8카테고리 트리아지 시스템.
+증상 → 수집 → 진단 → 수정 → 검증 순서로 진행합니다.
+
+## Triage: 8 Error Categories
+
+| Category | Symptoms | First Check |
+|----------|----------|-------------|
+| **Build** | `bun run build` fails, TS errors | `bunx mandu guard arch --ci` |
+| **White Screen** | Page loads but blank | Browser console, SSR output |
+| **Island** | Component not interactive | `"use client"`, import path |
+| **API** | 4xx/5xx from endpoints | Route file, `Mandu.filling()` chain |
+| **CSS** | Styles missing/broken | `app/globals.css`, Tailwind config |
+| **Guard** | Architecture violations | `bunx mandu guard arch` |
+| **HMR** | Changes not reflecting | Dev server restart, port conflict |
+| **Hydration** | Mismatch warnings | Server vs client render diff |
+
+## Parallel Collection Phase
+
+문제 발생 시 동시에 수집할 정보:
+
+```bash
+# 1. Guard check (아키텍처 위반 여부)
+bunx mandu guard arch --ci
+
+# 2. TypeScript check
+bunx tsc --noEmit
+
+# 3. Dev server logs
+# 이미 실행 중이면 터미널 출력 확인
+
+# 4. Browser console
+# 개발자 도구에서 에러 메시지 확인
+```
+
+MCP 도구로 수집:
+```
+mandu_brain_diagnose({ symptoms: "white screen on /dashboard" })
+```
+
+## Fix Patterns by Category
+
+### Build Failure
+1. `bunx tsc --noEmit` - TypeScript 에러 위치 확인
+2. Import 경로 확인 (특히 `@mandujs/core` vs `@mandujs/core/client`)
+3. `bun install` - 의존성 누락 확인
+
+### White Screen
+1. `app/layout.tsx`에 `<html>/<head>/<body>` 태그가 있는지 확인 -> 있으면 제거
+2. `page.tsx`에서 default export 확인
+3. SSR 에러: 서버 로그에서 렌더링 에러 확인
+
+### Island Not Working
+1. `"use client"` 디렉티브 확인 (파일 최상단)
+2. Import: `@mandujs/core/client` (NOT `@mandujs/core`)
+3. `.island.tsx` 또는 `.client.tsx` 파일 확장자 확인
+4. `island()` API로 감싸져 있는지 확인
+
+### API Error
+1. `route.ts` (NOT `route.tsx`) 확인
+2. `Mandu.filling()` 체인으로 default export 확인
+3. `ctx.body()` await 누락 확인
+4. `.guard()` 반환값 확인 (void = 계속, Response = 차단)
+
+### CSS Missing
+1. `app/globals.css` 존재 확인
+2. Tailwind v4 import 확인: `@import "tailwindcss"`
+3. 프로덕션: `cssPath` 옵션이 서버에 전달되는지 확인
+
+### Guard Violation
+1. `bunx mandu guard arch` 실행
+2. Layer 위반: import 방향 확인 (상위 → 하위만 허용)
+3. `mandu.config.ts`의 preset 확인
+
+### HMR Not Working
+1. Dev server 재시작: `Ctrl+C` → `bun run dev`
+2. 포트 충돌: `lsof -i :3333` 또는 다른 포트 사용
+3. `.mandu/` 캐시 삭제: `rm -rf .mandu/generated`
+
+### Hydration Mismatch
+1. 서버/클라이언트 렌더링 차이 확인
+2. `Date.now()`, `Math.random()` 등 비결정적 값 제거
+3. `useHydrated()` 훅으로 클라이언트 전용 코드 분기
+
+## Verification
+
+수정 후 반드시 검증:
+
+```bash
+bunx mandu guard arch --ci  # 아키텍처 검증
+bunx tsc --noEmit            # 타입 검증
+bun run dev                  # 런타임 검증
+```
+
+## MCP Tools for Debugging
+
+| Tool | Purpose |
+|------|---------|
+| `mandu_brain_diagnose` | 증상 기반 자동 진단 |
+| `mandu_guard` | 아키텍처 규칙 검사 |
+| `mandu_guard_heal` | 위반 자동 수정 |
+| `mandu_runtime_check` | 런타임 상태 점검 |