Skip to content
Back to search

skills

Agent skills by mizchi, distributed via APM

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mizchi/skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mizchi/skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mizchi--skills/badge.svg)](/listings/mizchi--skills)

HTML

<a href="/listings/mizchi--skills"><img src="/api/listings/mizchi--skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install an individual skill (global / user scope):

apm install -g mizchi/skills/<skill-name>

Or add to a project's `apm.yml`:

dependencies:
  apm:
    - mizchi/skills/<skill-name>

Pin to a tag:

apm install -g mizchi/skills/<skill-name>#v0.1.0

These follow the open [Agent Skills](https://agentskills.io) format, so any compatible agent (Claude Code, Codex, opencode, Gemini CLI, Cursor, …) can use them without APM. Each skill's README shows a `npx skills add` command (the [`skills`](https://github.com/vercel-labs/skills) CLI, installs into every detected agent) and a raw `npx degit` folder copy as alternatives:

npx skills add mizchi/skills --skill <skill-name>

Every skill directory carries its own `README.md` with copy-paste install examples, generated from the skill's `SKILL.md` frontmatter. Regenerate them all after editing any frontmatter:

pkf run gen:readme     # write / sync every skill README
pkf run check:readme   # CI: verify they are in sync

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 319 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # mizchi/skills
  2. A collection of agent skills maintained by [@mizchi](https://github.com/mizchi), distributed via [APM](https://github.com/microsoft/apm) (Agent Package Manager).
  3. Each directory is a standalone skill following the [agentskills.io](https://agentskills.io/specification) open standard.
  4. ## Install
  5. Install an individual skill (global / user scope):
  6. ```sh
  7. apm install -g mizchi/skills/<skill-name>
  8. ```
  9. Or add to a project's `apm.yml`:
  10. ```yaml
  11. dependencies:
  12. apm:
  13. - mizchi/skills/<skill-name>
  14. ```
  15. Pin to a tag:
  16. ```sh
  17. apm install -g mizchi/skills/<skill-name>#v0.1.0
  18. ```
  19. These follow the open [Agent Skills](https://agentskills.io) format, so any
  20. compatible agent (Claude Code, Codex, opencode, Gemini CLI, Cursor, …) can use
  21. them without APM. Each skill's README shows a `npx skills add` command (the
  22. [`skills`](https://github.com/vercel-labs/skills) CLI, installs into every
  23. detected agent) and a raw `npx degit` folder copy as alternatives:
  24. ```sh
  25. npx skills add mizchi/skills --skill <skill-name>
  26. ```
  27. Every skill directory carries its own `README.md` with copy-paste install
  28. examples, generated from the skill's `SKILL.md` frontmatter. Regenerate them all
  29. after editing any frontmatter:
  30. ```sh
  31. pkf run gen:readme # write / sync every skill README
  32. pkf run check:readme # CI: verify they are in sync
  33. ```
  34. ## Skills
  35. ### Frontend
  36. A toolkit for frontend consulting engagements. Install skills from `mizchi/skills/<skill-name>`.
  37. | Skill | Install path | Description |
  38. | --- | --- | --- |
  39. | [frontend-review-triage](frontend-review-triage/) | `frontend-review-triage` | Day 0 initial assessment — scorecard, top 3 risks, app classification. |
  40. | [frontend-review-ci](frontend-review-ci/) | `frontend-review-ci` | CI timing analysis — bottleneck identification, sharding/cache/concurrency recommendations. |
  41. | [frontend-review-hygiene](frontend-review-hygiene/) | `frontend-review-hygiene` | Code quality — TypeScript strictness, lint, dead code, duplication. |
  42. | [frontend-review-deps](frontend-review-deps/) | `frontend-review-deps` | Dependency health — freshness, CVE triage with attack-vector weighting, Tier 1/2/3 library detection. |
  43. | [frontend-review-testing](frontend-review-testing/) | `frontend-review-testing` | Testing posture — vitest coverage, Playwright config, VRT setup. |
  44. | [frontend-review-security](frontend-review-security/) | `frontend-review-security` | Security review — HTML sinks, auth/token storage, route guards, env var exposure, AI self-pentest. |
  45. | [frontend-review-state](frontend-review-state/) | `frontend-review-state` | State management architecture — server/URL/form/UI classification, Jotai/Zustand/Redux anti-patterns. |
  46. | [frontend-review-performance](frontend-review-performance/) | `frontend-review-performance` | Rendering performance — profiler-first, memo correctness, virtual scroll, useTransition. |
  47. | [frontend-review-weekly](frontend-review-weekly/) | `frontend-review-weekly` | Weekly orchestrator — runs all domain skills, diffs KPIs, files repeat-finding issues. |
  48. Perspective sub-skills (invoked by `frontend-review-weekly`): `frontend-expert`, `react-expert`, `performance-expert`, `security-expert`, `frontend-ops-expert`.
  49. ### Node.js
  50. | Skill | Install path | Description |
  51. | --- | --- | --- |
  52. | [node-sqlite-vec](node-sqlite-vec/) | `node-sqlite-vec` | Combine Node 24+ `node:sqlite` with the `sqlite-vec` extension — extension load, vec0 BigInt rowids, why vitest fails, CLI shebang. |
  53. | [pi-coding-agent](pi-coding-agent/) | `pi-coding-agent` | Embed `@mariozechner/pi-coding-agent` as a coding-agent runtime in Node scripts, write pi extensions (plugins) with `pi.registerTool` / `pi.on`, package and `pi install` from npm/git, SDK vs `pi --mode rpc`. |
  54. ### AWS
  55. | Skill | Install path | Description |
  56. | --- | --- | --- |
  57. | [aws-ecs-codedeploy-blue-green](aws-ecs-codedeploy-blue-green/) | `aws-ecs-codedeploy-blue-green` | ECS blue/green — recommends ALB-native weighted routing; covers CodeDeploy for teams already using it. |
  58. | [aws-ecs-service-connect-ipv6](aws-ecs-service-connect-ipv6/) | `aws-ecs-service-connect-ipv6` | Diagnose and work around ECS Service Connect DNS aliases returning IPv6 addresses to IPv4-only Fargate tasks. |
  59. | [aws-github-oidc-scoped-role](aws-github-oidc-scoped-role/) | `aws-github-oidc-scoped-role` | GitHub Actions OIDC trust pattern — `job_workflow_ref` scoping vs `sub` alone, Bedrock cross-region inference ARNs, required `aws-marketplace` permissions, ReadOnlyAccess + explicit Deny for AI agent roles. |
  60. | [aws-vault-mfa-iam](aws-vault-mfa-iam/) | `aws-vault-mfa-iam` | Configure aws-vault for IAM APIs blocked by MFA-required policies; FIDO2 passkey + virtual TOTP setup. |
  61. ### Cloudflare
  62. | Skill | Install path | Description |
  63. | --- | --- | --- |
  64. | [void-app](void-app/) | `void-app` | Build full-stack apps with Void and Vite+ — React Pages, typed loaders/actions/forms, D1 migrations, tests, and deployment. [日本語チートシート](void-app/SKILL-ja.md) |
  65. | [cloudflare-deploy](cloudflare-deploy/) | `cloudflare-deploy` | Deploy Workers and platform resources through cf and typed configuration. |
  66. | [cloudflare-access-app-setup](cloudflare-access-app-setup/) | `cloudflare-access-app-setup` | One-shot Cloudflare Access self-hosted application provisioning via the API — app + email allowlist policy + service token. |
  67. | [cloudflare-workers-otel-utels](cloudflare-workers-otel-utels/) | `cloudflare-workers-otel-utels` | Cloudflare Worker telemetry — OTLP traces / metrics / logs + utels error tracking + D1 Proxy slow-query warnings. |
  68. | [cloudflare-mbt-worker-bundle](cloudflare-mbt-worker-bundle/) | `cloudflare-mbt-worker-bundle` | Bundle a Cloudflare Worker that combines MoonBit core code with a TypeScript entry. |
  69. ### SQL
  70. | Skill | Install path | Description |
  71. | --- | --- | --- |
  72. | [sql-lint](sql-lint/) | `sql-lint` | Static lint for sqlc-style SQL catalogs — duplicate query names, missing semicolons, SELECT *, double-wildcard LIKE. |
  73. | [sql-plan-audit](sql-plan-audit/) | `sql-plan-audit` | Run EXPLAIN QUERY PLAN against every query in a sqlc catalog and diff plans against baseline. |
  74. | [sql-schema-audit](sql-schema-audit/) | `sql-schema-audit` | Index coverage and N+1 review aids for SQLite/D1 schemas with a sqlc catalog. |
  75. | [sql-security](sql-security/) | `sql-security` | SQL injection screening for host code (MoonBit / TS / Rust) plus secretlint setup notes. |
  76. | [sqlc-gen-moonbit-safety](sqlc-gen-moonbit-safety/) | `sqlc-gen-moonbit-safety` | Post-generation safety checks for sqlc-gen-moonbit + Cloudflare D1 — BigInt-bind hangs (D1 1101) and SQL placeholder mix. |
  77. ### Languages
  78. | Skill | Install path | Description |
  79. | --- | --- | --- |
  80. | [moonbit-practice](moonbit-practice/) | `moonbit-practice` | MoonBit code generation best practices — syntax, tests, benchmarks, FFI, Nix, mbtx. |
  81. | [moonbit-js-binding](moonbit-js-binding/) | `moonbit-js-binding` | Write MoonBit bindings to JavaScript with `extern "js"` (Promises, opaque types, esm/cjs/iife). |
  82. | [gleam-practice](gleam-practice/) | `gleam-practice` | Build and review Gleam projects on the Erlang target (Wisp + Mist, OTP, just, CI). |
  83. | [translate-programming-language](translate-programming-language/) | `translate-programming-language` | Plan and execute language-to-language migrations with behavior parity — oracles, fixtures, parity tests, compatibility layers. |
  84. | [ts2moonbit-migration](ts2moonbit-migration/) | `ts2moonbit-migration` | Migrate TypeScript to MoonBit on the `js` target — JS-compatible exported boundary over an idiomatic MoonBit core, using mizchi/js, mizchi/x, mizchi/npm_typed; contract capture, type classification, `.d.ts` diff gate, parity verification. |
  85. ### Graphics / GPU
  86. | Skill | Install path | Description |
  87. | --- | --- | --- |
  88. | [metal-practice](metal-practice/) | `metal-practice` | Apple Metal rendering and compute — MetalKit, shader ABI, resource synchronization, Metal 4, GPU validation and profiling. |
  89. ### Testing / Browser
  90. | Skill | Install path | Description |
  91. | --- | --- | --- |
  92. | [playwright-cli](playwright-cli/) | `playwright-cli` | Run Playwright via terminal CLI (test runner, codegen, screenshot, CI sharding). |
  93. | [stryker-js](stryker-js/) | `stryker-js` | Measure JavaScript/TypeScript test quality with StrykerJS; run Git diff mutations in CI and use surviving mutants to improve assertions locally. Includes setup snippets and AI-readable reports. |
  94. | [playwright-test](playwright-test/) | `playwright-test` | Playwright Test (E2E) best practices — no fixed waits, network triggers, DnD, CI sharding/retry. |
  95. ### AI / VLM
  96. | Skill | Install path | Description |
  97. | --- | --- | --- |
  98. | [review-image](review-image/) | `review-image` | Review screenshots or generated images with OpenRouter vision models via Deno scripts; includes a strict CI `pass|fail` wrapper for VRT prechecks. |
  99. | [vlmkit](vlmkit/) | `vlmkit` | Entry-point for `@mizchi/vlmkit` — VLM-driven frontend toolkit (visual regression, markup synthesis from screenshots, design-token / theme / a11y / i18n audits, 2-stage VLM+LLM CSS auto-repair). Routes to 5 detailed sub-skills shipped under the vlmkit repo's `.claude/skills/`. |
  100. ### Formal Methods
  101. | Skill | Install path | Description |
  102. | --- | --- | --- |
  103. | [formal-methods-reconciler](formal-methods-reconciler/) | `formal-methods-reconciler` | Reconcile specs, docs, code, tests, config, logs, and incidents with formal-methods checks; choose Z3 / Alloy / TLA+ / P / Dafny / MoonBit prove / Lean / Rocq and translate counterexamples into domain questions. |
  104. | [formal-methods-drift-guard](formal-methods-drift-guard/) | `formal-methods-drift-guard` | Maintain existing formal models by checking spec/code/model drift, classifying stale claims, and translating verifier changes into domain questions. |
  105. ### Tooling / Infra
  106. | Skill | Install path | Description |
  107. | --- | --- | --- |
  108. | [apm-usage](apm-usage/) | `apm-usage` | Use APM (Agent Package Manager) to manage agent skills and dependencies. |
  109. | [ast-grep-practice](ast-grep-practice/) | `ast-grep-practice` | Run ast-grep as a project lint tool — `sgconfig.yml`, fix/rewrite rules, constraints, CI. |
  110. | [chezmoi-management](chezmoi-management/) | `chezmoi-management` | mizchi's personal chezmoi dotfiles workflow (diff/apply, skill placement, APM vs chezmoi boundary). |
  111. | [conventional-changelog](conventional-changelog/) | `conventional-changelog` | Conventional Commits + CHANGELOG generator comparison (release-please, changesets, git-cliff, towncrier). |
  112. | [dotenvx](dotenvx/) | `dotenvx` | dotenvx reference for existing adoption or explicit user choice (encryption, multi-env, CI). |
  113. | [justfile](justfile/) | `justfile` | `just` command runner reference with GitHub Actions examples. |
  114. | [nix-setup](nix-setup/) | `nix-setup` | Requested or existing Nix environments — flakes, per-language templates, direnv, CI; devbox only when already adopted or explicitly selected. |
  115. | [upstream-fix-and-pin](upstream-fix-and-pin/) | `upstream-fix-and-pin` | Upstream PR + temporary git-ref pin workflow — branch HEAD SHA → merge SHA, `link:` fallback, pnpm v10 build script gating. |
  116. | [maintainer-persona](maintainer-persona/) | `maintainer-persona` | Measure a target repo's maintainers into an editable persona file, branch by OSS first-time / returning / internal team, draft in Japanese then translate and slop-check against their own PRs, gate the send. |
  117. | [utels-project-bootstrap](utels-project-bootstrap/) | `utels-project-bootstrap` | One-shot helper for registering a utels.dev project and writing the returned ingest token into a Worker secret through cf. |
  118. ### Kubernetes
  119. | Skill | Install path | Description |
  120. | --- | --- | --- |
  121. | [k8s-crd-from-typed-schema](k8s-crd-from-typed-schema/) | `k8s-crd-from-typed-schema` | Generate Kubernetes CRDs from a typed schema source (zod / TypeBox / Valibot / json-schema) — Structural Schema dialect, /status subresource trap, metadata-prohibition rule. |
  122. ### DevOps
  123. | Skill | Install path | Description |
  124. | --- | --- | --- |
  125. | [opentelemetry](opentelemetry/) | `opentelemetry` | Platform-agnostic OTel reference — signal selection, span design, context propagation, sampling, OTLP exporter config. |
  126. | [otel-node](otel-node/) | `otel-node` | Node.js OTel setup — SDK init, auto-instrumentation, and the esbuild ESM silent-failure gotcha. |
  127. | [gh-fix-ci](gh-fix-ci/) | `gh-fix-ci` | Debug and fix failing GitHub Actions PR checks via `gh`. |
  128. | [flaker-storage-cache-on-ci](flaker-storage-cache-on-ci/) | `flaker-storage-cache-on-ci` | Persist flaker's DuckDB storage across GitHub Actions via `actions/cache@v6` with sliding key. |
  129. | [cloudflare-workers-cd-rollback](cloudflare-workers-cd-rollback/) | `cloudflare-workers-cd-rollback` | GitHub Actions CD for a Cloudflare Worker with auto-rollback on smoke failure. |
  130. ### Process / Meta
  131. | Skill | Install path | Description |
  132. | --- | --- | --- |
  133. | [publish-agent-skill](publish-agent-skill/) | `publish-agent-skill` | Publish and update portable skills through Claude Code marketplaces, APM and the skills CLI; verify discovery, installed resources and consumer updates. |
  134. | [multi-agent-orchestration](multi-agent-orchestration/) | `multi-agent-orchestration` | Decide whether to spawn agents and which topology to use — single-agent default, independently verifiable work, DAG + verifier. |
  135. | [empirical-prompt-tuning](empirical-prompt-tuning/) | `empirical-prompt-tuning` | Iteratively evaluate and improve agent-facing text instructions using unbiased subagent executors. |
  136. | [task-based-eval](task-based-eval/) | `task-based-eval` | Measure goal achievement from fresh agents using tools, documents, interfaces or workflows; organize task definitions under `evals/<task-name>/` and improve from observable evidence. |
  137. | [retrospective-codify](retrospective-codify/) | `retrospective-codify` | Convert trial-and-error lessons into ast-grep rules / skills / CLAUDE.md rules. |
  138. | [skill-selector](skill-selector/) | `skill-selector` | Decide which skills to add to a project — Phase 1 picks from a curated catalog (Phase 2 escalates to `skill-finder`). |
  139. | [skill-finder](skill-finder/) | `skill-finder` | Cross-source skill discovery (Anthropic official → claude-skill-registry → VoltAgent → ComposioHQ → Superpowers → GitHub topic) with a mandatory waxa eval gate before adoption. |
  140. | [waxa-eval](waxa-eval/) | `waxa-eval` | Operating manual for the `waxa` CLI — scenario authoring, grader selection, ledger schema, the four-stage iteration pattern, convergence rules. |
  141. | [extract-glossary](extract-glossary/) | `extract-glossary` | Extract domain-specific terms, repository implementation maps, and onboarding Mermaid diagrams from one or more repos / GitHub orgs. |
  142. | [optimizing-descriptions](optimizing-descriptions/) | `optimizing-descriptions` | Audit and rewrite SKILL.md `description` fields per the agentskills.io optimizing-descriptions framework. |
  143. | [mizchi-blog-style](mizchi-blog-style/) | `mizchi-blog-style` | Style guide and AI-smell detection for blog posts published as mizchi (zenn / dev.to). |
  144. | [tech-article-reproducibility](tech-article-reproducibility/) | `tech-article-reproducibility` | Simulate a first-time reader reproducing a technical article and list missing information. |
  145. ## Tools
  146. ### Freshness review
  147. The [2026-11-16 skill freshness audit](docs/skill-freshness-audit-2026-11-16.md)
  148. inventories all 76 maintained entrypoints, separates confirmed stale guidance
  149. from version-specific examples needing revalidation, and prioritizes update
  150. detection. The [upstream watchlist](docs/skill-upstream-watchlist.json) records
  151. sources and validation gates for fifteen groups affecting 38 skills. The [daily freshness check](docs/skill-freshness.md) fetches current upstream evidence,
  152. compares declared topics with jev-lint and fails on unreviewed upstream drift.
  153. It reports candidates without rewriting skills or accepting a baseline automatically.
  154. Run `just --justfile skill-freshness.justfile check`.
  155. [PR semantic review](docs/skill-review-ci.md) checks changed entrypoints and their
  156. English/Japanese pairs using trusted tooling. Maintained Node examples use Node 24+.
  157. ### Markdown links
  158. ```sh
  159. pnpm links:install
  160. just --justfile markdown-links.justfile check
  161. just --justfile markdown-links.justfile online
  162. ```
  163. Pinned lychee checks local files and heading fragments on every Markdown PR.
  164. External URL status checks run manually and weekly. See
  165. [scope, reports, and configuration](docs/markdown-links.md).
  166. ### Skill consistency checks
  167. The repository uses pinned `jev-lint` tooling and the upstream `jev-lint` skill.
  168. Custom rules check description/body agreement, conflicting instructions and
  169. terminology across all maintained skill entrypoints. English/Japanese pairs also
  170. receive explicit translation and activation-condition comparisons.
  171. ```sh
  172. pnpm install --frozen-lockfile
  173. apm install --frozen
  174. just --justfile skill-lint.justfile plan
  175. just --justfile skill-lint.justfile check
  176. just --justfile skill-lint.justfile translations
  177. ```
  178. Live checks read `TYPESAFE_API_KEY` from the environment. CI tests source selection
  179. and replays calibrated rule fixtures without making API requests. See the
  180. [configuration and workflow](.jev-lint/README.md) and [initial audit](.jev-lint/AUDIT.md).
  181. ### `waxa` — skill evaluation CLI
  182. Lives at [`tools/waxa/`](tools/waxa/) and is published as [`@mizchi/waxa`](https://www.npmjs.com/package/@mizchi/waxa). Used by the `waxa-eval` skill, and forms the adoption gate of `skill-finder`.
  183. Run via `npx` (no global install needed):
  184. ```sh
  185. npx @mizchi/waxa <eval.yaml>
  186. ```
  187. `npx` caches the package after the first run, so subsequent invocations are fast. Pin a version with `npx @mizchi/waxa@0.1.1` when reproducibility matters (do not pin `0.1.0` — that release shipped a broken shebang and crashes before argv parsing).
  188. Alternatives:
  189. ```sh
  190. # install globally (when calling waxa frequently)
  191. npm i -g @mizchi/waxa
  192. # run from source (requires Deno 2+)
  193. git clone https://github.com/mizchi/skills.git
  194. cd skills/tools/waxa
  195. deno task run -- path/to/eval.yaml
  196. ```
  197. Requirements: `claude` CLI on `PATH` and authenticated (OAuth login or `ANTHROPIC_API_KEY`).
  198. Quick reference:
  199. ```sh
  200. npx @mizchi/waxa init [--skill <name>] [--force] # scaffold <skill>/evals/ (skill-local)
  201. npx @mizchi/waxa <skill>/evals/eval.yaml # single run
  202. npx @mizchi/waxa <skill>/evals/eval.yaml --baseline # with_skill vs without_skill + delta
  203. npx @mizchi/waxa iterate <skill>/evals/eval.yaml [--max N] # iteration loop with ledger
  204. npx @mizchi/waxa compare <skill>/evals/eval.yaml --models <m1>,<m2> # multi-model comparison
  205. npx @mizchi/waxa variant <skill>/evals/eval.yaml --base <skill-a> --candidate <skill-b> # A/B
  206. ```
  207. From 0.2.0 evals live at `<skill>/evals/` (skill-local layout, agentskills.io-aligned). Workspace outputs go to `<workspace-root>/results/<skill>/iteration-N/`. The npm package bundles `references/empirical-prompt-tuning.md` (the methodology document), so iter / convergence semantics ship with the CLI.
  208. Full reference: [`tools/waxa/README.md`](tools/waxa/README.md).
  209. ## Recommended starter set
  210. If you are setting up a new project that will produce or consume skills, this combination covers selection, discovery, and iteration:
  211. ```yaml
  212. # apm.yml
  213. targets:
  214. - claude
  215. dependencies:
  216. apm:
  217. - mizchi/skills/apm-usage # APM manifest reference
  218. - mizchi/skills/skill-selector # Phase 1: pick from curated catalog
  219. - mizchi/skills/skill-finder # Phase 2: cross-source discovery + waxa eval gate
  220. - mizchi/skills/waxa-eval # waxa CLI operating manual
  221. - mizchi/skills/empirical-prompt-tuning # methodology / Iter 0 / [critical]-tag checklist
  222. ```
  223. Then:
  224. ```sh
  225. apm install # installs the skills under .claude/skills/
  226. npx @mizchi/waxa --help # cache the waxa CLI on first call
  227. # (or `npm i -g @mizchi/waxa` if you call waxa often enough that startup matters)
  228. ```
  229. The skill-selection / discovery / evaluation flow then proceeds as: `skill-selector` (catalog pre-flight) → if no fit, `skill-finder` (Tier 1-4 sweep) → adoption gated by `waxa-eval` running `waxa iterate` against a `evals/<skill>/` directory you author. `empirical-prompt-tuning` covers what `waxa` cannot reach (the Iter 0 description / body consistency check, `tool_uses`-based skill self-containment diagnosis, and the `[critical]`-tagged requirements checklist that gives binary success judgment).
  230. ## Language
  231. All `SKILL.md` files are written in English. Skills that were originally written in Japanese preserve the original as `SKILL-ja.md` alongside the English version. `mizchi-blog-style` is the single exception and stays Japanese-only because the skill itself is about Japanese blog writing style.
  232. ## Upstream skills (not in this repo)
  233. These are maintained in their own repositories and installed separately:
  234. - [mizchi/flaker](https://github.com/mizchi/flaker) — `flaker-setup`
  235. - [mizchi/tui.mbt](https://github.com/mizchi/tui.mbt) — `tuimbt-practice`
  236. - [moonbitlang/moonbit-agent-guide](https://github.com/moonbitlang/moonbit-agent-guide) — `moonbit-agent-guide`, `moonbit-refactoring`, `moonbit-c-binding`
  237. - [ast-grep/agent-skill](https://github.com/ast-grep/agent-skill) — `ast-grep`
  238. ## License
  239. Each skill may carry its own license (see `LICENSE.txt` inside the skill directory). Skills without an explicit license default to MIT at the repository owner's discretion.
maintainer-persona/scripts/persona.ts · Bundled script · 344 lines · 3 findings marked
  1. // Pure logic for maintainer-persona: summarise fetched history, classify the
  2. // contributor context, render the measured block, merge it into a persona file.
  3. // No I/O here; measure.ts does the fetching and writing.
  4. export type Pull = {
  5. number: number;
  6. title: string;
  7. state: "MERGED" | "CLOSED" | "OPEN";
  8. isDraft: boolean;
  9. authorAssociation: string;
  10. author: string;
  11. mergedBy: string | null;
  12. createdAt: string;
  13. closedAt: string | null;
  14. body: string;
  15. reviewers: string[];
  16. files: string[];
  17. commitMessages: string[];
  18. labels: string[];
  19. closesIssues: number;
  20. // earliest review or comment by a human other than the author
  21. firstResponseAt: string | null;
  22. // the author had no merged PR in this repo when this PR was opened.
  23. // Not the same as authorAssociation, which GitHub computes at query time:
  24. // an outsider whose first PR merged is now CONTRIBUTOR.
  25. firstTimeAtCreation: boolean;
  26. closedByAutomation: boolean;
  27. };
  28. export type Issue = { number?: number; author?: string; body: string; labels: string[] };
  29. export type Tally = [string, number][];
  30. export type Spread = { median: number; p90: number };
  31. export type AssociationOutcome = {
  32. merged: number;
  33. closedUnmerged: number;
  34. noResponse: number;
  35. firstResponseHoursMedian: number | null;
  36. };
  37. export type FirstTimerOutcome = AssociationOutcome & { closedByAutomation: number };
  38. export type PullSummary = {
  39. merged: number;
  40. closedUnmerged: number;
  41. conventionalTitles: number;
  42. closesIssue: number;
  43. touchesTests: number;
  44. signedOff: number;
  45. selfMerged: number;
  46. drafts: number;
  47. japaneseBodies: number;
  48. politeBodies: number;
  49. bodyChars: Spread;
  50. headings: Tally;
  51. labels: Tally;
  52. humanReviewers: Tally;
  53. botReviewers: Tally;
  54. byAssociation: Record<string, AssociationOutcome>;
  55. firstTimers: FirstTimerOutcome;
  56. };
  57. export type IssueSummary = { count: number; japaneseBodies: number; politeBodies: number; bodyChars: Spread; headings: Tally; labels: Tally };
  58. export type Relation = "oss" | "internal";
  59. export type Context = { relation: Relation; standing: "first-time" | "returning"; exposure: "public" | "private" };
  60. export type Measured = {
  61. repo: string;
  62. measuredAt: string;
  63. headSha: string;
  64. context: Context;
  65. languages: Record<Kind, Language>;
  66. viewer: string;
  67. files: { contributing: string | null; prTemplate: string | null; issueTemplates: string[]; codeowners: boolean };
  68. rules: string[];
  69. pulls: PullSummary;
  70. issues: IssueSummary;
  71. };
  72. const TOP = 15;
  73. const CONVENTIONAL = /^(feat|fix|docs|chore|refactor|test|tests|perf|build|ci|style|revert)(\([^)]*\))?!?:\s/i;
  74. const TEST_PATH = /(^|\/)(tests?|__tests__|spec|specs)\/|[._-](test|spec)s?\.[a-z0-9]+$/i;
  75. const SIGNED_OFF = /^Signed-off-by:/m;
  76. const BOT = /\[bot\]$/i;
  77. export function spread(values: number[]): Spread {
  78. if (values.length === 0) return { median: 0, p90: 0 };
  79. const s = [...values].sort((a, b) => a - b);
  80. const mid = Math.floor(s.length / 2);
  81. const median = s.length % 2 ? s[mid] : Math.floor((s[mid - 1] + s[mid]) / 2);
  82. // nearest-rank percentile
  83. const p90 = s[Math.min(s.length - 1, Math.ceil(0.9 * s.length) - 1)];
  84. return { median, p90 };
  85. }
  86. function tally(groups: Iterable<string>[]): Tally {
  87. const counts = new Map<string, number>();
  88. for (const g of groups) for (const k of new Set(g)) counts.set(k, (counts.get(k) ?? 0) + 1);
  89. // stable: ties keep first-seen order
  90. return [...counts].sort((a, b) => b[1] - a[1]).slice(0, TOP);
  91. }
  92. const HEADING_MAX = 60;
  93. const KANA = /[\u3040-\u30ff]/;
  94. export function headingsOf(body: string): string[] {
  95. return [...body.matchAll(/^#{1,6}\s+(.+?)\s*#*\s*$/gm)].map((m) => {
  96. const h = m[1].toLowerCase();
  97. return h.length > HEADING_MAX ? `${h.slice(0, HEADING_MAX).trimEnd()}…` : h;
  98. });
  99. }
  100. // What a reader sees without expanding anything: <details> and HTML comments
  101. // (PR template instructions) are dropped, on the corpus and the draft alike.
  102. export function visibleText(body: string): string {
  103. return body.replace(/<details>[\s\S]*?<\/details>/gi, "").replace(/<!--[\s\S]*?-->/g, "");
  104. }
  105. const POLITE_END = /(です|ます|でした|ました|ません|でしょう|ください)$/;
  106. // 敬体 or 常体, by the majority of sentence endings; null when not Japanese.
  107. export function registerOf(body: string): "polite" | "plain" | null {
  108. const sentences = visibleText(body)
  109. .split(/[。.!!??\n]+/)
  110. .map((x) => x.replace(/[\s))」』*`]+$/, ""))
  111. .filter((x) => KANA.test(x));
  112. if (sentences.length === 0) return null;
  113. const polite = sentences.filter((x) => POLITE_END.test(x)).length;
  114. return polite * 2 >= sentences.length ? "polite" : "plain";
  115. }
  116. const hoursBetween = (a: string, b: string) => (Date.parse(b) - Date.parse(a)) / 3_600_000;
  117. export function summarizePulls(pulls: Pull[]): PullSummary {
  118. const merged = pulls.filter((p) => p.state === "MERGED");
  119. const closed = pulls.filter((p) => p.state === "CLOSED");
  120. const reviewerGroups = merged.map((p) => p.reviewers);
  121. const outcome = (group: Pull[]): AssociationOutcome => {
  122. const responded = group.filter((p) => p.firstResponseAt);
  123. return {
  124. merged: group.filter((p) => p.state === "MERGED").length,
  125. closedUnmerged: group.filter((p) => p.state === "CLOSED").length,
  126. noResponse: group.length - responded.length,
  127. firstResponseHoursMedian: responded.length
  128. ? spread(responded.map((p) => Math.round(hoursBetween(p.createdAt, p.firstResponseAt!)))).median
  129. : null,
  130. };
  131. };
  132. const done = pulls.filter((p) => p.state !== "OPEN");
  133. const byAssociation: Record<string, AssociationOutcome> = {};
  134. for (const assoc of new Set(done.map((p) => p.authorAssociation))) {
  135. byAssociation[assoc] = outcome(done.filter((p) => p.authorAssociation === assoc));
  136. }
  137. // automated closes are reported apart: they say nothing about human review
  138. const first = done.filter((p) => p.firstTimeAtCreation);
  139. const firstTimers = {
  140. ...outcome(first.filter((p) => !p.closedByAutomation)),
  141. closedByAutomation: first.filter((p) => p.closedByAutomation).length,
  142. };
  143. return {
  144. merged: merged.length,
  145. closedUnmerged: closed.length,
  146. conventionalTitles: merged.filter((p) => CONVENTIONAL.test(p.title)).length,
  147. closesIssue: merged.filter((p) => p.closesIssues > 0).length,
  148. touchesTests: merged.filter((p) => p.files.some((f) => TEST_PATH.test(f))).length,
  149. signedOff: merged.filter((p) => p.commitMessages.some((m) => SIGNED_OFF.test(m))).length,
  150. selfMerged: merged.filter((p) => p.mergedBy === p.author).length,
  151. drafts: pulls.filter((p) => p.isDraft).length,
  152. japaneseBodies: merged.filter((p) => KANA.test(p.body)).length,
  153. politeBodies: merged.filter((p) => registerOf(p.body) === "polite").length,
  154. bodyChars: spread(merged.map((p) => visibleText(p.body).length)),
  155. headings: tally(merged.map((p) => headingsOf(p.body))),
  156. labels: tally(merged.map((p) => p.labels)),
  157. humanReviewers: tally(reviewerGroups.map((g) => g.filter((r) => !BOT.test(r)))),
  158. botReviewers: tally(reviewerGroups.map((g) => g.filter((r) => BOT.test(r)))),
  159. byAssociation,
  160. firstTimers,
  161. };
  162. }
  163. export const KANA_RE = KANA;
  164. export function summarizeIssues(issues: Issue[]): IssueSummary {
  165. return {
  166. count: issues.length,
  167. japaneseBodies: issues.filter((i) => KANA.test(i.body)).length,
  168. politeBodies: issues.filter((i) => registerOf(i.body) === "polite").length,
  169. bodyChars: spread(issues.map((i) => visibleText(i.body).length)),
  170. headings: tally(issues.map((i) => headingsOf(i.body))),
  171. labels: tally(issues.map((i) => i.labels)),
  172. };
  173. }
  174. export type Language = "ja" | "en" | "mixed";
  175. // The language maintainers write in, decided separately for PRs and issues:
  176. // one repo can take English PRs and Japanese issues.
  177. export function languageOf(japanese: number, total: number): Language {
  178. if (total === 0) return "en";
  179. const share = japanese / total;
  180. return share >= 0.5 ? "ja" : share <= 0.1 ? "en" : "mixed";
  181. }
  182. export type Kind = "issue" | "pr";
  183. export function classify(input: {
  184. visibility: string;
  185. viewerIsOrgMember: boolean;
  186. myPrs: number;
  187. myMergedPrs: number;
  188. relationOverride?: Relation;
  189. }): Context {
  190. const exposure = input.visibility === "PUBLIC" ? "public" : "private";
  191. const relation: Relation =
  192. input.relationOverride ?? (exposure === "private" || input.viewerIsOrgMember ? "internal" : "oss");
  193. return { relation, standing: input.myMergedPrs > 0 ? "returning" : "first-time", exposure };
  194. }
  195. // ---- rendering -----------------------------------------------------------
  196. const BEGIN = "<!-- maintainer-persona:measured:begin -->";
    • Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
    • Line 225 on GitHub
  197. const END = "<!-- maintainer-persona:measured:end -->";
    • Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
    • Line 226 on GitHub
  198. const DATA = /<!-- maintainer-persona:data (.*?) -->/s;
    • Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
    • Line 227 on GitHub
  199. const pct = (n: number, d: number) => (d ? `${n}/${d} (${Math.round((100 * n) / d)}%)` : "0/0");
  200. const list = (t: Tally) => (t.length ? t.map(([k, n]) => `\`${k}\` ${n}`).join(", ") : "none");
  201. export function renderMeasured(m: Measured): string {
  202. const p = m.pulls;
  203. const ft = p.firstTimers;
  204. const assoc = Object.entries(p.byAssociation)
  205. .map(
  206. ([k, v]) =>
  207. `| ${k} | ${v.merged} | ${v.closedUnmerged} | ${v.noResponse} | ${v.firstResponseHoursMedian ?? "-"} |`,
  208. )
  209. .join("\n");
  210. const data = JSON.stringify(m).replace(/-->/g, "--\\u003e");
  211. return [
  212. BEGIN,
  213. `<!-- maintainer-persona:data ${data} -->`,
  214. "",
  215. `Measured ${m.measuredAt} at \`${m.headSha.slice(0, 12)}\` as \`${m.viewer}\`.`,
  216. `Context: **${m.context.relation}**, **${m.context.standing}**, exposure **${m.context.exposure}**.`,
  217. `PRs are written in **${m.languages.pr}** (Japanese ${pct(m.pulls.japaneseBodies, m.pulls.merged)}),` +
  218. ` issues in **${m.languages.issue}** (Japanese ${pct(m.issues.japaneseBodies, m.issues.count)}).` +
  219. ` Polite form (敬体) among Japanese bodies: PRs ${pct(m.pulls.politeBodies, m.pulls.japaneseBodies)},` +
  220. ` issues ${pct(m.issues.politeBodies, m.issues.japaneseBodies)}.`,
  221. "",
  222. "### Gates and files",
  223. "",
  224. `- CONTRIBUTING: ${m.files.contributing ? `\`${m.files.contributing}\`` : "none"}`,
  225. `- PR template: ${m.files.prTemplate ? `\`${m.files.prTemplate}\`` : "none"}`,
  226. `- Issue templates: ${m.files.issueTemplates.length ? m.files.issueTemplates.map((f) => `\`${f}\``).join(", ") : "none"}`,
  227. `- CODEOWNERS: ${m.files.codeowners ? "yes" : "no"}`,
  228. `- Rules on the default branch: ${m.rules.length ? m.rules.join("; ") : "none readable"}`,
  229. "",
  230. `### Pull requests (${p.merged} merged, ${p.closedUnmerged} closed unmerged)`,
  231. "",
  232. `- Visible body length (chars, outside <details> and comments): median ${p.bodyChars.median}, p90 ${p.bodyChars.p90}`,
  233. `- Conventional-commit titles: ${pct(p.conventionalTitles, p.merged)}`,
  234. `- Links a closing issue: ${pct(p.closesIssue, p.merged)}`,
  235. `- Touches a test file: ${pct(p.touchesTests, p.merged)}`,
  236. `- Signed-off-by in commits: ${pct(p.signedOff, p.merged)}`,
  237. `- Self-merged: ${pct(p.selfMerged, p.merged)}`,
  238. `- Drafts in sample: ${p.drafts}`,
  239. `- Headings: ${list(p.headings)}`,
  240. `- Labels: ${list(p.labels)}`,
  241. `- Human reviewers (PRs reviewed): ${list(p.humanReviewers)}`,
  242. `- Bot reviewers: ${list(p.botReviewers)}`,
  243. "",
  244. `First-time authors (no merged PR when they opened it): ${ft.merged} merged, ${ft.closedUnmerged} closed by a human,` +
  245. ` ${ft.closedByAutomation} closed by automation; ${ft.noResponse} of the human-handled got no human response;` +
  246. ` first human response median ${ft.firstResponseHoursMedian ?? "-"} h.`,
  247. "",
  248. "| author association as of now (merged first-timers show as CONTRIBUTOR) | merged | closed unmerged | no response | first response, median h |",
  249. "|---|---|---|---|---|",
  250. assoc,
  251. "",
  252. `### Issues (${m.issues.count})`,
  253. "",
  254. `- Visible body length (chars): median ${m.issues.bodyChars.median}, p90 ${m.issues.bodyChars.p90}`,
  255. `- Headings: ${list(m.issues.headings)}`,
  256. `- Labels: ${list(m.issues.labels)}`,
  257. END,
  258. ].join("\n");
  259. }
  260. export function readMeasuredData(text: string): Measured | null {
  261. const m = text.match(DATA);
  262. return m ? (JSON.parse(m[1]) as Measured) : null;
  263. }
  264. const SKELETON = (repo: string) => `# Persona: ${repo}
  265. Everything outside the measured block is hand-written and survives re-measuring.
  266. The measured block is regenerated by \`measure.ts\`; do not edit inside it.
  267. Measurements transfer between findings; the advice in sections 4-6 depends on the
  268. finding you had in mind when you wrote it, so re-derive it when that changes.
  269. ## 1. Readers
  270. <!-- Who triages, who reviews which directory, what they are paid to care about. -->
  271. ## 2. Vocabulary usable bare
  272. <!-- Terms that appear in their own README, labels, issues. Cite where. -->
  273. ## 3. Needs translating
  274. <!-- Your terms -> their terms. A word with zero hits in their repo goes here. -->
  275. | ours | why it does not land | theirs |
  276. |---|---|---|
  277. ## 4. Issue conventions
  278. ## 5. PR conventions
  279. ## 6. Landmines
  280. ## 7. Evidence and weak spots
  281. <!-- Commands you ran, what you read, and which rows rest on few examples. -->
  282. ## 8. Measurements
  283. `;
  284. export function mergePersona(existing: string | null, block: string): string {
  285. if (existing === null) {
  286. const repo = readMeasuredData(block)?.repo ?? "unknown";
  287. return `${SKELETON(repo)}${block}\n`;
  288. }
  289. const b = existing.indexOf(BEGIN);
  290. const e = existing.indexOf(END);
  291. if (b < 0 || e < b) {
  292. throw new Error("persona file has no measured-block markers; restore them or move the file aside");
  293. }
  294. return existing.slice(0, b) + block + existing.slice(e + END.length);
  295. }
maintainer-persona/scripts/persona_test.ts · Bundled script · 231 lines · 2 findings marked
  1. import { test } from "node:test";
  2. import assert from "node:assert/strict";
  3. import {
  4. classify,
  5. mergePersona,
  6. readMeasuredData,
  7. renderMeasured,
  8. summarizeIssues,
  9. summarizePulls,
  10. headingsOf,
  11. visibleText,
  12. registerOf,
  13. languageOf,
  14. type Measured,
  15. type Pull,
  16. } from "./persona.ts";
  17. const pull = (over: Partial<Pull>): Pull => ({
  18. number: 1,
  19. title: "fix: handle empty input",
  20. state: "MERGED",
  21. isDraft: false,
  22. authorAssociation: "CONTRIBUTOR",
  23. author: "alice",
  24. mergedBy: "maint",
  25. createdAt: "2026-01-01T00:00:00Z",
  26. closedAt: "2026-01-02T00:00:00Z",
  27. body: "## Summary\nfix\n\nCloses #3",
  28. reviewers: ["maint"],
  29. files: ["src/a.ts", "src/a.test.ts"],
  30. commitMessages: ["fix: handle empty input\n\nSigned-off-by: Alice <a@example.com>"],
  31. labels: ["bug"],
  32. closesIssues: 1,
  33. firstResponseAt: "2026-01-01T06:00:00Z",
  34. firstTimeAtCreation: false,
  35. closedByAutomation: false,
  36. ...over,
  37. });
  38. test("summarizePulls counts conventions over merged PRs only", () => {
  39. const s = summarizePulls([
  40. pull({ number: 1 }),
  41. pull({ number: 2, title: "Handle empty input", body: "x", closesIssues: 0, files: ["src/b.ts"], commitMessages: ["Handle"] }),
  42. pull({ number: 3, state: "CLOSED", title: "feat: rejected" }),
  43. ]);
  44. assert.equal(s.merged, 2);
  45. assert.equal(s.closedUnmerged, 1);
  46. assert.equal(s.conventionalTitles, 1);
  47. assert.equal(s.closesIssue, 1);
  48. assert.equal(s.touchesTests, 1);
  49. assert.equal(s.signedOff, 1);
  50. assert.deepEqual(s.bodyChars, { median: 13, p90: 25 });
  51. });
  52. test("summarizePulls separates bot reviewers and counts self-merges", () => {
  53. const s = summarizePulls([
  54. pull({ author: "maint", mergedBy: "maint", reviewers: ["copilot-pull-request-reviewer[bot]", "maint"] }),
  55. pull({ reviewers: ["maint", "bob", "maint"] }),
  56. ]);
  57. assert.deepEqual(s.humanReviewers, [["maint", 2], ["bob", 1]]);
  58. assert.deepEqual(s.botReviewers, [["copilot-pull-request-reviewer[bot]", 1]]);
  59. assert.equal(s.selfMerged, 1);
  60. });
  61. test("summarizePulls reports outcome per author association", () => {
  62. const s = summarizePulls([
  63. pull({ authorAssociation: "FIRST_TIME_CONTRIBUTOR" }),
  64. pull({ authorAssociation: "FIRST_TIME_CONTRIBUTOR", state: "CLOSED", firstResponseAt: null }),
  65. pull({ authorAssociation: "MEMBER" }),
  66. ]);
  67. assert.deepEqual(s.byAssociation.FIRST_TIME_CONTRIBUTOR, { merged: 1, closedUnmerged: 1, noResponse: 1, firstResponseHoursMedian: 6 });
  68. assert.equal(s.byAssociation.MEMBER.merged, 1);
  69. });
  70. test("summarizePulls counts headings once per body", () => {
  71. const s = summarizePulls([
  72. pull({ body: "## Summary\n## Summary\n### Test plan" }),
  73. pull({ body: "## summary\nno test plan" }),
  74. ]);
  75. assert.deepEqual(s.headings, [["summary", 2], ["test plan", 1]]);
  76. });
  77. test("summarizeIssues measures length, headings and labels", () => {
  78. const s = summarizeIssues([
  79. { body: "## Steps\n1. run", labels: ["bug"] },
  80. { body: "short", labels: ["bug", "p1"] },
  81. ]);
  82. assert.equal(s.count, 2);
  83. assert.deepEqual(s.labels, [["bug", 2], ["p1", 1]]);
  84. assert.deepEqual(s.headings, [["steps", 1]]);
  85. });
  86. test("classify: outsider on a public repo with no merged PR is a first-time OSS contributor", () => {
  87. assert.deepEqual(classify({ visibility: "PUBLIC", viewerIsOrgMember: false, myPrs: 2, myMergedPrs: 0 }), {
  88. relation: "oss",
  89. standing: "first-time",
  90. exposure: "public",
  91. });
  92. });
  93. test("classify: org member is internal even on a public repo, and exposure stays public", () => {
  94. assert.deepEqual(classify({ visibility: "PUBLIC", viewerIsOrgMember: true, myPrs: 5, myMergedPrs: 3 }), {
  95. relation: "internal",
  96. standing: "returning",
  97. exposure: "public",
  98. });
  99. });
  100. test("classify: private repo is internal and private; an override wins", () => {
  101. assert.equal(classify({ visibility: "PRIVATE", viewerIsOrgMember: false, myPrs: 0, myMergedPrs: 0 }).relation, "internal");
  102. assert.equal(classify({ visibility: "INTERNAL", viewerIsOrgMember: true, myPrs: 0, myMergedPrs: 0 }).exposure, "private");
  103. assert.equal(
  104. classify({ visibility: "PUBLIC", viewerIsOrgMember: true, myPrs: 0, myMergedPrs: 0, relationOverride: "oss" }).relation,
  105. "oss",
  106. );
  107. });
  108. const measured = (): Measured => ({
  109. repo: "acme/widget",
  110. measuredAt: "2026-09-24",
  111. headSha: "0123456789abcdef",
  112. context: { relation: "oss", standing: "first-time", exposure: "public" },
  113. languages: { pr: "en", issue: "ja" },
  114. viewer: "me",
  115. files: { contributing: "CONTRIBUTING.md", prTemplate: null, issueTemplates: [], codeowners: false },
  116. rules: ["pull_request: 1 approval"],
  117. pulls: summarizePulls([pull({})]),
  118. issues: summarizeIssues([{ body: "b", labels: [] }]),
  119. });
  120. test("renderMeasured embeds machine-readable data that readMeasuredData recovers", () => {
  121. const block = renderMeasured(measured());
  122. assert.match(block, /^<!-- maintainer-persona:measured:begin -->/);
    • Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
    • Line 133 on GitHub
  123. assert.match(block, /<!-- maintainer-persona:measured:end -->$/);
    • Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
    • Line 134 on GitHub
  124. assert.equal(readMeasuredData(block)?.repo, "acme/widget");
  125. });
  126. test("mergePersona creates a skeleton with hand-edited sections outside the block", () => {
  127. const doc = mergePersona(null, renderMeasured(measured()));
  128. assert.match(doc, /^# Persona: acme\/widget/);
  129. for (const h of ["## 1. Readers", "## 2. Vocabulary", "## 3. Needs translating", "## 6. Landmines"]) {
  130. assert.ok(doc.includes(h), h);
  131. }
  132. });
  133. test("mergePersona replaces only the measured block and keeps hand edits", () => {
  134. const first = mergePersona(null, renderMeasured(measured()));
  135. const edited = first.replace("## 6. Landmines\n", "## 6. Landmines\n\n- never mention the old API\n");
  136. const next = measured();
  137. next.headSha = "fedcba9876543210";
  138. const merged = mergePersona(edited, renderMeasured(next));
  139. assert.ok(merged.includes("never mention the old API"));
  140. assert.ok(merged.includes("fedcba9876543210"));
  141. assert.ok(!merged.includes("0123456789abcdef"));
  142. });
  143. test("mergePersona refuses a file whose markers were removed", () => {
  144. assert.throws(() => mergePersona("# Persona: acme/widget\n\nhand text only\n", renderMeasured(measured())), /markers/);
  145. });
  146. test("headingsOf truncates template-length headings", () => {
  147. const [h] = headingsOf(`## ${"please don't delete this checklist ".repeat(4)}`);
  148. assert.ok(h.length <= 61, h);
  149. assert.ok(h.endsWith("…"));
  150. });
  151. test("summarizePulls counts bodies written in Japanese", () => {
  152. const s = summarizePulls([pull({ body: "## 概要\n修正します" }), pull({ body: "## Summary" })]);
  153. assert.equal(s.japaneseBodies, 1);
  154. });
  155. test("languageOf decides by share of Japanese bodies", () => {
  156. assert.equal(languageOf(6, 10), "ja");
  157. assert.equal(languageOf(1, 10), "en");
  158. assert.equal(languageOf(3, 10), "mixed");
  159. assert.equal(languageOf(0, 0), "en");
  160. });
  161. test("renderMeasured reports the language per submission kind", () => {
  162. const block = renderMeasured(measured());
  163. assert.match(block, /PRs are written in \*\*en\*\*/);
  164. assert.match(block, /issues in \*\*ja\*\*/);
  165. });
  166. test("kanji-only text is not taken as Japanese (it may be Chinese)", () => {
  167. assert.equal(summarizeIssues([{ body: "修复错误", labels: [] }]).japaneseBodies, 0);
  168. });
  169. test("firstTimers counts PRs whose author had no merged PR when they opened it, whatever their association is now", () => {
  170. const s = summarizePulls([
  171. // merged first PR: GitHub now labels the author CONTRIBUTOR
  172. pull({ authorAssociation: "CONTRIBUTOR", firstTimeAtCreation: true }),
  173. pull({ authorAssociation: "NONE", firstTimeAtCreation: true, state: "CLOSED", firstResponseAt: null }),
  174. pull({ authorAssociation: "NONE", firstTimeAtCreation: true, state: "CLOSED", closedByAutomation: true, firstResponseAt: null }),
  175. pull({ authorAssociation: "CONTRIBUTOR", firstTimeAtCreation: false }),
  176. ]);
  177. assert.deepEqual(s.firstTimers, {
  178. merged: 1,
  179. closedUnmerged: 1,
  180. closedByAutomation: 1,
  181. noResponse: 1,
  182. firstResponseHoursMedian: 6,
  183. });
  184. });
  185. test("visibleText drops <details> blocks and HTML comments", () => {
  186. assert.equal(visibleText("a\n<!-- note -->\n<details>\n<summary>x</summary>\nlong\n</details>\nb"), "a\n\n\nb");
  187. });
  188. test("body length is measured on the visible part", () => {
  189. const s = summarizePulls([pull({ body: "short<details>" + "x".repeat(500) + "</details>" })]);
  190. assert.deepEqual(s.bodyChars, { median: 5, p90: 5 });
  191. });
  192. test("renderMeasured labels the association table as current, and shows first-timers at creation", () => {
  193. const m = measured();
  194. const block = renderMeasured(m);
  195. assert.match(block, /association as of now/);
  196. assert.match(block, /First-time authors \(no merged PR when they opened it\)/);
  197. });
  198. test("registerOf classifies Japanese bodies by sentence endings", () => {
  199. assert.equal(registerOf("修正します。確認しました。"), "polite");
  200. assert.equal(registerOf("修正する。確認した。原因である。"), "plain");
  201. assert.equal(registerOf("Fix the link."), null);
  202. });
  203. test("summaries count polite Japanese bodies", () => {
  204. assert.equal(summarizeIssues([{ body: "壊れています。", labels: [] }, { body: "壊れている。", labels: [] }]).politeBodies, 1);
  205. assert.equal(summarizePulls([pull({ body: "直しました。" })]).politeBodies, 1);
  206. });
vlmkit/scripts/doctor.sh · Bundled script · 162 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # scripts/doctor.sh — pre-flight environment check for @mizchi/vlmkit.
  3. #
  4. # Runs without depending on the vlmkit CLI itself; safe to invoke as the
  5. # very first thing on a new machine before installing anything. Echoes
  6. # PASS / WARN / FAIL per check, then a one-line verdict.
  7. #
  8. # Exit code:
  9. # 0 — every REQUIRED check is PASS (WARN-only is OK)
  10. # 1 — at least one REQUIRED check is FAIL
  11. #
  12. # Usage:
  13. # bash <(curl -sSL https://raw.githubusercontent.com/mizchi/skills/main/vlmkit/scripts/doctor.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 13 on GitHub
  14. # or after apm install:
  15. # bash ~/.claude/skills/vlmkit/scripts/doctor.sh
  16. set -u
  17. # ---- output helpers --------------------------------------------------------
  18. if [ -t 1 ]; then
  19. G=$'\033[32m'; Y=$'\033[33m'; R=$'\033[31m'; D=$'\033[2m'; B=$'\033[1m'; X=$'\033[0m'
  20. else
  21. G=""; Y=""; R=""; D=""; B=""; X=""
  22. fi
  23. PASS_CT=0
  24. WARN_CT=0
  25. FAIL_CT=0
  26. FAIL_LINES=()
  27. pass() { printf ' %s✓%s %-26s %s\n' "$G" "$X" "$1" "$2"; PASS_CT=$((PASS_CT+1)); }
  28. warn() { printf ' %s•%s %-26s %s%s%s\n' "$Y" "$X" "$1" "$D" "$2" "$X"; WARN_CT=$((WARN_CT+1)); }
  29. fail() { printf ' %s✗%s %-26s %s%s%s\n' "$R" "$X" "$1" "$D" "$2" "$X"; FAIL_CT=$((FAIL_CT+1)); FAIL_LINES+=("$1 — $2"); }
  30. section() { printf '\n%s%s%s\n' "$B" "$1" "$X"; }
  31. # ---- checks ----------------------------------------------------------------
  32. section "Runtime"
  33. if command -v node >/dev/null 2>&1; then
  34. ver=$(node --version | sed 's/^v//')
  35. major=${ver%%.*}
  36. if [ "$major" -ge 24 ]; then
  37. pass "Node ($ver)" "≥ 24 required"
  38. else
  39. fail "Node ($ver)" "vlmkit requires Node 24+; upgrade via nvm/fnm/volta"
  40. fi
  41. else
  42. fail "Node" "not found on PATH"
  43. fi
  44. if command -v pnpm >/dev/null 2>&1; then
  45. pass "pnpm ($(pnpm --version))" "preferred package manager"
  46. elif command -v npm >/dev/null 2>&1; then
  47. warn "pnpm" "not found; npm ($(npm --version)) will work too"
  48. else
  49. fail "pnpm / npm" "no Node package manager found"
  50. fi
  51. # ---- vlmkit CLI --------------------------------------------------------------
  52. section "vlmkit CLI"
  53. if command -v vlmkit >/dev/null 2>&1; then
  54. ver=$(vlmkit --version 2>/dev/null | head -1)
  55. pass "vlmkit installed" "${ver:-(version not parseable)}"
  56. else
  57. warn "vlmkit CLI" "not found on PATH — install with: pnpm add -g @mizchi/vlmkit"
  58. fi
  59. # ---- Playwright Chromium ---------------------------------------------------
  60. section "Playwright Chromium"
  61. # Playwright stores browsers under one of:
  62. # $PLAYWRIGHT_BROWSERS_PATH (override)
  63. # ~/Library/Caches/ms-playwright/ (macOS default)
  64. # ~/.cache/ms-playwright/ (Linux default)
  65. # %USERPROFILE%\AppData\Local\ms-playwright\ (Windows — skipped here)
  66. pw_dirs=()
  67. [ -n "${PLAYWRIGHT_BROWSERS_PATH:-}" ] && pw_dirs+=("$PLAYWRIGHT_BROWSERS_PATH")
  68. pw_dirs+=("$HOME/Library/Caches/ms-playwright" "$HOME/.cache/ms-playwright")
  69. found_chromium=0
  70. for d in "${pw_dirs[@]}"; do
  71. if [ -d "$d" ] && ls -d "$d"/chromium-* >/dev/null 2>&1; then
  72. pass "Chromium installed" "$(ls -d "$d"/chromium-* 2>/dev/null | head -1 | xargs basename)"
  73. found_chromium=1
  74. break
  75. fi
  76. done
  77. if [ "$found_chromium" -eq 0 ]; then
  78. fail "Chromium" "not found — run: npx playwright install chromium"
  79. fi
  80. # ---- API keys (VLM features are optional) ----------------------------------
  81. section "VLM provider credentials (optional)"
  82. any_key=0
  83. for kv in "OPENROUTER_API_KEY:OpenRouter (default provider)" "ANTHROPIC_API_KEY:Anthropic (claude: prefix)" "GEMINI_API_KEY:Google AI (gemini: prefix)"; do
  84. k=${kv%%:*}
  85. desc=${kv#*:}
  86. v=$(eval echo "\${$k:-}")
  87. if [ -n "$v" ]; then
  88. pass "$k" "$desc (${#v} chars)"
  89. any_key=1
  90. else
  91. warn "$k" "$desc — unset"
  92. fi
  93. done
  94. if [ "$any_key" -eq 0 ]; then
  95. warn "VLM features" "no provider key set; vlmkit diff/snapshot still work, but fix-loop / vlm-bench / migration subagent need at least one"
  96. fi
  97. # ---- APM + sub-skills (optional) ------------------------------------------
  98. section "APM + sub-skills (optional)"
  99. if command -v apm >/dev/null 2>&1; then
  100. pass "apm CLI" "$(apm --version 2>/dev/null | head -1)"
  101. found_sub=0
  102. for s in vrt-visual-diff vrt-migration-eval vrt-regression-watch vrt-markup-synth vrt-css-fix-loop; do
  103. for root in "$HOME/.claude/skills" "$PWD/.claude/skills"; do
  104. if [ -f "$root/$s/SKILL.md" ]; then
  105. pass " $s" "$root/$s"
  106. found_sub=$((found_sub+1))
  107. break
  108. fi
  109. done
  110. done
  111. if [ "$found_sub" -eq 0 ]; then
  112. warn "sub-skills" "none of the 5 installed; run: apm install -g mizchi/vlmkit/.claude/skills/<name>"
  113. fi
  114. else
  115. warn "apm CLI" "not found; sub-skills are optional anyway"
  116. fi
  117. # ---- verdict ---------------------------------------------------------------
  118. section "Verdict"
  119. printf ' PASS: %d WARN: %d FAIL: %d\n' "$PASS_CT" "$WARN_CT" "$FAIL_CT"
  120. if [ "$FAIL_CT" -gt 0 ]; then
  121. printf '\n%s%sFailures (required):%s\n' "$R" "$B" "$X"
  122. for line in "${FAIL_LINES[@]}"; do
  123. printf ' • %s\n' "$line"
  124. done
  125. echo
  126. exit 1
  127. fi
  128. if [ "$WARN_CT" -gt 0 ]; then
  129. printf '\n%sReady for basic CLI use. Optional features may need attention above.%s\n\n' "$Y" "$X"
  130. else
  131. printf '\n%sReady.%s\n\n' "$G" "$X"
  132. fi
  133. exit 0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.