Skill: wpank/extraction (version 1.0.0)

--- name: pattern-extraction model: reasoning description: Extract design systems, architecture patterns, and methodology from codebases into reusable skills and documentation. Use when analyzing a project to capture patterns, creating skills from existing code, extracting design tokens, or documenting how a project was built. Triggers on "extract patterns", "extract from this repo", "analyze this codebase", "create skills from this project", "extract design system". --- # Pattern Extraction Extract reusable patterns, skills, and methodology documentation from existing codebases. ## Installation ### OpenClaw / Moltbot / Clawbot ```bash npx clawhub@latest install extraction ``` --- ## Before Starting **MANDATORY**: Read these reference files based on what you're extracting: | Extracting | Read First | |------------|------------| | Any extraction | [`methodology-values.md`](references/methodology-values.md) — priority order and what to look for | | Specific categories | [`extraction-categories.md`](references/extraction-categories.md) — detailed patterns per category | | Generating skills | [`skill-quality-criteria.md`](references/skill-quality-criteria.md) — quality checklist | --- ## Extraction Process ### Phase 1: Discovery Analyze the project to understand what exists. **Scan for project structure:** ``` - Root directory layout - Key config files (package.json, tailwind.config.*, etc.) - Documentation (README, docs/, etc.) - Source organization (src/, app/, components/, etc.) ``` **Identify tech stack:** | Indicator | Technology | |-----------|------------| | `package.json` with react | React | | `tailwind.config.*` | Tailwind CSS | | `components.json` | shadcn/ui | | `go.mod` | Go | | `Dockerfile` | Docker | | `k8s/` or `.yaml` manifests | Kubernetes | | `turbo.json` | Turborepo | | `Makefile` | Make automation | **Look for design system signals:** - Custom Tailwind config (not defaults) - CSS variables / custom properties - Theme files - Design documentation - Mood boards or reference lists **Capture key findings:** - What's the tech stack? - What's the folder structure? - Is there a documented design direction? - What workflows exist (Makefile, scripts)? --- ### Phase 2: Categorization Map discoveries to extraction categories, prioritized: **Priority order:** 1. **Design Systems** — Color tokens, typography, spacing, motion, aesthetic documentation 2. **UI Patterns** — Component organization, layouts, interactions 3. **Architecture** — Folder structure, data flow, API patterns 4. **Workflows** — Build, dev, deploy, CI/CD 5. **Domain-Specific** — Patterns unique to this application type **For each category found, note:** - What specific patterns exist? - Where are they defined? (file paths) - Are they documented? (comments, docs) - Are they worth extracting? (used in multiple places, well-designed) **Filter by value:** | Extract | Skip | |---------|------| | Patterns used across multiple components | One-off solutions | | Customized configs with intention | Default configurations | | Documented design decisions | Arbitrary choices | | Reusable infrastructure | Project-specific hacks | --- ### Phase 3: Extraction For each valuable pattern, generate outputs. **Design Systems → Design System Doc + Skill** 1. Read the Tailwind config, CSS files, theme files 2. Extract actual token values (colors, typography, spacing) 3. Document the aesthetic direction 4. Create: - `docs/extracted/[project]-design-system.md` using [`design-system.md`](references/output-templates/design-system.md) template - `ai/skills/[project]-design-system/SKILL.md` if patterns are reusable **Architecture → Methodology Doc** 1. Document folder structure with reasoning 2. Capture data flow patterns 3. Note key technical decisions 4. Create `docs/extracted/[project]-summary.md` using [`project-summary.md`](references/output-templates/project-summary.md) template **Patterns → Skills** For each pattern worth a skill: 1. Load [`skill-quality-criteria.md`](references/skill-quality-criteria.md) 2. Use [`skill-template.md`](references/output-templates/skill-template.md) template 3. Verify the quality checklist: - Description has WHAT, WHEN, KEYWORDS - No explanations of basics Claude knows - Has specific NEVER list - < 300 lines ideal 4. Create `ai/skills/[project]-[pattern]/SKILL.md` --- ### Phase 4: Validation Before writing output, validate extracted content. **For each skill, verify:** - [ ] Description has WHAT, WHEN, and trigger KEYWORDS - [ ] >70% expert knowledge (not in base Claude model) - [ ] <300 lines (max 500) - [ ] Has "When to Use" section with clear triggers - [ ] Has code examples (if applicable) - [ ] Has NEVER Do section with anti-patterns - [ ] Project-agnostic (no hardcoded project names) **For documentation, verify:** - [ ] Actual values extracted (not placeholders) - [ ] Templates fully filled out - [ ] Aesthetic direction documented (for design systems) - [ ] File paths are correct **Conflict detection:** Before creating a new skill, check if similar skills exist: ```bash # Check existing skills in the target repo ls ai/skills/*/ ``` | Situation | Action | |-----------|--------| | Similar skill exists | Enhance existing skill instead | | Overlapping patterns | Note overlap, may merge in refinement | | Unique pattern | Proceed with new skill | --- ### Phase 5: Output Write extracted content to target locations. **Methodology Documentation:** ``` docs/extracted/ ├── [project]-summary.md # Overall methodology ├── [project]-design-system.md # Design tokens and aesthetic └── [project]-architecture.md # Code patterns (if complex) ``` **Skills:** ``` ai/skills/ └── [project]-[category]/ ├── SKILL.md └── references/ # (if needed for detailed content) ``` **Create docs/extracted/ directory if it doesn't exist.** --- ## Extraction Focus Areas ### Design System Extraction (Highest Priority) When a project has intentional design work, extract thoroughly: **Must capture:** - Color palette (primary, secondary, accent, semantic) - Typography (fonts, scale, weights) - Spacing scale - Motion/animation patterns - The "vibe" or aesthetic direction **Look in:** - `tailwind.config.js` / `tailwind.config.ts` - `globals.css` / `app.css` / root CSS files - `theme.ts` / `theme.js` - Any design documentation **Generate:** 1. Design system documentation with actual values 2. Skill capturing the aesthetic philosophy (if distinctive) ### Workflow Extraction **Look for:** - Makefile targets - package.json scripts - Docker configurations - CI/CD workflows **Extract:** - Dev setup commands - Build processes - Deployment patterns --- ## Error Handling | Situation | Resolution | |-----------|------------| | No patterns found | Create project summary only; document why extraction failed | | Pattern too project-specific | Skip or generalize by removing project names | | Incomplete pattern | Extract what exists, note gaps in skill | | Quality criteria not met | Revise skill or skip pattern | | Similar skill already exists | Update existing skill instead of creating new | | Can't find source files | Note in extraction log, skip that category | **When extraction fails partially:** 1. Complete what can be extracted 2. Document gaps in the project summary 3. Note "Incomplete extraction" in output 4. Suggest what additional information would be needed --- ## NEVER Do - **NEVER extract default configurations** — Only extract customized, intentional patterns - **NEVER create skills for basic concepts** — Claude already knows React, Tailwind basics - **NEVER skip the aesthetic** — Design philosophy is highest priority - **NEVER generate skills > 500 lines** — Use references/ for detailed content - **NEVER create skills without good descriptions** — Description determines if skill activates - **NEVER extract one-off solutions** — Focus on patterns used in multiple places - **NEVER skip validation phase** — Quality check before writing output - **NEVER leave project names in skills** — Make patterns project-agnostic - **NEVER create duplicate skills** — Check for existing similar skills first --- ## Quality Check Before Finishing - [ ] Design system captured (if one exists)? - [ ] Methodology summary created? - [ ] Skills have proper descriptions (WHAT, WHEN, KEYWORDS)? - [ ] Skills pass the expert knowledge test? - [ ] Anti-patterns documented in skills? - [ ] Output files created in correct locations? --- ## After Extraction: Staging for Refinement If you're extracting to later consolidate patterns across multiple projects: **Copy results to the skills toolkit repo for staging:** ```bash # From this project, copy to the skills repo staging area cp -r ai/skills/[project]-* /path/to/skills-repo/ai/staging/skills/ cp -r docs/extracted/* /path/to/skills-repo/ai/staging/docs/ ``` **Staging folder structure:** ``` ai/staging/ ├── skills/ # Extracted skills from multiple projects │ ├── project-a-design-system/ │ ├── project-b-ui-patterns/ │ └── ... └── docs/ # Extracted methodology docs ├── project-a-summary.md ├── project-b-design-system.md └── ... ``` **After staging content from multiple projects:** - Say "refine staged content" or "consolidate staged skills" - The refinement process will: - Identify patterns across projects - Consolidate into project-agnostic skills - Update methodology docs with insights - Promote refined skills to active locations --- ## Related Skills - **Agent:** [`ai/agents/extraction/`](../../agents/extraction/) — Autonomous extraction workflow - **Command:** [`/extract-patterns`](../commands/extraction/extract-patterns.md) — Quick extraction command - **Next step:** [`ai/skills/refinement/`](../refinement/) — Consolidate extracted patterns - **Quality criteria:** [`references/skill-quality-criteria.md`](references/skill-quality-criteria.md)

