clikit-plugin 0.2.45 → 0.2.46

package/skill/vercel-react-best-practices/SKILL.md

@@ -1,174 +1,85 @@
 ---
 name: vercel-react-best-practices
-description: Use when writing, reviewing, or refactoring React/Next.js code. Performance optimization patterns from Vercel Engineering.
+description: Use when writing, reviewing, or refactoring React/Next.js code. Enforces Server Components first, parallel fetching, and bundle optimization.
 ---
 
-# Vercel React Best Practices Skill
+# Vercel React Best Practices
 
-You are running the **vercel-react-best-practices** skill. Optimize React and Next.js applications.
+## Component Rules
 
-## Core Principles
+**Default to Server Components.** Use `'use client'` only when you need interactivity, browser APIs, or hooks.
 
-From Vercel Engineering team's production experience.
-
-## Component Patterns
-
-### 1. Composition Over Inheritance
+**Composition over prop explosion:**
 ```jsx
-// Good: Composition
-function Card({ header, children, footer }) {
-  return (
-    <div className="card">
-      {header}
-      <div className="content">{children}</div>
-      {footer}
-    </div>
-  );
-}
-
-// Avoid: Prop explosion
-function Card({ headerTitle, headerSubtitle, footerText, ... }) {}
-```
+// Good
+function Card({ header, children, footer }) { … }
 
-### 2. Colocate Components
-```
-/components/
-  Card/
-    index.tsx      # Export
-    Card.tsx       # Component
-    Card.test.tsx  # Test
-    styles.ts      # Styles
+// Bad
+function Card({ headerTitle, headerSubtitle, footerText, … }) { … }
 ```
 
-### 3. Server Components First
-```jsx
-// Default to Server Component
-async function UserProfile({ id }) {
-  const user = await fetchUser(id); // Direct DB access
-  return <div>{user.name}</div>;
-}
-
-// Use 'use client' only when needed
-'use client';
-function InteractiveButton() {
-  const [count, setCount] = useState(0);
-  // ...
-}
+**Colocate files:**
 ```
-
-## Performance Patterns
-
-### 1. Dynamic Imports
-```jsx
-// Lazy load heavy components
-const HeavyChart = dynamic(() => import('./Chart'), {
-  loading: () => <Skeleton />,
-  ssr: false
-});
+Card/
+  index.tsx       Card.tsx       Card.test.tsx       styles.ts
 ```
 
-### 2. Image Optimization
-```jsx
-import Image from 'next/image';
-
-// Automatic optimization
-<Image
-  src="/hero.jpg"
-  alt="Hero"
-  width={1200}
-  height={600}
-  priority // Above fold
-/>
-```
+## Performance
 
-### 3. Font Optimization
 ```jsx
-import { Inter } from 'next/font/google';
+// Dynamic import for heavy components
+const HeavyChart = dynamic(() => import('./Chart'), { loading: () => <Skeleton />, ssr: false });
+
+// next/image — always, no raw <img>
+<Image src="/hero.jpg" width={1200} height={600} priority />
 
-const inter = Inter({ 
-  subsets: ['latin'],
-  display: 'swap'
-});
+// next/font — always
+const inter = Inter({ subsets: ['latin'], display: 'swap' });
 ```
 
 ## Data Fetching
 
-### 1. Parallel Requests
 ```jsx
-// Good: Parallel
-async function Page() {
-  const [user, posts] = await Promise.all([
-    fetchUser(),
-    fetchPosts()
-  ]);
-  // ...
-}
-
-// Avoid: Waterfall
-async function Page() {
-  const user = await fetchUser();
-  const posts = await fetchPosts(); // Waits for user
-}
-```
-
-### 2. Cache Strategies
-```jsx
-// Revalidate periodically
-fetch(url, { next: { revalidate: 60 } });
+// Parallel — always
+const [user, posts] = await Promise.all([fetchUser(), fetchPosts()]);
 
-// Skip cache
-fetch(url, { cache: 'no-store' });
-
-// Force cache
-fetch(url, { cache: 'force-cache' });
+// Cache strategies
+fetch(url, { next: { revalidate: 60 } });   // ISR
+fetch(url, { cache: 'no-store' });           // SSR
+fetch(url, { cache: 'force-cache' });        // static
 ```
 
