ArkEnv

https://github.com/yamcodes/arkenv
Admin
Environment variable validation from editor to runtime for modern JavaScript runtimes, providing...
Tokens:297,706
Snippets:3,925
Trust Score:8.4
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run the Next.js example

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/nextjs/README.md

Commands to install dependencies and run the development or production build.

```bash
# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Build for production
pnpm build
```

--------------------------------

### Run development mode

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/bun/README.md

Start the development server, which may trigger automatic dependency installation.

```bash
cd apps/playgrounds/bun && bun dev
```

--------------------------------

### Initialize ArkEnv Project

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/www/content/docs/cli/index.mdx

Run the CLI using your package manager to start the interactive setup process.

```npm
npx @arkenv/cli@latest init [project-name] [options]
```

--------------------------------

### Complete CI Workflow Example

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/ci/github-actions.md

A full example integrating remote caching and pnpm setup into a single workflow.

```yaml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - uses: pnpm/action-setup@v3
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: turbo run build --affected

      - name: Test
        run: turbo run test --affected

      - name: Lint
        run: turbo run lint --affected
```

--------------------------------

### Install the package

Source: https://github.com/yamcodes/arkenv/blob/dev/packages/fumadocs-ui/README.md

Install the package using pnpm.

```bash
pnpm add @arkenv/fumadocs-ui
```

--------------------------------

### Install dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/bun-react/README.md

Run this command to install the project dependencies.

```bash
bun install
```

--------------------------------

### Copy environment example file

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/node/README.md

Create a local .env file from the provided example.

```bash
cp .env.example .env
```

--------------------------------

### Complete Next.js configuration example

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/environment/gotchas.md

A comprehensive example showing global environment settings and task-specific configurations.

```json
{
  "$schema": "https://v2-9-17-canary-1.turborepo.dev/schema.json",
  "globalEnv": ["CI", "NODE_ENV", "VERCEL"],
  "globalPassThroughEnv": ["GITHUB_TOKEN", "VERCEL_URL"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["DATABASE_URL", "NEXT_PUBLIC_*", "!NEXT_PUBLIC_ANALYTICS_ID"],
      "passThroughEnv": ["SENTRY_AUTH_TOKEN"],
      "inputs": [
        "$TURBO_DEFAULT$",
        ".env",
        ".env.local",
        ".env.production",
        ".env.production.local"
      ],
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}
```

--------------------------------

### Benchmark install times

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/best-practices-performance.md

Commands to measure installation performance under different conditions.

```bash
# Clean install
rm -rf node_modules pnpm-lock.yaml
time pnpm install

# Cached install (with lockfile)
rm -rf node_modules
time pnpm install --frozen-lockfile

# With store cache
time pnpm install --frozen-lockfile --prefer-offline
```

--------------------------------

### Start development server

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/bun-react/README.md

Run this command to launch the development server.

```bash
bun dev
```

--------------------------------

### Complete Turborepo configuration example

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/environment/RULE.md

A comprehensive example showing schema definition, global variables, and task-specific configurations.

```json
{
  "$schema": "https://v2-9-17-canary-1.turborepo.dev/schema.json",
  "globalEnv": ["CI", "NODE_ENV"],
  "globalPassThroughEnv": ["GITHUB_TOKEN", "NPM_TOKEN"],
  "tasks": {
    "build": {
      "env": ["DATABASE_URL", "API_*"],
      "passThroughEnv": ["SENTRY_AUTH_TOKEN"]
    },
    "test": {
      "env": ["TEST_DATABASE_URL"]
    }
  }
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/www/content/docs/bun-plugin/index.mdx

Install the required packages for the plugin to function.

```bash
@arkenv/bun-plugin arkenv arktype
```

--------------------------------

### Install dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/docs/CONTRIBUTING.md

Install project dependencies using pnpm.

```sh
pnpm install
```

--------------------------------

### Add Icon to Diagram Examples

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/excalidraw/scripts/README.md

Various examples demonstrating how to add icons with labels, custom paths, and edit modes.

```bash
# Add EC2 icon at position (400, 300)
python add-icon-to-diagram.py diagram.excalidraw EC2 400 300

# Add VPC icon with label
python add-icon-to-diagram.py diagram.excalidraw VPC 200 150 --label "VPC"