path: README.md
content: # Extraction

Skills for mining reusable patterns, design systems, and methodology documentation from existing codebases.

## Skills

| Skill | Description |
|-------|-------------|
| [pattern-extraction](./) | Extract design systems, architecture patterns, and methodology from codebases into reusable skills and documentation. |

## Installation

```bash
# Add individual skills
npx add https://github.com/wpank/ai/tree/main/skills/extraction/pattern-extraction
```
### OpenClaw / Moltbot / Clawbot

```bash
npx clawhub@latest install extraction
```

## See Also

- [All Skills](../) — Complete skills catalog
- [Agents](../../agents/) — Workflow agents


path: COMMAND.md
content: # /extract-patterns

Extract patterns, design systems, and methodology from the current codebase.

## Usage

```
/extract-patterns [focus]
```

**Focus options:**
- `all` (default) — Full extraction across all categories
- `design` — Design system and visual patterns only
- `architecture` — Code organization and patterns only
- `workflow` — Build, dev, deploy patterns only

## Examples

```
/extract-patterns
/extract-patterns design
/extract-patterns architecture
```

## What It Does

1. **Discovers** what exists in the codebase (tech stack, structure, design)
2. **Categorizes** findings by type (design > architecture > workflow)
3. **Extracts** valuable patterns into skills and documentation
4. **Outputs** to `ai/skills/` and `docs/extracted/`

