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.
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
Markdown
[](/listings/mizchi--skills)HTML
<a href="/listings/mizchi--skills"><img src="/api/listings/mizchi--skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
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.
- # mizchi/skills
- A collection of agent skills maintained by [@mizchi](https://github.com/mizchi), distributed via [APM](https://github.com/microsoft/apm) (Agent Package Manager).
- Each directory is a standalone skill following the [agentskills.io](https://agentskills.io/specification) open standard.
- ## Install
- Install an individual skill (global / user scope):
- ```sh
- apm install -g mizchi/skills/<skill-name>
- ```
- Or add to a project's `apm.yml`:
- ```yaml
- dependencies:
- apm:
- - mizchi/skills/<skill-name>
- ```
- Pin to a tag:
- ```sh
- 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:
- ```sh
- 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:
- ```sh
- pkf run gen:readme # write / sync every skill README
- pkf run check:readme # CI: verify they are in sync
- ```
- ## Skills
- ### Frontend
- A toolkit for frontend consulting engagements. Install skills from `mizchi/skills/<skill-name>`.
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [frontend-review-triage](frontend-review-triage/) | `frontend-review-triage` | Day 0 initial assessment — scorecard, top 3 risks, app classification. |
- | [frontend-review-ci](frontend-review-ci/) | `frontend-review-ci` | CI timing analysis — bottleneck identification, sharding/cache/concurrency recommendations. |
- | [frontend-review-hygiene](frontend-review-hygiene/) | `frontend-review-hygiene` | Code quality — TypeScript strictness, lint, dead code, duplication. |
- | [frontend-review-deps](frontend-review-deps/) | `frontend-review-deps` | Dependency health — freshness, CVE triage with attack-vector weighting, Tier 1/2/3 library detection. |
- | [frontend-review-testing](frontend-review-testing/) | `frontend-review-testing` | Testing posture — vitest coverage, Playwright config, VRT setup. |
- | [frontend-review-security](frontend-review-security/) | `frontend-review-security` | Security review — HTML sinks, auth/token storage, route guards, env var exposure, AI self-pentest. |
- | [frontend-review-state](frontend-review-state/) | `frontend-review-state` | State management architecture — server/URL/form/UI classification, Jotai/Zustand/Redux anti-patterns. |
- | [frontend-review-performance](frontend-review-performance/) | `frontend-review-performance` | Rendering performance — profiler-first, memo correctness, virtual scroll, useTransition. |
- | [frontend-review-weekly](frontend-review-weekly/) | `frontend-review-weekly` | Weekly orchestrator — runs all domain skills, diffs KPIs, files repeat-finding issues. |
- Perspective sub-skills (invoked by `frontend-review-weekly`): `frontend-expert`, `react-expert`, `performance-expert`, `security-expert`, `frontend-ops-expert`.
- ### Node.js
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [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. |
- | [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`. |
- ### AWS
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [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. |
- | [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. |
- | [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. |
- | [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. |
- ### Cloudflare
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [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) |
- | [cloudflare-deploy](cloudflare-deploy/) | `cloudflare-deploy` | Deploy Workers and platform resources through cf and typed configuration. |
- | [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. |
- | [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. |
- | [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. |
- ### SQL
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [sql-lint](sql-lint/) | `sql-lint` | Static lint for sqlc-style SQL catalogs — duplicate query names, missing semicolons, SELECT *, double-wildcard LIKE. |
- | [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. |
- | [sql-schema-audit](sql-schema-audit/) | `sql-schema-audit` | Index coverage and N+1 review aids for SQLite/D1 schemas with a sqlc catalog. |
- | [sql-security](sql-security/) | `sql-security` | SQL injection screening for host code (MoonBit / TS / Rust) plus secretlint setup notes. |
- | [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. |
- ### Languages
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [moonbit-practice](moonbit-practice/) | `moonbit-practice` | MoonBit code generation best practices — syntax, tests, benchmarks, FFI, Nix, mbtx. |
- | [moonbit-js-binding](moonbit-js-binding/) | `moonbit-js-binding` | Write MoonBit bindings to JavaScript with `extern "js"` (Promises, opaque types, esm/cjs/iife). |
- | [gleam-practice](gleam-practice/) | `gleam-practice` | Build and review Gleam projects on the Erlang target (Wisp + Mist, OTP, just, CI). |
- | [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. |
- | [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. |
- ### Graphics / GPU
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [metal-practice](metal-practice/) | `metal-practice` | Apple Metal rendering and compute — MetalKit, shader ABI, resource synchronization, Metal 4, GPU validation and profiling. |
- ### Testing / Browser
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [playwright-cli](playwright-cli/) | `playwright-cli` | Run Playwright via terminal CLI (test runner, codegen, screenshot, CI sharding). |
- | [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. |
- | [playwright-test](playwright-test/) | `playwright-test` | Playwright Test (E2E) best practices — no fixed waits, network triggers, DnD, CI sharding/retry. |
- ### AI / VLM
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [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. |
- | [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/`. |
- ### Formal Methods
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [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. |
- | [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. |
- ### Tooling / Infra
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [apm-usage](apm-usage/) | `apm-usage` | Use APM (Agent Package Manager) to manage agent skills and dependencies. |
- | [ast-grep-practice](ast-grep-practice/) | `ast-grep-practice` | Run ast-grep as a project lint tool — `sgconfig.yml`, fix/rewrite rules, constraints, CI. |
- | [chezmoi-management](chezmoi-management/) | `chezmoi-management` | mizchi's personal chezmoi dotfiles workflow (diff/apply, skill placement, APM vs chezmoi boundary). |
- | [conventional-changelog](conventional-changelog/) | `conventional-changelog` | Conventional Commits + CHANGELOG generator comparison (release-please, changesets, git-cliff, towncrier). |
- | [dotenvx](dotenvx/) | `dotenvx` | dotenvx reference for existing adoption or explicit user choice (encryption, multi-env, CI). |
- | [justfile](justfile/) | `justfile` | `just` command runner reference with GitHub Actions examples. |
- | [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. |
- | [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. |
- | [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. |
- | [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. |
- ### Kubernetes
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [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. |
- ### DevOps
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [opentelemetry](opentelemetry/) | `opentelemetry` | Platform-agnostic OTel reference — signal selection, span design, context propagation, sampling, OTLP exporter config. |
- | [otel-node](otel-node/) | `otel-node` | Node.js OTel setup — SDK init, auto-instrumentation, and the esbuild ESM silent-failure gotcha. |
- | [gh-fix-ci](gh-fix-ci/) | `gh-fix-ci` | Debug and fix failing GitHub Actions PR checks via `gh`. |
- | [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. |
- | [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. |
- ### Process / Meta
- | Skill | Install path | Description |
- | --- | --- | --- |
- | [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. |
- | [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. |
- | [empirical-prompt-tuning](empirical-prompt-tuning/) | `empirical-prompt-tuning` | Iteratively evaluate and improve agent-facing text instructions using unbiased subagent executors. |
- | [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. |
- | [retrospective-codify](retrospective-codify/) | `retrospective-codify` | Convert trial-and-error lessons into ast-grep rules / skills / CLAUDE.md rules. |
- | [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`). |
- | [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. |
- | [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. |
- | [extract-glossary](extract-glossary/) | `extract-glossary` | Extract domain-specific terms, repository implementation maps, and onboarding Mermaid diagrams from one or more repos / GitHub orgs. |
- | [optimizing-descriptions](optimizing-descriptions/) | `optimizing-descriptions` | Audit and rewrite SKILL.md `description` fields per the agentskills.io optimizing-descriptions framework. |
- | [mizchi-blog-style](mizchi-blog-style/) | `mizchi-blog-style` | Style guide and AI-smell detection for blog posts published as mizchi (zenn / dev.to). |
- | [tech-article-reproducibility](tech-article-reproducibility/) | `tech-article-reproducibility` | Simulate a first-time reader reproducing a technical article and list missing information. |
- ## Tools
- ### Freshness review
- The [2026-11-16 skill freshness audit](docs/skill-freshness-audit-2026-11-16.md)
- inventories all 76 maintained entrypoints, separates confirmed stale guidance
- from version-specific examples needing revalidation, and prioritizes update
- detection. The [upstream watchlist](docs/skill-upstream-watchlist.json) records
- sources and validation gates for fifteen groups affecting 38 skills. The [daily freshness check](docs/skill-freshness.md) fetches current upstream evidence,
- compares declared topics with jev-lint and fails on unreviewed upstream drift.
- It reports candidates without rewriting skills or accepting a baseline automatically.
- Run `just --justfile skill-freshness.justfile check`.
- [PR semantic review](docs/skill-review-ci.md) checks changed entrypoints and their
- English/Japanese pairs using trusted tooling. Maintained Node examples use Node 24+.
- ### Markdown links
- ```sh
- pnpm links:install
- just --justfile markdown-links.justfile check
- just --justfile markdown-links.justfile online
- ```
- Pinned lychee checks local files and heading fragments on every Markdown PR.
- External URL status checks run manually and weekly. See
- [scope, reports, and configuration](docs/markdown-links.md).
- ### Skill consistency checks
- The repository uses pinned `jev-lint` tooling and the upstream `jev-lint` skill.
- Custom rules check description/body agreement, conflicting instructions and
- terminology across all maintained skill entrypoints. English/Japanese pairs also
- receive explicit translation and activation-condition comparisons.
- ```sh
- pnpm install --frozen-lockfile
- apm install --frozen
- just --justfile skill-lint.justfile plan
- just --justfile skill-lint.justfile check
- just --justfile skill-lint.justfile translations
- ```
- Live checks read `TYPESAFE_API_KEY` from the environment. CI tests source selection
- and replays calibrated rule fixtures without making API requests. See the
- [configuration and workflow](.jev-lint/README.md) and [initial audit](.jev-lint/AUDIT.md).
- ### `waxa` — skill evaluation CLI
- 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`.
- Run via `npx` (no global install needed):
- ```sh
- npx @mizchi/waxa <eval.yaml>
- ```
- `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).
- Alternatives:
- ```sh
- # install globally (when calling waxa frequently)
- npm i -g @mizchi/waxa
- # run from source (requires Deno 2+)
- git clone https://github.com/mizchi/skills.git
- cd skills/tools/waxa
- deno task run -- path/to/eval.yaml
- ```
- Requirements: `claude` CLI on `PATH` and authenticated (OAuth login or `ANTHROPIC_API_KEY`).
- Quick reference:
- ```sh
- npx @mizchi/waxa init [--skill <name>] [--force] # scaffold <skill>/evals/ (skill-local)
- npx @mizchi/waxa <skill>/evals/eval.yaml # single run
- npx @mizchi/waxa <skill>/evals/eval.yaml --baseline # with_skill vs without_skill + delta
- npx @mizchi/waxa iterate <skill>/evals/eval.yaml [--max N] # iteration loop with ledger
- npx @mizchi/waxa compare <skill>/evals/eval.yaml --models <m1>,<m2> # multi-model comparison
- npx @mizchi/waxa variant <skill>/evals/eval.yaml --base <skill-a> --candidate <skill-b> # A/B
- ```
- 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.
- Full reference: [`tools/waxa/README.md`](tools/waxa/README.md).
- ## Recommended starter set
- If you are setting up a new project that will produce or consume skills, this combination covers selection, discovery, and iteration:
- ```yaml
- # apm.yml
- targets:
- - claude
- dependencies:
- apm:
- - mizchi/skills/apm-usage # APM manifest reference
- - mizchi/skills/skill-selector # Phase 1: pick from curated catalog
- - mizchi/skills/skill-finder # Phase 2: cross-source discovery + waxa eval gate
- - mizchi/skills/waxa-eval # waxa CLI operating manual
- - mizchi/skills/empirical-prompt-tuning # methodology / Iter 0 / [critical]-tag checklist
- ```
- Then:
- ```sh
- apm install # installs the skills under .claude/skills/
- npx @mizchi/waxa --help # cache the waxa CLI on first call
- # (or `npm i -g @mizchi/waxa` if you call waxa often enough that startup matters)
- ```
- 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).
- ## Language
- 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.
- ## Upstream skills (not in this repo)
- These are maintained in their own repositories and installed separately:
- - [mizchi/flaker](https://github.com/mizchi/flaker) — `flaker-setup`
- - [mizchi/tui.mbt](https://github.com/mizchi/tui.mbt) — `tuimbt-practice`
- - [moonbitlang/moonbit-agent-guide](https://github.com/moonbitlang/moonbit-agent-guide) — `moonbit-agent-guide`, `moonbit-refactoring`, `moonbit-c-binding`
- - [ast-grep/agent-skill](https://github.com/ast-grep/agent-skill) — `ast-grep`
- ## License
- 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
- // Pure logic for maintainer-persona: summarise fetched history, classify the
- // contributor context, render the measured block, merge it into a persona file.
- // No I/O here; measure.ts does the fetching and writing.
- export type Pull = {
- number: number;
- title: string;
- state: "MERGED" | "CLOSED" | "OPEN";
- isDraft: boolean;
- authorAssociation: string;
- author: string;
- mergedBy: string | null;
- createdAt: string;
- closedAt: string | null;
- body: string;
- reviewers: string[];
- files: string[];
- commitMessages: string[];
- labels: string[];
- closesIssues: number;
- // earliest review or comment by a human other than the author
- firstResponseAt: string | null;
- // the author had no merged PR in this repo when this PR was opened.
- // Not the same as authorAssociation, which GitHub computes at query time:
- // an outsider whose first PR merged is now CONTRIBUTOR.
- firstTimeAtCreation: boolean;
- closedByAutomation: boolean;
- };
- export type Issue = { number?: number; author?: string; body: string; labels: string[] };
- export type Tally = [string, number][];
- export type Spread = { median: number; p90: number };
- export type AssociationOutcome = {
- merged: number;
- closedUnmerged: number;
- noResponse: number;
- firstResponseHoursMedian: number | null;
- };
- export type FirstTimerOutcome = AssociationOutcome & { closedByAutomation: number };
- export type PullSummary = {
- merged: number;
- closedUnmerged: number;
- conventionalTitles: number;
- closesIssue: number;
- touchesTests: number;
- signedOff: number;
- selfMerged: number;
- drafts: number;
- japaneseBodies: number;
- politeBodies: number;
- bodyChars: Spread;
- headings: Tally;
- labels: Tally;
- humanReviewers: Tally;
- botReviewers: Tally;
- byAssociation: Record<string, AssociationOutcome>;
- firstTimers: FirstTimerOutcome;
- };
- export type IssueSummary = { count: number; japaneseBodies: number; politeBodies: number; bodyChars: Spread; headings: Tally; labels: Tally };
- export type Relation = "oss" | "internal";
- export type Context = { relation: Relation; standing: "first-time" | "returning"; exposure: "public" | "private" };
- export type Measured = {
- repo: string;
- measuredAt: string;
- headSha: string;
- context: Context;
- languages: Record<Kind, Language>;
- viewer: string;
- files: { contributing: string | null; prTemplate: string | null; issueTemplates: string[]; codeowners: boolean };
- rules: string[];
- pulls: PullSummary;
- issues: IssueSummary;
- };
- const TOP = 15;
- const CONVENTIONAL = /^(feat|fix|docs|chore|refactor|test|tests|perf|build|ci|style|revert)(\([^)]*\))?!?:\s/i;
- const TEST_PATH = /(^|\/)(tests?|__tests__|spec|specs)\/|[._-](test|spec)s?\.[a-z0-9]+$/i;
- const SIGNED_OFF = /^Signed-off-by:/m;
- const BOT = /\[bot\]$/i;
- export function spread(values: number[]): Spread {
- if (values.length === 0) return { median: 0, p90: 0 };
- const s = [...values].sort((a, b) => a - b);
- const mid = Math.floor(s.length / 2);
- const median = s.length % 2 ? s[mid] : Math.floor((s[mid - 1] + s[mid]) / 2);
- // nearest-rank percentile
- const p90 = s[Math.min(s.length - 1, Math.ceil(0.9 * s.length) - 1)];
- return { median, p90 };
- }
- function tally(groups: Iterable<string>[]): Tally {
- const counts = new Map<string, number>();
- for (const g of groups) for (const k of new Set(g)) counts.set(k, (counts.get(k) ?? 0) + 1);
- // stable: ties keep first-seen order
- return [...counts].sort((a, b) => b[1] - a[1]).slice(0, TOP);
- }
- const HEADING_MAX = 60;
- const KANA = /[\u3040-\u30ff]/;
- export function headingsOf(body: string): string[] {
- return [...body.matchAll(/^#{1,6}\s+(.+?)\s*#*\s*$/gm)].map((m) => {
- const h = m[1].toLowerCase();
- return h.length > HEADING_MAX ? `${h.slice(0, HEADING_MAX).trimEnd()}…` : h;
- });
- }
- // What a reader sees without expanding anything: <details> and HTML comments
- // (PR template instructions) are dropped, on the corpus and the draft alike.
- export function visibleText(body: string): string {
- return body.replace(/<details>[\s\S]*?<\/details>/gi, "").replace(/<!--[\s\S]*?-->/g, "");
- }
- const POLITE_END = /(です|ます|でした|ました|ません|でしょう|ください)$/;
- // 敬体 or 常体, by the majority of sentence endings; null when not Japanese.
- export function registerOf(body: string): "polite" | "plain" | null {
- const sentences = visibleText(body)
- .split(/[。.!!??\n]+/)
- .map((x) => x.replace(/[\s))」』*`]+$/, ""))
- .filter((x) => KANA.test(x));
- if (sentences.length === 0) return null;
- const polite = sentences.filter((x) => POLITE_END.test(x)).length;
- return polite * 2 >= sentences.length ? "polite" : "plain";
- }
- const hoursBetween = (a: string, b: string) => (Date.parse(b) - Date.parse(a)) / 3_600_000;
- export function summarizePulls(pulls: Pull[]): PullSummary {
- const merged = pulls.filter((p) => p.state === "MERGED");
- const closed = pulls.filter((p) => p.state === "CLOSED");
- const reviewerGroups = merged.map((p) => p.reviewers);
- const outcome = (group: Pull[]): AssociationOutcome => {
- const responded = group.filter((p) => p.firstResponseAt);
- return {
- merged: group.filter((p) => p.state === "MERGED").length,
- closedUnmerged: group.filter((p) => p.state === "CLOSED").length,
- noResponse: group.length - responded.length,
- firstResponseHoursMedian: responded.length
- ? spread(responded.map((p) => Math.round(hoursBetween(p.createdAt, p.firstResponseAt!)))).median
- : null,
- };
- };
- const done = pulls.filter((p) => p.state !== "OPEN");
- const byAssociation: Record<string, AssociationOutcome> = {};
- for (const assoc of new Set(done.map((p) => p.authorAssociation))) {
- byAssociation[assoc] = outcome(done.filter((p) => p.authorAssociation === assoc));
- }
- // automated closes are reported apart: they say nothing about human review
- const first = done.filter((p) => p.firstTimeAtCreation);
- const firstTimers = {
- ...outcome(first.filter((p) => !p.closedByAutomation)),
- closedByAutomation: first.filter((p) => p.closedByAutomation).length,
- };
- return {
- merged: merged.length,
- closedUnmerged: closed.length,
- conventionalTitles: merged.filter((p) => CONVENTIONAL.test(p.title)).length,
- closesIssue: merged.filter((p) => p.closesIssues > 0).length,
- touchesTests: merged.filter((p) => p.files.some((f) => TEST_PATH.test(f))).length,
- signedOff: merged.filter((p) => p.commitMessages.some((m) => SIGNED_OFF.test(m))).length,
- selfMerged: merged.filter((p) => p.mergedBy === p.author).length,
- drafts: pulls.filter((p) => p.isDraft).length,
- japaneseBodies: merged.filter((p) => KANA.test(p.body)).length,
- politeBodies: merged.filter((p) => registerOf(p.body) === "polite").length,
- bodyChars: spread(merged.map((p) => visibleText(p.body).length)),
- headings: tally(merged.map((p) => headingsOf(p.body))),
- labels: tally(merged.map((p) => p.labels)),
- humanReviewers: tally(reviewerGroups.map((g) => g.filter((r) => !BOT.test(r)))),
- botReviewers: tally(reviewerGroups.map((g) => g.filter((r) => BOT.test(r)))),
- byAssociation,
- firstTimers,
- };
- }
- export const KANA_RE = KANA;
- export function summarizeIssues(issues: Issue[]): IssueSummary {
- return {
- count: issues.length,
- japaneseBodies: issues.filter((i) => KANA.test(i.body)).length,
- politeBodies: issues.filter((i) => registerOf(i.body) === "polite").length,
- bodyChars: spread(issues.map((i) => visibleText(i.body).length)),
- headings: tally(issues.map((i) => headingsOf(i.body))),
- labels: tally(issues.map((i) => i.labels)),
- };
- }
- export type Language = "ja" | "en" | "mixed";
- // The language maintainers write in, decided separately for PRs and issues:
- // one repo can take English PRs and Japanese issues.
- export function languageOf(japanese: number, total: number): Language {
- if (total === 0) return "en";
- const share = japanese / total;
- return share >= 0.5 ? "ja" : share <= 0.1 ? "en" : "mixed";
- }
- export type Kind = "issue" | "pr";
- export function classify(input: {
- visibility: string;
- viewerIsOrgMember: boolean;
- myPrs: number;
- myMergedPrs: number;
- relationOverride?: Relation;
- }): Context {
- const exposure = input.visibility === "PUBLIC" ? "public" : "private";
- const relation: Relation =
- input.relationOverride ?? (exposure === "private" || input.viewerIsOrgMember ? "internal" : "oss");
- return { relation, standing: input.myMergedPrs > 0 ? "returning" : "first-time", exposure };
- }
- // ---- rendering -----------------------------------------------------------
- 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
- 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
- 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
- const pct = (n: number, d: number) => (d ? `${n}/${d} (${Math.round((100 * n) / d)}%)` : "0/0");
- const list = (t: Tally) => (t.length ? t.map(([k, n]) => `\`${k}\` ${n}`).join(", ") : "none");
- export function renderMeasured(m: Measured): string {
- const p = m.pulls;
- const ft = p.firstTimers;
- const assoc = Object.entries(p.byAssociation)
- .map(
- ([k, v]) =>
- `| ${k} | ${v.merged} | ${v.closedUnmerged} | ${v.noResponse} | ${v.firstResponseHoursMedian ?? "-"} |`,
- )
- .join("\n");
- const data = JSON.stringify(m).replace(/-->/g, "--\\u003e");
- return [
- BEGIN,
- `<!-- maintainer-persona:data ${data} -->`,
- "",
- `Measured ${m.measuredAt} at \`${m.headSha.slice(0, 12)}\` as \`${m.viewer}\`.`,
- `Context: **${m.context.relation}**, **${m.context.standing}**, exposure **${m.context.exposure}**.`,
- `PRs are written in **${m.languages.pr}** (Japanese ${pct(m.pulls.japaneseBodies, m.pulls.merged)}),` +
- ` issues in **${m.languages.issue}** (Japanese ${pct(m.issues.japaneseBodies, m.issues.count)}).` +
- ` Polite form (敬体) among Japanese bodies: PRs ${pct(m.pulls.politeBodies, m.pulls.japaneseBodies)},` +
- ` issues ${pct(m.issues.politeBodies, m.issues.japaneseBodies)}.`,
- "",
- "### Gates and files",
- "",
- `- CONTRIBUTING: ${m.files.contributing ? `\`${m.files.contributing}\`` : "none"}`,
- `- PR template: ${m.files.prTemplate ? `\`${m.files.prTemplate}\`` : "none"}`,
- `- Issue templates: ${m.files.issueTemplates.length ? m.files.issueTemplates.map((f) => `\`${f}\``).join(", ") : "none"}`,
- `- CODEOWNERS: ${m.files.codeowners ? "yes" : "no"}`,
- `- Rules on the default branch: ${m.rules.length ? m.rules.join("; ") : "none readable"}`,
- "",
- `### Pull requests (${p.merged} merged, ${p.closedUnmerged} closed unmerged)`,
- "",
- `- Visible body length (chars, outside <details> and comments): median ${p.bodyChars.median}, p90 ${p.bodyChars.p90}`,
- `- Conventional-commit titles: ${pct(p.conventionalTitles, p.merged)}`,
- `- Links a closing issue: ${pct(p.closesIssue, p.merged)}`,
- `- Touches a test file: ${pct(p.touchesTests, p.merged)}`,
- `- Signed-off-by in commits: ${pct(p.signedOff, p.merged)}`,
- `- Self-merged: ${pct(p.selfMerged, p.merged)}`,
- `- Drafts in sample: ${p.drafts}`,
- `- Headings: ${list(p.headings)}`,
- `- Labels: ${list(p.labels)}`,
- `- Human reviewers (PRs reviewed): ${list(p.humanReviewers)}`,
- `- Bot reviewers: ${list(p.botReviewers)}`,
- "",
- `First-time authors (no merged PR when they opened it): ${ft.merged} merged, ${ft.closedUnmerged} closed by a human,` +
- ` ${ft.closedByAutomation} closed by automation; ${ft.noResponse} of the human-handled got no human response;` +
- ` first human response median ${ft.firstResponseHoursMedian ?? "-"} h.`,
- "",
- "| author association as of now (merged first-timers show as CONTRIBUTOR) | merged | closed unmerged | no response | first response, median h |",
- "|---|---|---|---|---|",
- assoc,
- "",
- `### Issues (${m.issues.count})`,
- "",
- `- Visible body length (chars): median ${m.issues.bodyChars.median}, p90 ${m.issues.bodyChars.p90}`,
- `- Headings: ${list(m.issues.headings)}`,
- `- Labels: ${list(m.issues.labels)}`,
- END,
- ].join("\n");
- }
- export function readMeasuredData(text: string): Measured | null {
- const m = text.match(DATA);
- return m ? (JSON.parse(m[1]) as Measured) : null;
- }
- const SKELETON = (repo: string) => `# Persona: ${repo}
- Everything outside the measured block is hand-written and survives re-measuring.
- The measured block is regenerated by \`measure.ts\`; do not edit inside it.
- Measurements transfer between findings; the advice in sections 4-6 depends on the
- finding you had in mind when you wrote it, so re-derive it when that changes.
- ## 1. Readers
- <!-- Who triages, who reviews which directory, what they are paid to care about. -->
- ## 2. Vocabulary usable bare
- <!-- Terms that appear in their own README, labels, issues. Cite where. -->
- ## 3. Needs translating
- <!-- Your terms -> their terms. A word with zero hits in their repo goes here. -->
- | ours | why it does not land | theirs |
- |---|---|---|
- ## 4. Issue conventions
- ## 5. PR conventions
- ## 6. Landmines
- ## 7. Evidence and weak spots
- <!-- Commands you ran, what you read, and which rows rest on few examples. -->
- ## 8. Measurements
- `;
- export function mergePersona(existing: string | null, block: string): string {
- if (existing === null) {
- const repo = readMeasuredData(block)?.repo ?? "unknown";
- return `${SKELETON(repo)}${block}\n`;
- }
- const b = existing.indexOf(BEGIN);
- const e = existing.indexOf(END);
- if (b < 0 || e < b) {
- throw new Error("persona file has no measured-block markers; restore them or move the file aside");
- }
- return existing.slice(0, b) + block + existing.slice(e + END.length);
- }
maintainer-persona/scripts/persona_test.ts · Bundled script · 231 lines · 2 findings marked
- import { test } from "node:test";
- import assert from "node:assert/strict";
- import {
- classify,
- mergePersona,
- readMeasuredData,
- renderMeasured,
- summarizeIssues,
- summarizePulls,
- headingsOf,
- visibleText,
- registerOf,
- languageOf,
- type Measured,
- type Pull,
- } from "./persona.ts";
- const pull = (over: Partial<Pull>): Pull => ({
- number: 1,
- title: "fix: handle empty input",
- state: "MERGED",
- isDraft: false,
- authorAssociation: "CONTRIBUTOR",
- author: "alice",
- mergedBy: "maint",
- createdAt: "2026-01-01T00:00:00Z",
- closedAt: "2026-01-02T00:00:00Z",
- body: "## Summary\nfix\n\nCloses #3",
- reviewers: ["maint"],
- files: ["src/a.ts", "src/a.test.ts"],
- commitMessages: ["fix: handle empty input\n\nSigned-off-by: Alice <a@example.com>"],
- labels: ["bug"],
- closesIssues: 1,
- firstResponseAt: "2026-01-01T06:00:00Z",
- firstTimeAtCreation: false,
- closedByAutomation: false,
- ...over,
- });
- test("summarizePulls counts conventions over merged PRs only", () => {
- const s = summarizePulls([
- pull({ number: 1 }),
- pull({ number: 2, title: "Handle empty input", body: "x", closesIssues: 0, files: ["src/b.ts"], commitMessages: ["Handle"] }),
- pull({ number: 3, state: "CLOSED", title: "feat: rejected" }),
- ]);
- assert.equal(s.merged, 2);
- assert.equal(s.closedUnmerged, 1);
- assert.equal(s.conventionalTitles, 1);
- assert.equal(s.closesIssue, 1);
- assert.equal(s.touchesTests, 1);
- assert.equal(s.signedOff, 1);
- assert.deepEqual(s.bodyChars, { median: 13, p90: 25 });
- });
- test("summarizePulls separates bot reviewers and counts self-merges", () => {
- const s = summarizePulls([
- pull({ author: "maint", mergedBy: "maint", reviewers: ["copilot-pull-request-reviewer[bot]", "maint"] }),
- pull({ reviewers: ["maint", "bob", "maint"] }),
- ]);
- assert.deepEqual(s.humanReviewers, [["maint", 2], ["bob", 1]]);
- assert.deepEqual(s.botReviewers, [["copilot-pull-request-reviewer[bot]", 1]]);
- assert.equal(s.selfMerged, 1);
- });
- test("summarizePulls reports outcome per author association", () => {
- const s = summarizePulls([
- pull({ authorAssociation: "FIRST_TIME_CONTRIBUTOR" }),
- pull({ authorAssociation: "FIRST_TIME_CONTRIBUTOR", state: "CLOSED", firstResponseAt: null }),
- pull({ authorAssociation: "MEMBER" }),
- ]);
- assert.deepEqual(s.byAssociation.FIRST_TIME_CONTRIBUTOR, { merged: 1, closedUnmerged: 1, noResponse: 1, firstResponseHoursMedian: 6 });
- assert.equal(s.byAssociation.MEMBER.merged, 1);
- });
- test("summarizePulls counts headings once per body", () => {
- const s = summarizePulls([
- pull({ body: "## Summary\n## Summary\n### Test plan" }),
- pull({ body: "## summary\nno test plan" }),
- ]);
- assert.deepEqual(s.headings, [["summary", 2], ["test plan", 1]]);
- });
- test("summarizeIssues measures length, headings and labels", () => {
- const s = summarizeIssues([
- { body: "## Steps\n1. run", labels: ["bug"] },
- { body: "short", labels: ["bug", "p1"] },
- ]);
- assert.equal(s.count, 2);
- assert.deepEqual(s.labels, [["bug", 2], ["p1", 1]]);
- assert.deepEqual(s.headings, [["steps", 1]]);
- });
- test("classify: outsider on a public repo with no merged PR is a first-time OSS contributor", () => {
- assert.deepEqual(classify({ visibility: "PUBLIC", viewerIsOrgMember: false, myPrs: 2, myMergedPrs: 0 }), {
- relation: "oss",
- standing: "first-time",
- exposure: "public",
- });
- });
- test("classify: org member is internal even on a public repo, and exposure stays public", () => {
- assert.deepEqual(classify({ visibility: "PUBLIC", viewerIsOrgMember: true, myPrs: 5, myMergedPrs: 3 }), {
- relation: "internal",
- standing: "returning",
- exposure: "public",
- });
- });
- test("classify: private repo is internal and private; an override wins", () => {
- assert.equal(classify({ visibility: "PRIVATE", viewerIsOrgMember: false, myPrs: 0, myMergedPrs: 0 }).relation, "internal");
- assert.equal(classify({ visibility: "INTERNAL", viewerIsOrgMember: true, myPrs: 0, myMergedPrs: 0 }).exposure, "private");
- assert.equal(
- classify({ visibility: "PUBLIC", viewerIsOrgMember: true, myPrs: 0, myMergedPrs: 0, relationOverride: "oss" }).relation,
- "oss",
- );
- });
- const measured = (): Measured => ({
- repo: "acme/widget",
- measuredAt: "2026-09-24",
- headSha: "0123456789abcdef",
- context: { relation: "oss", standing: "first-time", exposure: "public" },
- languages: { pr: "en", issue: "ja" },
- viewer: "me",
- files: { contributing: "CONTRIBUTING.md", prTemplate: null, issueTemplates: [], codeowners: false },
- rules: ["pull_request: 1 approval"],
- pulls: summarizePulls([pull({})]),
- issues: summarizeIssues([{ body: "b", labels: [] }]),
- });
- test("renderMeasured embeds machine-readable data that readMeasuredData recovers", () => {
- const block = renderMeasured(measured());
- 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
- 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
- assert.equal(readMeasuredData(block)?.repo, "acme/widget");
- });
- test("mergePersona creates a skeleton with hand-edited sections outside the block", () => {
- const doc = mergePersona(null, renderMeasured(measured()));
- assert.match(doc, /^# Persona: acme\/widget/);
- for (const h of ["## 1. Readers", "## 2. Vocabulary", "## 3. Needs translating", "## 6. Landmines"]) {
- assert.ok(doc.includes(h), h);
- }
- });
- test("mergePersona replaces only the measured block and keeps hand edits", () => {
- const first = mergePersona(null, renderMeasured(measured()));
- const edited = first.replace("## 6. Landmines\n", "## 6. Landmines\n\n- never mention the old API\n");
- const next = measured();
- next.headSha = "fedcba9876543210";
- const merged = mergePersona(edited, renderMeasured(next));
- assert.ok(merged.includes("never mention the old API"));
- assert.ok(merged.includes("fedcba9876543210"));
- assert.ok(!merged.includes("0123456789abcdef"));
- });
- test("mergePersona refuses a file whose markers were removed", () => {
- assert.throws(() => mergePersona("# Persona: acme/widget\n\nhand text only\n", renderMeasured(measured())), /markers/);
- });
- test("headingsOf truncates template-length headings", () => {
- const [h] = headingsOf(`## ${"please don't delete this checklist ".repeat(4)}`);
- assert.ok(h.length <= 61, h);
- assert.ok(h.endsWith("…"));
- });
- test("summarizePulls counts bodies written in Japanese", () => {
- const s = summarizePulls([pull({ body: "## 概要\n修正します" }), pull({ body: "## Summary" })]);
- assert.equal(s.japaneseBodies, 1);
- });
- test("languageOf decides by share of Japanese bodies", () => {
- assert.equal(languageOf(6, 10), "ja");
- assert.equal(languageOf(1, 10), "en");
- assert.equal(languageOf(3, 10), "mixed");
- assert.equal(languageOf(0, 0), "en");
- });
- test("renderMeasured reports the language per submission kind", () => {
- const block = renderMeasured(measured());
- assert.match(block, /PRs are written in \*\*en\*\*/);
- assert.match(block, /issues in \*\*ja\*\*/);
- });
- test("kanji-only text is not taken as Japanese (it may be Chinese)", () => {
- assert.equal(summarizeIssues([{ body: "修复错误", labels: [] }]).japaneseBodies, 0);
- });
- test("firstTimers counts PRs whose author had no merged PR when they opened it, whatever their association is now", () => {
- const s = summarizePulls([
- // merged first PR: GitHub now labels the author CONTRIBUTOR
- pull({ authorAssociation: "CONTRIBUTOR", firstTimeAtCreation: true }),
- pull({ authorAssociation: "NONE", firstTimeAtCreation: true, state: "CLOSED", firstResponseAt: null }),
- pull({ authorAssociation: "NONE", firstTimeAtCreation: true, state: "CLOSED", closedByAutomation: true, firstResponseAt: null }),
- pull({ authorAssociation: "CONTRIBUTOR", firstTimeAtCreation: false }),
- ]);
- assert.deepEqual(s.firstTimers, {
- merged: 1,
- closedUnmerged: 1,
- closedByAutomation: 1,
- noResponse: 1,
- firstResponseHoursMedian: 6,
- });
- });
- test("visibleText drops <details> blocks and HTML comments", () => {
- assert.equal(visibleText("a\n<!-- note -->\n<details>\n<summary>x</summary>\nlong\n</details>\nb"), "a\n\n\nb");
- });
- test("body length is measured on the visible part", () => {
- const s = summarizePulls([pull({ body: "short<details>" + "x".repeat(500) + "</details>" })]);
- assert.deepEqual(s.bodyChars, { median: 5, p90: 5 });
- });
- test("renderMeasured labels the association table as current, and shows first-timers at creation", () => {
- const m = measured();
- const block = renderMeasured(m);
- assert.match(block, /association as of now/);
- assert.match(block, /First-time authors \(no merged PR when they opened it\)/);
- });
- test("registerOf classifies Japanese bodies by sentence endings", () => {
- assert.equal(registerOf("修正します。確認しました。"), "polite");
- assert.equal(registerOf("修正する。確認した。原因である。"), "plain");
- assert.equal(registerOf("Fix the link."), null);
- });
- test("summaries count polite Japanese bodies", () => {
- assert.equal(summarizeIssues([{ body: "壊れています。", labels: [] }, { body: "壊れている。", labels: [] }]).politeBodies, 1);
- assert.equal(summarizePulls([pull({ body: "直しました。" })]).politeBodies, 1);
- });
vlmkit/scripts/doctor.sh · Bundled script · 162 lines · 1 finding marked
- #!/usr/bin/env bash
- # scripts/doctor.sh — pre-flight environment check for @mizchi/vlmkit.
- #
- # Runs without depending on the vlmkit CLI itself; safe to invoke as the
- # very first thing on a new machine before installing anything. Echoes
- # PASS / WARN / FAIL per check, then a one-line verdict.
- #
- # Exit code:
- # 0 — every REQUIRED check is PASS (WARN-only is OK)
- # 1 — at least one REQUIRED check is FAIL
- #
- # Usage:
- # 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
- # or after apm install:
- # bash ~/.claude/skills/vlmkit/scripts/doctor.sh
- set -u
- # ---- output helpers --------------------------------------------------------
- if [ -t 1 ]; then
- G=$'\033[32m'; Y=$'\033[33m'; R=$'\033[31m'; D=$'\033[2m'; B=$'\033[1m'; X=$'\033[0m'
- else
- G=""; Y=""; R=""; D=""; B=""; X=""
- fi
- PASS_CT=0
- WARN_CT=0
- FAIL_CT=0
- FAIL_LINES=()
- pass() { printf ' %s✓%s %-26s %s\n' "$G" "$X" "$1" "$2"; PASS_CT=$((PASS_CT+1)); }
- warn() { printf ' %s•%s %-26s %s%s%s\n' "$Y" "$X" "$1" "$D" "$2" "$X"; WARN_CT=$((WARN_CT+1)); }
- fail() { printf ' %s✗%s %-26s %s%s%s\n' "$R" "$X" "$1" "$D" "$2" "$X"; FAIL_CT=$((FAIL_CT+1)); FAIL_LINES+=("$1 — $2"); }
- section() { printf '\n%s%s%s\n' "$B" "$1" "$X"; }
- # ---- checks ----------------------------------------------------------------
- section "Runtime"
- if command -v node >/dev/null 2>&1; then
- ver=$(node --version | sed 's/^v//')
- major=${ver%%.*}
- if [ "$major" -ge 24 ]; then
- pass "Node ($ver)" "≥ 24 required"
- else
- fail "Node ($ver)" "vlmkit requires Node 24+; upgrade via nvm/fnm/volta"
- fi
- else
- fail "Node" "not found on PATH"
- fi
- if command -v pnpm >/dev/null 2>&1; then
- pass "pnpm ($(pnpm --version))" "preferred package manager"
- elif command -v npm >/dev/null 2>&1; then
- warn "pnpm" "not found; npm ($(npm --version)) will work too"
- else
- fail "pnpm / npm" "no Node package manager found"
- fi
- # ---- vlmkit CLI --------------------------------------------------------------
- section "vlmkit CLI"
- if command -v vlmkit >/dev/null 2>&1; then
- ver=$(vlmkit --version 2>/dev/null | head -1)
- pass "vlmkit installed" "${ver:-(version not parseable)}"
- else
- warn "vlmkit CLI" "not found on PATH — install with: pnpm add -g @mizchi/vlmkit"
- fi
- # ---- Playwright Chromium ---------------------------------------------------
- section "Playwright Chromium"
- # Playwright stores browsers under one of:
- # $PLAYWRIGHT_BROWSERS_PATH (override)
- # ~/Library/Caches/ms-playwright/ (macOS default)
- # ~/.cache/ms-playwright/ (Linux default)
- # %USERPROFILE%\AppData\Local\ms-playwright\ (Windows — skipped here)
- pw_dirs=()
- [ -n "${PLAYWRIGHT_BROWSERS_PATH:-}" ] && pw_dirs+=("$PLAYWRIGHT_BROWSERS_PATH")
- pw_dirs+=("$HOME/Library/Caches/ms-playwright" "$HOME/.cache/ms-playwright")
- found_chromium=0
- for d in "${pw_dirs[@]}"; do
- if [ -d "$d" ] && ls -d "$d"/chromium-* >/dev/null 2>&1; then
- pass "Chromium installed" "$(ls -d "$d"/chromium-* 2>/dev/null | head -1 | xargs basename)"
- found_chromium=1
- break
- fi
- done
- if [ "$found_chromium" -eq 0 ]; then
- fail "Chromium" "not found — run: npx playwright install chromium"
- fi
- # ---- API keys (VLM features are optional) ----------------------------------
- section "VLM provider credentials (optional)"
- any_key=0
- for kv in "OPENROUTER_API_KEY:OpenRouter (default provider)" "ANTHROPIC_API_KEY:Anthropic (claude: prefix)" "GEMINI_API_KEY:Google AI (gemini: prefix)"; do
- k=${kv%%:*}
- desc=${kv#*:}
- v=$(eval echo "\${$k:-}")
- if [ -n "$v" ]; then
- pass "$k" "$desc (${#v} chars)"
- any_key=1
- else
- warn "$k" "$desc — unset"
- fi
- done
- if [ "$any_key" -eq 0 ]; then
- warn "VLM features" "no provider key set; vlmkit diff/snapshot still work, but fix-loop / vlm-bench / migration subagent need at least one"
- fi
- # ---- APM + sub-skills (optional) ------------------------------------------
- section "APM + sub-skills (optional)"
- if command -v apm >/dev/null 2>&1; then
- pass "apm CLI" "$(apm --version 2>/dev/null | head -1)"
- found_sub=0
- for s in vrt-visual-diff vrt-migration-eval vrt-regression-watch vrt-markup-synth vrt-css-fix-loop; do
- for root in "$HOME/.claude/skills" "$PWD/.claude/skills"; do
- if [ -f "$root/$s/SKILL.md" ]; then
- pass " $s" "$root/$s"
- found_sub=$((found_sub+1))
- break
- fi
- done
- done
- if [ "$found_sub" -eq 0 ]; then
- warn "sub-skills" "none of the 5 installed; run: apm install -g mizchi/vlmkit/.claude/skills/<name>"
- fi
- else
- warn "apm CLI" "not found; sub-skills are optional anyway"
- fi
- # ---- verdict ---------------------------------------------------------------
- section "Verdict"
- printf ' PASS: %d WARN: %d FAIL: %d\n' "$PASS_CT" "$WARN_CT" "$FAIL_CT"
- if [ "$FAIL_CT" -gt 0 ]; then
- printf '\n%s%sFailures (required):%s\n' "$R" "$B" "$X"
- for line in "${FAIL_LINES[@]}"; do
- printf ' • %s\n' "$line"
- done
- echo
- exit 1
- fi
- if [ "$WARN_CT" -gt 0 ]; then
- printf '\n%sReady for basic CLI use. Optional features may need attention above.%s\n\n' "$Y" "$X"
- else
- printf '\n%sReady.%s\n\n' "$G" "$X"
- fi
- exit 0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.