@olegkoval/agent-skills 1.16.0 → 1.18.0

package/packages/marketing/search-console-indexing-audit/adapters/grok/skills/search-console-indexing-audit/scripts/summarize_gsc_coverage.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Summarize Google Search Console Coverage CSV exports."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+from pathlib import Path
+from typing import Any
+
+
+STANDARD_FILES = {
+    "chart": "Chart.csv",
+    "metadata": "Metadata.csv",
+    "critical": "Critical issues.csv",
+    "non_critical": "Non-critical issues.csv",
+}
+
+
+def read_rows(path: Path) -> list[dict[str, str]]:
+    if not path.exists():
+        return []
+    with path.open(newline="", encoding="utf-8-sig") as handle:
+        return [
+            {key: (value or "").strip() for key, value in row.items()}
+            for row in csv.DictReader(handle)
+        ]
+
+
+def int_or_none(value: str) -> int | None:
+    if value == "":
+        return None
+    try:
+        return int(value.replace(",", ""))
+    except ValueError:
+        return None
+
+
+def chart_summary(rows: list[dict[str, str]]) -> dict[str, Any]:
+    points = []
+    for row in rows:
+        points.append(
+            {
+                "date": row.get("Date", ""),
+                "not_indexed": int_or_none(row.get("Not indexed", "")),
+                "indexed": int_or_none(row.get("Indexed", "")),
+                "impressions": int_or_none(row.get("Impressions", "")),
+            }
+        )
+
+    indexed_points = [
+        point for point in points if point["indexed"] is not None or point["not_indexed"] is not None
+    ]
+    first = indexed_points[0] if indexed_points else None
+    last = indexed_points[-1] if indexed_points else None
+
+    return {
+        "date_range": [points[0]["date"], points[-1]["date"]] if points else None,
+        "first_indexing_point": first,
+        "latest_indexing_point": last,
+        "indexed_delta": None if not first or not last else (last["indexed"] or 0) - (first["indexed"] or 0),
+        "not_indexed_delta": None
+        if not first or not last
+        else (last["not_indexed"] or 0) - (first["not_indexed"] or 0),
+        "impressions_total": sum(point["impressions"] or 0 for point in points),
+    }
+
+
+def issue_summary(rows: list[dict[str, str]]) -> list[dict[str, Any]]:
+    issues = []
+    for row in rows:
+        reason = row.get("Reason", "")
+        if not reason:
+            continue
+        issues.append(
+            {
+                "reason": reason,
+                "source": row.get("Source", ""),
+                "validation": row.get("Validation", ""),
+                "pages": int_or_none(row.get("Pages", "")) or 0,
+            }
+        )
+    return sorted(issues, key=lambda issue: issue["pages"], reverse=True)
+
+
+def load_export(export_dir: Path) -> dict[str, Any]:
+    files = {key: export_dir / filename for key, filename in STANDARD_FILES.items()}
+    metadata_rows = read_rows(files["metadata"])
+    return {
+        "export_dir": str(export_dir),
+        "metadata": {row.get("Property", ""): row.get("Value", "") for row in metadata_rows},
+        "chart": chart_summary(read_rows(files["chart"])),
+        "critical_issues": issue_summary(read_rows(files["critical"])),
+        "non_critical_issues": issue_summary(read_rows(files["non_critical"])),
+        "missing_files": [filename for filename in STANDARD_FILES.values() if not (export_dir / filename).exists()],
+    }
+
+
+def print_markdown(summary: dict[str, Any]) -> None:
+    chart = summary["chart"]
+    latest = chart["latest_indexing_point"] or {}
+    print("# Search Console Coverage Summary")
+    print()
+    print(f"- Export: `{summary['export_dir']}`")
+    if chart["date_range"]:
+        print(f"- Date range: {chart['date_range'][0]} to {chart['date_range'][1]}")
+    print(f"- Latest indexed: {latest.get('indexed', 'n/a')}")
+    print(f"- Latest not indexed: {latest.get('not_indexed', 'n/a')}")
+    print(f"- Total impressions in chart: {chart['impressions_total']}")
+    if summary["metadata"]:
+        print(f"- Metadata: {summary['metadata']}")
+    if summary["missing_files"]:
+        print(f"- Missing standard files: {', '.join(summary['missing_files'])}")
+
+    for label, issues in (
+        ("Critical Issues", summary["critical_issues"]),
+        ("Non-Critical Issues", summary["non_critical_issues"]),
+    ):
+        print()
+        print(f"## {label}")
+        if not issues:
+            print("- None reported")
+            continue
+        for issue in issues:
+            print(
+                f"- {issue['reason']}: {issue['pages']} pages"
+                f" ({issue['source']}, validation: {issue['validation']})"
+            )
+
+    print()
+    print("## Notes")
+    print("- Standard Coverage exports are aggregate reports; they may not include affected URL examples.")
+    print("- Redirect and canonical buckets should be checked against sitemap URLs and live canonical tags.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("export_dir", type=Path)
+    parser.add_argument("--json", action="store_true", help="Print machine-readable JSON")
+    args = parser.parse_args()
+
+    summary = load_export(args.export_dir)
+    if args.json:
+        print(json.dumps(summary, indent=2, sort_keys=True))
+    else:
+        print_markdown(summary)
+
+
+if __name__ == "__main__":
+    main()

package/packages/marketing/viral-launch/adapters/grok/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:viral-launch",
+  "version": "0.1.0",
+  "description": "Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops.",
+  "skills": "skills/"
+}

