📖 docs: add PR commenting use case to Gitea client skill

Enhance documentation with real-world examples:

- Add PR commenting workflow use case

- Include actual examples from this project

- Show automated feedback patterns

- Document CI integration examples

Makes the skill more practical and valuable

for both humans and AI agents.

.vibe/skills/gitea-client/SKILL.md

@@ -283,6 +283,102 @@ The skill handles common API errors:
 4. **Logging**: Redirect output to files for debugging
 5. **Timeouts**: Use reasonable timeouts for wait operations
 
+## Real-World Use Case: PR Commenting Workflow
+
+The Gitea client skill excels at automated PR commenting during CI/CD workflows.
+
+### Example: Automated PR Feedback
+
+```bash
+# Scenario: CI job fails, diagnose and comment on PR
+
+# 1. Find the PR associated with this branch
+PR_NUMBER=$(gitea-client list-prs arcodange DanceLessonsCoach \
+  | jq -r '.[] | select(.head.ref == "ci/trunk-based-development") | .number')
+
+# 2. Monitor CI job status
+JOB_ID=352
+JOB_STATUS=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.status')
+
+# 3. If job fails, diagnose and comment
+if [ "$JOB_STATUS" = "completed" ]; then
+    CONCLUSION=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.conclusion')
+    
+    if [ "$CONCLUSION" = "failure" ]; then
+        # Get detailed logs
+        gitea-client job-logs arcodange DanceLessonsCoach $JOB_ID job_logs.txt
+        
+        # Find error patterns
+        ERRORS=$(grep -i "error\|fail\|panic" job_logs.txt | head -5)
+        
+        # Comment on PR with findings
+        gitea-client comment-pr arcodange DanceLessonsCoach $PR_NUMBER \
+            "⚠️ CI Job Failed: $JOB_ID\n\n🔍 Diagnosis:\n$ERRORS\n\n📊 Job Details: $(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.html_url')"
+    fi
+fi
+
+# 4. Success case - comment on successful build
+if [ "$CONCLUSION" = "success" ]; then
+    gitea-client comment-pr arcodange DanceLessonsCoach $PR_NUMBER \
+        "✅ CI Job Passed: $JOB_ID\n\n🎉 All checks successful!\n\n📊 Job Details: $(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.html_url')"
+fi
+```
+
+### Real Example from This Project
+
+```bash
+# Actual commands used to comment on PR #1:
+
+# Add summary comment
+gitea-client comment-pr arcodange DanceLessonsCoach 1 \
+    "🎉 Comprehensive PR Summary\n\nThis PR includes CI improvements and new Gitea client skill."
+
+# Add detailed breakdown
+gitea-client comment-pr arcodange DanceLessonsCoach 1 \
+    "📋 This PR includes 5 key improvements:\n\n1. 🤖 Gitea Client Skill\n2. 🐛 Swagger Generation Fix\n3. ⚡ Performance Optimization\n4. 🔧 Workflow Validation\n5. 📖 Documentation Updates"
+```
+
+### Benefits of Automated PR Commenting
+
+1. **Immediate Feedback**: Developers get instant CI results
+2. **Rich Context**: Comments include direct links to jobs and logs
+3. **Consistency**: Standardized feedback format
+4. **Traceability**: All CI events documented in PR timeline
+5. **Collaboration**: Bridges gap between automation and human review
+
+### Advanced Patterns
+
+```bash
+# Comment with job comparison
+PREV_JOB=350
+CURRENT_JOB=352
+
+gitea-client comment-pr arcodange DanceLessonsCoach 1 \
+    "📊 CI Performance Improvement:\n\n- Job $PREV_JOB: ❌ Failed (missing swag)\n- Job $CURRENT_JOB: ⏳ In Progress (with fixes)\n\n🎯 Expected: Faster execution, better reliability"
+
+# Comment with log snippets
+gitea-client job-logs arcodange DanceLessonsCoach $CURRENT_JOB > current_logs.txt
+ERROR_LINE=$(grep -n "pattern docs/swagger.json" current_logs.txt | head -1)
+
+gitea-client comment-pr arcodange DanceLessonsCoach 1 \
+    "🔍 Error Analysis:\n\nPrevious error (Job $PREV_JOB):\n> pkg/server/server.go:30:12: pattern docs/swagger.json: no matching files found\n\nCurrent fix:\n> Added: go install github.com/swaggo/swag/cmd/swag@latest\n> Result: Files now generate properly ✅"
+```
+
+## Integration with CI Workflows
+
+Add PR commenting to your GitHub Actions workflow:
+
+```yaml
+- name: Comment PR on failure
+  if: failure()
+  run: |
+    PR_NUMBER=$(gitea-client list-prs owner repo | jq -r ".[] | select(.head.ref == '\${{ github.ref_name }}') | .number")
+    if [ -n "$PR_NUMBER" ]; then
+      gitea-client comment-pr owner repo $PR_NUMBER \
+        "❌ Build failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+    fi
+```
+
 ## Web UI Integration
 
 All API responses include `html_url` fields that provide direct links to Gitea's web interface. Use these to: