@opendirectory.dev/skills 0.1.39 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendirectory.dev/skills",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/registry.json

@@ -252,6 +252,14 @@
     "version": "1.0.0",
     "path": "skills/pricing-page-psychology-audit"
   },
+  {
+    "name": "product-update-logger",
+    "description": "Tell the skill what your product shipped.",
+    "tags": [],
+    "author": "opendirectory",
+    "version": "0.0.1",
+    "path": "skills/product-update-logger"
+  },
   {
     "name": "producthunt-launch-kit",
     "description": "Generate every asset you need for a Product Hunt launch: listing copy, maker comment, and day-one social posts.",

package/skills/product-update-logger/.env.example

@@ -0,0 +1,4 @@
+GITHUB_TOKEN=      # optional -- github.com/settings/tokens (no scopes needed for public repos)
+                   # Without it: free text + git commits work fully
+                   # With it: GitHub PR fetching enabled (richer context from PR bodies)
+                   # Core changelog generation works without any token

package/skills/product-update-logger/README.md

@@ -0,0 +1,197 @@
+# product-update-logger
+
+Tell the skill what your product shipped. It writes a polished, living `docs/changelog.md` entry and hands you a ready-to-use content package: tweet thread, LinkedIn post, email snippet, and one-liner.
+
+Run it after every deploy. Over quarters, `docs/changelog.md` becomes a complete, shareable product history.
+
+## Install
+
+```bash
+npx "@opendirectory.dev/skills" install product-update-logger --target claude
+```
+
+### Video Tutorial
+Watch this quick video to see how it's done:
+
+https://github.com/user-attachments/assets/ee98a1b5-ebc4-452f-bbfb-c434f2935067
+
+### Step 1: Download the skill from GitHub
+1. Click the **Code** button on this repo's GitHub page.
+2. Select **Download ZIP** to download the repository.
+3. Extract the ZIP file on your computer.
+
+### Step 2: Install the Skill in Claude
+1. Open your **Claude desktop app**.
+2. Go to the sidebar on the left side and click on the **Customize** section.
+3. Click on the **Skills** tab, then click on the **+** (plus) icon button to create a new skill.
+4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
+
+> **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## What It Does
+
+- Accepts: free text items, git commits (auto-read), GitHub PRs -- any combination
+- Filters noise: merge commits, version bumps, CI/CD, typos excluded automatically
+- Transforms: technical commit language -> user-facing benefit language
+- Categorizes: New / Improved / Fixed / Under the hood
+- Generates a content package: one-liner, tweet thread, LinkedIn post, email snippet
+- Appends a new dated entry to `docs/changelog.md` (living log, newest entry first)
+- Saves the content package to `docs/product-updates/[date]-content.md`
+
+## Requirements
+
+| Requirement | Purpose | How to Set Up |
+|---|---|---|
+| GITHUB_TOKEN | Optional -- enables GitHub PR fetching for richer context | github.com/settings/tokens (no scopes needed) |
+
+No other API keys required. Free text + git auto-read work with no configuration.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Add GITHUB_TOKEN if you want to pull from GitHub PRs
+```
+
+## How to Use
+
+```
+"We shipped dark mode and fixed the export bug this week."
+"Log my product updates. I'm in a git repo."
+"We launched 3 things: dark mode, faster search, fixed mobile login."
+"Log updates from last 14 days. Repo: acme/dashboard"
+"We shipped the onboarding redesign. Version: v2.1.0"
+```
+
+Include competitor names for richer channel discovery. Include ICP role + pain for accurate signal-tracing.
+
+## What Gets Generated
+
+### docs/changelog.md (living log)
+
+```markdown
+# Changelog
+
+## Week of April 23, 2026
+
+### New
+- **Dark mode** -- Toggle in Settings > Appearance. Works across all views.
+
+### Improved
+- **Search** -- Results now load in under half a second.
+
+### Fixed
+- **CSV export** -- Exports no longer drop the last row.
+
+---
+
+## Week of April 14, 2026
+...
+```
+
+### docs/product-updates/[date]-content.md (content package)
+
+```
+## One-liner
+Dark mode, faster search, and a fix for the export bug.
+
+## Tweet Thread
+[1/4] We shipped 3 things this week.
+[2/4] Dark mode is live. Toggle it in Settings > Appearance.
+...
+
+## LinkedIn Post
+We shipped 3 updates this week.
+...
+
+## Email Snippet
+Subject: What shipped this week: dark mode + faster search
+...
+```
+
+## Input Sources
+
+The skill pulls from all three sources automatically:
+
+| Source | When used | How to trigger |
+|---|---|---|
+| Free text | Always first | Just describe what shipped in your message |
+| Git commits | Auto-read when in a git repo | Run the skill from your project directory |
+| GitHub PRs | When GITHUB_TOKEN + repo provided | Mention "repo: owner/repo" in your message |
+
+All three can be combined. Overlapping items are deduplicated.
+
+## Changelog Entry Format
+
+Each entry follows a consistent structure:
+
+```
+## [Version label]
+
+### New
+- **Feature** -- Benefit sentence.
+
+### Improved
+- **Feature** -- Benefit sentence.
+
+### Fixed
+- **Feature** -- What was broken, now fixed.
+
+### Under the hood
+- **Component** -- Developer-relevant change only.
+```
+
+Version labels default to `Week of [Month Day, Year]`. Detected semver format is preserved and incremented automatically.
+
+## Content Rules
+
+- **Tweets**: Under 280 chars each, no hashtags, no em dashes, active voice
+- **LinkedIn**: No markdown formatting, no hashtags, founder voice ("We shipped" not "We are excited to announce")
+- **Email**: 50-100 word body, subject line formula, casual and direct
+- **One-liner**: Max 20 words, covers top 1-2 items
+
+## Standalone Script
+
+Run data collection without Claude. Useful for raw item discovery before analysis.
+
+```bash
+# Git auto-read
+python3 scripts/gather.py --since 7 --output /tmp/pul-raw.json
+
+# Free text items
+python3 scripts/gather.py --items "Add dark mode|Fix CSV bug" --output /tmp/pul-raw.json
+
+# With GitHub PRs
+GITHUB_TOKEN=your_token python3 scripts/gather.py --repo owner/repo --since 14
+
+# Print to stdout
+python3 scripts/gather.py --since 7 --stdout | jq '.items'
+```
+
+## Project Structure
+
+```
+product-update-logger/
+├── SKILL.md
+├── README.md
+├── .env.example
+├── scripts/
+│   └── gather.py               git + GitHub + free text collector
+├── evals/
+│   └── evals.json              5 test cases
+└── references/
+    ├── changelog-format.md     entry structure, category rules, transformation examples
+    ├── content-rules.md        tweet/LinkedIn/email writing rules + banned words
+    └── noise-filter.md         git commit patterns to skip
+```
+
+## Cost Per Run
+
+- Git, free text: free, no auth
+- GitHub PRs: free with optional token
+- AI analysis: uses the model running the skill
+- Total: free
+
+## License
+
+MIT

package/skills/product-update-logger/SKILL.md

@@ -0,0 +1,462 @@
+---
+name: product-update-logger
+description: "Tell the skill what your product shipped. It writes a polished dated entry to a living docs/changelog.md and produces a ready-to-use content package: tweet thread, LinkedIn post, email snippet, and one-liner."
+---
+
+# product-update-logger
+
+Tell this skill what your product shipped. It writes a polished changelog entry to `docs/changelog.md` (a living log, newest entry first) and simultaneously produces a content package: tweet thread, LinkedIn post, email snippet, and one-liner.
+
+Input sources: free text from your message, git commits auto-read from the local repo, or GitHub PRs if you provide a repo. Any combination works.
+
+## Reference Files
+
+Read these files before each run:
+
+```bash
+cat references/changelog-format.md
+cat references/content-rules.md
+cat references/noise-filter.md
+```
+
+---
+
+## Step 1: Setup Check
+
+```bash
+echo "GITHUB_TOKEN: ${GITHUB_TOKEN:-not set -- GitHub PR fetching disabled}"
+echo "Git:          $(git rev-parse --is-inside-work-tree 2>/dev/null && echo 'repo detected' || echo 'not a git repo')"
+echo "Changelog:    $(ls docs/changelog.md 2>/dev/null && echo 'exists' || echo 'will be created')"
+```
+
+Note whether git is available and whether a changelog already exists. This determines the version label format.
+
+---
+
+## Step 2: Parse Input
+
+Collect from the conversation:
+
+- `items` -- free text description of what shipped (pipe-separated if multiple). Optional if git is available.
+- `since` -- how many days back to look. Default: 7. User may say "last 2 weeks" (14) or "since last release."
+- `repo` -- GitHub "owner/repo" for PR fetching. Optional.
+- `version_label` -- custom label like "v2.1.0" or "The Speed Update." Optional; default is date-based.
+
+**If the user said nothing about items AND there is no git repo:** Ask "What did you ship? List the features, fixes, or improvements -- one per line."
+
+**If git is available and user said nothing specific:** Proceed with git auto-read in Step 3. Show the user what was found and confirm before transforming.
+
+Write parsed input:
+
+```bash
+python3 << 'PYEOF'
+import json, os, re
+
+inp = {
+    "items": "",          # FILL: pipe-separated free text, or "" if none
+    "since": 7,           # FILL: integer days
+    "repo": "",           # FILL: "owner/repo" or ""
+    "version_label": ""   # FILL: "" means auto (date-based), or custom string
+}
+
+with open("/tmp/pul-input.json", "w") as f:
+    json.dump(inp, f, indent=2)
+print(f"Since: {inp['since']} days")
+print(f"Free text items: {inp['items'] or 'none (will use git/GitHub)'}")
+print(f"GitHub repo: {inp['repo'] or 'none'}")
+print(f"Version label: {inp['version_label'] or 'auto (date-based)'}")
+PYEOF
+```
+
+---
+
+## Step 3: Run the Gather Script
+
+```bash
+ls scripts/gather.py 2>/dev/null && echo "script found" || echo "ERROR: scripts/gather.py not found"
+```
+
+```bash
+GITHUB_TOKEN="${GITHUB_TOKEN:-}" python3 scripts/gather.py \
+    --since "$(python3 -c "import json; print(json.load(open('/tmp/pul-input.json'))['since'])")" \
+    --repo "$(python3 -c "import json; print(json.load(open('/tmp/pul-input.json'))['repo'])")" \
+    --items "$(python3 -c "import json; print(json.load(open('/tmp/pul-input.json'))['items'])")" \
+    --output /tmp/pul-raw.json
+```
+
+Verify output:
+
+```bash
+python3 -c "
+import json
+with open('/tmp/pul-raw.json') as f:
+    d = json.load(f)
+print(f'Items found:      {d[\"total_items\"]}')
+print(f'Noise filtered:   {d[\"noise_filtered\"]}')
+print(f'Git available:    {d[\"git_available\"]}')
+print(f'GitHub available: {d[\"github_available\"]}')
+print(f'Sources: git={sum(1 for i in d[\"items\"] if i[\"source\"]==\"git_commit\")}, '
+      f'prs={sum(1 for i in d[\"items\"] if i[\"source\"]==\"github_pr\")}, '
+      f'text={sum(1 for i in d[\"items\"] if i[\"source\"]==\"free_text\")}')
+print()
+print('Items:')
+for item in d['items']:
+    print(f'  [{item[\"source\"]}] {item[\"subject\"]}')
+"
+```
+
+**If total_items == 0:** Stop. Tell the user: "No shipped items found. Either describe what you shipped, point me to a git repo with recent commits, or add a GitHub repo with `repo: owner/repo` and a GITHUB_TOKEN."
+
+**Show the item list to the user and ask: "These are the items I found. Anything to add or remove before I write the changelog?"**
+
+Wait for confirmation or edits. If the user says "looks good", "proceed", or makes no changes, continue. If the user adds or removes items, update `/tmp/pul-raw.json` accordingly before Step 4.
+
+---
+
+## Step 4: Generate Changelog Entry
+
+Print items for context:
+
+```bash
+python3 -c "
+import json
+with open('/tmp/pul-raw.json') as f:
+    d = json.load(f)
+print(json.dumps(d['items'], indent=2))
+print()
+print(f'Existing changelog format: {d[\"existing_changelog\"][\"format\"]}')
+print(f'Last label: {d[\"existing_changelog\"][\"last_label\"]}')
+print(f'Today: {d[\"date\"]}')
+"
+```
+
+**AI instructions:** Transform each raw item from technical language to user-facing benefit language. Follow `references/changelog-format.md` for transformation rules and examples.
+
+Rules:
+- **Do NOT invent outcomes or metrics.** "40% faster" must come from the source data. If no number is in the commit or PR, do not add one.
+- **Use past tense:** "Added", "Fixed", "Improved" -- not "Adds", "Fixes"
+- **Assign exactly one category** to each item: New, Improved, Fixed, or Under the hood
+- **Under the hood:** Only include if developer-relevant (API changes, breaking changes). Omit empty sections.
+- **Omit** anything that maps to: test changes, CI changes, documentation-only commits
+
+Determine version label:
+- If user specified one: use it exactly
+- If `existing_changelog.format == "semver"`: increment based on changes (patch for fixes only, minor for any new feature)
+- Default: `Week of [Month Day, Year]` using today's date
+
+Write the entry to `/tmp/pul-entry.json`:
+
+```json
+{
+  "label": "Week of April 23, 2026",
+  "date": "2026-04-23",
+  "new": [
+    {"title": "Dark mode", "description": "Toggle in Settings > Appearance. Works across all views."}
+  ],
+  "improved": [
+    {"title": "API response time", "description": "40% faster on average. Dashboard now loads in under 1 second."}
+  ],
+  "fixed": [
+    {"title": "CSV export", "description": "Exports no longer drop the last row."}
+  ],
+  "under_the_hood": []
+}
+```
+
+Verify the entry:
+
+```bash
+python3 -c "
+import json
+with open('/tmp/pul-entry.json') as f:
+    e = json.load(f)
+print(f'Label: {e[\"label\"]}')
+total = 0
+for cat in ['new', 'improved', 'fixed', 'under_the_hood']:
+    items = e.get(cat, [])
+    if items:
+        print(f'{cat.replace(\"_\", \" \").title()} ({len(items)}):')
+        for item in items:
+            print(f'  - {item[\"title\"]}: {item[\"description\"]}')
+        total += len(items)
+print(f'Total: {total} items')
+"
+```
+
+---
+
+## Step 5: Generate Content Package
+
+Using the changelog entry from Step 4, generate all four content pieces. Follow `references/content-rules.md` strictly.
+
+**One-liner** (max 20 words): One sentence covering the biggest 1-2 items. Plain language, no jargon.
+
+**Tweet thread** (3-5 tweets):
+- Tweet 1: Hook -- "We shipped [N] things this week." or lead with the biggest feature
+- Tweets 2-N: One item per tweet, 1-2 sentences max
+- Last tweet: "Changelog: [link]" or "More next week." (optional)
+- Each tweet strictly under 280 characters
+- No hashtags. No em dashes. Active voice.
+
+**LinkedIn post**:
+- No markdown (asterisks render as literal on LinkedIn)
+- No hashtags
+- Founder voice: "We shipped", not "We are excited to announce"
+- Short paragraphs (1-2 sentences each), blank lines between them
+- Close with a question or observation, not a CTA
+- 150-400 words total
+
+**Email snippet**:
+- Subject: "What shipped this week: [biggest item] + [1 more]"
+- Body: 50-100 words. "Here's what we shipped this week:" then bullets.
+
+Write to `/tmp/pul-content.json`:
+
+```json
+{
+  "one_liner": "Dark mode, faster API, and a fixed export bug.",
+  "tweet_thread": [
+    "We shipped 3 things this week.",
+    "Dark mode is live. Toggle it in Settings > Appearance. Works everywhere.",
+    "API response time is now 40% faster. Dashboard loads in under a second.",
+    "Fixed: CSV exports were dropping the last row. That's gone now.",
+    "Changelog: [link]"
+  ],
+  "linkedin_post": "We shipped 3 updates this week.\n\nDark mode is live. Toggle it in Settings under Appearance. It works across every view.\n\nAPI response time is 40% faster on average. The dashboard now loads in under a second for most users.\n\nWe also fixed a bug where CSV exports were silently dropping the last row. If you hit this and stopped exporting, it's worth trying again.\n\nWhat feature have you been waiting for?",
+  "email_snippet": {
+    "subject": "What shipped this week: dark mode + faster API",
+    "body": "Here's what we shipped this week:\n\n- Dark mode: toggle in Settings > Appearance\n- API response time: 40% faster, dashboard loads under 1 second\n- Fixed: CSV exports no longer drop the last row\n\nFull changelog below."
+  }
+}
+```
+
+---
+
+## Step 6: Self-QA
+
+```bash
+python3 -c "
+import json, re
+
+with open('/tmp/pul-raw.json') as f:
+    raw = json.load(f)
+with open('/tmp/pul-entry.json') as f:
+    entry = json.load(f)
+with open('/tmp/pul-content.json') as f:
+    content = json.load(f)
+
+full_text = json.dumps(entry) + json.dumps(content)
+fails = 0
+
+# Check 1: No em dashes
+if chr(8212) in full_text:
+    print('FAIL: em dash found -- replace with hyphen')
+    fails += 1
+else:
+    print('PASS: no em dashes')
+
+# Check 2: Banned words
+banned = ['powerful', 'robust', 'seamless', 'innovative', 'game-changing',
+          'streamline', 'leverage', 'transform', 'revolutionize', 'excited to announce',
+          'pleased to announce', 'we are thrilled', 'cutting-edge', 'best-in-class',
+          'world-class', 'unlock', 'delightful']
+found = [w for w in banned if w.lower() in full_text.lower()]
+if found:
+    print(f'FAIL: banned words found: {found}')
+    fails += 1
+else:
+    print('PASS: no banned words')
+
+# Check 3: Tweet length
+thread = content.get('tweet_thread', [])
+long_tweets = [(i+1, len(t)) for i, t in enumerate(thread) if len(t) > 280]
+if long_tweets:
+    print(f'FAIL: tweets over 280 chars: {long_tweets}')
+    fails += 1
+else:
+    print(f'PASS: all {len(thread)} tweets under 280 chars')
+
+# Check 4: LinkedIn no hashtags
+li = content.get('linkedin_post', '')
+if re.search(r'#[A-Za-z]', li):
+    print('FAIL: hashtags found in LinkedIn post')
+    fails += 1
+else:
+    print('PASS: no hashtags in LinkedIn')
+
+# Check 5: No markdown in LinkedIn
+if '**' in li or '__' in li:
+    print('FAIL: markdown formatting in LinkedIn (renders as literal asterisks)')
+    fails += 1
+else:
+    print('PASS: no markdown in LinkedIn')
+
+# Check 6: One-liner word count
+one_liner = content.get('one_liner', '')
+word_count = len(one_liner.split())
+if word_count > 20:
+    print(f'FAIL: one-liner is {word_count} words (max 20)')
+    fails += 1
+else:
+    print(f'PASS: one-liner is {word_count} words')
+
+# Check 7: Item count
+entry_items = (len(entry.get('new', [])) + len(entry.get('improved', [])) +
+               len(entry.get('fixed', [])) + len(entry.get('under_the_hood', [])))
+raw_total = raw['total_items']
+print(f'INFO: {entry_items} changelog items from {raw_total} raw items')
+
+print()
+print(f'Result: {\"PASS\" if fails == 0 else f\"FAIL ({fails} issues)\"}')
+"
+```
+
+**If any check fails:** Fix the issue in the relevant temp file before proceeding to Step 7. Re-run the check after fixing.
+
+---
+
+## Step 7: Append to Changelog + Save Content
+
+```bash
+python3 << 'PYEOF'
+import json, os, re
+
+with open('/tmp/pul-entry.json') as f:
+    entry = json.load(f)
+with open('/tmp/pul-content.json') as f:
+    content = json.load(f)
+
+# Build the new changelog section
+lines = [f"## {entry['label']}", ""]
+
+CAT_HEADERS = {
+    "new": "### New",
+    "improved": "### Improved",
+    "fixed": "### Fixed",
+    "under_the_hood": "### Under the hood",
+}
+
+for cat, header in CAT_HEADERS.items():
+    items = entry.get(cat, [])
+    if items:
+        lines.append(header)
+        for item in items:
+            lines.append(f"- **{item['title']}** -- {item['description']}")
+        lines.append("")
+
+lines.append("---")
+lines.append("")
+new_section = "\n".join(lines)
+
+# Prepend to docs/changelog.md
+os.makedirs("docs", exist_ok=True)
+changelog_path = "docs/changelog.md"
+
+if os.path.exists(changelog_path):
+    existing = open(changelog_path).read()
+    # Insert after the top-level heading (if any) or at the very top
+    if existing.startswith("# "):
+        end_of_heading = existing.index("\n") + 1
+        updated = existing[:end_of_heading] + "\n" + new_section + existing[end_of_heading:]
+    else:
+        updated = new_section + existing
+else:
+    updated = "# Changelog\n\n" + new_section
+
+with open(changelog_path, "w") as f:
+    f.write(updated)
+
+print(f"Changelog updated: {changelog_path}")
+
+# Save content package
+date = entry['date']
+content_dir = "docs/product-updates"
+os.makedirs(content_dir, exist_ok=True)
+content_path = f"{content_dir}/{date}-content.md"
+
+content_lines = [
+    f"# Content Package: {entry['label']}",
+    "",
+    "## One-liner",
+    content.get('one_liner', ''),
+    "",
+    "## Tweet Thread",
+    "",
+]
+thread = content.get('tweet_thread', [])
+for i, tweet in enumerate(thread, 1):
+    content_lines.append(f"[{i}/{len(thread)}] {tweet}")
+    content_lines.append("")
+
+content_lines += [
+    "## LinkedIn Post",
+    "",
+    content.get('linkedin_post', ''),
+    "",
+    "## Email Snippet",
+    "",
+    f"Subject: {content.get('email_snippet', {}).get('subject', '')}",
+    "",
+    content.get('email_snippet', {}).get('body', ''),
+    "",
+]
+
+with open(content_path, "w") as f:
+    f.write("\n".join(content_lines))
+
+print(f"Content package: {content_path}")
+PYEOF
+```
+
+---
+
+## Step 8: Clean Up and Present
+
+```bash
+rm -f /tmp/pul-input.json /tmp/pul-raw.json /tmp/pul-entry.json /tmp/pul-content.json
+echo "Done."
+```
+
+Present to the user in this order:
+
+**1. Changelog entry** (formatted markdown, not raw JSON):
+
+```
+## Week of April 23, 2026
+
+### New
+- **Dark mode** -- Toggle in Settings > Appearance. Works across all views.
+
+### Improved
+- **API response time** -- 40% faster on average. Dashboard now loads in under 1 second.
+
+### Fixed
+- **CSV export** -- Exports no longer drop the last row.
+```
+
+**2. Content package:**
+
+- One-liner: `[text]`
+- Tweet thread: numbered list of tweets
+- LinkedIn post: full text
+- Email snippet: subject line + body
+
+**3. Saved files:**
+- `docs/changelog.md` -- updated (new entry prepended)
+- `docs/product-updates/[date]-content.md` -- full content package saved
+
+---
+
+## Common Mistakes
+
+| The agent will want to... | Why that's wrong |
+|---|---|
+| Invent outcomes or metrics | Every claim must come from the raw items. "40% faster" needs to come from the commit message or PR body. If no number is present, don't add one. |
+| Write "We are excited to announce" | Banned. Use "We shipped", "[Feature] is now live", or just state the fact. |
+| Use markdown bold (**) in LinkedIn | LinkedIn renders ** as literal asterisks. Plain text only. |
+| Add hashtags to LinkedIn or tweets | This skill never uses hashtags. |
+| Put all items in "New" | Bugs are Fixed, speed improvements are Improved. Miscategorizing weakens the changelog. |
+| Skip the confirmation step in Step 3 | Always show the item list and ask the user to confirm before transforming. This prevents wrong-branch commits or stale items. |
+| Include empty "Under the hood" section | Omit if empty. Silence is better than noise. |
+| Combine multiple items into one tweet | One item per tweet. Specificity > breadth. |
+| Pad with filler tweets | If there's one real item, write 2 tweets. Don't pad to 5. |