@olegkoval/agent-skills 1.6.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.kiro/steering/add-to-my-skills.md +78 -0
  3. package/.kiro/steering/ai-tools-setup.md +263 -0
  4. package/.kiro/steering/changelog-generator.md +106 -0
  5. package/.kiro/steering/cloudflare-block-countries.md +167 -0
  6. package/.kiro/steering/docs-index-keeper.md +53 -0
  7. package/.kiro/steering/fill-music-player.md +101 -0
  8. package/.kiro/steering/gallery.md +228 -0
  9. package/.kiro/steering/gh-cli.md +2190 -0
  10. package/.kiro/steering/git-commit.md +125 -0
  11. package/.kiro/steering/open-source-publisher.md +427 -0
  12. package/.kiro/steering/product-builder.md +213 -0
  13. package/.kiro/steering/promptctl.md +81 -0
  14. package/.kiro/steering/search-console-indexing-audit.md +57 -0
  15. package/.kiro/steering/semantic-release-beta.md +48 -0
  16. package/.kiro/steering/starter-rules.md +62 -0
  17. package/.kiro/steering/viral-launch.md +92 -0
  18. package/.windsurf/rules/add-to-my-skills.md +77 -0
  19. package/.windsurf/rules/ai-tools-setup.md +262 -0
  20. package/.windsurf/rules/changelog-generator.md +105 -0
  21. package/.windsurf/rules/cloudflare-block-countries.md +166 -0
  22. package/.windsurf/rules/docs-index-keeper.md +52 -0
  23. package/.windsurf/rules/fill-music-player.md +100 -0
  24. package/.windsurf/rules/gallery.md +227 -0
  25. package/.windsurf/rules/gh-cli.md +2189 -0
  26. package/.windsurf/rules/git-commit.md +124 -0
  27. package/.windsurf/rules/open-source-publisher.md +426 -0
  28. package/.windsurf/rules/product-builder.md +212 -0
  29. package/.windsurf/rules/promptctl.md +80 -0
  30. package/.windsurf/rules/search-console-indexing-audit.md +56 -0
  31. package/.windsurf/rules/semantic-release-beta.md +47 -0
  32. package/.windsurf/rules/starter-rules.md +61 -0
  33. package/.windsurf/rules/viral-launch.md +91 -0
  34. package/README.md +67 -14
  35. package/catalog/skills.json +48 -16
  36. package/docs/skill-anatomy.md +10 -6
  37. package/package.json +3 -1
  38. package/packages/marketing/search-console-indexing-audit/SKILL.md +3 -0
  39. package/packages/marketing/search-console-indexing-audit/adapters/claude/skills/search-console-indexing-audit/SKILL.md +3 -0
  40. package/packages/marketing/search-console-indexing-audit/adapters/cursor/plugin.json +1 -1
  41. package/packages/marketing/search-console-indexing-audit/adapters/cursor/skills/search-console-indexing-audit/SKILL.md +3 -0
  42. package/packages/marketing/search-console-indexing-audit/adapters/kiro/steering/search-console-indexing-audit.md +57 -0
  43. package/packages/marketing/search-console-indexing-audit/adapters/windsurf/rules/search-console-indexing-audit.md +56 -0
  44. package/packages/marketing/viral-launch/SKILL.md +3 -1
  45. package/packages/marketing/viral-launch/adapters/claude/skills/viral-launch/SKILL.md +3 -1
  46. package/packages/marketing/viral-launch/adapters/cursor/skills/viral-launch/SKILL.md +3 -1
  47. package/packages/marketing/viral-launch/adapters/kiro/steering/viral-launch.md +92 -0
  48. package/packages/marketing/viral-launch/adapters/windsurf/rules/viral-launch.md +91 -0
  49. package/packages/music/fill-music-player/SKILL.md +2 -1
  50. package/packages/music/fill-music-player/adapters/claude/skills/fill-music-player/SKILL.md +2 -1
  51. package/packages/music/fill-music-player/adapters/cursor/plugin.json +1 -1
  52. package/packages/music/fill-music-player/adapters/cursor/skills/fill-music-player/SKILL.md +2 -1
  53. package/packages/music/fill-music-player/adapters/kiro/steering/fill-music-player.md +101 -0
  54. package/packages/music/fill-music-player/adapters/windsurf/rules/fill-music-player.md +100 -0
  55. package/packages/photography/gallery/SKILL.md +3 -1
  56. package/packages/photography/gallery/adapters/claude/skills/gallery/SKILL.md +3 -1
  57. package/packages/photography/gallery/adapters/cursor/skills/gallery/SKILL.md +3 -1
  58. package/packages/photography/gallery/adapters/kiro/steering/gallery.md +228 -0
  59. package/packages/photography/gallery/adapters/windsurf/rules/gallery.md +227 -0
  60. package/packages/software-development/add-to-my-skills/SKILL.md +2 -1
  61. package/packages/software-development/add-to-my-skills/adapters/claude/skills/add-to-my-skills/SKILL.md +2 -1
  62. package/packages/software-development/add-to-my-skills/adapters/cursor/skills/add-to-my-skills/SKILL.md +2 -1
  63. package/packages/software-development/add-to-my-skills/adapters/kiro/steering/add-to-my-skills.md +78 -0
  64. package/packages/software-development/add-to-my-skills/adapters/windsurf/rules/add-to-my-skills.md +77 -0
  65. package/packages/software-development/ai-tools-setup/adapters/kiro/steering/ai-tools-setup.md +263 -0
  66. package/packages/software-development/ai-tools-setup/adapters/windsurf/rules/ai-tools-setup.md +262 -0
  67. package/packages/software-development/changelog-generator/SKILL.md +3 -1
  68. package/packages/software-development/changelog-generator/adapters/claude/skills/changelog-generator/SKILL.md +3 -1
  69. package/packages/software-development/changelog-generator/adapters/cursor/skills/changelog-generator/SKILL.md +3 -1
  70. package/packages/software-development/changelog-generator/adapters/kiro/steering/changelog-generator.md +106 -0
  71. package/packages/software-development/changelog-generator/adapters/windsurf/rules/changelog-generator.md +105 -0
  72. package/packages/software-development/cloudflare-block-countries/SKILL.md +1 -1
  73. package/packages/software-development/cloudflare-block-countries/adapters/claude/skills/cloudflare-block-countries/SKILL.md +1 -1
  74. package/packages/software-development/cloudflare-block-countries/adapters/cursor/skills/cloudflare-block-countries/SKILL.md +1 -1
  75. package/packages/software-development/cloudflare-block-countries/adapters/kiro/steering/cloudflare-block-countries.md +167 -0
  76. package/packages/software-development/cloudflare-block-countries/adapters/windsurf/rules/cloudflare-block-countries.md +166 -0
  77. package/packages/software-development/docs-index-keeper/SKILL.md +2 -1
  78. package/packages/software-development/docs-index-keeper/adapters/claude/skills/docs-index-keeper/SKILL.md +2 -1
  79. package/packages/software-development/docs-index-keeper/adapters/cursor/plugin.json +1 -1
  80. package/packages/software-development/docs-index-keeper/adapters/cursor/skills/docs-index-keeper/SKILL.md +2 -1
  81. package/packages/software-development/docs-index-keeper/adapters/kiro/steering/docs-index-keeper.md +53 -0
  82. package/packages/software-development/docs-index-keeper/adapters/windsurf/rules/docs-index-keeper.md +52 -0
  83. package/packages/software-development/gh-cli/SKILL.md +3 -1
  84. package/packages/software-development/gh-cli/adapters/claude/skills/gh-cli/SKILL.md +3 -1
  85. package/packages/software-development/gh-cli/adapters/cursor/skills/gh-cli/SKILL.md +3 -1
  86. package/packages/software-development/gh-cli/adapters/kiro/steering/gh-cli.md +2190 -0
  87. package/packages/software-development/gh-cli/adapters/windsurf/rules/gh-cli.md +2189 -0
  88. package/packages/software-development/git-commit/SKILL.md +1 -1
  89. package/packages/software-development/git-commit/adapters/claude/skills/git-commit/SKILL.md +1 -1
  90. package/packages/software-development/git-commit/adapters/cursor/skills/git-commit/SKILL.md +1 -1
  91. package/packages/software-development/git-commit/adapters/kiro/steering/git-commit.md +125 -0
  92. package/packages/software-development/git-commit/adapters/windsurf/rules/git-commit.md +124 -0
  93. package/packages/software-development/open-source-publisher/SKILL.md +2 -1
  94. package/packages/software-development/open-source-publisher/adapters/claude/skills/open-source-publisher/SKILL.md +2 -1
  95. package/packages/software-development/open-source-publisher/adapters/cursor/skills/open-source-publisher/SKILL.md +2 -1
  96. package/packages/software-development/open-source-publisher/adapters/kiro/steering/open-source-publisher.md +427 -0
  97. package/packages/software-development/open-source-publisher/adapters/windsurf/rules/open-source-publisher.md +426 -0
  98. package/packages/software-development/product-builder/SKILL.md +2 -1
  99. package/packages/software-development/product-builder/adapters/claude/skills/product-builder/SKILL.md +2 -1
  100. package/packages/software-development/product-builder/adapters/cursor/plugin.json +1 -1
  101. package/packages/software-development/product-builder/adapters/cursor/skills/product-builder/SKILL.md +2 -1
  102. package/packages/software-development/product-builder/adapters/kiro/steering/product-builder.md +213 -0
  103. package/packages/software-development/product-builder/adapters/windsurf/rules/product-builder.md +212 -0
  104. package/packages/software-development/promptctl/SKILL.md +3 -1
  105. package/packages/software-development/promptctl/adapters/claude/skills/promptctl/SKILL.md +3 -1
  106. package/packages/software-development/promptctl/adapters/cursor/skills/promptctl/SKILL.md +3 -1
  107. package/packages/software-development/promptctl/adapters/kiro/steering/promptctl.md +81 -0
  108. package/packages/software-development/promptctl/adapters/windsurf/rules/promptctl.md +80 -0
  109. package/packages/software-development/semantic-release-beta/SKILL.md +3 -1
  110. package/packages/software-development/semantic-release-beta/adapters/claude/skills/semantic-release-beta/SKILL.md +3 -1
  111. package/packages/software-development/semantic-release-beta/adapters/cursor/skills/semantic-release-beta/SKILL.md +3 -1
  112. package/packages/software-development/semantic-release-beta/adapters/kiro/steering/semantic-release-beta.md +48 -0
  113. package/packages/software-development/semantic-release-beta/adapters/windsurf/rules/semantic-release-beta.md +47 -0
  114. package/packages/software-development/starter-rules/SKILL.md +2 -1
  115. package/packages/software-development/starter-rules/adapters/claude/skills/starter-rules/SKILL.md +2 -1
  116. package/packages/software-development/starter-rules/adapters/cursor/plugin.json +3 -2
  117. package/packages/software-development/starter-rules/adapters/cursor/skills/starter-rules/SKILL.md +2 -1
  118. package/packages/software-development/starter-rules/adapters/kiro/steering/starter-rules.md +62 -0
  119. package/packages/software-development/starter-rules/adapters/windsurf/rules/starter-rules.md +61 -0
  120. package/scripts/build-adapters.sh +97 -8
  121. package/scripts/validate-catalog.sh +4 -0