## Quick Start

Just run `/extract-patterns` and the extraction process will:

1. Scan the project structure
2. Identify the tech stack
3. Look for design system signals (Tailwind config, CSS variables, themes)
4. Find architecture patterns (folder structure, components, data flow)
5. Capture workflow patterns (Makefile, scripts, CI/CD)
6. Generate methodology documentation
7. Create skills for reusable patterns

## Output Locations

```
docs/extracted/
├── [project]-summary.md       # Methodology overview
├── [project]-design-system.md # Design tokens and aesthetic
└── [project]-architecture.md  # Architecture patterns

ai/skills/
└── [project]-[pattern]/
    └── SKILL.md               # Extracted skill
```

## Priority Order

Extraction prioritizes in this order:

1. **Design Systems** — Highest priority (colors, typography, motion, aesthetic)
2. **UI Patterns** — Components, layouts, interactions
3. **Architecture** — Folder structure, data flow, APIs
4. **Workflows** — Build, dev, deploy, CI/CD
5. **Domain-Specific** — Application-specific patterns

## After Extraction

To consolidate patterns from multiple projects:

```bash
# Copy extracted content to the skills repo staging area
cp -r ai/skills/[project]-* /path/to/skills-repo/ai/staging/skills/
cp -r docs/extracted/* /path/to/skills-repo/ai/staging/docs/
```

Then in the skills repo, say "refine staged content" to consolidate.

## Related

- Full skill: [`SKILL.md`](SKILL.md)
- Values reference: [`references/methodology-values.md`](references/methodology-values.md)
- Categories: [`references/extraction-categories.md`](references/extraction-categories.md)
- Staging: [`../../staging/README.md`](../../staging/README.md)
- Refinement: [`../refinement/SKILL.md`](../refinement/SKILL.md)


path: references/validation-checklist.md
content: # Extraction Validation Checklist

Pre-output validation steps to ensure extraction quality.

---

## Skill Validation

### Required Sections

- [ ] **Frontmatter** with `name` and `description`
- [ ] **When to Use** section with clear triggers
- [ ] **Code examples** (if applicable)
- [ ] **NEVER Do** section with anti-patterns
- [ ] **Related Skills** section (if applicable)

### Description Quality

The description must contain:

| Component | Example | Check |
|-----------|---------|-------|
| WHAT | "Extract design tokens from Tailwind configs" | What does this skill do? |
| WHEN | "Use when analyzing existing design systems" | When should it activate? |
| KEYWORDS | "extract, design tokens, Tailwind, CSS variables" | Trigger words |

**Test:** Read the description aloud. Would you know when to use this skill?

### Expert Knowledge Test

Ask: "Does Claude already know this?"

| Type | Keep | Delete |
|------|------|--------|
| Expert intuition | ✓ | |
| Decision trees | ✓ | |
| Anti-patterns from experience | ✓ | |
| Basic concepts | | ✓ |
| Tutorial content | | ✓ |
| API documentation | | ✓ |

**Rule:** >70% of content should be expert knowledge not in base model.

### Size Check

| Status | Lines | Action |
|--------|-------|--------|
| Ideal | <300 | Proceed |
| Acceptable | 300-500 | Consider splitting |
| Too large | >500 | Must split into references/ |

### Project-Agnostic Check

Search for:
- [ ] Hardcoded project names (remove)
- [ ] Specific file paths (generalize)
- [ ] Unique configurations (abstract to patterns)
- [ ] Team-specific conventions (generalize)

---

## Documentation Validation

### Design System Docs

- [ ] **Color palette** — Actual hex/HSL values extracted
- [ ] **Typography** — Font families and scale captured
- [ ] **Spacing** — Scale documented
- [ ] **Motion** — Animation timings captured
- [ ] **Aesthetic direction** — "The vibe" documented in words

### Project Summary Docs

- [ ] **Tech stack** — Complete and accurate
- [ ] **Folder structure** — Documented with reasoning
- [ ] **Key decisions** — Notable patterns explained
- [ ] **What worked** — Lessons learned
- [ ] **What to improve** — Honest assessment

### Template Completeness

| Issue | Fix |
|-------|-----|
| `[placeholder]` text | Replace with actual values |
| `TODO` comments | Complete or remove |
| Empty sections | Fill or delete section |
| Sample data | Replace with real extracted data |

---

## Common Validation Errors

### Skills

| Error | Fix |
|-------|-----|
| Description too vague | Add specific WHEN and KEYWORDS |
| No When to Use section | Add section with 3-5 triggers |
| No code examples | Add at least one example |
| No NEVER Do section | Add 3-5 anti-patterns |
| Too long (>500 lines) | Move details to references/ |
| Project-specific content | Generalize or remove |

### Documentation

| Error | Fix |
|-------|-----|
| Placeholder text remains | Replace with actual values |
| Missing aesthetic description | Add "The Vibe" section |
| Incomplete token extraction | Re-scan source files |
| No file paths | Add source file references |

---

## Validation Commands