package/packages/marketing/viral-launch/adapters/grok/skills/viral-launch/SKILL.md

@@ -0,0 +1,105 @@
+---
+
+name: viral-launch
+description: Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops without pretending virality is guaranteed.
+license: MIT
+allowed-tools: Bash, Read, Write, WebSearch, WebFetch
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Useful for product repos, open-source packages, SaaS launches, waitlists, and creator tools.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - marketing
+    - launch
+    - growth
+    - virality
+    - positioning
+    - github
+
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# viral-launch
+
+Use this skill when a user wants to launch a project, make a repo marketable, improve discoverability, or build shareable launch assets.
+
+This skill is opinionated: virality is not a promise. The goal is to make the project easy to understand, easy to share, and easy to act on.
+
+## Trigger phrases
+
+- make this repo launch-ready
+- set this up to go viral
+- prepare a product launch
+- create marketing assets for this project
+- improve the README for launch
+- prepare Product Hunt / Hacker News / X / LinkedIn launch copy
+- set up an open-source repo for growth
+
+## Workflow
+
+1. Inspect the project first:
+  - product purpose
+  - target user
+  - core use case
+  - current README and docs
+  - install or demo path
+  - screenshots, videos, or visual proof
+  - analytics or waitlist capture if present
+2. Define the launch angle in one sentence:
+  - who it is for
+  - what painful job it solves
+  - why now
+  - what makes it different
+3. Make the repo launch-ready:
+  - clear README headline and first paragraph
+  - demo or quickstart within the first screen
+  - installation steps that work from a clean checkout
+  - screenshots, GIF, or demo link where possible
+  - feature list based on outcomes, not implementation trivia
+  - examples for the highest-intent use cases
+  - badges only when they add trust
+  - license, contributing notes, and issue templates when useful
+4. Create launch assets:
+  - short tagline
+  - 1-paragraph announcement
+  - 5 social post variants
+  - Product Hunt tagline and description when relevant
+  - Hacker News title candidates when relevant
+  - launch email or DM when relevant
+  - creator/influencer outreach list criteria, not spam copy
+5. Design share loops:
+  - a reason users would show the output to someone else
+  - a public artifact worth linking
+  - a before/after demo
+  - a template, benchmark, checklist, or gallery that can travel
+  - referral or waitlist loop only if it fits the product
+6. Define proof and metrics:
+  - activation event
+  - share event
+  - conversion event
+  - retention proxy
+  - launch-day dashboard or simple tracking checklist
+7. Keep claims grounded:
+  - do not invent traction, logos, benchmarks, testimonials, or user counts
+  - mark assumptions explicitly
+  - prefer specific proof over hype
+  - avoid dark patterns and spam
+
+## Output format
+
+When planning, produce:
+
+- Launch angle
+- Repo changes
+- Launch assets
+- Share loops
+- Metrics
+- Risks and assumptions
+- Next actions
+
+When editing a repository, make the smallest useful set of changes first, then validate by reading the README from a new user's perspective.
+
+## References
+
+- `references/launch-checklist.md`
+- `references/external-skills.md`

package/packages/music/fill-music-player/adapters/grok/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:fill-music-player",
+  "version": "0.1.0",
+  "description": "Fill a portable music player with a curated random selection from a source music library while balancing formats, artists, albums, and capacity.",
+  "skills": "skills/"
+}

package/packages/music/fill-music-player/adapters/grok/skills/fill-music-player/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: fill-music-player
+description: Use when a user wants to fill a portable music player (Walkman, iPod, USB drive) with a curated random selection from a music library on a NAS or local directory. Handles format filtering, artist/album diversity balancing, and size targeting.
+license: MIT
+allowed-tools: Bash
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires shell access and the fill-music-player CLI or underlying script in the target environment.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - music
+    - media
+    - curation
+    - copy
+    - cli
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# fill-music-player
+
+Curates a DJ-balanced selection of tracks from a source music library and copies them to a portable player, respecting device capacity and supported formats.
+
+## Quick Reference
+
+```bash
+# Dry run first (always recommend this)
+fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC --dry-run
+
+# Copy for real
+fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC
+
+# Or run the script directly with uv
+uv run fill_music_player.py --source ~/Music --dest /Volumes/USB --dry-run
+```
+
+Run `fill-music-player --help` for all options.
+
+## Key Parameters
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--source` / `-s` | required | Source music root (NAS mount, ~/Music, etc.) |
+| `--dest` / `-d` | required | Player destination directory |
+| `--target-gb` | 95% of free space | How many GB to fill |
+| `--formats` | mp3,m4a,wma,aac | Allowed extensions |
+| `--max-per-artist` | 4 | Artist diversity cap |
+| `--max-per-album` | 3 | Album diversity cap |
+| `--skip-dirs` | (none) | Top-level dirs to skip |
+| `--dry-run` | false | Preview without copying |
+
+## Workflow
+
+1. Always do `--dry-run` first
+2. Review the per-genre breakdown
+3. Adjust `--skip-dirs`, `--max-file-mb`, or `--max-per-artist` if needed
+4. Run without `--dry-run` to copy
+
+## Device Formats
+
+| Device | Recommended `--formats` |
+|--------|------------------------|
+| Sony Walkman NWZ series | `mp3,m4a,wma` |
+| iPod (classic/nano) | `mp3,m4a,aac` |
+| Generic USB player | `mp3` |
+| Any modern player | `mp3,m4a,wma,aac,ogg,flac` |
+
+## Edge Cases and Troubleshooting
+
+| Situation | What happens | Fix |
+|-----------|-------------|-----|
+| NAS disconnects mid-copy | Copy fails for that file, logged as error, continues with next track | Re-run; already-copied files are skipped (`if not dst.exists()`) |
+| Source has only FLAC/lossless | 0 files selected (FLAC not in default formats) | Use `--formats flac` or `--formats mp3,flac` |
+| FAT32 filename too long or illegal chars | Filenames are sanitized: `<>:"/\|?*` replaced with `_`, truncated to 80 chars | Automatic — no action needed |
+| Mixed/broken ID3 tags | Falls back to folder name parsing (`Genre/Artist - Album/track.mp3`) | Works transparently; folder structure is the reliable fallback |
+| Very large files (DJ mixes, radio shows) | Skipped by default (>20 MB) | Adjust with `--max-file-mb 50` to include mixes |
+| Tiny files (jingles, corrupt) | Skipped by default (<300 KB) | Adjust with `--min-file-kb 100` to be more permissive |
+| One artist dominates the library | Capped at 4 tracks per artist, 3 per album | Lower with `--max-per-artist 2` for more variety |
+| Empty genre directories | Silently skipped, no error | Normal behavior |
+| Destination already has files | Existing files are not overwritten or deleted; new tracks added alongside | Clear destination first if you want a fresh set |
+| SMB/NFS mount is slow | Scanning with mutagen tag reading can take 5-10 min for large libraries | Expected; the dry-run output appears once scanning completes |
+
+## Real-World Example
+
+Filling a **Sony Walkman NWZ-B183F (4 GB)** from a **Synology DS918+ NAS** with ~9,000 tracks across blues, funk, hip-hop, soul, IDM, dubstep, dub, indie, and post-rock:
+
+```bash
+# Step 1: Preview
+fill-music-player \
+  --source /Volumes/music \
+  --dest /Volumes/WALKMAN/MUSIC \
+  --skip-dirs "jingles,!recordings,!restored,dubrecords" \
+  --formats mp3,m4a,wma \
+  --dry-run
+
+# Output:
+#   Found 8914 candidate tracks across 14 genres
+#   Funk     →  86 tracks  (440.8 MB)
+#   blues    →  38 tracks  (316.7 MB)
+#   hiphop   →  33 tracks  (234.7 MB)
+#   ...
+#   Selected 348 tracks  (2473.0 MB)
+
+# Step 2: Copy
+fill-music-player \
+  --source /Volumes/music \
+  --dest /Volumes/WALKMAN/MUSIC \
+  --skip-dirs "jingles,!recordings,!restored,dubrecords" \
+  --formats mp3,m4a,wma
+```
+
+Result: 348 tracks, 2.4 GB, balanced across 14 genres with max 4 tracks per artist. Artists included Fela Kuti, ZZ Top, Mobb Deep, Gregory Porter, Tinariwen, Chick Corea, Hudson Mohawke, and Funkadelic. Total copy time over SMB: ~12 minutes.

package/packages/photography/gallery/adapters/grok/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:gallery",
+  "version": "0.1.0",
+  "description": "Create photo galleries with AI-assisted layout curation and sequencing.",
+  "skills": "skills/"
+}

package/packages/photography/gallery/adapters/grok/skills/gallery/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: gallery
+description: Create photo galleries with AI-assisted layout curation. Orchestrates atomic scripts and sub-agents. Use when user wants to create a gallery from photos, mentions "/gallery", or asks about photo layout and sequencing.
+license: MIT
+allowed-tools: Bash, Read, Write, WebSearch, WebFetch
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a project that contains the gallery scripts and expected data layout.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - photos
+    - gallery
+    - layout
+    - curation
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Gallery Workflow
+
+Composed skill that creates photo galleries by orchestrating atomic scripts and sub-agents.
+
+## Philosophy
+
+This skill applies principles from masters of photo sequencing and curation:
+
+- **Keith Smith** — Group/Series/Sequence taxonomy; the gallery as a unified experience
+- **Jörg Colberg** — Ruthless editing; visual rhythm; pacing
+- **John Szarkowski** — The Five Characteristics for image assessment
+
+> "The individual pages have to give up their independence in order to form a union." — Keith Smith
+
+For detailed principles, see `docs/photo-layout-principles.md`.
+
+## Usage
+
+`/gallery {folder} "{title}" {slug}`
+
+Example: `/gallery cabo-2025 "CABO 2025" cabo`
+
+**Important:** All paths are relative to the current project directory. The `{folder}` argument is a path within the project (e.g., `./photos/cabo-2025` or just `cabo-2025`). Do NOT search the filesystem for folders — assume the user's folder exists in the current working directory.
+
+## Gallery Modes
+
+Before starting, identify the gallery's organizational mode:
+
+| Mode | Definition | Implication |
+|------|------------|-------------|
+| **Series** | Chronological journey (default) | Respect timestamp order; adjust only within temporal clusters |
+| **Group** | Thematic collection | Order is flexible; optimize for visual rhythm |
+| **Sequence** | Strict order with meaning | Order is sacred; only adjust layout, not arrangement |
+
+Most travel/event galleries are **Series**.
+
+## Architecture
+
+```
+Atomic Scripts (reusable):
+├── init-gallery-manifest.ts    Create manifest from EXIF
+├── merge-gallery-batches.ts    Combine batch files
+├── validate-gallery-manifest.ts Fix common errors
+└── generate-gallery-files.ts   Generate .astro pages
+
+Sub-Agent Skill:
+└── review-image-batch          AI reviews images → batch-NN.json
+```
+
+## Workflow
+
+### Phase 1: Initialize
+
+```bash
+bun scripts/init-gallery-manifest.ts {folder} "{title}" {slug}
+```
+
+Creates:
+- `src/data/gallery-manifests/{folder}.json` (images array, empty blocks)
+- `/tmp/gallery-batches/{folder}/` (clean directory for batch files)
+
+### Phase 2: Batch Review
+
+Spawn sub-agents to review images. **Each writes to its own file** (parallel-safe).
+
+```
+For batchIndex in 0..ceil(imageCount/8):
+  Task(
+    subagent_type: "general-purpose",
+    description: "Review gallery batch {batchIndex}",
+    prompt: <see below>
+  )
+```
+
+**Sub-agent prompt template:**
+
+```
+Review batch {batchIndex} for {folder} gallery.
+
+Read:
+- Manifest: src/data/gallery-manifests/{folder}.json
+- Layout guide: {plugin_base_dir}/skills/review-image-batch/references/layout-guide.md
+  (The plugin base directory is provided in the skill invocation header)
+
+Images to review: indices {startImage} to {endImage}
+(Calculate: startImage = batchIndex * 8, endImage = min(startImage + 7, totalImages - 1))
+
+Workflow:
+1. Read manifest to get image filenames
+2. Read layout guide for rules
+3. View each image file with Read tool
+4. Create layout blocks using your visual judgment
+5. Write JSON to: /tmp/gallery-batches/{folder}/batch-{NN}.json
+   where NN = batchIndex padded to 2 digits (00, 01, 02...)
+6. Return TEXT SUMMARY ONLY
+
+Output file format:
+{
+  "batchIndex": {batchIndex},
+  "startImage": {startImage},
+  "endImage": {endImage},
+  "blocks": [
+    { "layout": "WideImage", "images": ["DSCF1234.jpeg"], "props": {}, "notes": "..." }
+  ]
+}
+
+LAYOUT PHILOSOPHY:
+Apply visual judgment, not mechanical rules. A gallery needs rhythm and variety.
+
+Single-image (WideImage, OffsetImage, InsetImage, FullBleed):
+- Strong standalones, portraits, quiet moments
+
+Multi-image (TwoUp, ThreeUp):
+- Use when juxtaposition creates meaning beyond either image alone
+- Apply Lyons's test: Temporal? Spatial? Formal echo? Emotional pairing? Transformation?
+- A good TwoUp is BETTER than two mediocre WideImages
+- A true sequence (entering→through→emerging) deserves ThreeUp
+
+Spacer: Add breathing room after powerful images
+Chapter: Insert at location/theme changes
+```
+
+**Parallel execution:** Sub-agents can run in parallel since each writes to its own file.
+
+### Phase 3: Merge & Validate
+
+After all batches complete:
+
+```bash
+bun scripts/merge-gallery-batches.ts {folder}
+bun scripts/validate-gallery-manifest.ts src/data/gallery-manifests/{folder}.json
+```
+
+This combines all batch files and validates the result.
+
+### Phase 4: Global Arc Review (NEW)
+
+Before generating, review the merged manifest for overall coherence:
+
+1. **Count hero moments** — If >4 FullBleeds, demote some to WideImage
+2. **Check multi-image limits** — Max 2-3 TwoUp, 1-2 ThreeUp across entire gallery
+3. **Verify rhythm** — No consecutive high-weight blocks
+4. **Identify the climax** — One clear emotional peak, not many
+5. **Working backwards** — Does the final image provide satisfying closure?
+
+### Phase 5: Generate
+
+```bash
+bun scripts/generate-gallery-files.ts {folder}
+```
+
+Creates:
+- `src/data/{folder}.ts` (data file with chapters)
+- `src/pages/photographing/{slug}/index.astro`
+- Additional `.astro` files for each chapter (if multi-chapter)
+
+## Resume Protocol
+
+If interrupted, check `/tmp/gallery-batches/{folder}/` for existing batch files:
+
+```bash
+ls /tmp/gallery-batches/{folder}/
+```
+
+Only run missing batches, then merge.
+
+## Layout Philosophy
+
+A gallery needs **rhythm and variety** — loud moments, quiet moments, pairings that create meaning.
+
+| Layout | Purpose |
+|--------|---------|
+| WideImage | Strong standalone landscapes |
+| OffsetImage | Portraits, quiet moments, breathing room |
+| FullBleed | Hero shots, climactic moments |
+| InsetImage | Intimate details, visual whispers |
+| Spacer | Pacing, section breaks |
+| TwoUp | Images that speak to each other |
+| ThreeUp | True sequences (entering→through→emerging) |
+| SplitLayout | Asymmetric pairs, one frames the other |
+| Chapter | Location/theme breaks |
+
+### Lyons's Juxtaposition Test
+
+Pair images when juxtaposition creates meaning beyond either image alone:
+
+1. **Temporal** — Same moment, different angles
+2. **Spatial** — Same scene, complementary views
+3. **Formal echo** — Compositional rhyme (lines, shapes, colors)
+4. **Emotional** — Contrast or reinforcement
+5. **Transformation** — Together they say something neither says alone
+
+A strong TwoUp is better than two mediocre WideImages.
+
+## Output
+
+When complete:
+- Gallery URL: `/photographing/{slug}/`
+- Files:
+  - `src/data/gallery-manifests/{folder}.json`
+  - `src/data/{folder}.ts`
+  - `src/pages/photographing/{slug}/*.astro`
+
+## Composability
+
+Each piece is reusable:
+
+```bash
+# Just extract EXIF
+bun scripts/init-gallery-manifest.ts photos "Photos" photos
+
+# Just merge existing batches
+bun scripts/merge-gallery-batches.ts photos
+
+# Just regenerate pages from manifest
+bun scripts/generate-gallery-files.ts photos
+
+# Validate any manifest
+bun scripts/validate-gallery-manifest.ts src/data/gallery-manifests/photos.json
+```

package/packages/software-development/apple-store-submit/adapters/grok/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:apple-store-submit",
+  "version": "0.1.0",
+  "description": "Handle Apple App Store rejection emails end-to-end: parse rejection reasons, plan fixes, implement code changes, navigate App Store Connect, and resubmit.",
+  "skills": "skills/"
+}