# Safe edit mode is enabled by default (avoids editor overwrite issues)
# Use `--no-use-edit-suffix` to disable
python add-icon-to-diagram.py diagram.excalidraw EC2 500 300

# Add icon from another library
python add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
   --library-path libraries/gcp-icons --label "API Server"
```

--------------------------------

### Example project structure

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/core-workspaces.md

Standard directory layout for a pnpm monorepo.

```text
my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── pnpm-lock.yaml
├── packages/
│   ├── core/
│   │   └── package.json
│   ├── utils/
│   │   └── package.json
│   └── types/
│       └── package.json
└── apps/
    ├── web/
    │   └── package.json
    └── api/
        └── package.json
```

--------------------------------

### Start development server

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/node/README.md

Launch the development server with hot reloading enabled.

```bash
npm run dev
```

--------------------------------

### Install dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playwright-www/README.md

Commands to install project dependencies and the required Playwright browsers.

```bash
pnpm install
```

```bash
pnpm exec playwright install
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/core-cli.md

Use these commands to install project dependencies from the lockfile.

```bash
pnpm install
# or
pnpm i
```

--------------------------------

### Install turbo-ignore

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/ci/vercel.md

Commands to install or execute the turbo-ignore utility for skipping unnecessary builds.

```bash
npx turbo-ignore
```

```bash
pnpm add -D turbo-ignore
```

--------------------------------

### Examples of add-arrow.py usage

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/excalidraw/scripts/README.md

Various command-line examples for adding arrows with different styles, labels, and edit modes.

```bash
# Simple arrow
python add-arrow.py diagram.excalidraw 300 200 500 300

# Arrow with label
python add-arrow.py diagram.excalidraw 300 200 500 300 --label "HTTPS"

# Dashed arrow with custom color
python add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"

# Safe edit mode is enabled by default (avoids editor overwrite issues)
# Use `--no-use-edit-suffix` to disable
python add-arrow.py diagram.excalidraw 300 200 500 300
```

--------------------------------

### Install @arkenv/nextjs

Source: https://github.com/yamcodes/arkenv/blob/dev/packages/nextjs/README.md

Install the package and its peer dependency using pnpm.

```bash
pnpm add @arkenv/nextjs arktype
```

--------------------------------

### Run for production

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/bun-react/README.md

Run this command to start the application in production mode.

```bash
bun start
```

--------------------------------

### Install dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/www/content/docs/arkenv/integrations/standard-schema.mdx

Install the necessary packages to use ArkEnv with Zod.

```bash
arkenv arktype zod
```

--------------------------------

### Text Element Examples

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/excalidraw/references/element-types.md

JSON examples for configuring title and annotation text elements.

```json
{
  "type": "text",
  "x": 100,
  "y": 50,
  "width": 400,
  "height": 40,
  "text": "System Architecture",
  "fontSize": 32,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "top"
}
```

```json
{
  "type": "text",
  "x": 150,
  "y": 200,
  "width": 100,
  "height": 20,
  "text": "User input",
  "fontSize": 14,
  "fontFamily": 1,
  "textAlign": "left",
  "verticalAlign": "top"
}
```

--------------------------------

### Theme layer example structure

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/advanced-layers.md

Example directory layout for a theme-based layer.

```text
theme-layer/
├── nuxt.config.ts
├── app/
│   ├── app.config.ts
│   ├── components/
│   │   ├── ThemeButton.vue
│   │   └── ThemeCard.vue
│   ├── composables/
│   │   └── useTheme.ts
│   └── assets/
│       └── theme.css
└── package.json
```

--------------------------------

### Format commit message examples

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/create-skill/SKILL.md

Standardized way to present input/output examples within a skill.

```markdown
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
```

--------------------------------

### Install workspace dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/bun/README.md

Execute this command from the repository root to install all workspace dependencies.

```bash
cd <repo-root> && pnpm install
```

--------------------------------

### Common Workflows

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-cli.md

Standard sequences for development, deployment, and project setup.

```bash
# Install dependencies and start dev
pnpm install
pnpm dev  # or npx nuxt dev
```

```bash
# Build and preview locally
pnpm build
pnpm preview

# Or for static hosting
pnpm generate
```

```bash
# Install deps and prepare types
pnpm install
npx nuxt prepare
```

--------------------------------

### Install Bun-specific dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/bun/README.md

Run this command within the playground directory to install dependencies specific to the Bun environment.

```bash
cd apps/playgrounds/bun && bun install
```