```bash
# Count lines in skill
wc -l SKILL.md

# Search for placeholders
grep -E '\[.*\]|TODO|FIXME' SKILL.md

# Search for project names
grep -i '[project-name]' SKILL.md
```

---

## Pre-Output Checklist

Before writing any output:

### For Skills
- [ ] Description has WHAT, WHEN, KEYWORDS
- [ ] When to Use section exists with triggers
- [ ] Code examples included
- [ ] NEVER Do section with 3+ anti-patterns
- [ ] <300 lines (or justified if larger)
- [ ] No project-specific content
- [ ] No placeholders remaining

### For Docs
- [ ] Template fully filled out
- [ ] Actual values (not examples)
- [ ] Aesthetic documented (for design systems)
- [ ] File paths correct and accessible

---

## Related

- **Quality criteria:** [`skill-quality-criteria.md`](skill-quality-criteria.md)
- **Templates:** [`output-templates/`](output-templates/)
- **Extraction skill:** [`../SKILL.md`](../SKILL.md)


path: references/methodology-values.md
content: # Methodology Values

What to look for and prioritize when extracting patterns. These values inform what's worth extracting and what makes a pattern valuable.

---

## Priority Order

When extracting from a project, prioritize in this order:

1. **Design Systems & Visual Patterns** — Highest priority
2. **Architecture & Code Patterns**
3. **Workflow & DX Patterns**
4. **Documentation Patterns**
5. **Infrastructure Patterns**

---

## Design & Visual (Highest Priority)

Look for evidence of intentional aesthetic choices:

**Aesthetic Foundation**
- Mood boards, reference lists, inspiration docs
- Documented "vibe" or design direction
- Color palettes with semantic naming
- Typography scales and font choices

**Design Tokens**
- Tailwind config customizations (not defaults)
- CSS custom properties / variables
- Theme files, color schemes
- Spacing scales, border radii, shadows

**Emotional Design Signals**
- Micro-interactions, hover states, transitions
- Loading states that feel satisfying
- Progress indicators, achievements, rewards
- Animations that enhance (not distract)

**Preferred Aesthetics to Identify**
- Retro-futuristic (CRT glows, analog-digital fusion)
- Video game UI (HUDs, score displays, achievements)
- Futuristic interfaces (sci-fi terminals, holographic)
- Anything with a distinct *feel* (not generic bootstrap)

**Anti-Patterns to Note**
- Generic template aesthetics
- Default Tailwind without customization
- "Clean" with no personality
- Missing design documentation

---

## Minimal Code Principles

Look for evidence of intentional minimalism:

**DRY Patterns**
- Shared components, utilities, helpers
- Extracted common logic
- No copy-paste duplication

**Small, Focused Files**
- Files < 200 lines (ideally < 100)
- Functions < 20 lines
- Single responsibility components

**Reusable Primitives**
- Component libraries
- Utility functions
- Shared hooks/composables

**Questions to Ask**
- Could this code be deleted without loss?
- Is there duplication that should be extracted?
- Are files doing too much?

---

## Compound Work Patterns

Look for work that compounds:

**Extracted Patterns**
- Design systems used across views
- Component libraries
- Shared configuration
- Utility packages

**Encoded Decisions**
- ADRs or decision docs
- Comments explaining "why" not "what"
- Documented trade-offs

**Reusable Infrastructure**
- Dockerfile patterns
- CI/CD configurations
- Makefile targets
- Docker Compose setups

---

## DX Patterns

Look for developer experience investments:

**Fast Feedback**
- Hot reload configuration
- Watch mode scripts
- Fast build times

**One-Command Operations**
- `make dev` or equivalent
- `make clean`, `make reset`
- `make seed` for test data

**Environment Parity**
- Local, Docker, production modes
- Easy switching between environments
- Consistent configuration

---

## UX Patterns

Look for intentional user experience:

**Minimal UI**
- Only necessary elements
- No redundant information
- Clean, focused interfaces

**Fast & Responsive**
- Optimistic updates
- Skeleton screens
- Lazy loading

**Real-Time**
- WebSocket implementations
- Live updates
- Streaming responses

---

## Documentation Patterns

Look for docs-first evidence:

**Project Documentation**
- PRDs, specs, feature docs
- Persona definitions
- Architecture diagrams

**Runbooks**
- Operational guides
- Deployment procedures
- Troubleshooting docs

**Current vs Future Separation**
- Clear distinction between what exists and what's planned
- No aspirational docs mixed with reality

---

## What's Worth Extracting

| High Value | Lower Value |
|------------|-------------|
| Patterns used across multiple views/components | One-off solutions |
| Decisions with clear rationale | Arbitrary choices |
| Workflows you'd use again | Project-specific hacks |
| Design systems with documentation | Default configurations |
| Reusable infrastructure | Overcomplicated setups |

---

## Extraction Mindset

For each pattern found, ask:

1. **Why was this built this way?** — Capture the reasoning
2. **What would you keep?** — Identify the core value
3. **What would you change?** — Note improvements
4. **What's generalizable?** — Strip project-specific details
5. **Would an expert say "this captures real knowledge"?** — The quality test


path: references/extraction-categories.md
content: # Extraction Categories

What kinds of things to extract from a codebase, organized by category with specific patterns to look for.

---

## Category 1: Design Systems (Highest Priority)

Visual and aesthetic patterns that define how the application looks and feels.

### What to Extract

| Pattern | Where to Look | Output |
|---------|---------------|--------|
| Color tokens | `tailwind.config.*`, CSS variables, theme files | design-system skill |
| Typography | Font configs, text scale, font imports | design-system skill |
| Spacing | Spacing scale, layout rhythm | design-system skill |
| Motion | Animation configs, transitions, easing | motion-patterns skill |
| Component styles | Styled components, Tailwind classes | ui-patterns skill |

### Files to Scan

```
tailwind.config.js / tailwind.config.ts
postcss.config.js
app.css / globals.css / index.css
styles/ directory
theme.ts / theme.js
components.json (shadcn)
```

### Questions to Answer

- What's the color palette? Primary, secondary, accent, semantic?
- What fonts are used? What's the type scale?
- What's the spacing rhythm? 4px, 8px base?
- How are animations handled? Timing, easing?
- Is there a documented aesthetic (retro-futuristic, minimal, etc.)?

---

## Category 2: UI Patterns

Component patterns, layouts, and interaction designs.

### What to Extract

| Pattern | Where to Look | Output |
|---------|---------------|--------|
| Component organization | `components/` structure | component-patterns skill |
| Layout patterns | Page layouts, grid systems | layout-patterns skill |
| Form handling | Form components, validation | form-patterns skill |
| Loading states | Skeletons, spinners, optimistic UI | loading-patterns skill |
| Navigation | Routing patterns, menus | navigation-patterns skill |

### Files to Scan

```
components/ directory
layouts/ directory
pages/ or app/ directory (for Next.js/Nuxt)
hooks/ (for custom React hooks)
composables/ (for Vue)
```

### Questions to Answer

- How are components organized? Atomic design? Feature-based?
- What reusable layout patterns exist?
- How are forms validated and submitted?
- What loading states are implemented?
- How is navigation structured?

---

## Category 3: Architecture Patterns

Code organization, separation of concerns, data flow.

### What to Extract

| Pattern | Where to Look | Output |
|---------|---------------|--------|
| Folder structure | Root directory layout | architecture skill |
| API patterns | API routes, services | api-patterns skill |
| State management | Stores, context, hooks | state-patterns skill |
| Data fetching | API clients, React Query, SWR | data-fetching skill |
| Error handling | Error boundaries, handlers | error-patterns skill |

### Files to Scan

```
src/ structure
lib/ or utils/
services/ or api/
stores/ or state/
middleware/
```

### Questions to Answer

- What's the high-level folder organization?
- How is business logic separated from UI?
- What's the data fetching strategy?
- How is state managed? Local, global, server?
- How are errors handled throughout?

---

## Category 4: Workflow Patterns

Build processes, development workflows, CI/CD.

### What to Extract

| Pattern | Where to Look | Output |
|---------|---------------|--------|
| Build config | Vite, webpack, esbuild configs | build-patterns skill |
| Task automation | Makefile, package.json scripts | dev-workflow skill |
| Testing setup | Test configs, patterns | testing-patterns skill |
| CI/CD | GitHub Actions, deployment | cicd-patterns skill |
| Docker | Dockerfiles, compose files | docker-patterns skill |

### Files to Scan

```
Makefile
package.json (scripts section)
vite.config.* / webpack.config.*
vitest.config.* / jest.config.*
.github/workflows/
Dockerfile / docker-compose.yml
```

### Questions to Answer

- What's the dev command? (`make dev`, `npm run dev`)
- How are tests run and organized?
- What's the deployment process?
- How is the Docker setup structured?
- What automation exists?

---

## Category 5: Domain-Specific Patterns

Application-specific patterns based on what the app does.

### Detection by App Type

| App Type | Indicators | Domain Patterns to Look For |
|----------|------------|----------------------------|
| E-commerce | Cart, checkout, products | pricing, inventory, order flows |
| Dashboard | Charts, metrics, admin | data viz, filters, table patterns |
| SaaS | Auth, billing, multi-tenant | subscription, team, permission patterns |
| Real-time | WebSockets, live updates | presence, sync, conflict resolution |
| Content | CMS, blog, pages | content models, SEO, publishing |

### Files to Scan

Look for domain-specific directories:
```
features/ (feature-based organization)
modules/
domains/
Any directory named after business concepts
```

### Questions to Answer

- What domain is this application in?
- What are the core business entities?
- What unique workflows exist?
- What domain-specific patterns were developed?

---

## Category 6: Infrastructure Patterns

Kubernetes, monitoring, configuration.

### What to Extract

| Pattern | Where to Look | Output |
|---------|---------------|--------|
| K8s manifests | `k8s/` directory | k8s-patterns skill |
| Monitoring | Prometheus configs, Grafana dashboards | monitoring-patterns skill |
| Logging | Log format, aggregation | logging-patterns skill |
| Config management | env files, config loaders | config-patterns skill |

### Files to Scan

```
k8s/ or kubernetes/
monitoring/ or observability/
prometheus.yml
grafana/ (dashboard JSONs)
.env.example
config/ directory
```

---

## Output Structure

For each extraction category, create:

```
ai/skills/[project-name]-[category]/
├── SKILL.md          # Main skill with patterns
└── references/       # (optional) detailed docs
    └── [pattern].md
```

Or for methodology documentation:

```
docs/extracted/
├── [project-name]-summary.md       # Overall methodology
├── [project-name]-design-system.md # Design patterns
└── [project-name]-architecture.md  # Code patterns
```


path: references/skill-quality-criteria.md
content: # Skill Quality Criteria

Condensed quality checklist for generating high-quality skills. Based on the 8-dimension evaluation framework.

---

## The Core Formula

> **Good Skill = Expert-only Knowledge − What Claude Already Knows**

A skill's value is measured by its **knowledge delta** — the gap between what it provides and what Claude already knows.

---

## Quick Quality Checklist

Before finalizing any extracted skill, verify:

### Knowledge Delta (Most Important)
- [ ] No "What is X" explanations for basic concepts
- [ ] No step-by-step tutorials for standard operations
- [ ] Has decision trees for non-obvious choices
- [ ] Has trade-offs only experts would know
- [ ] Has edge cases from real-world experience

### Description Quality (Critical for Activation)
- [ ] Answers WHAT: What does this skill do?
- [ ] Answers WHEN: In what situations should it be used?
- [ ] Contains KEYWORDS: Searchable trigger terms
- [ ] Specific enough that agent knows exactly when to use it

### Anti-Patterns
- [ ] Has explicit NEVER list
- [ ] Anti-patterns are specific, not vague
- [ ] Includes WHY (non-obvious reasons)

### Structure
- [ ] SKILL.md < 500 lines (ideal < 300)
- [ ] Heavy content in references/ if needed
- [ ] Loading triggers embedded in workflow (if references exist)

### Usability
- [ ] Decision trees for multi-path scenarios
- [ ] Working code examples (not pseudocode)
- [ ] Error handling and fallbacks
- [ ] Edge cases covered

---

## Three Types of Knowledge

When writing skill content, categorize each section:

| Type | Definition | Treatment |
|------|------------|-----------|
| **Expert** | Claude genuinely doesn't know this | Must keep — this is the skill's value |
| **Activation** | Claude knows but may not think of | Keep if brief — serves as reminder |
| **Redundant** | Claude definitely knows this | Should delete — wastes tokens |

Target ratio: >70% Expert, <20% Activation, <10% Redundant

---

## Description Template

The description is THE MOST IMPORTANT field — determines if skill gets activated.

```yaml
---
name: [lowercase-hyphenated-name]
description: [WHAT it does]. Use when [WHEN scenarios]. Triggers on [KEYWORDS].
---
```

**Good example:**
```yaml
description: Design system patterns for retro-futuristic UI with CRT effects, 
  scan lines, and analog-digital fusion. Use when building video game-style 
  interfaces, sci-fi terminals, or applications needing a distinct nostalgic-future 
  aesthetic. Triggers on retro, futuristic, CRT, synthwave, cyberpunk.
```

**Bad example:**
```yaml
description: Helps with design.
```

---

## Anti-Pattern Quality

Expert anti-patterns are specific with non-obvious reasons:

**Good:**
```markdown
NEVER:
- Use Inter, Roboto, or system-ui for distinctive aesthetics (too generic)
- Apply purple gradients on white (screams "AI-generated")
- Use default Tailwind spacing (looks like every other site)
```

**Bad:**
```markdown
NEVER:
- Make mistakes
- Be inconsistent
- Forget edge cases
```

---

## Skill Patterns

Choose the appropriate pattern based on task type:

| Pattern | ~Lines | When to Use |
|---------|--------|-------------|
| **Mindset** | ~50 | Creative tasks requiring taste |
| **Navigation** | ~30 | Multiple distinct sub-scenarios |
| **Philosophy** | ~150 | Art/creation requiring originality |
| **Process** | ~200 | Complex multi-step projects |
| **Tool** | ~300 | Precise operations on specific formats |

---

## Common Failure Patterns to Avoid

1. **The Tutorial** — Explains basics Claude already knows
2. **The Dump** — Everything in SKILL.md (>500 lines, no structure)
3. **The Orphan References** — References exist but never loaded
4. **The Checkbox Procedure** — Generic Step 1, 2, 3 without thinking frameworks
5. **The Vague Warning** — "Be careful" without specifics
6. **The Invisible Skill** — Great content, poor description
7. **The Over-Engineered** — README, CHANGELOG, INSTALLATION_GUIDE, etc.

---

## The Meta-Question

Before finalizing any skill, ask:

> **"Would an expert in this domain say: 'Yes, this captures knowledge that took me years to learn'?"**

If yes → the skill has genuine value.
If no → it's compressing what Claude already knows.


path: references/output-templates/project-summary.md
content: # Project Summary Template

Use this template when generating a methodology summary document for an extracted project.

---

## Template

```markdown
# [Project Name] - Methodology Summary

Brief one-line description of what this project is.

---

## How This Was Built

High-level approach and key decisions that shaped this project.

### Development Approach
- [Docs-first? Iterative? Feature-driven?]
- [Key methodologies used]

### Key Decisions
| Decision | Choice | Why |
|----------|--------|-----|
| [e.g., Framework] | [e.g., Next.js] | [Reasoning] |
| [e.g., Styling] | [e.g., Tailwind + custom tokens] | [Reasoning] |
| [e.g., State] | [e.g., React Query + Zustand] | [Reasoning] |

---

## Design Philosophy

The intentional aesthetic and emotional direction.

### Aesthetic Direction
- **Vibe**: [e.g., Retro-futuristic, minimal, video game UI]
- **Inspirations**: [Reference sites, mood boards, influences]
- **Emotions to evoke**: [e.g., Satisfying, nostalgic, powerful]

### Design System Highlights
- **Colors**: [Key palette decisions]
- **Typography**: [Font choices and why]
- **Motion**: [Animation philosophy]

---

## Architecture Patterns

How the code is organized and why.

### Folder Structure
```
[Key directory structure]
```

### Core Patterns
- **Components**: [Organization approach]
- **Data Flow**: [State management, fetching]
- **API Design**: [REST, GraphQL, tRPC, etc.]

---

## Workflow

Build process, dev setup, deployment.

### Development
- **Start command**: `[e.g., make dev]`
- **Hot reload**: [What reloads automatically]
- **Test command**: `[e.g., make test]`

### Deployment
- **Platform**: [e.g., Vercel, GKE]
- **CI/CD**: [e.g., GitHub Actions]
- **Process**: [How deploys happen]

---

## Patterns to Reuse

What's worth extracting for future projects.

### High Value
- [Pattern 1 - why it's valuable]
- [Pattern 2 - why it's valuable]

### Design System Elements
- [Specific tokens, themes, or components worth extracting]

### Infrastructure
- [Docker patterns, CI/CD configs, etc.]

---

## Lessons Learned

What would be done differently next time.

- [Lesson 1]
- [Lesson 2]
```

---

## Usage Notes

When filling this template:

1. **Be specific** — Don't say "good architecture", say what the architecture is
2. **Capture reasoning** — The "why" is more valuable than the "what"
3. **Focus on reusable** — Emphasize what can be extracted for future projects
4. **Include examples** — Concrete code snippets, file paths, command examples
5. **Note aesthetics** — Design philosophy is high priority, capture it thoroughly


path: references/output-templates/skill-template.md
content: # Skill Template

Use this template when generating extracted skills from a project.

---

## Template

```markdown
---
name: [project-name]-[category]
description: [WHAT it does]. Use when [WHEN scenarios]. Triggers on [KEYWORDS].
---

# [Skill Title]

[One sentence describing what expert knowledge this skill captures.]

---

## When to Use

- [Specific scenario 1]
- [Specific scenario 2]
- [Specific scenario 3]

---

## Core Patterns

### [Pattern 1 Name]

[Expert knowledge about this pattern - decision trees, trade-offs, edge cases]

### [Pattern 2 Name]

[Expert knowledge about this pattern]

---

## Decision Tree

[For multi-path scenarios, provide clear decision guidance]

| Situation | Approach | Why |
|-----------|----------|-----|
| [When X] | [Do Y] | [Because Z] |
| [When A] | [Do B] | [Because C] |

---

## Code Examples

[Working code examples, not pseudocode]

```[language]
// Example with explanation
```

---

## NEVER Do

- **[Specific anti-pattern]** — [Non-obvious reason why]
- **[Specific anti-pattern]** — [Non-obvious reason why]

---

## Edge Cases

| Case | Solution |
|------|----------|
| [Edge case 1] | [How to handle] |
| [Edge case 2] | [How to handle] |
```

---

## Quality Checklist

Before finalizing, verify:

- [ ] Description has WHAT, WHEN, and KEYWORDS
- [ ] No explanations of things Claude already knows
- [ ] Has specific NEVER list with reasons
- [ ] Working code examples (not pseudocode)
- [ ] Decision trees for multi-path scenarios
- [ ] < 300 lines (ideal), < 500 lines (max)
- [ ] Would an expert say "this captures real knowledge"?

---

## Pattern Guidelines

Choose structure based on skill type:

| Type | Lines | Structure |
|------|-------|-----------|
| Mindset | ~50 | Thinking principles + NEVER list |
| Navigation | ~30 | Routes to sub-files for scenarios |
| Philosophy | ~150 | Philosophy section + expression section |
| Process | ~200 | Phased workflow with checkpoints |
| Tool | ~300 | Decision trees + code examples + edge cases |


path: references/output-templates/design-system.md
content: # Design System Template

Use this template when extracting design system documentation from a project.

---

## Template

```markdown
# [Project Name] - Design System

The visual language and token system for this project.

---

## Aesthetic Foundation

### The Vibe
[Describe the overall aesthetic in 2-3 sentences. What does it look like? What does it feel like?]

### Inspirations
- [Reference 1 - what was taken from it]
- [Reference 2 - what was taken from it]
- [Mood board link if exists]

### Emotions to Evoke
| Emotion | How It's Achieved |
|---------|-------------------|
| [e.g., Satisfaction] | [e.g., Micro-interactions on completion] |
| [e.g., Nostalgia] | [e.g., CRT scan lines, pixel fonts] |
| [e.g., Power] | [e.g., Dark mode, sharp angles] |

---

## Color Tokens

### Palette

| Token | Value | Usage |
|-------|-------|-------|
| `--color-primary` | [hex/hsl] | [Primary actions, key elements] |
| `--color-secondary` | [hex/hsl] | [Secondary elements] |
| `--color-accent` | [hex/hsl] | [Highlights, emphasis] |
| `--color-background` | [hex/hsl] | [Base background] |
| `--color-surface` | [hex/hsl] | [Cards, elevated surfaces] |
| `--color-text` | [hex/hsl] | [Primary text] |
| `--color-text-muted` | [hex/hsl] | [Secondary text] |

### Semantic Colors

| Token | Value | Usage |
|-------|-------|-------|
| `--color-success` | [hex/hsl] | [Success states] |
| `--color-warning` | [hex/hsl] | [Warning states] |
| `--color-error` | [hex/hsl] | [Error states] |
| `--color-info` | [hex/hsl] | [Info states] |

### Dark Mode
[How dark mode is implemented, token overrides]

---

## Typography

### Font Families

| Token | Value | Usage |
|-------|-------|-------|
| `--font-primary` | [font stack] | [Body text] |
| `--font-heading` | [font stack] | [Headings] |
| `--font-mono` | [font stack] | [Code, technical] |

### Type Scale

| Token | Size | Line Height | Usage |
|-------|------|-------------|-------|
| `--text-xs` | [rem] | [value] | [Captions, labels] |
| `--text-sm` | [rem] | [value] | [Secondary text] |
| `--text-base` | [rem] | [value] | [Body text] |
| `--text-lg` | [rem] | [value] | [Lead paragraphs] |
| `--text-xl` | [rem] | [value] | [H4, subheadings] |
| `--text-2xl` | [rem] | [value] | [H3] |
| `--text-3xl` | [rem] | [value] | [H2] |
| `--text-4xl` | [rem] | [value] | [H1] |

### Font Weights
| Token | Value | Usage |
|-------|-------|-------|
| `--font-normal` | 400 | [Body] |
| `--font-medium` | 500 | [Emphasis] |
| `--font-semibold` | 600 | [Subheadings] |
| `--font-bold` | 700 | [Headings] |

---

## Spacing

### Scale

| Token | Value | Usage |
|-------|-------|-------|
| `--space-1` | [rem] | [Tight gaps] |
| `--space-2` | [rem] | [Small gaps] |
| `--space-3` | [rem] | [Medium gaps] |
| `--space-4` | [rem] | [Default gaps] |
| `--space-6` | [rem] | [Section gaps] |
| `--space-8` | [rem] | [Large gaps] |
| `--space-12` | [rem] | [Page sections] |

### Layout Rhythm
[How spacing is applied consistently across the UI]

---

## Motion

### Timing

| Token | Value | Usage |
|-------|-------|-------|
| `--duration-fast` | [ms] | [Micro-interactions] |
| `--duration-normal` | [ms] | [Standard transitions] |
| `--duration-slow` | [ms] | [Page transitions] |

### Easing

| Token | Value | Usage |
|-------|-------|-------|
| `--ease-default` | [cubic-bezier] | [Most animations] |
| `--ease-in` | [cubic-bezier] | [Enter animations] |
| `--ease-out` | [cubic-bezier] | [Exit animations] |
| `--ease-bounce` | [cubic-bezier] | [Playful interactions] |

### Animation Patterns
- **Hover states**: [How hovers work]
- **Loading**: [Skeleton, spinner patterns]
- **Transitions**: [Page/component transitions]

---

## Borders & Shadows

### Border Radius

| Token | Value | Usage |
|-------|-------|-------|
| `--radius-sm` | [rem] | [Buttons, inputs] |
| `--radius-md` | [rem] | [Cards] |
| `--radius-lg` | [rem] | [Modals, large cards] |
| `--radius-full` | 9999px | [Circles, pills] |

### Shadows

| Token | Value | Usage |
|-------|-------|-------|
| `--shadow-sm` | [value] | [Subtle elevation] |
| `--shadow-md` | [value] | [Cards, dropdowns] |
| `--shadow-lg` | [value] | [Modals, popovers] |

---

## Components

### Key Component Patterns
[Document the most important reusable components and their variants]

### Component Tokens
[Any component-specific tokens like button colors, card padding, etc.]

---

## Implementation

### Tailwind Config
```javascript
// Relevant tailwind.config.js excerpt
```

### CSS Variables
```css
/* Root variable definitions */
```

---

## Anti-Patterns

Things to NEVER do in this design system:

- [Specific thing to avoid + why]
- [Specific thing to avoid + why]
```

---

## Usage Notes

When filling this template:

1. **Extract actual values** — Don't guess, pull from Tailwind config, CSS files
2. **Document the "why"** — Why these colors? Why this font? What feeling?
3. **Include code** — Actual Tailwind config, CSS variable definitions
4. **Note anti-patterns** — What should never be done in this system
5. **Capture the vibe** — The aesthetic direction is as important as the tokens


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)