-## Rendering Strategies
+## Rendering Strategy
 
-| Strategy | Use When |
+| Use When | Strategy |
 |----------|----------|
-| Static (SSG) | Content doesn't change often |
-| Dynamic (SSR) | Per-request data needed |
-| ISR | Periodic updates needed |
-| Edge | Low latency globally |
+| Content rarely changes | SSG (static) |
+| Per-request data | SSR (dynamic) |
+| Periodic updates | ISR |
+| Global low-latency | Edge |
 
-## State Management
+## State
 
-### 1. Start Local
-```jsx
-// Keep state as local as possible
-function FilterableList({ items }) {
-  const [filter, setFilter] = useState('');
-  // Not in global store
-}
-```
+- Keep state as **local as possible** — no global store until proven necessary
+- Use URL state (`useSearchParams`) for shareable/filterable state
 
-### 2. URL State
-```jsx
-// For shareable state
-import { useSearchParams } from 'next/navigation';
-
-function Search() {
-  const searchParams = useSearchParams();
-  const query = searchParams.get('q');
-}
-```
+## Anti-Patterns
 
-## Common Anti-Patterns
+| Pattern | Fix |
+|---------|-----|
+| `'use client'` on static content | Remove — use Server Component |
+| `import { everything } from 'lib'` | Use tree-shaking or dynamic import |
+| Raw `<img>` | `next/image` |
+| Sequential `await` for independent data | `Promise.all` |
+| Prop drilling 3+ levels | Composition or context |
 
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Client components for static content | Use Server Components |
-| Large bundle imports | Use tree-shaking or dynamic imports |
-| Unoptimized images | Use next/image |
-| Blocking requests | Use Promise.all |
-| Prop drilling | Use composition or context |
+## Pre-ship Checklist
 
-## Checklist
-
-- [ ] Default to Server Components
-- [ ] Images use next/image
-- [ ] Fonts are optimized
+- [ ] Server Components by default
+- [ ] `next/image` for all images
+- [ ] `next/font` for all fonts
 - [ ] Parallel data fetching
 - [ ] Dynamic imports for heavy code
-- [ ] Proper caching strategy
+- [ ] Correct caching strategy per route
+
+See [references/patterns.md](references/patterns.md) for extended examples.

package/skill/vercel-react-best-practices/references/patterns.md

@@ -0,0 +1,70 @@
+# Vercel React — Extended Patterns
+
+## Server vs Client Decision Tree
+
+```
+Does it need: onClick/onChange, useState/useEffect, browser-only APIs?
+  YES → 'use client'
+  NO  → Server Component (default)
+```
+
+## Streaming with Suspense
+
+```jsx
+export default function Page() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <SlowComponent />
+    </Suspense>
+  );
+}
+```
+
+## Error Boundaries
+
+```jsx
+// app/error.tsx
+'use client';
+export default function Error({ error, reset }) {
+  return (
+    <div>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Route Handlers (API Routes)
+
+```ts
+// app/api/users/route.ts
+export async function GET(request: Request) {
+  const users = await db.user.findMany();
+  return Response.json(users);
+}
+```
+
+## Metadata
+
+```tsx
+// Static
+export const metadata: Metadata = { title: 'Page' };
+
+// Dynamic
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const product = await fetchProduct(params.id);
+  return { title: product.name };
+}
+```
+
+## Server Actions
+
+```tsx
+async function createUser(formData: FormData) {
+  'use server';
+  const name = formData.get('name');
+  await db.user.create({ data: { name } });
+  revalidatePath('/users');
+}
+```

package/skill/verification-before-completion/SKILL.md

@@ -1,55 +1,37 @@
 ---
 name: verification-before-completion
-description: Use when marking any task complete. Enforces fresh verification evidence.
+description: Use before marking any task complete. Run verification commands first, show output, then claim the result.
 ---
 
-# Verification Before Completion Skill
-
-You are running the **verification-before-completion** skill. No claims without evidence.
+# Verification Before Completion
 
 ## Process
 
-1. **Run** the verification command
-2. **Read** the FULL output
-3. **Check** the exit code
-4. **THEN** claim the result
+```
+Run command → read full output → check exit code → THEN claim result
+```
 
-## Verification Commands
+## Commands by Task Type
 
-| Task Type | Command |
-|-----------|---------|
+| Type | Command |
+|------|---------|
 | TypeScript | `npm run typecheck` |
 | Tests | `npm test` |
 | Lint | `npm run lint` |
 | Build | `npm run build` |
-| All | `npm run typecheck && npm test && npm run lint && npm run build` |
-
-## Red Flags
-
-These phrases indicate lack of verification:
+| All gates | `npm run typecheck && npm test && npm run lint && npm run build` |
 
-| Phrase | Problem |
-|--------|---------|
-| "should work" | Not verified |
-| "probably fixed" | Not tested |
-| "looks good" | Not run |
-| "in theory" | No evidence |
-| Expressing satisfaction before running | Premature |
+## Evidence Block (required output)
 
-## Evidence Format
-
-```markdown
-## Verification
-
-- [x] Type check: Passed
-- [x] Tests: 42 passed, 0 failed
-- [x] Lint: 0 errors
-- [x] Build: Successful
-
-Output:
-[paste relevant output]
 ```
+- [x] typecheck: 0 errors
+- [x] tests: N passed, 0 failed
+- [x] lint: 0 errors
+- [x] build: exit 0
+```
+
+## Phrases That Signal No Verification
 