--------------------------------

### Skip scripts during install

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/best-practices-performance.md

Useful for CI environments where postinstall scripts are not required.

```bash
pnpm install --ignore-scripts
```

--------------------------------

### Profile resolution

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/best-practices-performance.md

Debugs slow installation processes using verbose logging.

```bash
# Verbose logging
pnpm install --reporter=append-only

# Debug mode
DEBUG=pnpm:* pnpm install
```

--------------------------------

### Run development workflow

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/watch/RULE.md

Example of running dev servers while watching for build changes.

```bash
# Run dev servers and watch for build changes
turbo watch dev build
```

--------------------------------

### npx nuxt preview

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-cli.md

Starts a local server to preview the production build.

```APIDOC
## npx nuxt preview

### Description
Serves the production build locally for testing.

### Parameters
- **--port** (number) - Optional - Port to listen on.
```

--------------------------------

### Configure Diamond Example

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/excalidraw/references/element-types.md

A complete JSON configuration for a diamond shape.

```json
{
  "type": "diamond",
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 150,
  "backgroundColor": "#ffe4a3",
  "text": "Valid?",
  "fontSize": 18,
  "textAlign": "center",
  "verticalAlign": "middle"
}
```

--------------------------------

### Directory Structure Example

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/triage/OUT-OF-SCOPE.md

Shows the expected file layout for the .out-of-scope/ directory.

```text
.out-of-scope/
├── dark-mode.md
├── plugin-system.md
└── graphql-api.md
```

--------------------------------

### Deploy to Netlify

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-deployment.md

CLI commands to install the Netlify tool and deploy the application to production.

```bash
# Install Netlify CLI
npm i -g netlify-cli

# Deploy
netlify deploy --prod
```

--------------------------------

### Configure Arkenv Example Metadata

Source: https://github.com/yamcodes/arkenv/blob/dev/examples/README.md

Add this configuration to the package.json of a new playground to enable automatic example generation.

```json
{
  "arkenvExamples": [
    {
      "name": "with-my-tool",
      "packageManager": "npm"
    }
  ]
}
```

--------------------------------

### Install Husky and lint-staged

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/bulletproof-react/references/project-standards.md

Commands to initialize Husky and lint-staged for pre-commit hooks.

```shell
npm install -D husky lint-staged
npx husky init
```

--------------------------------

### Setup .pnpmfile.cjs

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/features-hooks.md

Create a .pnpmfile.cjs file at the workspace root to define readPackage and afterAllResolved hooks.

```js
// .pnpmfile.cjs
function readPackage(pkg, context) {
  // Modify package metadata
  return pkg
}

function afterAllResolved(lockfile, context) {
  // Modify lockfile
  return lockfile
}

module.exports = {
  hooks: {
    readPackage,
    afterAllResolved
  }
}
```

--------------------------------

### Deploy to Vercel

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-deployment.md

CLI commands to install the Vercel tool and deploy the application.

```bash
# Install Vercel CLI
npm i -g vercel

# Deploy
vercel
```

--------------------------------

### Define module dependencies in Nuxt

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-modules.md

Use the moduleDependencies property to ensure required modules are installed and configured before your module setup runs.

```ts
export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    '@nuxt/image': {
      version: '>=1.0.0',
      defaults: {
        provider: 'ipx',
      },
    },
  },
  setup() {
    // @nuxt/image is guaranteed to be installed
  },
})
```

--------------------------------

### Install layer dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/advanced-layers.md

Automatically install dependencies for a layer by setting the install option.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    ['github:user/layer', { install: true }],
  ],
})
```

--------------------------------

### Install @arkenv/nuxt

Source: https://github.com/yamcodes/arkenv/blob/dev/packages/nuxt/README.md

Install the required packages using npm.

```bash
npm install @arkenv/nuxt arktype
```

--------------------------------

### Library Setup Instructions

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/excalidraw/SKILL.md

Instructions provided to users when a requested icon library is missing.

```text
To use [AWS/GCP/Azure/etc.] architecture icons, please follow these steps:

1. Visit https://libraries.excalidraw.com/
2. Search for "[AWS Architecture Icons/etc.]" and download the .excalidrawlib file
3. Create directory: skills/excalidraw/libraries/[icon-set-name]/
4. Place the downloaded file in that directory
5. Run the splitter script:
   python skills/excalidraw/scripts/split-excalidraw-library.py skills/excalidraw/libraries/[icon-set-name]/

