diff --git a/.agents/skills/usethis-skills-external-add/SKILL.md b/.agents/skills/usethis-skills-external-add/SKILL.md index 36974ef6..77b52861 100644 --- a/.agents/skills/usethis-skills-external-add/SKILL.md +++ b/.agents/skills/usethis-skills-external-add/SKILL.md @@ -4,7 +4,7 @@ description: Add an external (community) skill to the project from a third-party compatibility: usethis, agent skills, npx, markdown license: MIT metadata: - version: "1.0" + version: "1.1" --- # Adding External Skills @@ -13,14 +13,23 @@ External skills are sourced from third-party repositories rather than written lo ## Procedure -1. Install the skills using `npx skills add --skill '*' --agent github-copilot --yes` (e.g. `npx skills add CodSpeedHQ/codspeed --skill '*' --agent github-copilot --yes`). -2. Note the skill name(s) added to `skills-lock.json`. -3. Add each new skill to the external skills registry in `AGENTS.md`. -4. Verify the hook passes: `python hooks/check-skills-documented.py`. +1. Set the line-ending environment variables (see "Line endings and reproducible hashes" below). +2. Install the skills using `npx skills add --skill '*' --agent github-copilot --yes` (e.g. `npx skills add CodSpeedHQ/codspeed --skill '*' --agent github-copilot --yes`). +3. Note the skill name(s) added to `skills-lock.json`. +4. Add each new skill to the external skills registry in `AGENTS.md`. +5. Verify the hook passes: `python hooks/check-skills-documented.py`. + +## Line endings and reproducible hashes + +Due to a [bug in the skills CLI](https://github.com/vercel-labs/skills/issues/781), `computedHash` values in `skills-lock.json` differ depending on git's `core.autocrlf` setting. To produce reproducible hashes, **always** set the following environment variables when running any `npx skills` command: + +- `GIT_CONFIG_COUNT=1` +- `GIT_CONFIG_KEY_0=core.autocrlf` +- `GIT_CONFIG_VALUE_0=false` ## Installing the skill -To **add a new** external skill, run from the repository root: +To **add a new** external skill, run from the repository root (with the line-ending environment variables set as described above): ```commandline npx skills add / --skill '*' --agent github-copilot --yes @@ -28,12 +37,6 @@ npx skills add / --skill '*' --agent github-copilot --yes This adds the skill entry to `skills-lock.json`. Multiple skills may be added from a single source. -To **reinstall** already-tracked external skills that are not present locally (e.g. after a fresh clone): - -```commandline -npx skills experimental_install -``` - ## Documenting in AGENTS.md After installing, add a row to the external skills table in the "External skills" section of `AGENTS.md`: diff --git a/.agents/skills/usethis-skills-external-install/SKILL.md b/.agents/skills/usethis-skills-external-install/SKILL.md new file mode 100644 index 00000000..1e7200bc --- /dev/null +++ b/.agents/skills/usethis-skills-external-install/SKILL.md @@ -0,0 +1,26 @@ +--- +name: usethis-skills-external-install +description: Reinstall already-tracked external skills from skills-lock.json (e.g. after a fresh clone) +compatibility: usethis, agent skills, npx +license: MIT +metadata: + version: "1.0" +--- + +# Installing External Skills + +External skills tracked in `skills-lock.json` may not be present locally (e.g. after a fresh clone, since skill files are gitignored). This skill describes how to restore them. + +## Procedure + +1. Set the line-ending environment variables to ensure reproducible hashes (see below). +2. Run `npx skills experimental_install` from the repository root. +3. Verify `skills-lock.json` is unchanged (e.g. `git diff --exit-code skills-lock.json`). + +## Line endings and reproducible hashes + +Due to a [bug in the skills CLI](https://github.com/vercel-labs/skills/issues/781), `computedHash` values in `skills-lock.json` differ depending on git's `core.autocrlf` setting. To produce reproducible hashes, **always** set the following environment variables when running any `npx skills` command: + +- `GIT_CONFIG_COUNT=1` +- `GIT_CONFIG_KEY_0=core.autocrlf` +- `GIT_CONFIG_VALUE_0=false` diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index e64d88c7..6d3752b5 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -28,9 +28,14 @@ jobs: - name: Set up Node.js uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0 + with: + cache: "npm" + cache-dependency-path: ".github/workflows/copilot-setup-steps.yml" - name: Install external agent skills - run: npx skills experimental_install + run: | + npx skills experimental_install + git diff --exit-code skills-lock.json - name: Setup dependencies run: uv sync diff --git a/AGENTS.md b/AGENTS.md index d0052d95..1684ee30 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,12 +35,13 @@ The `.agents/skills` directory contains agent skills. | `usethis-qa-static-checks` | Perform static code checks | | `usethis-skills-create` | Create new agent skills (SKILL.md files) following best practices for content quality, structure, and discoverability | | `usethis-skills-external-add` | Add an external (community) skill and document it in AGENTS.md | +| `usethis-skills-external-install` | Install/reinstall already-tracked external skills from skills-lock.json (e.g. after a fresh clone) | | `usethis-skills-modify` | Modify agent skills (SKILL.md files) | | `usethis-test-with-coverage` | Write tests that achieve full code coverage and verify coverage locally before pushing | #### External skills -External skills can be installed via `npx skills experimental_install` if they are not present. +External skills can be installed if they are not present — see the `usethis-skills-external-install` skill. | Skill | Source | Description | | ------------------------ | --------------------- | ----------------------------------------------------------------------- | diff --git a/skills-lock.json b/skills-lock.json index f872e1be..7d483607 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -4,12 +4,12 @@ "codspeed-optimize": { "source": "CodSpeedHQ/codspeed", "sourceType": "github", - "computedHash": "7645f43a7a8ca9705a9a8e7367ac1f4ad9d8822ba94230e2b38381c05957d5c5" + "computedHash": "8521003ae5faf606e129f18139fa6eb401821c41f8948dd8e45f0db8d40e46b3" }, "codspeed-setup-harness": { "source": "CodSpeedHQ/codspeed", "sourceType": "github", - "computedHash": "bd861b140b75372438d0dbbf5b697e563a80d567bc8bb2b3f2880cdfe41ef27f" + "computedHash": "587a58bc7498635347ee7a7eba66ac17c75430db7543be4af7eaab74533a6714" } } }