docs(skills): rework setup-skillx with dry-run mode and full URLs#24
Merged
docs(skills): rework setup-skillx with dry-run mode and full URLs#24
Conversation
…l skills - Emit full repo URLs (e.g. `https://github.com/.../tree/main/...`) instead of the `github:` shorthand, matching the Famous Skills convention and giving README readers a clickable link. - Add a Dry-Run mode: detect cues like `dry run` / `preview only` / `--dry-run`, show all diffs, and skip every write. Step 5 splits Apply vs Dry-Run summary. - Handle conversational / wizard-style skills (no natural prompt) by dropping the trailing quoted argument so the command becomes `skillx run <source>`. - Strengthen sample-prompt guidance: verb-first, concrete, not a paraphrase of the skill's description; include good/bad examples. - Cover missing or malformed frontmatter in Edge Cases. - Suggest pinning to a release tag when the repo has published ones. - Relax the "no network requests" safety line to "no installers / install-type actions"; read-only git inspections are in scope. - Recommend a smoke-test run of the generated command in Step 5. - Remove the dead `<skill-name>` placeholder in Step 3.2. - Bump version to 1.1.0. Sync advertise-your-skill.md to match.
Preview DeploymentThis PR has been deployed to Cloudflare Pages: |
added 2 commits
April 19, 2026 12:11
…e, batch approval - Scope: state explicitly that the skill works against the user's cwd, not some external repo. Prevents an agent from fetching / cloning by default. - Step 2 <ref>: replace `.git/HEAD` (which tracks the current checkout) with `git symbolic-ref refs/remotes/origin/HEAD` / `git remote show origin`, so running from a feature branch no longer emits a feature-branch URL. Default `main` is now a last-resort fallback. - Step 1.3: handle multiple git remotes (prefer `origin`, ask when a fork has `upstream`) and git-submodule skills (run `git remote -v` from the skill's own directory). - Step 1.5: announce detected skills / host / remote / READMEs / locales before writing, so users can spot a missing locale or wrong remote. - Step 3 approval granularity: offer per-file (default) or batch approval when multiple files would be touched. - Step 3.5: explicit insertion-point fallback for title-less READMEs and for READMEs with no `##` sections at all. - Idempotency Rules: "update by marker, not by position" — if the user moved the marked block, keep it there instead of re-inserting at the Step 3.5 default. - Edge Cases: add language-detection rules for READMEs (filename suffix first, ask on ambiguity). - Bump to v1.2.0.
- Safety Guarantees: broaden "read-only local inspections" to cover the lightweight `git remote show origin` metadata probe used for default-branch detection. Still excludes any fetch/clone/download (I-4). - Step 2 <ref>: restructure as explicit 3-tier fallback. Local `git symbolic-ref refs/remotes/origin/HEAD` first, then remote probe (with user notice, since it touches the network), finally ask or default to `main`. Handles `git init` + `git remote add` repos where the symbolic ref was never set (I-1). - Step 1.3 submodule bullet: add detection criteria up front (.gitmodules / `git submodule status` / `.git` file pointing to gitdir). Clarify that a plain subdirectory has no remote of its own and should keep using the parent repo's (I-3). - Idempotency Rules: replace ambiguous "Step 3.5 default location" reference with prose pointing to "the default insertion point from Step 3" (I-2).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
setup-skillxnow emitshttps://<host>/<owner>/<repo>/tree/<ref>/<path>instead of thegithub:shorthand, matching the Famous Skills convention and giving README readers a clickable link. Includes a per-host URL-shape table (GitHub/GitLab/Bitbucket/Gitea/SourceHut) and an opt-in tag-pin suggestion.## Modessection. Cues likedry run,preview only,--dry-run,SKILLX_DRY_RUN=1run the full workflow, show every diff, and skip all writes. Step 5 now has split Apply / Dry-Run summary templates.skillx run <source>. Added as a first-class Step 3 branch and an Edge Case.description; good/bad examples inline.git remote -v).<skill-name>placeholder, bump tov1.1.0.web/src/content/docs/guides/advertise-your-skill.mdupdated to match (full URL in both examples, dry-run usage hint, conversational-skill scenario, safety wording).Test plan
skillx scan skills/setup-skillx— PASScargo test --test e2e_tests test_scan_firstparty_setup_skillx— passnpm run check:famous-skills(web smoke) — passnpm run check:homepage(web smoke) — passadvertise-your-skillpage on the Cloudflare Pages preview