@hexjasur/agents-md

Stop re-explaining your stack to your AI. Install it once.

Project rules and expert Agent Skills for React and the modern web, Tauri apps, CI/CD, and Ren'Py visual novels, installed into any repo with one command.

npx -y @hexjasur/agents-md

It shows what it will install, asks Continue with installation? [y/N], and on y writes:

AGENTS.md                              the project-wide contract for your agent
.agent/skills/                         the skills you chose (default: all 16)
.agent/hexjasurs.agent.scheme.json     version and SHA-256 manifest for safe updates

Works with any agent client that reads AGENTS.md and Agent Skills. Existing files are never overwritten without an explicit choice.

Who is this for?

You build…	Install	Your agent stops…
React and TypeScript apps	--skills react-typescript,ui-ux-design,testing-web	syncing state with effects, casting to any, and writing flaky tests
Any web project	(all skills)	guessing at performance, accessibility, security, and SEO
Tauri desktop apps	--skills tauri-best-practices,tauri-auto-update	granting broad permissions, shipping unsigned updates, and publishing a latest.json that misses a platform
Any repository	--skills repo-quality,github-actions	leaving broad CI permissions, unpinned actions, and unreviewable diffs
Visual novels and AVNs in Ren'Py	--skills renpy-visual-novel,renpy-ui-screens,renpy-main-menu-design	using define for changing variables, breaking saves between episodes, and shipping a stock-looking menu

npx -y @hexjasur/agents-md --list-skills                                   # see every skill
npx -y @hexjasur/agents-md --skills react-typescript,ui-ux-design           # install just these

What is included

Area	Skill	Best for
Frontend	react-typescript	React 19+ components, hooks, state and effects, strict TypeScript, forms, Tailwind
Frontend	ui-ux-design	Design tokens, hierarchy, dark and glass UI, motion, states, UI review
Frontend	testing-web	Vitest, Testing Library, Playwright, MSW, flaky tests, CI
Web platform	modern-web-guidance	Baseline-aware architecture, native APIs, progressive enhancement
Web platform	web-performance	Core Web Vitals, Lighthouse, loading, images, fonts, layout stability
Web platform	web-accessibility	WCAG 2.2, semantic HTML, keyboard, focus, forms, dialogs, contrast
Web platform	web-security	HTTPS, cookies, CSP, CORS, CSRF, validation, uploads, secrets
Web platform	web-seo	Crawlability, metadata, canonical URLs, sitemaps, structured data
Tauri	tauri-best-practices	Capabilities, CSP, Rust commands and IPC, testing, bundle size, CI, signing
Tauri	tauri-auto-update	Signed updates, latest.json, release pipeline, in-app update flow
Engineering	repo-quality	Minimal diffs, tests, builds, releases, code review
Engineering	github-actions	Least-privilege workflows, pinned actions, caching, releases, hardening
Engineering	skill-authoring	Writing, evaluating, and splitting Agent Skills and AGENTS.md
Engineering	llm-agent-integration	OpenRouter and LLM chat, streaming, tool calling, agent loops, prompt injection, safe file access, cost limits
Tauri	local-data-sqlite	Local SQLite storage, schema, migrations, WAL, backups, export, chat history
Frontend	i18n-localization	Translation keys, ICU plurals, Intl formatting, locale detection, Uzbek Latin and Cyrillic
Engineering	numerical-methods	Root finding, integration, linear systems, ODEs, tolerances, convergence tests
Engineering	rust-best-practices	Ownership, error handling, async, unsafe, clippy, audits, and release builds
Ren'Py	renpy-visual-novel	Script structure, state, saves and updates, translation, builds, itch.io
Ren'Py	renpy-ui-screens	GUI, screens, styles, ATL, PNG-free UI, accessibility, touch
Ren'Py	renpy-main-menu-design	Modern card-grid main menus: hero art, art tiles, Continue-from-save card

Every skill has a precise trigger description, a procedure, hard guardrails, real-world gotchas, a report format, and links to official sources. Each one is covered by eval prompts in evals/.

Quick start

Requirements: Node.js 18 or later.

npx -y @hexjasur/agents-md                       # interactive install into the current project
npx -y @hexjasur/agents-md init ./my-app         # install into a specific folder
npx -y @hexjasur/agents-md --yes                 # skip the confirmation (never overwrites files)
npx -y @hexjasur/agents-md --skills react-typescript,ui-ux-design
npx -y @hexjasur/agents-md update ./my-app       # refresh AGENTS.md and add missing skills
npx -y @hexjasur/agents-md --list-skills
npx -y @hexjasur/agents-md --help

--skills takes a comma-separated list, or all. update adds missing bundled skills, so pass --skills again to keep a limited set. Existing skill directories are never overwritten.

Download without npm

Every release publishes ready-to-download archives on GitHub Releases:

• agents-md-skills-vX.Y.Z.zip: only the modular skills/ bundle.
• agents-md-bundle-vX.Y.Z.zip: AGENTS.md, all skills, README, and license.
• SHA256SUMS.txt: checksums for verifying the downloads.

VERSION=1.4.0
curl -L -o agents-md-bundle.zip \
  "https://github.com/hexjasur/AGENTS.md/releases/download/v${VERSION}/agents-md-bundle-v${VERSION}.zip"
unzip agents-md-bundle.zip

From a source checkout: ./install-agents.sh init ../my-project.

Shipping a Tauri app with auto-update?

tauri-auto-update encodes a complete, safe update pipeline for Tauri v2 and GitHub Releases:

1. Signed updater artifacts and a fixed latest/download/latest.json endpoint.
2. A version-sync check across package.json, tauri.conf.json, Cargo.toml, and the changelog.
3. A draft-first release pipeline that builds every platform, verifies latest.json, and only then publishes.
4. A user-confirmed in-app update flow with progress and relaunch.
5. Update-screen resilience: reload or close mid-download, stuck progress, and a correctly scrolling dialog.

It also records the traps that bite in production: a manifest missing a platform, Linux updates needing AppImage, drafts never being served as latest, and losing the signing key. Pair it with tauri-best-practices for capabilities, CSP, commands, testing, and size.

Making a visual novel or AVN in Ren'Py?

Three skills built for VN and AVN developers, based on the official Ren'Py documentation:

• renpy-visual-novel covers project structure, define vs default vs persistent, rollback-safe state, lint-clean scripts, translations, and PC, Android, web, and itch.io builds. It includes a checklist for episodic releases, so new episodes do not break players' saves.
• renpy-ui-screens covers the GUI workflow, gui.rpy, screen language, styles, ATL transitions, PNG-free glass-style UI with solid colors, accessibility, and touch and gamepad support.
• renpy-main-menu-design replaces the stock text-list menu with a cinematic card-grid main menu: full-bleed hero art, a scrim, pill-shaped info bars, large art tiles, a Continue card that shows your latest save, hover motion, and a touch layout. It includes layout ideas and complete code.

Try prompts like:

"My game forgets choices after rollback, what's wrong?"

"I'm releasing episode 2 of my AVN. How do I keep episode 1 saves working?"

"My main menu is a boring text list. Make it look modern, with art cards and a Continue button that shows my last save."

How it works

flowchart LR
    A[Agent client] --> B[Project discovery]
    B --> C[AGENTS.md\nGlobal contract]
    B --> D[Skill catalog\nname + description]
    D --> E[Activate matching\nSKILL.md]
    E --> F[Load on demand\nreferences / scripts / assets]
    C --> G[Implement safely]
    F --> G
    G --> H[Test, audit, verify]

Loading

• AGENTS.md is the small, always-on contract: boundaries, trust and security, verification, and commit rules.
• skills/<name>/SKILL.md is a focused capability that loads only when the task matches its description.
• references/ holds deeper checklists, templates, and sources that load only when needed.

This keeps prompts small, makes guidance reusable across projects, and follows the Agent Skills specification and its progressive disclosure model.

Installation layout

my-app/
├── AGENTS.md
└── .agent/
    ├── hexjasurs.agent.scheme.json
    └── skills/
        ├── renpy-visual-novel/
        │   ├── SKILL.md
        │   └── references/
        ├── tauri-auto-update/
        └── …                     # the skills you selected

If AGENTS.md already exists, the default is to keep it and install missing skills. --yes keeps it without prompting. The manifest tracks AGENTS.md; when you keep a user-owned AGENTS.md, no manifest is created for it.

