🔧 chore: fix skill naming and gitea actions compatibility (related to #2)

.vibe/skills/swagger-documentation/README.md

@@ -0,0 +1,150 @@
+# Swagger Documentation Skill
+
+**Skill Name:** `swagger-documentation`
+**Status:** ✅ Active
+**Version:** 1.0.0
+
+## 📋 Overview
+
+This skill provides comprehensive guidance and automation for managing OpenAPI/Swagger documentation in the DanceLessonsCoach project. It captures our best practices, tagging strategies, and automation patterns for maintaining high-quality API documentation.
+
+## 🎯 Key Features
+
+### 1. **Hierarchical Tagging System**
+Our proprietary `Domain/Version/Function` tagging structure:
+- `API/v1/Greeting`, `API/v2/Greeting` for business endpoints
+- `System/Health`, `System/Metrics` for infrastructure endpoints
+- Clear separation between API domains and versions
+
+### 2. **Standardized Annotations**
+Pre-defined templates for all endpoint types:
+- Basic endpoints
+- Parameterized endpoints  
+- POST endpoints with request bodies
+- System/health endpoints
+
+### 3. **Automation Scripts**
+Ready-to-use scripts for:
+- Documentation generation
+- Validation and quality checks
+- CI/CD integration
+
+### 4. **Best Practices Guide**
+Comprehensive guidelines covering:
+- Tag consistency rules
+- Annotation completeness
+- Version management
+- Response documentation
+
+## 🚀 Quick Start
+
+### 1. Generate Documentation
+```bash
+# Regenerate all Swagger documentation
+go generate ./pkg/server/
+```
+
+### 2. Verify Structure
+```bash
+# Check hierarchical tags are present
+grep -c "API/v1/Greeting" pkg/server/docs/swagger.json
+grep -c "API/v2/Greeting" pkg/server/docs/swagger.json
+grep -c "System/Health" pkg/server/docs/swagger.json
+```
+
+### 3. Test in Swagger UI
+```bash
+# Access the interactive documentation
+open http://localhost:8080/swagger/
+```
+
+## 📚 Documentation Structure
+
+```
+swagger_documentation/
+├── SKILL.md          # Complete skill documentation
+├── README.md         # This file
+└── scripts/          # Automation scripts (future)
+```
+
+## 🎓 Usage Patterns
+
+### Adding New Endpoints
+1. **Choose the right tag** based on domain/version/function
+2. **Copy annotation template** from SKILL.md
+3. **Add complete annotations** to handler
+4. **Regenerate documentation** with `go generate`
+5. **Verify in Swagger UI**
+
+### Updating Existing Endpoints
+1. **Update handler code** as needed
+2. **Review annotations** for accuracy
+3. **Regenerate documentation**
+4. **Test changes** in Swagger UI
+
+### Adding New API Versions
+1. **Create new tag structure** (e.g., `API/v3/Greeting`)
+2. **Document in SKILL.md**
+3. **Update ADR 0013** with rationale
+4. **Implement endpoints** with new tags
+5. **Regenerate and test**
+
+## 🔧 Technical Details
+
+### Tag Structure Rules
+```
+Domain/Version/Function
+│      │        └─ Specific functionality (Greeting, User, Health)
+│      └─ API version (v1, v2, v3) - for API domain only
+└─ Domain (API, System, Admin)
+```
+
+### Required Flags
+```bash
+# These flags are CRITICAL for multi-package projects
+--parseDependency  # Parse dependent packages
+--parseInternal   # Include internal packages
+```
+
+### Embed Directive
+```go
+//go:embed docs/swagger.json
+var swaggerJSON embed.FS
+```
+
+## 📝 Maintenance
+
+### Updating This Skill
+When you:
+- Introduce new tag patterns
+- Discover better annotation approaches
+- Add new endpoint types
+- Find solutions to common issues
+
+**Please update SKILL.md** to share knowledge with the team!
+
+### Version History
+- **1.0.0**: Initial release with hierarchical tagging
+- **Next**: Add CI/CD integration scripts
+
+## 🤝 Contributing
+
+Found a better way? Have a new pattern? 
+
+1. **Update SKILL.md** with your improvements
+2. **Test thoroughly** in development
+3. **Document examples** clearly
+4. **Update ADR 0013** if architectural changes
+5. **Commit with clear message** using gitmoji
+
+## 📚 Related Resources
+
+- **[ADR 0013](adr/0013-openapi-swagger-toolchain.md)** - Architectural decision
+- **[AGENTS.md](#openapi-documentation)** - Project documentation
+- **[swaggo/swag](https://github.com/swaggo/swag)** - Official documentation
+
+---
+
+**Maintained by:** DanceLessonsCoach Team  
+**License:** MIT  
+**Status:** Actively developed