@flitzrrr/agent-skills 1.0.2 → 1.1.0

package/skills/product-description-seo/scripts/validate_json.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Validate catalog JSON structure after description updates.
+
+Usage:
+    python validate_json.py <catalog.json>
+
+Checks: valid JSON, required fields, no duplicate SKUs,
+no HTML in descriptions, valid slug format.
+"""
+
+import json
+import sys
+import re
+from collections import Counter
+
+REQUIRED_FIELDS = ["sku", "name", "slug"]
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python validate_json.py <catalog.json>")
+        sys.exit(1)
+
+    path = sys.argv[1]
+    errors = []
+    warnings = []
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"[-] FATAL: Invalid JSON: {e}")
+        sys.exit(1)
+
+    products = data.get("products", [])
+    print(f"Validating {len(products)} products in {path}...")
+
+    # Required fields
+    for i, p in enumerate(products):
+        for field in REQUIRED_FIELDS:
+            if field not in p:
+                errors.append(f"Product #{i} (SKU {p.get('sku', '?')}): missing field '{field}'")
+
+    # Duplicate SKUs
+    skus = [p.get("sku", "") for p in products]
+    dupes = [sku for sku, count in Counter(skus).items() if count > 1]
+    if dupes:
+        errors.append(f"Duplicate SKUs: {', '.join(dupes)}")
+
+    # Empty descriptions
+    desc_field = "beschreibung" if any("beschreibung" in p for p in products[:5]) else "description"
+    for p in products:
+        if not p.get(desc_field, "").strip():
+            warnings.append(f"SKU {p.get('sku', '?')}: empty description")
+
+    # HTML in descriptions
+    for p in products:
+        desc = p.get(desc_field, "")
+        if re.search(r'<[^>]+>', desc):
+            errors.append(f"SKU {p.get('sku', '?')}: HTML tags found in description")
+
+    # Slug format
+    for p in products:
+        slug = p.get("slug", "")
+        if slug and not re.match(r'^[a-z0-9\-_\.]+$', slug):
+            warnings.append(f"SKU {p.get('sku', '?')}: slug '{slug}' contains invalid characters")
+
+    # Report
+    print(f"\n{'=' * 50}")
+    if errors:
+        print(f"[-] {len(errors)} errors found:")
+        for e in errors:
+            print(f"  [-] {e}")
+    if warnings:
+        print(f"[!] {len(warnings)} warnings:")
+        for w in warnings:
+            print(f"  [!] {w}")
+    if not errors and not warnings:
+        print("[+] All validations passed!")
+    elif not errors:
+        print(f"\n[+] No critical errors. {len(warnings)} warnings.")
+
+    sys.exit(1 if errors else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/systematic-debugging/skill.md

@@ -0,0 +1,87 @@
+---
+name: systematic-debugging
+description: Investigate bugs, test failures, and unexpected behavior through root-cause analysis before proposing fixes. Use when encountering any technical issue.
+license: MIT
+compatibility:
+  opencode: ">=0.1"
+metadata:
+  category: debugging
+  phase: investigation
+---
+
+# Skill: Systematic Debugging
+
+This skill enforces root-cause investigation before any fix attempt. Random fixes waste time and create new bugs.
+
+---
+
+## When to Use
+
+Use for any technical issue:
+
+- Test failures
+- Bugs in production or development
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+Do **not** skip this skill when:
+
+- The issue seems simple (simple bugs have root causes too)
+- You are under time pressure (systematic debugging is faster than thrashing)
+- A fix seems obvious (obvious fixes often mask the real problem)
+
+---
+
+## Execution Model
+
+- **Primary agent** runs this skill directly.
+- **Rationale**: Debugging requires iterative investigation in the same context. Delegating to a subagent loses the accumulated understanding.
+- **Exception**: For multi-component issues spanning independent subsystems, delegate per-subsystem investigation to separate agents via the `dispatch-parallel-agents` skill.
+
+---
+
+## Workflow
+
+### Phase 1: Root Cause Investigation
+
+**No fixes are allowed until this phase is complete.**
+
+1. **Read error messages carefully** -- stack traces, line numbers, error codes. Do not skip past them.
+2. **Reproduce consistently** -- determine the exact steps. If not reproducible, gather more data instead of guessing.
+3. **Check recent changes** -- `git diff`, recent commits, new dependencies, config changes, environmental differences.
+4. **Gather evidence at component boundaries** -- for multi-layer systems (CI -> build -> deploy, API -> service -> database), add diagnostic logging at each boundary to identify where the failure occurs.
+5. **Trace data flow** -- follow the bad value backward through the call stack to its origin. Fix at the source, not at the symptom.
+
+### Phase 2: Pattern Analysis
+
+1. **Find working examples** -- locate similar working code in the same codebase.
+2. **Compare against references** -- if implementing a pattern, read the reference implementation completely. Do not skim.
+3. **Identify differences** -- list every difference between working and broken code, however small.
+4. **Understand dependencies** -- what components, settings, config, and environment does this code need?
+
+### Phase 3: Hypothesis and Testing
+
+1. **Form a single hypothesis** -- state clearly: "I think X is the root cause because Y."
+2. **Test minimally** -- make the smallest possible change to test the hypothesis. One variable at a time.
+3. **Verify before continuing** -- if the hypothesis is wrong, form a new one. Do not stack fixes.
+4. **Acknowledge unknowns** -- if you do not understand something, say so. Do not pretend.
+
+### Phase 4: Implementation
+
+1. **Fix the root cause, not the symptom.**
+2. **One change at a time** -- no "while I'm here" improvements, no bundled refactoring.
+3. **Verify the fix** -- run the relevant tests, confirm the issue is resolved, confirm no regressions.
+4. **If 3+ fixes have failed** -- stop. The issue is likely architectural, not a bug. Discuss with the user before attempting more fixes.
+
+---
+
+## Rules
+
+1. **No fixes without investigation**: Phase 1 must be complete before proposing any fix.
+2. **One hypothesis at a time**: Do not apply multiple changes simultaneously.
+3. **Evidence over intuition**: Every fix must be justified by evidence from the investigation, not by "it might work."
+4. **Escalate after 3 failed attempts**: Three failed fixes indicate an architectural problem. Stop fixing and discuss with the user.
+5. **Do not increase timeouts as a fix**: Find the real timing issue instead.
+6. **Read error messages completely**: Stack traces contain the answer more often than not.

package/skills/tob-gh-cli/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: gh-cli
+description: Intercepts GitHub URL fetches and redirects to the authenticated `gh` CLI. Use when Claude tries to access GitHub via WebFetch or curl/wget, when you see 404 errors on private repos, when hitting GitHub API rate limits, or when GitHub API responses are incomplete. Provides hooks that automatically suggest the correct `gh` CLI command for any GitHub URL access pattern.
+---
+
+# GitHub CLI Integration
+
+A plugin that intercepts GitHub URL fetches and redirects Claude to use the authenticated `gh` CLI instead.
+
+## Problem
+
+Claude Code's `WebFetch` tool and Bash `curl`/`wget` commands don't use the user's GitHub authentication. This means:
+
+- **Private repos**: Fetches fail with 404 errors
+- **Rate limits**: Unauthenticated requests are limited to 60/hour (vs 5,000/hour authenticated)
+- **Missing data**: Some API responses are incomplete without authentication
+
+## Solution
+
+This plugin provides PreToolUse hooks that intercept GitHub URL access via `WebFetch` or `curl`/`wget`, and suggest the correct `gh` CLI command.
+
+### What Gets Intercepted
+
+| Tool | Pattern | Suggestion |
+|------|---------|------------|
+| `WebFetch` | `github.com/{owner}/{repo}` | `gh repo view owner/repo` |
+| `WebFetch` | `github.com/.../blob/...` | `gh repo clone` + Read |
+| `WebFetch` | `github.com/.../tree/...` | `gh repo clone` + Read/Glob/Grep |
+| `WebFetch` | `api.github.com/repos/.../pulls` | `gh pr list` / `gh pr view` |
+| `WebFetch` | `api.github.com/repos/.../issues` | `gh issue list` / `gh issue view` |
+| `WebFetch` | `api.github.com/...` | `gh api <endpoint>` |
+| `WebFetch` | `raw.githubusercontent.com/...` | `gh repo clone` + Read |
+| `Bash` | `curl https://api.github.com/...` | `gh api <endpoint>` |
+| `Bash` | `curl https://raw.githubusercontent.com/...` | `gh repo clone` + Read |
+| `Bash` | `wget https://github.com/...` | `gh release download` |
+
+### What Passes Through
+
+- Non-GitHub URLs
+- GitHub Pages sites (`*.github.io`)
+- Commands already using `gh` (except anti-patterns)
+- Git commands (`git clone`, `git push`, etc.)
+- Search commands that mention GitHub URLs (`grep`, `rg`, etc.)
+
+## Prerequisites
+
+- [GitHub CLI (`gh`)](https://cli.github.com/) must be installed and authenticated (`gh auth login`)
+- If `gh` is not installed, the hooks pass through without disruption
+
+## Usage
+
+This skill operates automatically via hooks. No manual invocation required. When you attempt to access GitHub URLs, the hooks will intercept and suggest the authenticated alternative.
+
+### Common gh CLI Commands
+
+```bash
+# View repo info
+gh repo view owner/repo
+
+# List PRs
+gh pr list --repo owner/repo
+
+# View a specific PR
+gh pr view 123 --repo owner/repo
+
+# API access
+gh api repos/owner/repo/pulls
+
+# Clone a repo
+gh repo clone owner/repo
+```