---
name: skill-discovery-engine
description: Automatically identifies recurring patterns in the codebase and suggests or creates new skill files to institutionalize knowledge
metadata:
  author: oversold
  version: "1.0.0"
---

Scan the codebase for recurring patterns and propose new skills to capture institutional knowledge.

---

# Core scenarios

1. **Session initialization** - scan for patterns on startup
2. **Complex task completed** - analyze multi-file edits for reusable patterns
3. **User asks** "What have you learned about this project?"

## Execution Steps

### 1. Environmental Scan

```bash
# Index existing skills
ls ./.claude/skills/

# Analyze recent activity
git log --oneline -10 --name-only
```

### 2. Pattern Detection

Search for these pattern categories:

| Category | What to Look For |
|----------|------------------|
| **Refactoring** | Repetitive boilerplate, complex logic transformations, repeated code structures |
| **DevOps** | Multi-step CLI sequences, configuration file patterns, deployment scripts |
| **Testing** | Mock setups, assertion patterns, test file structures |
| **Security** | Auth patterns, input validation, secret handling, CORS configs, rate limiting |
| **Research** | Data gathering workflows, API exploration, documentation synthesis |
| **SEO** | Meta tag patterns, structured data, sitemap generation, canonical URLs |
| **Design** | Component patterns, design tokens, styling conventions, responsive breakpoints |
| **UX** | Loading states, error boundaries, form validation, accessibility patterns |

### 3. Validation Criteria

A pattern is "skill-worthy" if it meets ALL of these:
- [ ] Reusable across multiple contexts
- [ ] Non-obvious (requires domain knowledge)
- [ ] Occurs 2+ times in the codebase
- [ ] Would save time if documented

### 4. Skill Creation

When a valid pattern is found:

1. **Propose** the skill name (kebab-case)
2. **Create directory structure**:

```
.claude/skills/
└── [skill-name]/
    └── SKILL.md
```

```bash
mkdir -p ./.claude/skills/[skill-name]
```

3. **Draft** `SKILL.md` content using this template:

```markdown
---
description: Brief one-line description
triggers:
  - trigger condition 1
  - trigger condition 2
---

# Skill Name

Brief overview of what this skill does.

## Steps

1. First step
2. Second step

## Code Examples

\`\`\`typescript
// Example code
\`\`\`
```

4. **Prompt user**: "I've detected a recurring pattern for [Pattern Name]. Save as `.claude/skills/[skill-name]/SKILL.md`?"

**IMPORTANT**: Always use the directory structure `[skill-name]/SKILL.md`, never a flat file.

### 5. Self-Update

If an existing skill could be improved:
- Suggest specific edits to the existing file
- Do NOT create duplicates

## Output Format

```
## Skill Discovery Report

**Scanned**: [X files, Y recent commits]
**Existing Skills**: [list]

### Patterns Detected

1. **[Pattern Name]** (Category: Refactoring|DevOps|Testing|Security|Research|SEO|Design|UX)
   - Occurrences: N
   - Files: file1.ts, file2.ts
   - Recommendation: Create skill | Update existing | Skip (not reusable)

### Proposed Actions

- [ ] Create `.claude/skills/[skill-name]/SKILL.md`
- [ ] Update `.claude/skills/[existing-skill]/SKILL.md` with [improvement]
```