clerk

clerk expert with self-populating documentation

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill serves as a specialized Clerk authentication expert featuring a unique self-populating documentation engine. It ensures developers always work with the most current information by automatically fetching, validating, and synthesizing the latest Clerk patterns, best practices, and troubleshooting guides directly from official web sources, effectively eliminating issues caused by outdated API knowledge.

Use Cases

  • Implementing secure Clerk authentication flows in modern web frameworks (Next.js, Rails, Django) using the most recent 2025 best practices.
  • Automatically maintaining an up-to-date local knowledge base of Clerk documentation to prevent the use of deprecated methods or anti-patterns.
  • Debugging complex authentication middleware and session management issues with real-time troubleshooting data fetched from official sources.
  • Architecting seamless integrations between Clerk user management and backend databases like Prisma, Sequelize, or SQLAlchemy.
nameclerk
descriptionclerk expert with self-populating documentation
toolsRead, Write, WebSearch, WebFetch, Bash, Grep

clerk Expert

⚠️⚠️⚠️ MANDATORY PRE-EXECUTION CHECKLIST ⚠️⚠️⚠️

DO NOT SKIP THESE STEPS - Complete them in order before proceeding.

═══════════════════════════════════════════════

□ Step 1: Check if Documentation Exists

Action: Check if reference documentation file exists

ls -la .claude/skills/clerk/references/external/clerk-patterns.md 2>/dev/null && wc -w .claude/skills/clerk/references/external/clerk-patterns.md

Evaluate Result:

  • ✅ File exists AND word count > 1000 → GO TO STEP 2 (Check freshness)
  • ❌ File missing OR word count < 1000 → GO TO STEP 4 (Fetch from web)

□ Step 2: Check Documentation Freshness

Action: Read metadata to determine age

cat .claude/skills/clerk/.skill-metadata.json | grep last_verified

Calculate Age:

Current date: 2025-11-12
Last verified: [value from metadata, or null if never verified]
Age in days: [calculate difference, or ∞ if null]

Evaluate Result:

  • ✅ Age ≤ 30 days → GO TO STEP 3 (Documentation is fresh, ready to use)
  • ⚠️ Age > 30 days OR null → GO TO STEP 4 (Refresh from web)

□ Step 3: ✅ Documentation Ready - Proceed

Status: Documentation is fresh and ready to use.

Action: Skip to "Domain Knowledge" section below and apply clerk expertise from: references/external/clerk-patterns.md


□ Step 4: Fetch/Refresh Documentation from Web

Status: Documentation is missing, empty, or stale. Must fetch current information.

Step 4A: Detect Context

Read project context to make searches relevant:

cat .claude/core/context.yaml | grep -E "framework|database|auth"

Extract:

  • Framework: [e.g., nextjs, django, rails]
  • Database: [e.g., prisma, sequelize, sqlalchemy]
  • Auth: [e.g., clerk, auth0, passport]

Step 4B: Execute Web Searches

Run ALL of these search queries and collect results:

Query Set 1: Official Documentation

WebSearch: "clerk official documentation 2025"
WebSearch: "clerk getting started guide 2025"

Query Set 2: Best Practices & Patterns

WebSearch: "clerk best practices 2025"
WebSearch: "clerk architecture patterns 2025"
WebSearch: "clerk design principles"

Query Set 3: Common Pitfalls

WebSearch: "clerk common mistakes to avoid"
WebSearch: "clerk anti-patterns"
WebSearch: "clerk gotchas and pitfalls 2025"

Query Set 4: Integration (Context-Specific)

If framework detected:

WebSearch: "clerk [FRAMEWORK] integration best practices"

If database detected:

WebSearch: "clerk [DATABASE] patterns"

If auth detected:

WebSearch: "clerk [AUTH] integration"

Record: Save all URLs fetched for metadata

Step 4C: Synthesize Documentation

Create file: references/external/clerk-patterns.md

Required Structure:

# clerk Patterns & Best Practices

**Last Updated:** 2025-11-12
**Tech Version:** [from web search - e.g., "6.19.0"]
**Sources:**
- [List all URLs fetched]

---

## ⚠️ CRITICAL PATTERNS (Follow These)

[Extract 3-5 most important patterns from search results]

### Pattern 1: [Most Critical Pattern Name]

✅ **CORRECT APPROACH:**

[Code example showing the right way]


❌ **WRONG - Avoid This:**

[Code example showing common mistake]


**Why this matters:** [Explanation of consequences]
**When to use:** [Guidelines for application]

[Repeat for patterns 2-5]

---

## 🚫 COMMON MISTAKES (Avoid These)

[Extract top 5 mistakes from "pitfalls" searches]

### Mistake 1: [Most Common Error]
**Symptom:** [How it manifests]
**Why it's bad:** [Consequences]
**How to fix:** [Solution with code example]

[Repeat for mistakes 2-5]

---

## 🔧 INTEGRATION PATTERNS

### clerk + [DETECTED_FRAMEWORK]
[Framework-specific integration examples if framework detected]

### clerk + [DETECTED_DATABASE]
[Database integration patterns if database detected]

### clerk + [DETECTED_AUTH]
[Auth integration patterns if auth detected]

---

## 📚 Quick Reference

[Create cheat sheet of 10-15 most common operations]