This will split the library into individual icon files for efficient use.
After setup is complete, I can create your diagram using the actual AWS/cloud icons.

Alternatively, I can create the diagram now using simple shapes (rectangles, ellipses) 
which you can later replace with icons manually in Excalidraw.
```

--------------------------------

### Launch Evaluation Viewer

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/create-skill/SKILL.md

Start the evaluation viewer server to review qualitative outputs and quantitative benchmark data.

```bash
nohup python <create-skill-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```

--------------------------------

### Lockfile-only install

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/best-practices-performance.md

Updates the lockfile without performing a full installation.

```bash
pnpm install --lockfile-only
```

--------------------------------

### Install pnpm

Source: https://github.com/yamcodes/arkenv/blob/dev/docs/CONTRIBUTING.md

Use this command to install the pnpm package manager.

```sh
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

--------------------------------

### Install ArkEnv dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/www/content/docs/vite-plugin/index.mdx

Install the required plugin and ArkType packages.

```package-install
@arkenv/vite-plugin arkenv arktype
```

--------------------------------

### Project lifecycle commands

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/playgrounds/solid-start/README.md

Standard commands for installing dependencies, running the development server, and building for production.

```bash
# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start
```

--------------------------------

### Preview Production Build

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-cli.md

Serves the built application locally to verify production behavior.

```bash
# Preview after build
npx nuxt preview

# Custom port
npx nuxt preview --port 4000
```

--------------------------------

### Initialize a New Nuxt Project

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-cli.md

Use these commands to scaffold a new Nuxt project with various configuration options.

```bash
# Interactive project creation
npx nuxi@latest init my-app

# With specific package manager
npx nuxi@latest init my-app --packageManager pnpm

# With modules
npx nuxi@latest init my-app --modules "@nuxt/ui,@nuxt/image"

# From template
npx nuxi@latest init my-app --template v3

# Skip module selection prompt
npx nuxi@latest init my-app --no-modules
```

--------------------------------

### Setup Development Branch

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/tackle-issue/SKILL.md

Creates and checks out a new branch linked to the specified issue.

```bash
gh issue develop <issue-number> --checkout
```

--------------------------------

### Install with offline preference

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/best-practices-ci.md

Uses cached packages when available to speed up the installation process.

```bash
pnpm install --frozen-lockfile --prefer-offline
```

--------------------------------

### Useful pnpm installation flags

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/core-cli.md

Common flags to modify the behavior of the install command.

```bash
# Ignore scripts
pnpm install --ignore-scripts

# Prefer offline (use cache)
pnpm install --prefer-offline

# Strict peer dependencies
pnpm install --strict-peer-dependencies

# Production only
pnpm install --prod
pnpm install -P

# No optional dependencies
pnpm install --no-optional
```

--------------------------------

### Bootstrap an ArkEnv project with CLI

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/www/content/docs/arkenv/examples.mdx

Use the ArkEnv CLI to initialize a new project from a specific example template.

```npm
npx @arkenv/cli@latest init --example <example-name>
```

--------------------------------

### Use frozen lockfile for installs

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/best-practices-performance.md

Skips the resolution phase during installation when a lockfile is present.

```bash
pnpm install --frozen-lockfile
```

--------------------------------

### CI setup decision tree

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/SKILL.md

Resources for configuring CI environments and optimizing build performance.

```text
CI setup?
├─ GitHub Actions → references/ci/github-actions.md
├─ Vercel deployment → references/ci/vercel.md
├─ Remote cache in CI → references/caching/remote-cache.md
├─ Only build changed packages → --affected flag
├─ Skip unnecessary builds → turbo-ignore (references/cli/commands.md)
└─ Skip container setup when no changes → turbo-ignore
```

--------------------------------

### Install @arkenv/vite-plugin and arktype

Source: https://github.com/yamcodes/arkenv/blob/dev/packages/vite-plugin/README.md

Run this command to install the necessary dependencies for the Vite plugin.

```sh
npm install @arkenv/vite-plugin arktype
```

--------------------------------

### Install ArkEnv dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/www/content/docs/arkenv/quickstart.mdx

Install ArkEnv with recommended ArkType integration or as a standalone package.

```bash
arkenv arktype
```

```bash
arkenv
```

--------------------------------

