@flitzrrr/agent-skills 1.0.2 → 1.1.0

package/skills/execute-work-package/tpl-execution-digest.md

@@ -0,0 +1,24 @@
+---
+type: execution
+entity: digest
+skill: execute-work-package
+created: "{{date}}"
+---
+
+# Execution Digest (Reference Format)
+
+### Outcome
+- state: succeeded|failed
+
+### Edits
+- files_changed:
+  - path/to/file.ext — one-line summary
+
+### Verify
+- cmd: `...`
+- exit: 0|1|...
+- excerpt (only if failed): |
+    <few relevant lines>
+
+### Next
+- 1–3 bullets

package/skills/execute-work-package/tpl-implementer-execute-prompt.md

@@ -0,0 +1,57 @@
+---
+type: execution
+entity: subagent-execute-prompt
+skill: execute-work-package
+created: "{{date}}"
+---
+
+# Implementer Execute Prompt (Run Approved Steps)
+
+MODE: EXECUTE
+
+You are the **implementer** subagent. This is a **fresh** agent — you have no prior context.
+Read the referenced files yourself to build context, then execute.
+
+Execute the **approved** step list exactly.
+
+Constraints:
+- Do NOT re-plan. Do NOT add new steps unless required to fix an immediate error that blocks the final verify.
+- Do NOT run Git operations.
+- Run the single verify command at the end.
+- Return an **Execution Digest** (no raw diffs/logs).
+
+Execution invariants (must):
+- You MUST perform at least one concrete action: write/edit files and/or run a command.
+- You MUST run the verify command.
+- If you cannot change files or run commands, return:
+  - Outcome: BLOCKED
+  - Concrete reason
+  - What input is missing
+
+<!-- IF MCP: This prompt is used for Options B/C (Stateful/Fresh Agent). For Option A (MCP), call approve_blueprint() then execute() — this template is not needed. -->
+
+## Approved Step List
+{{approved_steps}}
+
+## Planning References (read these yourself for context)
+- Plan: {{plan_ref}}
+- Phase: {{phase_ref}}
+- Implementation Plan: {{implementation_plan_ref}}
+
+## Documentation References (read these yourself if needed)
+- Overview (optional): {{docs_overview_ref}}
+- Modules (optional): {{docs_modules_ref}}
+- Features (optional): {{docs_features_ref}}
+
+<!-- IF MCP: When using l4l MCP (Option A), the execute tool runs verification automatically. The output_format="skill" parameter returns a digest matching tpl-execution-digest.md format. -->
+
+## Verify Command
+{{verify_command}}
+
+## Output
+
+Return a Markdown **Execution Digest** using the canonical format in:
+
+- `skills/execute-work-package/tpl-execution-digest.md`
+
+Do not restate the template. Just produce the digest.

package/skills/execute-work-package/tpl-implementer-preflight-prompt.md

@@ -0,0 +1,66 @@
+---
+type: execution
+entity: subagent-preflight-prompt
+skill: execute-work-package
+created: "{{date}}"
+---
+
+# Implementer Preflight Prompt (Step List)
+
+MODE: BLUEPRINT
+
+You are the **implementer** subagent.
+
+Your job: return an **Execution Blueprint** (step list) for the work packet below.
+
+Constraints:
+- Execution-only: do NOT do planning (no risks/alternatives/architecture commentary).
+- Do NOT run Git operations.
+- Keep verification minimal: provide exactly **one** verify command.
+- Output must be compact and structured.
+
+In BLUEPRINT mode:
+- Do NOT apply patches.
+- Do NOT run commands.
+- Do NOT claim you changed code.
+
+<!-- IF MCP: This prompt is used for Options B/C (Stateful/Fresh Agent). For Option A (MCP), call precheck_new() directly — this template is not needed. -->
+
+## Work Packet
+
+### Intent
+{{intent}}
+
+### Scope (paths / modules)
+{{scope_paths}}
+
+### Planning References (read them yourself)
+- Plan: {{plan_ref}}
+- Phase: {{phase_ref}}
+- Implementation Plan: {{implementation_plan_ref}}
+- Todo (optional): {{todo_ref}}
+
+### Documentation References (if present, read them yourself)
+- Overview (optional): {{docs_overview_ref}}
+- Modules (optional): {{docs_modules_ref}}
+- Features (optional): {{docs_features_ref}}
+
+### DoD (short)
+{{dod}}
+
+### Verify Command
+{{verify_command}}
+
+If `{{verify_command}}` is empty/unknown, propose exactly **one** verify command.
+
+<!-- IF MCP: When using l4l MCP (Option A), the precheck_new tool accepts plan_ref, phase_ref, impl_plan_ref, and docs_refs parameters directly — no need to embed them in the prompt. -->
+
+## Output
+
+Return a Markdown **Execution Blueprint** using the canonical format in:
+
+- `skills/execute-work-package/tpl-execution-blueprint.md`
+
+Rules for BLUEPRINT:
+- Do NOT restate phase/impl-plan steps. Concretize using docs inventories (symbols/features/modules) plus a brief code cross-check.
+- Each step must include at least one concrete target (file path and/or symbol/component name).

