Using AI with ArkEnv

ArkEnv is designed to work seamlessly with AI coding assistants. ArkEnv provides features that help AI understand your environment schema and work more efficiently.

Coding-agent plugin

Most coding agents like Claude Code, Cursor, and Codex support plugins: a combination of skills, slash commands, and MCP tools. ArkEnv provides @arkenv/agent-plugin so those hosts can scaffold a project and catch unvalidated env access without grepping the tree.

You can add the plugin with:

npx plugins add yamcodes/arkenv

pnpm dlx plugins add yamcodes/arkenv

yarn dlx plugins add yamcodes/arkenv

bunx plugins add yamcodes/arkenv

Once it is installed, ask your assistant to add ArkEnv, or paste a prompt from Prompts that work well. The bundled skill and MCP tools are picked up automatically. You do not need to type a slash command.

The plugin teaches agents:

• Scaffold with arkenv init --agent instead of writing env.ts by hand
• Audit for raw process.env / import.meta.env access, server secrets on the client, public-prefix mistakes, and leftover v0 ambient .d.ts files

Agent skill

Agent Skills are an open standard that give new capabilities and expertise to agents. They're folders of instructions, scripts, and resources that agents can use to do things more accurately.

You can add the ArkEnv skill to your agent, making it an expert in ArkEnv and env validation:

npx skills add yamcodes/arkenv

pnpm dlx skills add yamcodes/arkenv

yarn dlx skills add yamcodes/arkenv

bunx skills add yamcodes/arkenv

The skill teaches agents:

• Schema authoring for ArkType (@arkenv/core) and Standard Schema (@arkenv/standard with Zod or Valibot)
• Client and server prefixes (NEXT_PUBLIC_, NUXT_PUBLIC_, VITE_, BUN_PUBLIC_)
• Non-interactive scaffolding with --agent
• .env.example templates without copying secret values

Find more skills at skills.sh.

Prompts that work well

Copy these into the assistant when you want it to use the CLI, honor public prefixes, and skip a runtimeEnv map.

Greenfield setup

Add ArkEnv to this repo. Run `npx arkenv init --agent`, parse the JSON on stdout, and only retry with `--force` if the refusal's `nextActions` include a `run-command` with `--force`. Do not hand-write next.config or env.ts unless init fails.

Existing keys

We already have a .env.example. Run `npx arkenv init --agent` and accept the detected keys for the schema. Keep .env.example values empty or placeholder-only; never copy secrets from .env into git.

Migrate raw process.env usage

Find direct `process.env` and `import.meta.env` reads and route them through the typed `env` export from env.ts. Do not add a runtimeEnv map. Match the framework public prefix (NEXT_PUBLIC_, NUXT_PUBLIC_, VITE_, BUN_PUBLIC_).

Add a variable

Add DATABASE_URL to the ArkEnv schema with the right type, update .env.example with an empty value, and document the key in a comment if it is non-obvious. Do not expose server keys on the client.

Hosting preset

Add Vercel hosting system variables to the ArkEnv schema using the provider snippet from `/docs/core-concepts/hosting-presets`.

Machine-readable documentation

ArkEnv's documentation site is optimized for AI consumption. Fetch markdown instead of HTML when you want a smaller context window.

Direct markdown routes

Append .md or .mdx to a docs URL, or use /llms.mdx/docs/...:

• /docs/frameworks/nextjs.md
• /docs/core-concepts/client-vs-server.md
• /llms.mdx/docs/frameworks/nextjs

Curated index (/llms.txt)

A short map of the docs lives at /llms.txt.

Full documentation (/llms-full.txt)

Every page concatenated: /llms-full.txt.

Next steps