@@ -0,0 +1,262 @@
1
+ <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
2
+
3
+ ---
4
+ description: "Install, repair, and measure the RTK+ICM+Vox AI development toolkit. Fixes missing hooks and MCP config, and shows a weekly effectiveness digest of token savings and memory health."
5
+ ---
6
+
7
+
8
+ # AI Tools Setup — RTK + ICM + Vox
9
+
10
+ Install, repair, and measure the RTK+ICM+Vox toolkit for Claude Code.
11
+
12
+ ## What This Skill Does
13
+
14
+ | Mode | When to use |
15
+ |------|-------------|
16
+ | **Setup** | First install on a new machine |
17
+ | **Repair** | Something broke — hooks missing, MCP not loading |
18
+ | **Digest** | Weekly check: token savings, memory health, voice stats |
19
+
20
+ ## Tools in the Bundle
21
+
22
+ | Tool | Version | Purpose |
23
+ |------|---------|---------|
24
+ | **RTK** | latest | Compresses CLI output by ~89% before it reaches the model |
25
+ | **ICM** | latest | Persistent SQLite memory across sessions (knowledge graph + hybrid search) |
26
+ | **Vox** | latest | Spoken task notifications via local TTS — zero API calls |
27
+
28
+ ---
29
+
30
+ ## Step 1: Detect Current State
31
+
32
+ Run this to see what is installed and what is missing:
33
+
34
+ ```bash
35
+ echo "=== Binary check ===" && \
36
+ (rtk --version 2>/dev/null && echo "RTK: ok") || echo "RTK: MISSING" && \
37
+ (icm --version 2>/dev/null && echo "ICM: ok") || echo "ICM: MISSING" && \
38
+ (vox --version 2>/dev/null && echo "Vox: ok") || echo "Vox: MISSING"
39
+
40
+ echo "=== RTK hook ===" && \
41
+ grep -c '"rtk hook claude"' ~/.claude/settings.json 2>/dev/null \
42
+ && echo "RTK hook: ok" || echo "RTK hook: MISSING"
43
+
44
+ echo "=== ICM hooks ===" && \
45
+ grep -c '"icm hook' ~/.claude/settings.json 2>/dev/null \
46
+ && echo "ICM hooks: ok" || echo "ICM hooks: MISSING"
47
+
48
+ echo "=== ICM MCP ===" && \
49
+ python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('ICM MCP: ok' if 'icm' in d.get('mcpServers',{}) else 'ICM MCP: MISSING')" 2>/dev/null || echo "ICM MCP: MISSING"
50
+
51
+ echo "=== Vox MCP ===" && \
52
+ python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('Vox MCP: ok' if 'vox' in d.get('mcpServers',{}) else 'Vox MCP: MISSING')" 2>/dev/null || echo "Vox MCP: MISSING"
53
+
54
+ echo "=== ICM CLAUDE.md ===" && \
55
+ grep -c 'icm:start' ~/.claude/CLAUDE.md 2>/dev/null \
56
+ && echo "ICM CLAUDE.md: ok" || echo "ICM CLAUDE.md: MISSING"
57
+ ```
58
+
59
+ Read the output and determine which of the following repair steps are needed.
60
+
61
+ ---
62
+
63
+ ## Step 2: Install Missing Binaries
64
+
65
+ Only run for tools that showed MISSING above.
66
+
67
+ **RTK:**
68
+ ```bash
69
+ brew install rtk
70
+ rtk --version
71
+ ```
72
+
73
+ **ICM:**
74
+ ```bash
75
+ brew install rtk-ai/tap/icm
76
+ icm --version
77
+ ```
78
+
79
+ **Vox:**
80
+ ```bash
81
+ brew install rtk-ai/tap/vox
82
+ vox --version
83
+ ```
84
+
85
+ ---
86
+
87
+ ## Step 3: Repair Hooks
88
+
89
+ ### RTK hook missing
90
+
91
+ Add the `PreToolUse` RTK hook to `~/.claude/settings.json`. Read the file first, then add inside the existing `"hooks"` block (or create one):
92
+
93
+ ```json
94
+ "PreToolUse": [
95
+ {
96
+ "matcher": "Bash",
97
+ "hooks": [{ "type": "command", "command": "rtk hook claude" }]
98
+ }
99
+ ]
100
+ ```
101
+
102
+ Then verify: `grep -c '"rtk hook claude"' ~/.claude/settings.json`
103
+
104
+ ### ICM hooks missing
105
+
106
+ Run:
107
+ ```bash
108
+ icm init --mode hook
109
+ ```
110
+
111
+ This adds `PreToolUse`, `PostToolUse`, `PreCompact`, `UserPromptSubmit`, `SessionStart`, `SessionEnd` hooks automatically.
112
+
113
+ ### Vox Stop hook missing
114
+
115
+ Run:
116
+ ```bash
117
+ vox init --mode cli
118
+ ```
119
+
120
+ ---
121
+
122
+ ## Step 4: Repair MCP Servers
123
+
124
+ ### ICM MCP missing
125
+
126
+ ```bash
127
+ icm init --mode mcp
128
+ ```
129
+
130
+ ### Vox MCP missing
131
+
132
+ ```bash
133
+ vox init --mode mcp
134
+ ```
135
+
136
+ Verify both by checking `~/.claude.json`:
137
+ ```bash
138
+ python3 -c "import json; d=json.load(open('$HOME/.claude.json')); print(list(d.get('mcpServers',{}).keys()))"
139
+ ```
140
+
141
+ ---
142
+
143
+ ## Step 5: Repair CLAUDE.md Instructions
144
+
145
+ If ICM instructions are missing from `~/.claude/CLAUDE.md`:
146
+
147
+ ```bash
148
+ icm init --mode cli
149
+ ```
150
+
151
+ Then move the block from wherever `icm init` placed it into `~/.claude/CLAUDE.md` (the global file), and remove it from any project-local files.
152
+
153
+ ---
154
+
155
+ ## Step 6: Effectiveness Digest
156
+
157
+ Run this report to see how the toolkit is performing. Good to run weekly.
158
+
159
+ ```bash
160
+ echo "=============================="
161
+ echo " AI TOOLS EFFECTIVENESS"
162
+ echo "=============================="
163
+ echo ""
164
+ echo "--- RTK: Token Savings ---"
165
+ rtk gain 2>/dev/null || echo "No data yet (run some commands first)"
166
+ echo ""
167
+ echo "--- ICM: Memory Health ---"
168
+ icm health 2>/dev/null || echo "No memories yet"
169
+ echo ""
170
+ echo "--- ICM: Topics ---"
171
+ icm topics 2>/dev/null || echo "No topics yet"
172
+ echo ""
173
+ echo "--- Vox: Usage ---"
174
+ vox stats 2>/dev/null || echo "No stats yet"
175
+ echo ""
176
+ echo "=============================="
177
+ ```
178
+
179
+ ### What healthy output looks like
180
+
181
+ - **RTK**: `Tokens saved: 5M+ (85%+)` across `500+ commands` — if savings are low, run `rtk discover` to find uncovered commands
182
+ - **ICM**: Topics like `decisions-*`, `errors-resolved`, `preferences` with recent timestamps — if empty, start storing manually with `icm store`
183
+ - **Vox**: Non-zero speak count means the Stop hook fired
184
+
185
+ ---
186
+
187
+ ## Step 7 (Optional): Schedule a Weekly Digest
188
+
189
+ To get a weekly automated report without having to remember to run this skill:
190
+
191
+ ```bash
192
+ # Create a weekly digest script
193
+ cat > ~/ai-tools-digest.sh << 'EOF'
194
+ #!/bin/bash
195
+ echo "=== Weekly AI Tools Digest — $(date) ===" | tee -a ~/ai-tools-digest.log
196
+ echo "" | tee -a ~/ai-tools-digest.log
197
+ rtk gain 2>/dev/null | tee -a ~/ai-tools-digest.log
198
+ echo "" | tee -a ~/ai-tools-digest.log
199
+ icm health 2>/dev/null | tee -a ~/ai-tools-digest.log
200
+ echo "" | tee -a ~/ai-tools-digest.log
201
+ icm topics 2>/dev/null | tee -a ~/ai-tools-digest.log
202
+ # Speak the summary if Vox is available
203
+ vox "Weekly digest complete. Check your log." 2>/dev/null || true
204
+ EOF
205
+ chmod +x ~/ai-tools-digest.sh
206
+ ```
207
+
208
+ Then set up a weekly launchd job (macOS):
209
+
210
+ ```bash
211
+ cat > ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist << 'EOF'
212
+ <?xml version="1.0" encoding="UTF-8"?>
213
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
214
+ <plist version="1.0">
215
+ <dict>
216
+ <key>Label</key>
217
+ <string>com.oleg.ai-tools-digest</string>
218
+ <key>ProgramArguments</key>
219
+ <array>
220
+ <string>/bin/bash</string>
221
+ <string>/Users/oleg.koval/ai-tools-digest.sh</string>
222
+ </array>
223
+ <key>StartCalendarInterval</key>
224
+ <dict>
225
+ <key>Weekday</key>
226
+ <integer>1</integer>
227
+ <key>Hour</key>
228
+ <integer>9</integer>
229
+ <key>Minute</key>
230
+ <integer>0</integer>
231
+ </dict>
232
+ <key>StandardOutPath</key>
233
+ <string>/tmp/ai-tools-digest.log</string>
234
+ <key>StandardErrorPath</key>
235
+ <string>/tmp/ai-tools-digest.err</string>
236
+ </dict>
237
+ </plist>
238
+ EOF
239
+
240
+ launchctl load ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist
241
+ echo "Weekly digest scheduled for Mondays at 9am"
242
+ ```
243
+
244
+ To view the digest log anytime: `cat ~/ai-tools-digest.log`
245
+
246
+ To unload: `launchctl unload ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist`
247
+
248
+ ---
249
+
250
+ ## Quick Reference
251
+
252
+ | Command | What it does |
253
+ |---------|-------------|
254
+ | `rtk gain` | Total tokens saved to date |
255
+ | `rtk discover` | Find commands not yet covered by RTK |
256
+ | `icm topics` | List all memory topic buckets |
257
+ | `icm health` | Memory hygiene — stale, redundant, decay stats |
258
+ | `icm recall "query"` | Search memories semantically |
259
+ | `icm store -t topic -c "content" -i high` | Store a memory manually |
260
+ | `vox "text"` | Speak text immediately |
261
+ | `vox stats` | Usage stats for the Vox backend |
262
+ | `cat ~/ai-tools-digest.log` | View scheduled digest history |
@@ -0,0 +1,105 @@
1
+ <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
2
+
3
+ ---
4
+ description: "Generate user-facing changelogs and release notes from git history."
5
+ ---
6
+
7
+
8
+ # Changelog Generator
9
+
10
+ This skill transforms technical git commits into polished, user-friendly changelogs that your customers and users will actually understand and appreciate.
11
+
12
+ ## When to Use This Skill
13
+
14
+ - Preparing release notes for a new version
15
+ - Creating weekly or monthly product update summaries
16
+ - Documenting changes for customers
17
+ - Writing changelog entries for app store submissions
18
+ - Generating update notifications
19
+ - Creating internal release documentation
20
+ - Maintaining a public changelog/product updates page
21
+
22
+ ## What This Skill Does
23
+
24
+ 1. **Scans Git History**: Analyzes commits from a specific time period or between versions
25
+ 2. **Categorizes Changes**: Groups commits into logical categories (features, improvements, bug fixes, breaking changes, security)
26
+ 3. **Translates Technical → User-Friendly**: Converts developer commits into customer language
27
+ 4. **Formats Professionally**: Creates clean, structured changelog entries
28
+ 5. **Filters Noise**: Excludes internal commits (refactoring, tests, etc.)
29
+ 6. **Follows Best Practices**: Applies changelog guidelines and your brand voice
30
+
31
+ ## How to Use
32
+
33
+ ### Basic Usage
34
+
35
+ From your project repository:
36
+
37
+ ```
38
+ Create a changelog from commits since last release
39
+ ```
40
+
41
+ ```
42
+ Generate changelog for all commits from the past week
43
+ ```
44
+
45
+ ```
46
+ Create release notes for version 2.5.0
47
+ ```
48
+
49
+ ### With Specific Date Range
50
+
51
+ ```
52
+ Create a changelog for all commits between March 1 and March 15
53
+ ```
54
+
55
+ ### With Custom Guidelines
56
+
57
+ ```
58
+ Create a changelog for commits since v2.4.0, using my changelog
59
+ guidelines from CHANGELOG_STYLE.md
60
+ ```
61
+
62
+ ## Example
63
+
64
+ **User**: "Create a changelog for commits from the past 7 days"
65
+
66
+ **Output**:
67
+ ```markdown
68
+ # Updates - Week of March 10, 2024
69
+
70
+ ## ✨ New Features
71
+
72
+ - **Team Workspaces**: Create separate workspaces for different
73
+ projects. Invite team members and keep everything organized.
74
+
75
+ - **Keyboard Shortcuts**: Press ? to see all available shortcuts.
76
+ Navigate faster without touching your mouse.
77
+
78
+ ## 🔧 Improvements
79
+
80
+ - **Faster Sync**: Files now sync 2x faster across devices
81
+ - **Better Search**: Search now includes file contents, not just titles
82
+
83
+ ## 🐛 Fixes
84
+
85
+ - Fixed issue where large images wouldn't upload
86
+ - Resolved timezone confusion in scheduled posts
87
+ - Corrected notification badge count
88
+ ```
89
+
90
+ **Inspired by:** Manik Aggarwal's use case from Lenny's Newsletter
91
+
92
+ ## Tips
93
+
94
+ - Run from your git repository root
95
+ - Specify date ranges for focused changelogs
96
+ - Use your CHANGELOG_STYLE.md for consistent formatting
97
+ - Review and adjust the generated changelog before publishing
98
+ - Save output directly to CHANGELOG.md
99
+
100
+ ## Related Use Cases
101
+
102
+ - Creating GitHub release notes
103
+ - Writing app store update descriptions
104
+ - Generating email updates for users
105
+ - Creating social media announcement posts
@@ -0,0 +1,166 @@
1
+ <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
2
+
3
+ ---
4
+ description: "Block specific countries via Cloudflare WAF Custom Rules using the Cloudflare API. Handles creating new rulesets and updating existing ones across single or multiple zones."
5
+ ---
6
+
7
+
8
+ # Cloudflare Country Block via WAF Custom Rules
9
+
10
+ Block traffic from specific countries using Cloudflare WAF Custom Rules and the Cloudflare API.
11
+
12
+ ## Prerequisites
13
+
14
+ - Cloudflare API Token with `Zone:Rulesets:Edit` permission
15
+ - Zone ID for the target domain
16
+ - `curl` and `jq` installed
17
+
18
+ ## Workflow
19
+
20
+ ### 1. Get Zone IDs
21
+
22
+ ```bash
23
+ curl -s -X GET \
24
+ "https://api.cloudflare.com/client/v4/zones?account.id=YOUR_ACCOUNT_ID&status=active" \
25
+ -H "Authorization: Bearer YOUR_API_TOKEN" \
26
+ -H "Content-Type: application/json" | jq '.result[] | {name: .name, id: .id}'
27
+ ```
28
+
29
+ ### 2. Check Existing Custom Firewall Rulesets
30
+
31
+ ```bash
32
+ curl -s -X GET \
33
+ "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/rulesets" \
34
+ -H "Authorization: Bearer YOUR_API_TOKEN" \
35
+ -H "Content-Type: application/json" | \
36
+ jq '.result[] | select(.phase == "http_request_firewall_custom")'
37
+ ```
38
+
39
+ If the output is empty — no existing ruleset. Go to **3a**. If a ruleset exists, note its `id` and go to **3b**.
40
+
41
+ ### 3a. Create NEW Ruleset with Block Rule
42
+
43
+ ```bash
44
+ curl -s -X POST \
45
+ "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/rulesets" \
46
+ -H "Authorization: Bearer YOUR_API_TOKEN" \
47
+ -H "Content-Type: application/json" \
48
+ --data '{
49
+ "name": "default",
50
+ "description": "WAF Custom Rules",
51
+ "kind": "zone",
52
+ "phase": "http_request_firewall_custom",
53
+ "rules": [
54
+ {
55
+ "action": "block",
56
+ "description": "Block traffic from sanctioned countries",
57
+ "enabled": true,
58
+ "expression": "(ip.src.country in {\"RU\" \"BY\" \"IR\" \"KP\"})"
59
+ }
60
+ ]
61
+ }' | jq '.success'
62
+ ```
63
+
64
+ ### 3b. Update EXISTING Ruleset
65
+
66
+ ```bash
67
+ curl -s -X PUT \
68
+ "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/rulesets/RULESET_ID" \
69
+ -H "Authorization: Bearer YOUR_API_TOKEN" \
70
+ -H "Content-Type: application/json" \
71
+ --data '{
72
+ "description": "WAF Custom Rules",
73
+ "rules": [
74
+ {
75
+ "action": "block",
76
+ "description": "Block traffic from sanctioned countries",
77
+ "enabled": true,
78
+ "expression": "(ip.src.country in {\"RU\" \"BY\" \"IR\" \"KP\"})"
79
+ }
80
+ ]
81
+ }' | jq '.success'
82
+ ```
83
+
84
+ ### 4. Verify the Rule is Active
85
+
86
+ ```bash
87
+ curl -s -X GET \
88
+ "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/rulesets/RULESET_ID" \
89
+ -H "Authorization: Bearer YOUR_API_TOKEN" \
90
+ -H "Content-Type: application/json" | jq '.result.rules'
91
+ ```
92
+
93
+ ## Country Codes Reference
94
+
95
+ | Code | Country |
96
+ |------|---------|
97
+ | `RU` | Russia |
98
+ | `BY` | Belarus |
99
+ | `IR` | Iran |
100
+ | `KP` | North Korea |
101
+ | `CN` | China |
102
+ | `CU` | Cuba |
103
+ | `SY` | Syria |
104
+ | `VE` | Venezuela |
105
+
106
+ ## WAF Expression Examples
107
+
108
+ ```
109
+ # Block multiple countries
110
+ (ip.src.country in {"RU" "BY" "IR" "KP"})
111
+
112
+ # Block country + specific ASN
113
+ (ip.src.country eq "RU") or (ip.geoip.asnum eq 12345)
114
+
115
+ # Block all except allowlisted IPs
116
+ (ip.src.country in {"RU" "BY"}) and not (ip.src in {1.2.3.4/32})
117
+ ```
118
+
119
+ ## Multi-Zone Script
120
+
121
+ To apply the same block rule across multiple zones:
122
+
123
+ ```bash
124
+ #!/usr/bin/env bash
125
+ API_TOKEN="YOUR_API_TOKEN"
126
+ ZONES=("ZONE_ID_1" "ZONE_ID_2" "ZONE_ID_3")
127
+ EXPRESSION='(ip.src.country in {"RU" "BY" "IR" "KP"})'
128
+
129
+ for ZONE_ID in "${ZONES[@]}"; do
130
+ EXISTING=$(curl -s -X GET \
131
+ "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \
132
+ -H "Authorization: Bearer $API_TOKEN" \
133
+ -H "Content-Type: application/json" | \
134
+ jq -r '.result[] | select(.phase == "http_request_firewall_custom") | .id')
135
+
136
+ if [ -z "$EXISTING" ]; then
137
+ METHOD="POST"
138
+ URL="https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets"
139
+ DATA=$(jq -n --arg expr "$EXPRESSION" '{
140
+ name: "default", description: "WAF Custom Rules",
141
+ kind: "zone", phase: "http_request_firewall_custom",
142
+ rules: [{action: "block", description: "Block sanctioned countries", enabled: true, expression: $expr}]
143
+ }')
144
+ else
145
+ METHOD="PUT"
146
+ URL="https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$EXISTING"
147
+ DATA=$(jq -n --arg expr "$EXPRESSION" '{
148
+ description: "WAF Custom Rules",
149
+ rules: [{action: "block", description: "Block sanctioned countries", enabled: true, expression: $expr}]
150
+ }')
151
+ fi
152
+
153
+ RESULT=$(curl -s -X "$METHOD" "$URL" \
154
+ -H "Authorization: Bearer $API_TOKEN" \
155
+ -H "Content-Type: application/json" \
156
+ --data "$DATA" | jq '.success')
157
+
158
+ echo "Zone $ZONE_ID: $RESULT"
159
+ done
160
+ ```
161
+
162
+ ## Notes
163
+
164
+ - `PUT` on an existing ruleset **replaces all rules** in it. Include all rules in the payload if the ruleset already has other rules.
165
+ - WAF Custom Rules require a Cloudflare plan that supports rulesets (Free includes basic WAF; Pro/Business/Enterprise for full custom rules).
166
+ - Changes are applied globally within seconds; no cache purge needed.
@@ -0,0 +1,52 @@
1
+ <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
2
+
3
+ ---
4
+ description: "Keep a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows."
5
+ ---
6
+
7
+
8
+ # docs-index-keeper
9
+
10
+ Use this skill when a repository keeps docs under `docs/` and needs a Markdown index table updated automatically as docs are added or changed.
11
+
12
+ ## Trigger phrases
13
+
14
+ - keep a docs index up to date
15
+ - auto-update `docs/README.md`
16
+ - add a pre-commit hook for docs indexing
17
+ - enforce docs index freshness in CI
18
+ - add a specific `docs/*.md` file into a Markdown index table
19
+
20
+ ## Workflow
21
+
22
+ 1. Confirm the repo has a docs directory and an index table such as `| Doc | Purpose |`.
23
+ 2. Install the package if it is not already present:
24
+
25
+ ```bash
26
+ npm install -D docs-index-keeper
27
+ ```
28
+
29
+ 3. Initialize the hook:
30
+
31
+ ```bash
32
+ npx docs-index-keeper init
33
+ ```
34
+
35
+ 4. For CI enforcement, run:
36
+
37
+ ```bash
38
+ npx docs-index-keeper check
39
+ ```
40
+
41
+ 5. For one-off staged maintenance, run:
42
+
43
+ ```bash
44
+ npx docs-index-keeper update
45
+ ```
46
+
47
+ ## Notes
48
+
49
+ - `update` operates on staged Markdown files.
50
+ - `check` exits non-zero when the index is missing entries for staged docs.
51
+ - Purpose text comes from the first Markdown heading when available.
52
+ - New rows are inserted before an archive sentinel row when present.
@@ -0,0 +1,100 @@
1
+ <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
2
+
3
+ ---
4
+ description: "Fill a portable music player with a curated random selection from a source music library while balancing formats, artists, albums, and capacity."
5
+ ---
6
+
7
+
8
+ # fill-music-player
9
+
10
+ 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.
11
+
12
+ ## Quick Reference
13
+
14
+ ```bash
15
+ # Dry run first (always recommend this)
16
+ fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC --dry-run
17
+
18
+ # Copy for real
19
+ fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC
20
+
21
+ # Or run the script directly with uv
22
+ uv run fill_music_player.py --source ~/Music --dest /Volumes/USB --dry-run
23
+ ```
24
+
25
+ Run `fill-music-player --help` for all options.
26
+
27
+ ## Key Parameters
28
+
29
+ | Flag | Default | Purpose |
30
+ |------|---------|---------|
31
+ | `--source` / `-s` | required | Source music root (NAS mount, ~/Music, etc.) |
32
+ | `--dest` / `-d` | required | Player destination directory |
33
+ | `--target-gb` | 95% of free space | How many GB to fill |
34
+ | `--formats` | mp3,m4a,wma,aac | Allowed extensions |
35
+ | `--max-per-artist` | 4 | Artist diversity cap |
36
+ | `--max-per-album` | 3 | Album diversity cap |
37
+ | `--skip-dirs` | (none) | Top-level dirs to skip |
38
+ | `--dry-run` | false | Preview without copying |
39
+
40
+ ## Workflow
41
+
42
+ 1. Always do `--dry-run` first
43
+ 2. Review the per-genre breakdown
44
+ 3. Adjust `--skip-dirs`, `--max-file-mb`, or `--max-per-artist` if needed
45
+ 4. Run without `--dry-run` to copy
46
+
47
+ ## Device Formats
48
+
49
+ | Device | Recommended `--formats` |
50
+ |--------|------------------------|
51
+ | Sony Walkman NWZ series | `mp3,m4a,wma` |
52
+ | iPod (classic/nano) | `mp3,m4a,aac` |
53
+ | Generic USB player | `mp3` |
54
+ | Any modern player | `mp3,m4a,wma,aac,ogg,flac` |
55
+
56
+ ## Edge Cases and Troubleshooting
57
+
58
+ | Situation | What happens | Fix |
59
+ |-----------|-------------|-----|
60
+ | 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()`) |
61
+ | Source has only FLAC/lossless | 0 files selected (FLAC not in default formats) | Use `--formats flac` or `--formats mp3,flac` |
62
+ | FAT32 filename too long or illegal chars | Filenames are sanitized: `<>:"/\|?*` replaced with `_`, truncated to 80 chars | Automatic — no action needed |
63
+ | Mixed/broken ID3 tags | Falls back to folder name parsing (`Genre/Artist - Album/track.mp3`) | Works transparently; folder structure is the reliable fallback |
64
+ | Very large files (DJ mixes, radio shows) | Skipped by default (>20 MB) | Adjust with `--max-file-mb 50` to include mixes |
65
+ | Tiny files (jingles, corrupt) | Skipped by default (<300 KB) | Adjust with `--min-file-kb 100` to be more permissive |
66
+ | One artist dominates the library | Capped at 4 tracks per artist, 3 per album | Lower with `--max-per-artist 2` for more variety |
67
+ | Empty genre directories | Silently skipped, no error | Normal behavior |
68
+ | Destination already has files | Existing files are not overwritten or deleted; new tracks added alongside | Clear destination first if you want a fresh set |
69
+ | 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 |
70
+
71
+ ## Real-World Example
72
+
73
+ 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:
74
+
75
+ ```bash
76
+ # Step 1: Preview
77
+ fill-music-player \
78
+ --source /Volumes/music \
79
+ --dest /Volumes/WALKMAN/MUSIC \
80
+ --skip-dirs "jingles,!recordings,!restored,dubrecords" \
81
+ --formats mp3,m4a,wma \
82
+ --dry-run
83
+
84
+ # Output:
85
+ # Found 8914 candidate tracks across 14 genres
86
+ # Funk → 86 tracks (440.8 MB)
87
+ # blues → 38 tracks (316.7 MB)
88
+ # hiphop → 33 tracks (234.7 MB)
89
+ # ...
90
+ # Selected 348 tracks (2473.0 MB)
91
+
92
+ # Step 2: Copy
93
+ fill-music-player \
94
+ --source /Volumes/music \
95
+ --dest /Volumes/WALKMAN/MUSIC \
96
+ --skip-dirs "jingles,!recordings,!restored,dubrecords" \
97
+ --formats mp3,m4a,wma
98
+ ```
99
+
100
+ 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.