### Full Diagram Workflow

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/excalidraw/SKILL.md

A complete example demonstrating the sequence of creating a diagram, adding icons, and connecting them.

```bash
# Step 1: Create base diagram with title and structure
# (Create .excalidraw file with initial elements)

# Step 2: Add icons with labels
python scripts/add-icon-to-diagram.py my-diagram.excalidraw "Internet-gateway" 200 150 --label "Internet Gateway"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw VPC 250 250
python scripts/add-icon-to-diagram.py my-diagram.excalidraw ELB 350 300 --label "Load Balancer"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw EC2 450 350 --label "EC2 Instance"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw RDS 550 400 --label "Database"

# Step 3: Add connecting arrows
python scripts/add-arrow.py my-diagram.excalidraw 250 200 300 250  # Internet → VPC
python scripts/add-arrow.py my-diagram.excalidraw 300 300 400 300  # VPC → ELB
python scripts/add-arrow.py my-diagram.excalidraw 400 330 500 350  # ELB → EC2
python scripts/add-arrow.py my-diagram.excalidraw 500 380 600 400  # EC2 → RDS
```

--------------------------------

### Package Manager Setup

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/ci/github-actions.md

Configuration steps for pnpm, Yarn, and Bun package managers in GitHub Actions.

```yaml
- uses: pnpm/action-setup@v3
  with:
    version: 9

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: "pnpm"

- run: pnpm install --frozen-lockfile
```

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: "yarn"

- run: yarn install --frozen-lockfile
```

```yaml
- uses: oven-sh/setup-bun@v1
  with:
    bun-version: latest

- run: bun install --frozen-lockfile
```

--------------------------------

### Initialize ArkEnv

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/arkenv/SKILL.md

Run the CLI to detect the framework and configure plugins and type augmentations.

```bash
pnpm dlx @arkenv/cli@latest init [options]
```

--------------------------------

### Initialize a new layer template

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/advanced-layers.md

Use nuxi to scaffold a new layer project.

```bash
npx nuxi init --template layer my-layer
```

--------------------------------

### Install multiple versions of the same package

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/features-aliases.md

Use aliases to install different versions of a package side-by-side.

```json
{
  "dependencies": {
    "lodash3": "npm:lodash@3",
    "lodash4": "npm:lodash@4"
  }
}
```

```js
import lodash3 from 'lodash3'
import lodash4 from 'lodash4'
```

--------------------------------

### Initialize OpenNext

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/next-best-practices/self-hosting.md

Commands to initialize or build an OpenNext project for serverless environments.

```bash
npx create-sst@latest
# or
npx @opennextjs/aws build
```

--------------------------------

### Define skill description examples

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/write-a-skill/SKILL.md

Examples of effective and ineffective skill descriptions for agent triggering.

```text
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

```text
Helps with documents.
```

--------------------------------

### Implement Server Plugins

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/features-server.md

Plugins run once when the server starts. Use hooks to initialize resources and attach them to the event context.

```ts
// server/plugins/db.ts
export default defineNitroPlugin((nitroApp) => {
  // Initialize database connection
  const db = createDbConnection()

  // Add to context
  nitroApp.hooks.hook('request', (event) => {
    event.context.db = db
  })
})
```

--------------------------------

### Install ignoring lifecycle scripts

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/pnpm/references/best-practices-ci.md

Skips execution of lifecycle scripts for faster installs; use with caution.

```bash
pnpm install --frozen-lockfile --ignore-scripts
```

--------------------------------

### View Test File Structure

Source: https://github.com/yamcodes/arkenv/blob/dev/apps/www/tests/README.md

Example showing the colocation of a component file and its corresponding test file.

```text
apps/www/components/page/star-us-button.tsx
apps/www/components/page/star-us-button.test.tsx
```

--------------------------------

### Bad Agent Brief Example

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/triage/AGENT-BRIEF.md

An example of a poorly structured brief that lacks necessary context and criteria.

```markdown
## Agent Brief

**Summary:** Fix the triage bug

**What to do:**
The triage thing is broken. Look at the main file and fix it.
The function around line 150 has the issue.

**Files to change:**
- src/triage/handler.ts (line 150)
- src/types.ts (line 42)
```

--------------------------------

### Good Agent Brief Example (Enhancement)

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/triage/AGENT-BRIEF.md

An example of a well-defined enhancement request for tracking rejected features.

```markdown
## Agent Brief

**Category:** enhancement
**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests

**Current behavior:**
When a feature request is rejected, the issue is closed with a `wontfix` label
and a comment. There is no persistent record of the decision or reasoning.
Future similar requests require the maintainer to recall or search for the
prior discussion.

**Desired behavior:**
Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
files that capture the decision, reasoning, and links to all issues that
requested the feature. When triaging new issues, these files should be
checked for matches.

**Key interfaces:**
- Markdown file format in `.out-of-scope/` - each file should have a
  `# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
  and a `**Prior requests:**` list with issue links
- The triage workflow should read all `.out-of-scope/*.md` files early
  and match incoming issues against them by concept similarity

**Acceptance criteria:**
- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
- [ ] The file includes the decision, reasoning, and link to the closed issue
- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
      appended to its "Prior requests" list rather than creating a duplicate
- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
      when a new issue matches a prior rejection

**Out of scope:**
- Automated matching (human confirms the match)
- Reopening previously rejected features
- Bug reports (only enhancement rejections go to `.out-of-scope/`)
```

--------------------------------

### Good Agent Brief Example (Bug)

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/triage/AGENT-BRIEF.md

An example of a well-defined bug report focusing on truncation logic.

```markdown
## Agent Brief

**Category:** bug
**Summary:** Skill description truncation drops mid-word, producing broken output

**Current behavior:**
When a skill description exceeds 1024 characters, it is truncated at exactly
1024 characters regardless of word boundaries. This produces descriptions
that end mid-word (e.g. "Use when the user wants to confi").

**Desired behavior:**
Truncation should break at the last word boundary before 1024 characters
and append "..." to indicate truncation.

**Key interfaces:**
- The `SkillMetadata` type's `description` field - no type change needed,
  but the validation/processing logic that populates it needs to respect
  word boundaries
- Any function that reads SKILL.md frontmatter and extracts the description

**Acceptance criteria:**
- [ ] Descriptions under 1024 chars are unchanged
- [ ] Descriptions over 1024 chars are truncated at the last word boundary
      before 1024 chars
- [ ] Truncated descriptions end with "..."
- [ ] The total length including "..." does not exceed 1024 chars

**Out of scope:**
- Changing the 1024 char limit itself
- Multi-line description support
```

--------------------------------

### GitHub Actions Deployment Workflow

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/nuxt/references/core-deployment.md

Example YAML configuration for automating deployment to a server via rsync.

```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - run: npm ci
      - run: npm run build
      
      # Deploy to your server (example: rsync to VPS)
      - name: Deploy to server
        run: rsync -avz .output/ user@server:/app/
```

--------------------------------

### Install Workspace Dependencies

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/best-practices/packages.md

Run the package manager install command to update the lockfile after adding a new dependency.

```bash
pnpm install  # Updates lockfile with new dependency
```

--------------------------------

### Install Dependencies Locally

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/turborepo/references/best-practices/dependencies.md

Use package manager filters to install dependencies in specific packages rather than the root.

```bash
# Good: Install in specific package
pnpm add react --filter=@repo/ui
pnpm add next --filter=web

# Avoid: Installing in root
pnpm add react -w  # Only for repo-level tools!
```

--------------------------------

### Package a skill

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/create-skill/SKILL.md

Creates a .skill file for distribution if the present_files tool is available.

```bash
python -m scripts.package_skill <path/to/skill-folder>
```

--------------------------------

### Initialize ArkEnv with Bun

Source: https://github.com/yamcodes/arkenv/blob/dev/README.md

Run this command to initialize ArkEnv using the Bun package manager.

```sh
bunx @arkenv/cli@latest init
```

--------------------------------

### Explicit return type example

Source: https://github.com/yamcodes/arkenv/blob/dev/skills/typescript/references/type-explicit-return-types.md

An example of an exported function using an explicit interface for the return type to optimize compilation.

```typescript
interface UserProfile {
  id: string
  name: string
  email: string
  createdAt: Date
  permissions: Permission[]
}

export function fetchUserProfile(userId: string): Promise<UserProfile> {
  return fetch(`/api/users/${userId}`)
    .then(res => res.json())
    .then(data => ({
      id: data.id,
      name: data.name,
      email: data.email,
      createdAt: new Date(data.created_at),
      permissions: data.permissions,
    }))
}
```
Tokens:
Raw