**Installation:**
```bash
[commands]

Basic Setup:

[code]

Common Operations:

  1. ...

🔍 Troubleshooting

[Common errors and solutions from search results]

Error: [Error message] Cause: [Why it happens] Solution: [How to fix]


📖 Additional Resources

  • Official Docs: [URL]
  • Best Practices Guide: [URL]
  • Community Resources: [URL]

**Quality Check:**
- Minimum 1500 words
- At least 3 critical patterns
- At least 5 common mistakes
- Integration examples for detected stack
- Code examples throughout

### Step 4D: Update Metadata

**Write to:** `.claude/skills/clerk/.skill-metadata.json`

```json
{
  "skill_name": "clerk",
  "tech_version": "[from web search]",
  "last_verified": "2025-11-12T10:32:28.617648",
  "age_days": 0,
  "status": "fresh",

  "search_metadata": {
    "queries_used": [
      "[list all search queries executed]"
    ],
    "sources_fetched": [
      "[list all URLs from web search]"
    ],
    "search_timestamp": "2025-11-12T10:32:28.617648",
    "search_engine": "WebSearch"
  },

  "content_metadata": {
    "word_count": [actual count],
    "patterns_count": [number of critical patterns],
    "mistakes_count": [number of common mistakes],
    "has_official_docs": true/false,
    "has_best_practices": true/false,
    "has_antipatterns": true/false,
    "has_integration_examples": true/false,
    "confidence": "high/medium/low"
  },

  "detected_context": {
    "framework": "[from context.yaml]",
    "database": "[from context.yaml]",
    "auth": "[from context.yaml]"
  }
}

Step 4E: Validation

Verify documentation was created successfully:

wc -w .claude/skills/clerk/references/external/clerk-patterns.md

Expected: Minimum 1500 words

If validation passes: ✅ Continue to Step 4F

If validation fails:

⚠️⚠️⚠️ DOCUMENTATION FETCH FAILED ⚠️⚠️⚠️

Attempted: 2025-11-12T10:32:28.617648
Word count: [actual] (required: 1500+)

**DO NOT PROCEED** without valid documentation.

Possible causes:
- Internet connection issues
- Web search returned poor results
- Official docs not found

**Recovery options:**
1. Check internet connection and retry Step 4
2. Manually search for: "clerk official documentation"
3. If clerk is very new/niche, consider:
   - Creating minimal patterns.md from official GitHub
   - Marking metadata as "low confidence"
4. Run repair script: `./bootstrapper/scripts/repair_skills.py --skill clerk`

**If this is a critical blocker:** Ask user for clerk documentation sources.

STOP HERE - Do not proceed without valid documentation.

Step 4F: Success - Documentation Fetched

✅ Documentation successfully created and validated.

NOW GO TO STEP 3 to use the fresh documentation.

═══════════════════════════════════════════════ END OF MANDATORY CHECKLIST ═══════════════════════════════════════════════


Domain Knowledge

Read from: references/external/clerk-patterns.md

This section contains the comprehensive clerk expertise fetched from web searches. Apply patterns and avoid anti-patterns documented above.


When to Use This Skill

Use this skill when:

  • Working with clerk in the codebase
  • Implementing clerk features or integrations
  • Debugging clerk-related issues
  • Following clerk best practices
  • Architectural decisions involving clerk

Quality Standards

After implementing clerk changes, ensure:

  • ✅ Configuration is valid
  • ✅ Tests pass (if applicable)
  • ✅ Build succeeds without errors
  • ✅ Best practices from patterns.md followed
  • ✅ No anti-patterns from mistakes section used
  • ✅ Integration patterns applied correctly

Check against quality gates in .claude/core/gates.yaml


Skill Limitations

This skill covers:

  • ✅ clerk setup and configuration
  • ✅ Common patterns and best practices
  • ✅ Integration with detected stack
  • ✅ Troubleshooting guidance
  • ✅ Anti-patterns to avoid

This skill does NOT cover:

  • ❌ Tasks outside clerk domain
  • ❌ Deprecated or outdated patterns
  • ❌ Experimental/beta features (unless explicitly documented)
  • ❌ Deep internals (unless found in official docs)

Maintenance (Automatic)

This skill is self-maintaining:

  • ✅ Auto-checks freshness on each invocation
  • ✅ Auto-refreshes if > 30 days old
  • ✅ Tracks sources for reproducibility
  • ✅ Adapts to project context

Manual maintenance (optional):

  • Add project-specific patterns to references/
  • Customize for specific use cases
  • Override search queries in metadata if needed

Getting Help

If documentation is insufficient:

  1. Run specific search: WebSearch: "clerk [your specific topic] 2025"
  2. Check official docs: [URL from sources in patterns.md]
  3. Force refresh: Delete .skill-metadata.json and re-invoke skill
  4. Manual update: Edit clerk-patterns.md with additional patterns

Troubleshooting This Skill

Problem: Skill says documentation missing but file exists Solution: Check file size - might be empty or corrupted. Delete and retry Step 4.

Problem: Documentation feels outdated Solution: Check metadata age. If < 30 days but still feels stale, delete metadata to force refresh.

Problem: Web searches failing consistently Solution: Check internet connection. If offline, cannot use self-populating skills.

Problem: Documentation lacks context for my specific stack Solution: Re-run Step 4 after ensuring context.yaml is up to date.