-## Rule
+`"should work"` · `"probably fixed"` · `"looks good"` · `"in theory"` — **all invalid**.
 
-**Honesty is non-negotiable.** If something isn't verified, say so. Never claim completion without fresh evidence.
+If not run, say so. Never claim completion without fresh evidence.

package/skill/writing-plans/SKILL.md

@@ -1,55 +1,43 @@
 ---
 name: writing-plans
-description: Use when requirements are clear and you need to create an implementation plan with bite-sized tasks.
+description: Use when requirements are clear and you need to create an implementation plan with bite-sized tasks a junior engineer can execute with zero context.
 ---
 
-# Writing Plans Skill
-
-You are running the **writing-plans** skill. Create implementation plans that a junior engineer could follow with zero context.
+# Writing Plans
 
 ## Task Requirements
 
-Each task must be:
-- **2-5 minutes** to complete
-- Has **exact file paths**
-- Has **complete code** (no "...", no "implement this")
-- Has **verification steps**
+Every task must have:
+- **Exact file path** — no vague references
+- **Complete code** — no `...` or "implement this"
+- **Verification command + expected output**
+- Completable in **2–5 minutes**
 
 ## Task Format
 
 ```markdown
-### Task: [Action verb] [what]
-
-**File**: `path/to/file.ts`
+### Task: [Verb] [what]
 
-**Action**: [create|edit|delete]
+**File**: `src/foo/bar.ts`
+**Action**: create | edit | delete
 
 **Code**:
-[Complete, copy-pasteable code]
+[complete, copy-pasteable code]
 
 **Verification**:
-- [ ] Command: `npm test`
-- [ ] Expected: All tests pass
+- [ ] `npm test src/foo/bar.test.ts` → passes
 ```
 
-## Principles
-
-| Principle | Meaning |
-|-----------|---------|
-| YAGNI | Don't add "nice to have" features |
-| DRY | Extract shared logic immediately |
-| TDD | Write test before implementation |
-
 ## Plan Structure
 
-1. **Prerequisites** — Setup, dependencies, baseline tests
-2. **Core** — Main functionality, smallest working version
-3. **Edge Cases** — Error handling, validation
-4. **Polish** — Performance, documentation
+1. **Prerequisites** — deps, baseline tests
+2. **Core** — smallest working version
+3. **Edge Cases** — error handling, validation
+4. **Polish** — performance, docs
 
 ## Red Flags
 
-- Tasks longer than 5 minutes → Break down further
-- Vague file paths → Be specific
-- Missing verification → Add test commands
-- "Implement similar to" → Provide full code
+- Task > 5 min → break it down
+- Vague file path → make it exact
+- Missing verification → add test command
+- "Implement similar to X" → write the full code

package/skill/writing-skills/SKILL.md

@@ -1,68 +1,79 @@
 ---
 name: writing-skills
-description: Use when creating new skills. Follow TDD approach for skill development.
+description: Use when creating a new skill. Produces a well-structured skill package with SKILL.md, optional references/, and optional mcp.json following the Agent Skills standard.
 ---
 
-# Writing Skills Skill
+# Writing Skills
 
-You are running the **writing-skills** skill. Test-driven skill creation.
+## Skill Anatomy
 
-## Skill File Structure
+```
+skill-name/
+├── SKILL.md              ← required: frontmatter + workflow
+├── mcp.json              ← if skill calls MCP tools
+└── references/
+    └── *.md              ← knowledge details, loaded on-demand
+```
+
+## SKILL.md Format
 
 ```markdown
 ---
-name: skill-name
-description: Use when [specific trigger condition]. Brief purpose.
+name: skill-name          # lowercase, hyphens only, matches directory name
+description: …            # max 200 chars — trigger condition + what it does
 ---
 
 # Skill Title
 
-[Content]
-```
+## Workflow / Process
+[core steps — what the agent should do]
 
-## TDD for Skills: RED-GREEN-REFACTOR
+## Rules / Checklist
+[hard rules, decision tables]
 
-### RED: Baseline Test
+## Red Flags
+[what to watch for]
+
+## References       ← only if references/ exist
+- [name](references/file.md) — one-line description
+- MCP: server-name — see [mcp.json](mcp.json)
+```
 
-Before writing the skill:
-1. Identify the problem the skill solves
-2. Document expected behavior
-3. Note edge cases and failure modes
-4. This is your "test" — does the skill handle these?
+## Decision: What Belongs Where
 
-### GREEN: Write the Skill
+| Content | Where |
+|---------|-------|
+| Trigger condition, workflow, rules | `SKILL.md` body |
+| Tool signatures, long examples, lookup tables | `references/*.md` |
+| MCP server connection + tool list | `mcp.json` |
+| Nothing extra needed | `SKILL.md` only |
 
-Write the minimum skill content that:
-- Solves the identified problem
-- Handles documented edge cases
-- Provides clear guidance
+## When to Add references/
 
-### REFACTOR: Close Loopholes
+Split into a reference file when:
+- Section exceeds ~20 lines and is reference-only (not workflow)
+- Content is only needed for specific sub-tasks, not always
+- Examples/tables that would bloat the main SKILL.md
 
-Review and improve:
-- Are there ambiguous instructions?
-- Could the skill be misinterpreted?
-- Does it handle the failure modes?
-- Is it concise and actionable?
+Each reference file must be linked from SKILL.md so the agent knows it exists.
 
-## Description Rules
+## When to Add mcp.json
 
-- Start with "Use when..." for trigger clarity
-- One clear purpose per skill
-- Avoid vague descriptions like "Helps with code"
+Add `mcp.json` when the skill calls MCP tools directly.  
+List only the tools the skill actually uses — not all tools the server exposes.
 
 ## Quality Checklist
 
-- [ ] Name is clear and action-oriented
-- [ ] Description starts with "Use when..."
-- [ ] Covers when to invoke the skill
-- [ ] Provides actionable steps
-- [ ] Handles edge cases
-- [ ] Lists red flags or anti-patterns
+- [ ] `name` matches directory name, lowercase-hyphen only
+- [ ] `description` states *when to invoke* + *what it does* (≤ 200 chars)
+- [ ] SKILL.md body has a clear workflow or process section
+- [ ] No "You are running the X skill." boilerplate
+- [ ] Long reference content split into `references/*.md`
+- [ ] Each reference file linked from SKILL.md
+- [ ] `mcp.json` present if and only if skill calls MCP tools
+- [ ] `mcp.json` lists only tools this skill actually uses
+- [ ] Red Flags section present
 
-## Red Flags
+## References
 
-- Skills that are too broad (multiple purposes)
-- Missing trigger conditions
-- No actionable guidance
-- Emotional language instead of technical
+- [Skill anatomy reference](references/skill-anatomy.md) — full format spec for all three files