package/skills/product-description-seo/CROSS-SELL.md

@@ -0,0 +1,31 @@
+# Cross-Sell Matrix — Template
+
+Define which product categories should reference each other in descriptions. Each description should mention 1-2 complementary products to encourage browsing and increase average order value.
+
+## How to Use
+
+For each category, list which other categories make natural companions — products that customers typically buy together or that solve related problems.
+
+## Template
+
+| Category     | Cross-Sell To              | Example Phrasing                        |
+| ------------ | -------------------------- | --------------------------------------- |
+| [Category A] | [Category B], [Category C] | "Pairs well with our [Category B]..."   |
+| [Category B] | [Category A], [Category D] | "For a complete setup, combine with..." |
+
+## Example (Industrial Equipment)
+
+| Category         | Cross-Sell To                | Example Phrasing                                                    |
+| ---------------- | ---------------------------- | ------------------------------------------------------------------- |
+| Power Drills     | Drill Bits, Safety Equipment | "For optimal results, pair with our professional drill bit sets..." |
+| Drill Bits       | Power Drills, Storage Cases  | "Designed for use with our industrial power drills..."              |
+| Safety Equipment | All tool categories          | "Complete your safety setup with our full PPE range..."             |
+| Hand Tools       | Tool Storage, Safety Gloves  | "Store your set securely in our professional tool cases..."         |
+| Tool Storage     | Hand Tools, Power Tools      | "Organize your complete toolkit with matching drawer inserts..."     |
+
+## Principles
+
+- Cross-sells should be genuinely useful, not random upsells
+- Mention the complementary product naturally in the application paragraph (paragraph 3)
+- Use phrasing like "combines well with", "for a complete setup", "pairs with"
+- Maximum 2 cross-sell references per description to avoid sounding salesy

package/skills/product-description-seo/KEYWORDS.md

@@ -0,0 +1,35 @@
+# Keyword Map — Template
+
+Define SEO keywords per product category. Fill in with your catalog's categories and industry-specific terms.
+
+## How to Use
+
+For each category in your catalog, define three keyword tiers:
+
+- **Primary:** Main search term — typically [product type] + [industry term]
+- **Secondary:** Related terms, synonyms, specifications people search for
+- **Longtail:** Purchase-intent phrases, specific use cases
+
+## Template
+
+### [Category Name]
+- **Primary:** [main product term] + [industry]
+- **Secondary:** [synonym 1], [synonym 2], [specification term]
+- **Longtail:** "[product] buy", "[product] for [use case]"
+
+## Example (Industrial Equipment)
+
+### Power Drills
+- **Primary:** power drill industrial, cordless drill professional
+- **Secondary:** drill driver, impact drill, hammer drill, brushless motor
+- **Longtail:** "heavy duty power drill buy", "cordless drill for construction site"
+
+### Safety Equipment
+- **Primary:** safety helmet industrial, work gloves professional
+- **Secondary:** PPE, hard hat, cut-resistant gloves, safety goggles
+- **Longtail:** "safety equipment for warehouse buy", "EN 388 gloves"
+
+### Hand Tools
+- **Primary:** hand tools professional, wrench set industrial
+- **Secondary:** socket set, torque wrench, pliers, screwdriver set
+- **Longtail:** "professional hand tools for mechanics", "torque wrench buy"

