Initial commit

2025-11-29 18:47:15 +08:00
commit d024d22cd1
30 changed files with 9249 additions and 0 deletions
--- a/skills/clj-kondo/INDEX.md
+++ b/skills/clj-kondo/INDEX.md
@@ -0,0 +1,383 @@
+# clj-kondo Skill - Index
+
+Welcome to the comprehensive clj-kondo skill! Master Clojure linting, from basic usage to writing custom hooks for domain-specific rules.
+
+## 📚 Documentation Files
+
+### 1. [README.md](README.md) - Getting Started
+**Size:** ~8KB | **Reading time:** 10-15 minutes
+
+Quick overview including:
+- What is clj-kondo?
+- Installation
+- Basic usage examples
+- First hook example
+- What the skill covers
+- Learning path
+
+**Start here** if you're new to clj-kondo.
+
+### 2. [SKILL.md](SKILL.md) - Complete Guide
+**Size:** ~35KB | **Reading time:** 45-60 minutes
+
+Comprehensive documentation covering:
+- Introduction and installation
+- Getting started and basic usage
+- Configuration management
+- Built-in linters reference
+- **Custom hooks development** (extensive section)
+- Hook API reference
+- Practical hook examples
+- IDE integration
+- CI/CD integration
+- Best practices
+- Troubleshooting
+
+**Start here** for comprehensive learning or reference.
+
+### 3. [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Cheat Sheet
+**Size:** ~7KB | **Quick lookup**
+
+Concise reference with:
+- Command-line usage
+- Common configurations
+- Linter settings
+- Hook patterns
+- IDE integration snippets
+- CI/CD templates
+- Troubleshooting tips
+
+**Use this** when you need quick reference.
+
+### 4. [examples.clj](examples.clj) - Hook Examples
+**Size:** ~8KB | **Executable script**
+
+8 practical hook examples:
+1. Basic deprecation warning
+2. Argument count validation
+3. Argument type validation
+4. Required map keys validation
+5. Macro expansion for DSL
+6. Route definition expansion
+7. Thread-safety hints
+8. Team convention enforcement
+
+Plus complete hook file template.
+
+**Run this** to see hook patterns:
+```bash
+bb examples.clj
+```
+
+### 5. [metadata.edn](metadata.edn) - Skill Metadata
+**Size:** ~4KB | **Machine-readable**
+
+Structured information about:
+- Skill properties and versioning
+- Library information
+- Use cases and features
+- Learning path
+- Platform support
+
+## 🎯 Quick Navigation
+
+### By Experience Level
+
+**Beginner** (Never used clj-kondo)
+1. Read [README.md](README.md) for overview
+2. Install clj-kondo
+3. Run basic linting on your code
+4. Review "Getting Started" in [SKILL.md](SKILL.md)
+5. Understand built-in linters
+
+**Intermediate** (Used clj-kondo, want customization)
+1. Read "Configuration" in [SKILL.md](SKILL.md)
+2. Study "Built-in Linters" section
+3. Customize for your project
+4. Set up IDE integration
+5. Add to CI/CD pipeline
+
+**Advanced** (Ready to write hooks)
+1. Read "Custom Hooks" in [SKILL.md](SKILL.md)
+2. Run [examples.clj](examples.clj) to see patterns
+3. Study Hook API reference
+4. Write your first deprecation hook
+5. Progress to complex validation hooks
+6. Learn macro expansion hooks
+
+### By Task
+
+**Need to install and start using clj-kondo?**
+- README.md → "Quick Start"
+- SKILL.md → "Installation" and "Getting Started"
+
+**Need to configure linters?**
+- SKILL.md → "Configuration"
+- QUICK_REFERENCE.md → "Basic Configuration" and "Common Linter Configurations"
+
+**Want to understand what clj-kondo checks?**
+- SKILL.md → "Built-in Linters"
+- QUICK_REFERENCE.md → "Common Linter Configurations"
+
+**Need to write a deprecation warning hook?**
+- SKILL.md → "Custom Hooks" → "Creating Your First Hook"
+- examples.clj → Example 1 (Deprecation Warning)
+- QUICK_REFERENCE.md → "Common Hook Patterns" → "Deprecation Warning"
+
+**Need to validate function arguments?**
+- SKILL.md → "Custom Hooks" → "Practical Hook Examples"
+- examples.clj → Examples 2-4 (Argument validation)
+- QUICK_REFERENCE.md → "Common Hook Patterns"
+
+**Need to support a custom DSL/macro?**
+- SKILL.md → "Custom Hooks" → ":macroexpand Hooks"
+- examples.clj → Examples 5-6 (Macro expansion)
+- QUICK_REFERENCE.md → "macroexpand Hook"
+
+**Need to integrate with IDE?**
+- SKILL.md → "IDE Integration"
+- QUICK_REFERENCE.md → "IDE Integration"
+
+**Need to add to CI/CD?**
+- SKILL.md → "CI/CD Integration"
+- QUICK_REFERENCE.md → "CI/CD Patterns"
+
+## 🚀 Suggested Learning Paths
+
+### Path 1: Basic User (2-3 hours)
+
+**Goal:** Use clj-kondo effectively for your projects
+
+1. ✅ **Read README.md** (10 min)
+   - Understand what clj-kondo does
+   - See quick examples
+
+2. ✅ **Install and test** (15 min)
+   - Install clj-kondo
+   - Run on your codebase
+   - Review findings
+
+3. ✅ **Study SKILL.md: Getting Started** (20 min)
+   - Command-line usage
+   - Output formats
+   - Basic workflow
+
+4. ✅ **Study SKILL.md: Configuration** (30 min)
+   - Configuration file structure
+   - Linter levels
+   - Inline suppressions
+
+5. ✅ **Study SKILL.md: Built-in Linters** (30 min)
+   - Understand what's checked
+   - Configure for your needs
+
+6. ✅ **Integrate with IDE** (20 min)
+   - Set up editor integration
+   - Test real-time linting
+
+7. ✅ **Practice** (30 min)
+   - Configure for your project
+   - Fix some linting issues
+   - Customize linter levels
+
+### Path 2: Hook Developer (6-8 hours)
+
+**Goal:** Write custom hooks for domain-specific linting
+
+**Prerequisites:** Complete Basic User path
+
+1. ✅ **Study SKILL.md: Custom Hooks intro** (45 min)
+   - What are hooks
+   - When to use hooks
+   - Hook architecture
+
+2. ✅ **Run examples.clj** (15 min)
+   - See hook patterns in action
+   - Understand hook structure
+
+3. ✅ **Study SKILL.md: Hook API Reference** (45 min)
+   - Node functions
+   - Node constructors
+   - Return values
+
+4. ✅ **Write first hook: Deprecation** (60 min)
+   - Create hook file
+   - Register in config
+   - Test it
+
+5. ✅ **Study examples.clj in detail** (60 min)
+   - Analyze each example
+   - Understand patterns
+   - Note code structure
+
+6. ✅ **Write validation hooks** (90 min)
+   - Argument count validation
+   - Argument type validation
+   - Map keys validation
+
+7. ✅ **Study macroexpand hooks** (60 min)
+   - SKILL.md → ":macroexpand Hooks"
+   - examples.clj → Examples 5-6
+   - Understand node transformation
+
+8. ✅ **Write DSL expansion hook** (90 min)
+   - For your own macros
+   - Test thoroughly
+   - Document usage
+
+9. ✅ **Study SKILL.md: Testing and Distribution** (30 min)
+   - Testing strategies
+   - Distribution patterns
+
+10. ✅ **Practice** (90 min)
+    - Write hooks for your codebase
+    - Test edge cases
+    - Document hooks
+
+### Path 3: Team Lead (4-5 hours)
+
+**Goal:** Set up clj-kondo for team with custom rules
+
+**Prerequisites:** Complete Basic User path
+
+1. ✅ **Study SKILL.md: Configuration** (deep dive) (45 min)
+   - Team configuration strategies
+   - Consistent aliases
+   - Convention enforcement
+
+2. ✅ **Set up team configuration** (60 min)
+   - Define team standards
+   - Configure linters
+   - Document choices
+
+3. ✅ **Study custom hooks** (90 min)
+   - SKILL.md → "Custom Hooks"
+   - examples.clj → All examples
+   - Identify team needs
+
+4. ✅ **Write team convention hooks** (90 min)
+   - Naming conventions
+   - API usage rules
+   - Deprecation warnings
+
+5. ✅ **Set up CI/CD** (45 min)
+   - SKILL.md → "CI/CD Integration"
+   - Add to your pipeline
+   - Configure failure thresholds
+
+6. ✅ **Documentation** (30 min)
+   - Document configuration
+   - Document custom hooks
+   - Create team guide
+
+## 📊 Skill Coverage
+
+This skill covers **100%** of clj-kondo's core functionality:
+
+### Basic Usage
+- ✅ Installation (all platforms)
+- ✅ Command-line usage
+- ✅ Output formats
+- ✅ Cache management
+
+### Configuration
+- ✅ Configuration file structure
+- ✅ Linter levels
+- ✅ Global and local config
+- ✅ Inline suppressions
+- ✅ Configuration merging
+
+### Built-in Linters
+- ✅ Namespace linters
+- ✅ Binding linters
+- ✅ Function/arity linters
+- ✅ Collection linters
+- ✅ Type checking
+
+### Custom Hooks (Advanced)
+- ✅ Hook architecture
+- ✅ `:analyze-call` hooks
+- ✅ `:macroexpand` hooks
+- ✅ Hook API reference
+- ✅ 8+ practical examples
+- ✅ Testing strategies
+- ✅ Distribution patterns
+
+### Integration
+- ✅ VS Code (Calva)
+- ✅ Emacs
+- ✅ IntelliJ/Cursive
+- ✅ Vim/Neovim
+- ✅ GitHub Actions
+- ✅ GitLab CI
+- ✅ Pre-commit hooks
+
+## 🎓 What You'll Learn
+
+After completing this skill:
+
+**Basic Level:**
+- ✅ Install and run clj-kondo
+- ✅ Understand linting output
+- ✅ Configure linters for your project
+- ✅ Suppress warnings appropriately
+- ✅ Integrate with IDE
+- ✅ Add to CI/CD pipeline
+
+**Advanced Level:**
+- ✅ Write deprecation warning hooks
+- ✅ Validate function arguments
+- ✅ Check required map keys
+- ✅ Expand custom macros for analysis
+- ✅ Enforce team conventions
+- ✅ Test hooks effectively
+- ✅ Distribute hooks with libraries
+
+## 💡 Use Cases Covered
+
+1. **Basic Linting** - Catch syntax errors and common mistakes
+2. **Code Quality** - Enforce best practices
+3. **API Deprecation** - Warn about deprecated functions
+4. **Argument Validation** - Check function arguments
+5. **DSL Support** - Analyze custom macros
+6. **Team Conventions** - Enforce naming and style rules
+7. **Domain Rules** - Validate business logic
+8. **CI/CD Integration** - Automated quality checks
+
+## 🔗 External Resources
+
+- [Official GitHub Repository](https://github.com/clj-kondo/clj-kondo)
+- [Configuration Reference](https://github.com/clj-kondo/clj-kondo/blob/master/doc/config.md)
+- [Hooks API Documentation](https://github.com/clj-kondo/clj-kondo/blob/master/doc/hooks.md)
+- [Linters Reference](https://github.com/clj-kondo/clj-kondo/blob/master/doc/linters.md)
+- [Hook Examples Repository](https://github.com/clj-kondo/clj-kondo/tree/master/examples)
+
+## 📝 Version Information
+
+- **Skill Version:** 1.0.0
+- **clj-kondo Version:** 2024.11.14
+- **Created:** 2025-11-10
+- **Language:** Clojure
+- **Platform:** Cross-platform (Linux, macOS, Windows)
+- **License:** EPL-1.0
+
+## 🎯 Next Steps
+
+### If you're new to clj-kondo:
+1. Start with [README.md](README.md)
+2. Follow "Path 1: Basic User"
+3. Practice on your projects
+
+### If you want to write hooks:
+1. Complete Basic User path first
+2. Read [SKILL.md](SKILL.md) "Custom Hooks" section
+3. Run [examples.clj](examples.clj)
+4. Follow "Path 2: Hook Developer"
+
+### If you need quick reference:
+1. Use [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
+2. Bookmark for fast lookups
+
+---
+
+**Ready to start?** Begin with [README.md](README.md) for an introduction, or jump to [SKILL.md](SKILL.md) for comprehensive coverage!