Safety model

• Installation asks for confirmation unless --yes is supplied, and existing AGENTS.md files are never overwritten implicitly.
• Interactive init offers keep, replace, delete, or cancel after an explicit choice. Existing skill directories are kept unchanged.
• update compares the installed file's SHA-256 hash with the manifest and stops on local edits unless --force is supplied.
• Skill names are validated against the bundled list, and symlinked managed files and manifest paths are rejected.

The hash detects accidental or local edits; it is not a digital signature. Run the CLI from a trusted source and review the package before using it in sensitive repositories. To report a vulnerability, see SECURITY.md.

Contributing

Contributions are welcome: sharper skills, new skills for stacks you know well, fixes, and docs. Start with CONTRIBUTING.md, or open a skill request. Please follow the Code of Conduct. Release history is in CHANGELOG.md.

npm run verify    # tests, skill and eval validation, and a dry-run package listing

Lint Agent Skills

Check the bundled skills locally or lint skills in another repository:

npx -y @hexjasur/agents-md lint ./skills
npx -y @hexjasur/agents-md lint ./skills --max-review-age-days 180

The linter checks required metadata, relative links, linked reference files, review-date freshness, symbolic links, known credential formats, and commands that pipe downloaded scripts to a shell. It is also available as a GitHub Action; check out the target repository first:

steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
  - uses: hexjasur/AGENTS.md@<full-commit-SHA> # Pin a reviewed 40-character commit SHA.
    with:
      path: skills
      max-review-age-days: 180

For supply-chain security, this repository pins workflow actions to commit SHAs, scans source links and review dates weekly, publishes OpenSSF Scorecard results, and creates provenance attestations for downloadable release files.

Run skill evals

The eval runner compares each prompt's response with and without its expected skill, then asks the configured model to grade every assertion in both responses. It uses the OpenAI-compatible Chat Completions API and needs no additional package:

export EVAL_API_KEY="your-api-key"
export EVAL_MODEL="your-model"
# Optional; defaults to https://api.openai.com/v1
export EVAL_BASE_URL="https://api.openai.com/v1"
npm run eval -- --skill web-seo
npm run eval -- --skill web-seo --case casual --output eval-results.json

In PowerShell, set these with $env:EVAL_API_KEY="your-api-key", $env:EVAL_MODEL="your-model", and optionally $env:EVAL_BASE_URL="https://api.openai.com/v1" before running the same npm commands.

EVAL_BASE_URL is the API base URL (not the /chat/completions path). Run npm run eval without filters to evaluate every skill. The report includes baseline and skill assertion pass rates and their percentage-point difference. --output writes the full responses and per-assertion grades as JSON. The eval's should_trigger field controls whether its skill is included in the skill-enabled run; it does not measure a client's automatic skill-triggering behavior. Results vary by model, so compare runs using the same model and configuration; an unqualified README score badge would be misleading.

To publish a release, a maintainer bumps package.json to a new semantic version and pushes to main. CI verifies the repository, builds and attests the downloadable archives, calculates checksums, and creates the GitHub Release. A package version change also publishes to npm with OIDC trusted publishing and provenance; no npm token or manual 2FA is needed in CI.

Before the first automated npm publish, configure a trusted publisher in the @hexjasur/agents-md package settings on npmjs.com:

• Provider: GitHub Actions
• Organization/user: hexjasur
• Repository: AGENTS.md
• Workflow filename: release.yml
• Environment: leave blank
• Allow direct npm publish

To verify a downloaded release artifact's attestation with GitHub CLI:

gh attestation verify agents-md-skills-vX.Y.Z.zip --repo hexjasur/AGENTS.md
sha256sum -c SHA256SUMS.txt

Repository administrators must separately enable branch protection or a ruleset for main; require the ci checks for Node.js 18, 20, and 22 plus a CODEOWNERS review. GitHub does not allow a checked-in file to enforce these repository settings.

Official references

• Agent Skills specification
• Ren'Py documentation
• Tauri v2 documentation
• React documentation
• Google Chrome Modern Web Guidance
• web.dev Learn and MDN Web Docs
• Google Search SEO Starter Guide
• GitHub Actions security hardening

Links

• Repository and issues: hexjasur/AGENTS.md
• License: MIT