package/skills/product-description-seo/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: product-description-seo
+description: "End-to-end skill for SEO-optimized product descriptions: inventory analysis, generation, quality assurance, catalog update, and deployment. Use whenever the user wants to analyze, write, check, update, or deploy product descriptions — whether for a single product, a category, or an entire catalog. Triggers on: 'product description', 'Produktbeschreibung', 'SEO text', 'catalog text', 'update descriptions', 'which descriptions are missing', 'thin content', 'QA check', 'description quality', or when the user names a product category and wants texts for it. Also triggers on 'deploy' or 'commit' in the context of product descriptions."
+---
+
+# Product Description SEO — End-to-End Workflow
+
+A complete pipeline for turning thin or missing product descriptions into SEO-optimized, structured content. Works with any JSON-based product catalog, any language, any industry.
+
+## Quick Reference
+
+| Phase          | Task                                             | Tool                          |
+| -------------- | ------------------------------------------------ | ----------------------------- |
+| 1. Inventory   | Analyze catalog, find thin descriptions          | `scripts/analyze_catalog.py`  |
+| 2. Progress    | Check current completion status                  | `scripts/track_progress.py`   |
+| 3. Extraction  | Pull category products as batch-ready JSON       | `scripts/extract_category.py` |
+| 4. Generation  | Write descriptions using 4-paragraph structure   | See structure below           |
+| 5. QA          | Automated quality check (8 criteria)             | `scripts/check_quality.py`    |
+| 6. Update      | Write descriptions back to catalog JSON          | `scripts/update_catalog.py`   |
+| 7. Validation  | Verify JSON structure after update               | `scripts/validate_json.py`    |
+| 8. Rendering   | Adapt frontend for multi-paragraph text          | Code guidance below           |
+| 9. Deploy      | Feature branch, PR, merge                        | Git workflow                  |
+
+## Setup
+
+Before first use, create a `product-seo-config.json` in the working directory to configure the skill for a specific catalog. This is optional — all scripts work without it using sensible defaults.
+
+```json
+{
+  "catalog_path": "path/to/catalog/index.json",
+  "company": {
+    "name": "Company Name",
+    "founded": "1990",
+    "location": "City, Country",
+    "expertise": "short description of domain expertise",
+    "usp": "key selling points for the closing paragraph"
+  },
+  "fields": {
+    "description": "beschreibung",
+    "category": "kategorieName",
+    "sku": "sku",
+    "name": "name",
+    "status": "status",
+    "status_active_value": "aktiv"
+  },
+  "seo": {
+    "min_words": 200,
+    "max_words": 350,
+    "language": "de",
+    "primary_keyword_pattern": "{product_name} + {industry_term}",
+    "banned_words": ["best-in-class", "unparalleled", "revolutionary", "world-leading"]
+  },
+  "target_audience": "procurement managers, facility managers, technical buyers",
+  "tone": "professional, expert, trustworthy — like an experienced technical consultant",
+  "priorities": {
+    "1": ["Core Category A", "Core Category B"],
+    "2": ["Secondary Category C"],
+    "3": []
+  }
+}
+```
+
+## Catalog Format
+
+The catalog must be a JSON file with a `products` array. Field names are configurable via `product-seo-config.json`:
+
+```json
+{
+  "products": [
+    {
+      "sku": "401",
+      "name": "Product Name",
+      "beschreibung": "Current description text...",
+      "kategorie": "category-slug",
+      "kategorieName": "Category Display Name",
+      "preis": 29.99,
+      "einheit": "piece",
+      "status": "aktiv",
+      "slug": "product-name-401"
+    }
+  ]
+}
+```
+
+Only the description field is updated. Everything else stays untouched.
+
+---
+
+## Phase 1: Inventory
+
+Understand the current state of the catalog — which descriptions are too thin, which categories need work.
+
+```bash
+# Full catalog overview
+python scripts/analyze_catalog.py <catalog.json>
+
+# Single category (fuzzy match — "Tools" finds "Power Tools" etc.)
+python scripts/analyze_catalog.py <catalog.json> --category "Tools"
+
+# Custom word threshold
+python scripts/analyze_catalog.py <catalog.json> --min-words 150
+```
+
+Output: per-category statistics (avg word count, products below threshold), top-20 thinnest descriptions, and when filtering by category a JSON export ready for batch prompting.
+
+---
+
+## Phase 2: Progress
+
+Track the completion status of the description update campaign.
+
+```bash
+python scripts/track_progress.py <catalog.json>
+
+# With priority configuration
+python scripts/track_progress.py <catalog.json> --config product-seo-config.json
+```
+
+Output: progress bar, per-priority breakdown, next-action queue showing which categories and products to tackle next.
+
+---
+
+## Phase 3: Extraction
+
+Pull products from a category as prompt-ready JSON.
+
+```bash
+# First 8 products
+python scripts/extract_category.py <catalog.json> "Power Tools" --limit 8
+
+# Thinnest descriptions first (most urgent)
+python scripts/extract_category.py <catalog.json> "Power Tools" --thin-first
+
+# Pagination for large categories
+python scripts/extract_category.py <catalog.json> "Accessories" --offset 8 --limit 8
+```
+
+Category matching is fuzzy — partial matches work. If no match is found, available categories are listed.
+
+---
+
+## Phase 4: Generation
+
+Write descriptions following the **4-paragraph structure**. Process **5-8 products per batch** maximum to maintain quality.
+
+### 4-Paragraph Structure
+
+**Paragraph 1 — Introduction and Value (50-80 words)**
+Focus keyword (product name + industry/category term) in the **first sentence**. What is the product? What problem does it solve? Why does the target audience need it?
+
+The first 155 characters must work standalone as a meta description — complete thought, ending with a period.
+
+**Paragraph 2 — Technical Specifications (60-100 words)**
+Materials, dimensions, weight, capacity, special features. **Every** technical fact from the existing description must be preserved 1:1. Never omit data, never fabricate specs. If source data is vague, keep it vague.
+
+**Paragraph 3 — Application and Practice (40-60 words)**
+Typical use cases, ideal conditions, when to deploy. Mention 1-2 complementary products from the same catalog (cross-sell). Use CROSS-SELL.md as reference if available.
+
+**Paragraph 4 — Quality and Service (30-50 words)**
+Company expertise, personal consultation, delivery/support promise. Soft CTA: "Contact us for personalized advice." No aggressive sales pressure. Adapt to the company info from config.
+
+### Variant Rule
+
+Products with color, size, or material variants **must get unique texts**. The variant attribute must be mentioned and contextualized — never copy the same text across variants. Example: a red variant could mention visibility advantages; a compact variant could highlight space efficiency.
+
+### Tone
+
+- Professional, expert, trustworthy — like an experienced technical consultant
+- Formal address (German: "Sie"; English: naturally formal; adapt to language)
+- **Banned words:** best-in-class, unparalleled, revolutionary, sensational, unmatched, premium (without proof), world-leading, perfect, unique (without proof)
+- Superlatives only with concrete evidence (e.g., "proven for over 10 years")
+- Adapt to `target_audience` and `tone` from config
+
+### SEO Keywords
+
+- **Primary:** [Product Name] + industry/category term
+- **Secondary:** [Category Name], industry-standard terms
+- **Longtail:** "[Product Name] buy/purchase", "[Product Name] for [use case]"
+- Maximum 3x focus keyword per text — no keyword stuffing
+- Use KEYWORDS.md for category-specific targets if available
+
+### Output Format
+
+Save descriptions as a JSON array:
+
+```json
+[
+  {
+    "sku": "401",
+    "name": "Product Name",
+    "beschreibung": "Paragraph 1...\n\nParagraph 2...\n\nParagraph 3...\n\nParagraph 4..."
+  }
+]
+```
+
+Save as `updates-<category-slug>.json`.
+
+---
+
+## Phase 5: Quality Assurance
+
+Automated check against all requirements:
+
+```bash
+# Standard check
+python scripts/check_quality.py updates-tools.json
+
+# Strict mode (warnings become failures)
+python scripts/check_quality.py updates-tools.json --strict
+
+# Custom word range
+python scripts/check_quality.py updates-tools.json --min-words 150 --max-words 400
+```
+
+Checks per description:
+
+1. Word count within configured range (default 200-350)
+2. 4-paragraph structure (exactly 3x `\n\n` separator)
+3. Focus keyword (product name) in first sentence
+4. No banned superlatives
+5. Cross-sell reference present (company name or "combination with")
+6. Formal address (no informal pronouns in German texts)
+7. Meta-description-ready first 155 characters
+8. Plain text only (no HTML, no Markdown, no bullet points)
+
+Fix any failures, re-check. Proceed to Phase 6 only when all checks pass.
+
+---
+
+## Phase 6: Update
+
+Write QA-approved descriptions back to the catalog:
+
+```bash
+python scripts/update_catalog.py <catalog.json> updates-tools.json
+```
+
+The script:
+1. Creates an automatic backup (`catalog.json.backup_YYYYMMDD_HHMMSS`)
+2. Matches updates by SKU
+3. Reports word count before -> after per product
+4. Flags SKUs not found in catalog
+
+---
+
+## Phase 7: Validation
+
+Verify JSON integrity after the update:
+
+```bash
+python scripts/validate_json.py <catalog.json>
+```
+
+Checks: valid JSON parse, required fields on every product, no duplicate SKUs, no HTML tags in descriptions, valid slug format.
+
+---
+
+## Phase 8: Rendering
+
+If the frontend renders descriptions as a single element, adapt it for multi-paragraph text. Paragraphs are separated by `\n\n` in the JSON.
+
+**Svelte:**
+```svelte
+{#each description.split('\n\n') as paragraph}
+  <p class="description">{paragraph}</p>
+{/each}
+```
+
+**React:**
+```jsx
+{description.split('\n\n').map((p, i) => (
+  <p key={i} className="description">{p}</p>
+))}
+```
+
+**Vue:**
+```vue
+<p v-for="(p, i) in description.split('\n\n')" :key="i" class="description">{{ p }}</p>
+```
+
+**Meta description** — use the first paragraph, truncated:
+```javascript
+const metaDescription = description.split('\n\n')[0].slice(0, 155);
+```
+
+This change only needs to happen once and applies to all products.
+
+---
+
+## Phase 9: Deploy
+
+Standard git workflow — never push directly to main.
+
+```bash
+git checkout -b product-descriptions/<category-slug>
+git add path/to/catalog.json
+git commit -m "content: Update product descriptions for <Category>"
+gh pr create --title "Content: Product descriptions <Category>"
+```
+
+One PR per category or batch to keep reviews manageable.
+
+---
+
+## Example: Full Run
+
+```bash
+# 1. Where do we stand?
+python scripts/track_progress.py catalog.json
+
+# 2. Next category
+python scripts/extract_category.py catalog.json "Tools" --thin-first
+
+# 3. Generate descriptions (4-paragraph structure)
+#    -> save as updates-tools.json
+
+# 4. Quality check
+python scripts/check_quality.py updates-tools.json
+
+# 5. Write to catalog
+python scripts/update_catalog.py catalog.json updates-tools.json
+
+# 6. Validate JSON
+python scripts/validate_json.py catalog.json
+
+# 7. Commit and PR
+git checkout -b product-descriptions/tools
+git add catalog.json
+git commit -m "content: Update product descriptions Tools (8 products)"
+gh pr create --title "Content: Product descriptions Tools"
+```
+
+---
+
+## Optional Reference Files
+
+Not required, but improve output quality when present alongside the skill:
+
+| File                    | Purpose                                                          |
+| ----------------------- | ---------------------------------------------------------------- |
+| KEYWORDS.md             | Category-specific keyword targets (primary, secondary, longtail) |
+| CROSS-SELL.md           | Cross-sell matrix defining which categories reference each other |
+| product-seo-config.json | Company context, field mappings, priorities                      |
+
+Templates for KEYWORDS.md and CROSS-SELL.md are included — fill them in for your catalog.
+
+## Scripts
+
+| Script                        | Purpose                                               |
+| ----------------------------- | ----------------------------------------------------- |
+| `scripts/analyze_catalog.py`  | Catalog analysis (thinnest descriptions, word counts) |
+| `scripts/track_progress.py`   | Progress tracking with priority support               |
+| `scripts/extract_category.py` | Category extraction for batch prompting (fuzzy match) |
+| `scripts/check_quality.py`    | Automated QA with 8 configurable checks               |
+| `scripts/update_catalog.py`   | Write descriptions to catalog with automatic backup   |
+| `scripts/validate_json.py`    | JSON structure validation                             |
+
+## Dependencies
+
+- **Python 3.10+** for all scripts
+- **gh CLI** (optional) for PR creation in Phase 9