askaipods: Instructions file for Claude Code

askaipods — project instructions

A zero-dependency npm CLI (askaipods) and companion agentskills.io skill that wraps the podlens.net semantic search API, returning recent quote excerpts from 80+ AI-centred podcasts. Distributed as a global CLI via npx / npm install and as a skill drop-in under each runtime's skills/ directory (~/.claude/skills/, ~/.agents/skills/ for Codex and OpenClaw, ~/.openclaw/skills/, ~/.hermes/skills/). README holds the authoritative per-runtime path table.

Release notes style

GitHub release notes describe what changed, not how the change was arrived at. Do not mention Codex quality review rounds (R1, R2, ...), plugin-dev:skill-reviewer passes, /verify scans, /code-audit iterations, model identifiers, rejected-finding references, round counts, or "quality gates passed" sections. Include: features, fixes, contract changes, user-facing string changes, breaking changes, honest limitations, migration notes, and deferred scope for the next release (named in plain English, without review artifacts).

Release notes are written for npm / GitHub consumers, not for internal project history. The v0.2.3 and v0.2.4 release notes are the cleanest style templates.

This rule applies to the GitHub release body only — not to git commit messages (where referencing the review process for internal repo history is fine) and not to internal review transcripts.

Release workflow

1. Bump the version in four locations (all four must match, every time; npm test enforces it):
   • package.json "version"
   • skill/askaipods/scripts/cli.mjs const VERSION = "..."
   • skill/askaipods/scripts/client.mjs User-Agent header string
   • skill/askaipods/SKILL.md pinned fallback npx -y [email protected]
2. Recapture the README hero (the sample output at the top of README.md) in the same commit, so episode titles and results do not drift. Re-run its command and replace the block with the new real output — never hand-edit titles, dates or quotes; soft-wrapping quote lines is the only allowed change. Prefer an anonymous capture (no key, no --days) so the header reads Tier: anonymous; when the IP's anonymous quota is used up, capture with a key plus --days 30 and keep the command line and the italic note under the block saying so. Update the capture date in that note. If the top results have gone off-topic, pick a new query rather than trimming the list.
3. Commit and push to main. The .github/workflows/auto-tag.yml workflow watches package.json changes on main; when the version field changes and the tag does not already exist, it creates and pushes the vX.Y.Z tag. Whenever the version changes and no release exists for that tag yet, it also publishes a placeholder GitHub release (title = tag, auto-generated notes) so the "Latest" release never lags the newest tag.
4. Replace the placeholder release notes with gh release edit vX.Y.Z --title "vX.Y.Z — <short descriptor>" --notes "$(cat <<'EOF' ... EOF)", following the §Release notes style rule above. If the workflow failed to create the release, use gh release create with the same arguments instead. Do not delete-and-recreate (URLs break, subscribers re-notified).
5. Publish to npm (npm publish) right after the push if the release is a source change — skip npm publish for release-note-only corrections. Do not leave a gap: SKILL.md's fallback pins [email protected], which fails for anyone pulling main until that version is on npm. Authenticate interactively (npm login --auth-type=web) and complete the 2FA prompt on publish; do not store a long-lived publish token in ~/.npmrc — npm is removing direct-publish rights from 2FA-bypass granular tokens (January 2027). The 2FA step needs the user, so Claude hands this command to the user rather than running it.