skills/magnus919_agent-skills
1
0
Fork 0
mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): pin npx package versions in skill docs (Fixes #381)

Browse Source 
Pin copy-pasteable npx invocations to explicit versions so agents
executing them verbatim get reproducible behavior:

- playwright docs: npx playwright@1.62.1 (SKILL.md, README.md,
  references 02-selectors / 05-ci-integration / 07-accessibility)
- mermaid-diagrams: @mermaid-js/mermaid-cli@11.16.0 (SKILL.md,
  references/pdf-rendering-pipeline.md)
- hugo-theme seo-outputs-testing: @axe-core/cli@4.13.0
- agent-skills using-scripts.md: strengthen version-pinning bullet
  into a normative rule for copy-pasteable commands

Reword the anydoc cli-reference "Version pinning" prose so the
anti-pattern is explained didactically without presenting an unpinned
command as a recipe; the @0.1.6 house pin is unchanged.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
2026-08-22 22:07:49 -04:00
co-authored by factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
parent 688611ec15
commit b0845776a1
10 changed files with 27 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agent-skills/references/using-scripts.md
+1 -1
View File
@@ -47,7 +47,7 @@ When an existing package already does what you need, you can reference it direct
* Bundled with Node.js — no extra install needed.
* Downloads the package, runs it, and caches it for future use.
* Pin versions with `npx package@version` for reproducibility.
* **Pin versions for any command an agent will copy-paste** (`npx package@version`, e.g. `npx eslint@9.0.0`) so the command behaves the same over time — never leave a copy-pasteable `npx` invocation unpinned.
</Tab>
<Tab title="bunx">
anydoc/references/cli-reference.md
+5 -5
View File
@@ -112,11 +112,11 @@ curl -s https://example.com/paper.pdf | npx -y @firecrawl/anydoc@0.1.6 - # URL
### Version pinning
Always pin the version: `npx -y @firecrawl/anydoc@0.1.6`. An unpinned
`npx -y @firecrawl/anydoc` floats to the latest published tag, so conversions
are not reproducible across time. All behavior in this skill is documented
against **0.1.6**. The `-y` flag answers npx's "Ok to proceed?" install prompt
non-interactively; without it, bare `npx @firecrawl/anydoc` will prompt on a
cold cache.
invocation (`npx -y @firecrawl/anydoc` with no `@version` suffix) floats to the
latest published tag, so conversions are not reproducible across time. All
behavior in this skill is documented against **0.1.6**. The `-y` flag answers
npx's "Ok to proceed?" install prompt non-interactively — omitting it means npx
asks for confirmation before installing a cold-cache package.
### First run and offline behavior
hugo-theme/references/seo-outputs-testing.md
+2 -2
View File
@@ -305,7 +305,7 @@ jobs:
- name: Accessibility audit
run: |
npx @axe-core/cli http://localhost:1313/ --exit --stdout || true
npx @axe-core/cli@4.13.0 http://localhost:1313/ --exit --stdout || true
```
@@ -315,7 +315,7 @@ jobs:
|------|---------|-------------|
| `html5validator` | HTML spec compliance | `pip install html5validator` |
| `broken-link-checker` | Dead links | `npm install broken-link-checker` |
| `@axe-core/cli` | Accessibility | `npx @axe-core/cli` |
| `@axe-core/cli` | Accessibility | `npx @axe-core/cli@4.13.0` |
| `hugo --templateMetrics` | Template performance | Built-in CLI flag |
| `hugo --renderToMemory` | Build without writing to disk | `hugo --renderToMemory --gc` |
| `hugo mod verify` | Module integrity | Built-in |
mermaid-diagrams/SKILL.md
+4 -4
View File
@@ -33,7 +33,7 @@ Mermaid code blocks (```mermaid```) do NOT render in the Pandoc → HTML → Pup
**For any diagram destined for PDF output:**
1. Create the diagram as a standalone .mmd file
2. Pre-render to SVG: `npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg --width 800`
2. Pre-render to SVG: `npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg --width 800`
3. Choose one embedding method: use raw inline SVG by default, or base64 data URIs when the renderer corrupts raw SVG.
4. Strip hardcoded `max-width` pixel values from the SVG tags
5. Use `flowchart TD` (portrait) not `flowchart LR` (landscape) — see `references/portrait-layout.md`
@@ -116,9 +116,9 @@ See `references/c4-to-flowchart.md` for worked examples of all three C4 levels.
### CLI (mmdc) — for PDF/SVG/PNG output
```bash
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.pdf
npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg
npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.png
npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.pdf
```
Requires Puppeteer + Chromium (~1.7GB). Use the Docker image for isolated rendering:
mermaid-diagrams/references/pdf-rendering-pipeline.md
+1 -1
View File
@@ -8,7 +8,7 @@ This reference captures the lessons from a session where six PDF iterations were
```bash
# Step 1: Pre-render all Mermaid diagrams to SVG
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg --width 800
npx @mermaid-js/mermaid-cli@11.16.0 -i diagram.mmd -o diagram.svg --width 800
# Step 2: Embed SVGs in markdown (NOT as data URI img tags)
# Use raw <svg> tags inline in the markdown file
playwright/README.md
+3 -3
View File
@@ -30,11 +30,11 @@ bash scripts/pwrun report --report test-results/test-results.json --json
# Scaffold a new suite (copy the templates into your project)
cp templates/playwright.config.ts templates/example.spec.ts templates/accessibility.spec.ts .
npm i -D @playwright/test
npx playwright install
npx playwright test
npx playwright@1.62.1 install
npx playwright@1.62.1 test
```
The `--help` output documents every flag and works without Node. Set `BASE_URL` to override the smoke target; `scripts/pwrun smoke --url http://localhost:3000 --json` runs a delegated pass through `npx playwright test`.
The `--help` output documents every flag and works without Node. Set `BASE_URL` to override the smoke target; `scripts/pwrun smoke --url http://localhost:3000 --json` runs a delegated pass through `npx playwright@1.62.1 test`.
## Triggers
playwright/SKILL.md
+3 -3
View File
@@ -75,7 +75,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig
## CI integration
- Install browsers and OS deps on the runner (`npx playwright install --with-deps`), pin the Playwright version, and cache `~/.cache/ms-playwright`.
- Install browsers and OS deps on the runner (`npx playwright@1.62.1 install --with-deps`), pin the Playwright version, and cache `~/.cache/ms-playwright`.
- Configure `webServer`, `retries` (retry flaky tests on CI only), and `trace: 'on-first-retry'` so failures are debuggable. Report with `html`/`json`/`github` and upload artifacts on failure.
- Triage CI failures from the JSON report with `scripts/pwrun report --json` — it summarizes stats, failing specs, and error messages without opening a browser. Full CI recipes: `references/05-ci-integration.md`.
@@ -94,7 +94,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig
## Headed debugging
- Run headed (`--headed`), slow the action with `--slow-mo`, or drop into the inspector with `--debug` / `PWDEBUG=1` and the `page.pause()` breakpoint.
- Generate starter tests with `npx playwright codegen <url>`, then harden the generated selectors into user-facing locators.
- Generate starter tests with `npx playwright@1.62.1 codegen <url>`, then harden the generated selectors into user-facing locators.
- When a test fails: read the trace (`--trace on`), which records network, DOM snapshots, and console for the failed action. Use `scripts/pwrun report --report <json> --json` first to see the failure summary.
- Debugging workflows live in `references/07-accessibility-and-debugging.md`.
@@ -124,7 +124,7 @@ Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwrig
|---|---|
| Toolchain is present | `scripts/pwrun doctor --json` reports node, @playwright/test, and browsers available |
| Suite is understood | `scripts/pwrun inventory --json` lists config and spec files |
| A test passes | `npx playwright test` exit 0 on the targeted spec (or `smoke` delegation) |
| A test passes | `npx playwright@1.62.1 test` exit 0 on the targeted spec (or `smoke` delegation) |
| A CI failure is explained | `scripts/pwrun report --report test-results.json --json` names the failing specs and errors |
| Accessibility is covered | An axe scan runs with zero violations of the declared severity, and aria snapshots match |
| No regressions in the covered flows | The suite ran under the configured workers/sharding with expected/flaky/unexpected counts recorded |
playwright/references/02-selectors.md
+1 -1
View File
@@ -43,7 +43,7 @@ await card.getByRole('button', { name: 'Add to cart' }).click();
A flaky test is a bug report about your selectors, not a request for more
`waitForTimeout`. When a test passes sometimes:
1. Run the spec alone (`npx playwright test <spec> --workers=1 --repeat-each=5`)
1. Run the spec alone (`npx playwright@1.62.1 test <spec> --workers=1 --repeat-each=5`)
to measure flakiness deterministically.
2. Use `--debug` or the trace to see what the failing action actually resolved.
Common causes:
playwright/references/05-ci-integration.md
+4 -4
View File
@@ -19,8 +19,8 @@ jobs:
- uses: actions/setup-node@v4
with: { node-version: 20, cache: npm }
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx playwright test
- run: npx playwright@1.62.1 install --with-deps chromium
- run: npx playwright@1.62.1 test
- if: failure()
uses: actions/upload-artifact@v4
with:
@@ -31,7 +31,7 @@ jobs:
## Non-negotiables
1. **Install browsers with OS deps**: `npx playwright install --with-deps` (not
1. **Install browsers with OS deps**: `npx playwright@1.62.1 install --with-deps` (not
bare `install`) on Linux runners; `--with-deps` installs the system
libraries Chromium/Firefox/WebKit need.
2. **Pin and cache**:
@@ -77,7 +77,7 @@ strategy:
matrix:
shard: [1/4, 2/4, 3/4, 4/4]
steps:
- run: npx playwright test --shard=${{ matrix.shard }}
- run: npx playwright@1.62.1 test --shard=${{ matrix.shard }}
```
Merge reports from all shards with `playwright merge-reports` (see
playwright/references/07-accessibility-and-debugging.md
+3 -3
View File
@@ -42,7 +42,7 @@ await expect(page).toMatchAriaSnapshot(`
- These read like spec assertions ("the heading is X, the button is Y") and
catch regressions in structure, labels, and semantics — not just contrast.
- They are stable: inline text changes show up as a reviewable diff.
- **Update deliberately.** Run `npx playwright test --update-snapshots` only
- **Update deliberately.** Run `npx playwright@1.62.1 test --update-snapshots` only
after inspecting what changed; never blind-update to make CI green (hard
boundary in `SKILL.md`).
- Requires Playwright 1.49+ (see `00-source-index.md` for version notes).
@@ -56,14 +56,14 @@ When a test fails or a locator matches nothing:
2. **Run headed with slow-mo** to watch the actual page:
```bash
npx playwright test <spec> --headed --slow-mo 300
npx playwright@1.62.1 test <spec> --headed --slow-mo 300
```
3. **The inspector** (`--debug` or `PWDEBUG=1`) pauses before each action and
shows the current locator; `page.pause()` drops a breakpoint mid-test.
4. **Codegen** to prototype a flow quickly:
```bash
npx playwright codegen https://example.com
npx playwright@1.62.1 codegen https://example.com
```
Generate starter tests, then harden the emitted selectors into user-facing
locators (`02-selectors.md`).