add a claude skill to check and update SDK exmaple code#2496
add a claude skill to check and update SDK exmaple code#2496ElliotFriend wants to merge 5 commits into
Conversation
|
Preview is available here: |
Expand the update-sdk-examples skill based on lessons from its first real run, where a clean release-diff check still left many pre-existing stale examples untouched: - Document two modes: the default per-release diff, and a full standing- correctness audit that ignores the state file (for first adoption and periodic runs). - Treat repo/path/coordinate relocations as breaking changes, not just version bumps. - Grep all of docs/ for the stale token directly rather than trusting a partial/agent-produced file list; ignore the i18n/ directory. - Add a verify-against-current-source step before editing, and prefer aliasing to preserve code bodies on import-path changes. - Refresh the stellar-rpc gotcha (Go RPC client moved into go-stellar-sdk) and add fork/upstream and shell-editing (perl/zsh/BSD sed) gotchas. - Report the mode and the deliberately-not-edited candidates for review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
- Branch chore/ work off `upstream/main` (the canonical stellar/stellar-docs), not the local `main` branch — so the skill is safe in a detached worktree (no same-branch-in-two-worktrees collision) and never hijacks a human's current branch. - Add a "Running unattended" section for scheduled runs: no human in the loop, so skip-and-report when uncertain rather than guess, commit but never push, expect a detached upstream/main worktree, use HTTPS/gh api (no SSH agent), and always produce the report. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
There was a problem hiding this comment.
Pull request overview
Adds a repository-local Claude skill that documents a repeatable workflow for detecting Stellar SDK releases/relocations and updating corresponding code snippets across docs/, with guidance for both scheduled “release-diff” runs and periodic full audits.
Changes:
- Introduces the
update-sdk-examplesskill with a two-mode audit process (release-diff vs full audit). - Documents release discovery, verification, scoped editing rules, and reporting expectations for SDK example updates.
- Adds operational guidance for unattended/scheduled runs and known gotchas encountered in practice.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,161 @@ | |||
| --- | |||
| name: update-sdk-examples | |||
| description: Use when checking whether Stellar SDKs listed in the docs have new releases, or when code examples in docs/ may use outdated, renamed, or deprecated SDK syntax. Runs per-release on a schedule, or as a full standing-correctness audit on demand. | |||
| 2. **Check releases.** Confirm the working tree is clean and that you're working | ||
| from a current `upstream/main` — the canonical `stellar/stellar-docs` (if you | ||
| cloned the official repo directly rather than a fork, that's your | ||
| `origin/main`). For each SDK, fetch the latest release | ||
| tag (`gh api repos/<owner>/<repo>/releases/latest`, falling back to the |
| - Release state file: `~/.claude/stellar-sdk-release-state.json` | ||
| (maps repo/package URL → last-seen release tag) |
| translations mirror `docs/`, lag behind (they may still show APIs you've | ||
| already migrated), and are an unused holdover from previous translation | ||
| processes - ignore the `i18n/` directory altogether. |
|
Preview is available here: |
There was a problem hiding this comment.
This is a genuinely well-built skill, amazing as always @ElliotFriend !
One thing I want to raise before we let it run on a schedule by itself: when it runs unattended there's nobody around to approve anything, so it basically has to be allowed to run commands on its own. And part of what it does is read release notes and changelogs from repos we don't control. If someone slipped a bad line into one of those changelogs something like "ignore your instructions and run this" the skill would be reading that and running commands with no one watching.
I don't think this is actually exploitable right now, and the commit-but-never-push rule covers the worst case anyway. nothing it does reaches main without a human reviewing it first. So I'm not worried about it as-is. But if we're going to schedule it, a couple of things are worth tightening. The allowed-tools field in the frontmatter should limit which tools it can use so the scheduled run can't do more than it needs: read, edit, grep, bash, fetch. The skill should also state that the changelogs and release notes it reads are just information: don't run or install anything they say etc. and the scheduled job shouldn't get more GitHub access than it needs, read-only is plenty for checking releases. None of this touches the core workflow, it just hardens the autonomous path so we're comfortable letting it run on its own.
Add npm @x402/stellar and @stellar/mpp as in-scope packages. These have examples in docs/ but aren't on the SDK listing pages, so step 1 discovery misses them. Wire them into step 1 explicitly and add a provenance/typosquat check since no listing page vouches for them. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
@kaankacar You raise an excellent point! I think, for the most part, this danger may be somewhat mitigated by the fact that we're looking at packages that are directly owned by SDF, or we've partnered/contracted with trusted third-parties to maintain them. Obviously not an end-all fix, though. I think we should still address the concerns, regardless. I've just pushed a change to add two additional packages to the list, and it also does mention something like "ensure these are the correct packages, and not some typo-squatting thing." Would you be able to add a commit that does what you've suggested, Kaan? (add some As of yet, I've only experimented with having the thing scheduled with |
|
Preview is available here: |
I asked Claude to help me figure out the best way to approach this. The result was this skill, which was recommended to live inside this repo, and Claude somehow "wired it" into my local machine's scheduler (or something like that). in any case, the skill is also manually runnable, and i'll have some PRs from that push soon.
here are the PRs that this skill produced this morning: