@archal/skills 1.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Archal Labs, Inc. All rights reserved.
+
+This software is proprietary and confidential. No part of this software may be
+reproduced, distributed, or transmitted in any form or by any means, including
+photocopying, recording, or other electronic or mechanical methods, without the
+prior written permission of Archal Labs, Inc.
+
+For licensing inquiries, visit https://archal.ai or contact support@archal.ai.

package/README.md

@@ -0,0 +1,33 @@
+# @archal/skills
+
+Install [Archal](https://archal.ai) coding agent skills into your project. Works with Claude Code, Cursor, and Windsurf.
+
+## Install
+
+```bash
+npx @archal/skills
+```
+
+This copies skill files into `.claude/skills/`, `.cursor/skills/`, or `.windsurf/skills/` depending on what's detected in your project. No config, no prompts.
+
+To update:
+
+```bash
+npx @archal/skills@latest
+```
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| **onboard** | Set up Archal in your project — detects dependencies, scaffolds config, runs a first test |
+| **scenario** | Write and edit scenario markdown files with the correct format and criteria syntax |
+| **test** | Run scenarios and inline tasks, interpret results, debug failures |
+
+## What is Archal?
+
+Archal tests AI agents against digital twins of real services (GitHub, Slack, Stripe, Linear, Jira, Supabase, Google Workspace) before they touch production.
+
+- [Documentation](https://archal.ai/docs)
+- [Quickstart](https://archal.ai/docs/quickstart)
+- [GitHub](https://github.com/Archal-Labs/archal)

package/bin/install.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, cpSync, readdirSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillsSource = resolve(__dirname, '..', 'skills');
+const projectRoot = process.cwd();
+
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+const targets = [
+  { dir: '.claude', label: 'Claude Code', skillsPath: '.claude/skills' },
+  { dir: '.cursor', label: 'Cursor', skillsPath: '.cursor/skills' },
+  { dir: '.windsurf', label: 'Windsurf', skillsPath: '.windsurf/skills' },
+];
+
+const detected = targets.filter((t) => existsSync(join(projectRoot, t.dir)));
+
+if (detected.length === 0) {
+  // Default to Claude Code if no agent directory exists
+  detected.push(targets[0]);
+  mkdirSync(join(projectRoot, '.claude'), { recursive: true });
+}
+
+const skillDirs = readdirSync(skillsSource, { withFileTypes: true })
+  .filter((d) => d.isDirectory())
+  .map((d) => d.name);
+
+let installed = 0;
+
+for (const target of detected) {
+  for (const skill of skillDirs) {
+    const src = join(skillsSource, skill);
+    const dest = join(projectRoot, target.skillsPath, `archal-${skill}`);
+    mkdirSync(dest, { recursive: true });
+    cpSync(src, dest, { recursive: true });
+    installed++;
+  }
+}
+
+console.log(
+  `\n${GREEN}${BOLD}archal skills installed${RESET}`
+);
+console.log(
+  `${DIM}${installed} skill(s) -> ${detected.map((t) => t.label).join(', ')}${RESET}`
+);
+console.log(
+  `\n${DIM}Skills: onboard, scenario, test${RESET}`
+);
+console.log(
+  `${DIM}Try: "Set up Archal in this project" or "/onboard"${RESET}\n`
+);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@archal/skills",
+  "version": "1.0.0",
+  "description": "Install Archal coding agent skills into your project",
+  "type": "module",
+  "bin": {
+    "archal-skills": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "LICENSE"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Archal-Labs/archal.git",
+    "directory": "packages/archal-skills"
+  },
+  "homepage": "https://archal.ai",
+  "keywords": [
+    "archal",
+    "ai",
+    "agent",
+    "testing",
+    "skills",
+    "claude-code",
+    "cursor"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bugs": "https://github.com/Archal-Labs/archal/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/onboard/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: onboard
+description: Set up Archal in this project. Detects dependencies, installs the CLI, scaffolds config, and runs a first test.
+user-invocable: true
+---
+
+# Archal Onboard
+
+You are setting up Archal in this project. Archal tests AI agents against digital twins of real services (GitHub, Slack, Stripe, etc.) before they touch production. Walk the developer through each step interactively.
+
+## Step 1: Check if archal is installed
+
+```bash
+npx archal --version
+```
+
+If not installed, install it:
+
+```bash
+npm install -g archal
+```
+
+Or as a dev dependency:
+
+```bash
+npm install -D archal
+```
+
+The published npm package name is `archal`.
+
+## Step 2: Check authentication
+
+```bash
+archal usage
+```
+
+If not authenticated:
+
+```bash
+archal login
+```
+
+This opens a browser for OAuth. Alternatively: `archal login --token <token>`.
+
+## Step 3: Detect which twins this project needs
+
+If `package.json` exists, read it and check dependencies:
+
+| Dependency | Suggested twin |
+|-----------|----------------|
+| `@octokit/rest`, `octokit` | `github` |
+| `stripe` | `stripe` |
+| `@slack/web-api`, `@slack/bolt` | `slack` |
+| `@linear/sdk` | `linear` |
+| `@supabase/supabase-js` | `supabase` |
+| `googleapis`, `@google-cloud/*` | `google-workspace` |
+| `jira-client`, `jira.js` | `jira` |
+
+If there is no `package.json` or no matching dependencies are found, ask the developer directly: "Which services does your agent interact with?" and present the full list.
+
+All available twins: `github`, `slack`, `stripe`, `linear`, `jira`, `supabase`, `google-workspace`, `ramp`.
+
+## Step 4: Ask which workflow the developer wants
+
+Present these options:
+
+### Option A: Test my agent with scenarios
+
+1. Create `.archal.json`:
+
+```json
+{
+  "agent": "<their agent command>",
+  "twins": ["<detected twins>"]
+}
+```
+
+2. Create a starter scenario at `scenarios/hello.md`:
+
+```markdown
+# Hello World Test
+
+## Setup
+A GitHub repository with 3 open issues.
+
+## Prompt
+List all open issues and comment "acknowledged" on each one.
+
+## Success Criteria
+- [D] All 3 issues have a new comment
+- [P] Each comment says "acknowledged"
+```
+
+3. Run it: `archal run scenarios/hello.md`
+
+### Option B: Run quick inline tasks
+
+1. Create `.archal.json` with just twins:
+
+```json
+{
+  "twins": ["<detected twins>"]
+}
+```
+
+2. Run a demo: `archal run --task "Create an issue titled hello" --twin github`
+
+### Option C: Twins in my Vitest suite
+
+1. Install: `npm install -D @archal/vitest`
+2. Show them a sample `vitest.workspace.ts` config
+3. Create a sample test file
+
+### Option D: Persistent twins to develop against
+
+Run: `archal twin start <detected twins>`
+
+This gives them live twin URLs they can point their SDK clients at.
+
+## Step 5: Verify everything works
+
+Run the first test or task and show the result.
+
+## Step 6: Suggest next steps
+
+- Write more scenarios (use the `scenario` skill)
+- Run with `--runs 5` for a satisfaction score
+- Set up CI with `ARCHAL_TOKEN` secret
+
+## .archal.json full schema
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `agent` | string or `{ command, args }` | yes (for scenarios) | | Shell command to run the agent |
+| `title` | string | no | | Display name for reports |
+| `twins` | string[] | no | inferred | Which twins to provision |
+| `scenarios` | string[] | no | | Scenario file paths relative to config |
+| `seeds` | `Record<string, string>` | no | | Per-twin seed overrides |
+| `agentModel` | string | no | | LLM model the agent uses |
+| `model` | string | no | `gemini-2.5-pro` | Evaluator model |
+| `runs` | number | no | `1` | Runs per scenario |
+| `timeout` | number | no | `180` | Timeout per run in seconds |
+
+## Documentation
+
+- Quickstart: https://archal.ai/docs/quickstart
+- Full docs: https://archal.ai/docs

package/skills/scenario/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: scenario
+description: Write, edit, and validate Archal scenario files. Knows the markdown format, success criteria syntax, and config options.
+user-invocable: true
+argument-hint: "[scenario description or file path]"
+---
+
+# Archal Scenario Writer
+
+You write and edit Archal scenario files. Scenarios are markdown files that define a test for an AI agent running against digital twins.
+
+## Scenario format
+
+```markdown
+# Scenario Title
+
+## Setup
+Starting state described in plain English. Drives seed generation.
+
+## Prompt
+The task instruction given to the agent.
+
+## Expected Behavior
+Answer key for the evaluator. Never shown to the agent.
+
+## Success Criteria
+- [D] Deterministic criterion checked against twin state
+- [P] Probabilistic criterion judged by LLM
+
+## Config
+twins: github
+timeout: 90
+runs: 3
+```
+
+## Sections
+
+| Section | Required | Aliases | Purpose |
+|---------|----------|---------|---------|
+| `# Title` | yes | | Scenario name (H1 heading) |
+| `## Setup` | no | `Context`, `Initial State` | Starting state in plain English |
+| `## Prompt` | yes | `Task`, `Instruction`, `Instructions`, `Request` | Task given to the agent |
+| `## Expected Behavior` | no | `Expected Behaviour`, `Behavior`, `Behaviour`, `Judge Notes`, `Evaluation Notes` | Answer key for evaluator (never shown to agent) |
+| `## Success Criteria` | yes | `Success`, `Criteria`, `Checks`, `Assertions` | Evaluable checks |
+| `## Config` | no | | Runtime settings |
+| `## Seed State` | no | | Explicit seed data |
+
+## Success criteria syntax
+
+Each criterion is a bullet point. Tag with `[D]` or `[P]`:
+
+- `[D]` = **Deterministic**. Checked against twin state programmatically. Use for counts, existence checks, state assertions. No LLM cost.
+- `[P]` = **Probabilistic**. Judged by LLM evaluator from the trace and final state. Use for tone, quality, correctness, reasoning.
+
+If no tag is provided, Archal infers the type:
+- Numeric/state patterns (`exactly N`, `at least N`, `is created/closed/merged`, `no errors`, `count is/equals`) are auto-tagged `[D]`
+- Everything else defaults to `[P]`
+
+### Writing good criteria
+
+**Good `[D]` criteria:**
+- `[D] Exactly 4 issues are closed`
+- `[D] A pull request exists with title containing "fix"`
+- `[D] No issues have the label "wontfix"`
+- `[D] The Slack channel #incidents has at least 1 new message`
+
+**Good `[P]` criteria:**
+- `[P] Each closing comment explains the inactivity period`
+- `[P] The PR description summarizes all changes accurately`
+- `[P] The agent does not modify any unrelated issues`
+
+**Bad criteria (avoid):**
+- `The agent works correctly` (too vague)
+- `[D] The response is good` (not deterministic)
+- `[P] Exactly 3 items exist` (should be `[D]`)
+
+## Config keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `twins` | comma-separated | inferred from content | Which twins to use |
+| `seed` | string | | Named seed to load |
+| `timeout` | integer | `180` | Seconds per run |
+| `runs` | integer | `1` | Number of runs |
+| `evaluator-model` | string | `gemini-2.5-pro` | LLM for `[P]` criteria |
+| `difficulty` | `easy`/`medium`/`hard` | | Difficulty tag |
+| `tags` | comma-separated | | Scenario tags |
+
+Aliases for `evaluator-model`: `evaluator`, `evaluatormodel`, `model`.
+
+## Available twins and general-purpose seeds
+
+| Twin | Seeds |
+|------|-------|
+| `github` | `empty`, `small-project`, `enterprise-repo`, `ci-cd-pipeline`, `stale-issues`, `large-backlog` |
+| `slack` | `empty`, `engineering-team`, `busy-workspace`, `incident-active` |
+| `stripe` | `empty`, `small-business`, `checkout-flow`, `subscription-lifecycle`, `subscription-heavy` |
+| `jira` | `empty`, `small-project`, `enterprise`, `sprint-active`, `large-backlog` |
+| `linear` | `empty`, `small-team`, `engineering-org`, `multi-team`, `busy-backlog` |
+| `supabase` | `empty`, `small-project`, `saas-starter`, `ecommerce` |
+| `google-workspace` | `empty`, `assistant-baseline`, `gmail-busy-inbox`, `calendar-packed-week` |
+| `ramp` | `empty`, `default` |
+
+## Twin auto-detection from content
+
+If no `twins:` config is set, Archal infers twins from keywords in Setup, Expected Behavior, and Prompt:
+
+- `github`, `repository`, `pull request`, `create_issue` -> `github`
+- `slack`, `slack channel`, `send_message` -> `slack`
+- `linear`, `linear ticket` -> `linear`
+- `jira`, `jira sprint` -> `jira`
+- `stripe`, `payment`, `refund`, `subscription`, `invoice` -> `stripe`
+- `supabase`, `database`, `sql query` -> `supabase`
+- `google workspace`, `gmail`, `calendar event`, `inbox` -> `google-workspace`
+
+## Multi-service scenarios
+
+Use multiple twins by listing them in config:
+
+```markdown
+## Config
+twins: github, slack
+```
+
+The Setup section can describe state across both services. Each twin gets its own seed.
+
+## Validation
+
+Run `archal scenario list` to verify scenarios parse correctly. A valid scenario must have:
+- A title (H1 heading)
+- A Prompt section
+- At least one success criterion
+- At least one referenced twin (explicit or inferred)
+- Positive timeout and runs values
+
+## Common mistakes to avoid
+
+1. Writing `[D]` criteria that require subjective judgment
+2. Writing `[P]` criteria that could be checked deterministically
+3. Forgetting to specify which twin the scenario uses
+4. Writing Setup descriptions that are too vague for seed generation
+5. Using seed names that don't exist (check the seed table above)
+
+## Documentation
+
+- Writing scenarios: https://archal.ai/docs/guides/writing-scenarios
+- Twins and seeds: https://archal.ai/docs/twins/overview

package/skills/test/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: test
+description: Run Archal scenarios or inline tasks against digital twins. Interprets results and helps debug failures.
+user-invocable: true
+argument-hint: "[scenario.md or task description]"
+---
+
+# Archal Test Runner
+
+You run Archal scenarios and inline tasks against digital twins, then interpret the results.
+
+## Running a scenario
+
+```bash
+archal run scenario.md
+```
+
+With options:
+
+```bash
+archal run scenario.md --runs 5 --timeout 120 --seed enterprise-repo
+```
+
+## Running from .archal.json
+
+If `.archal.json` exists in the current directory:
+
+```bash
+archal run
+```
+
+With explicit config path:
+
+```bash
+archal run --config path/to/.archal.json
+```
+
+## Inline tasks (no scenario file)
+
+```bash
+archal run --task "Create an issue titled hello" --twin github
+archal run --task "Send a message to #general" --twin slack
+archal run --task "Create a customer and charge $50" --twin stripe
+```
+
+`--twin` is required with `--task`. Multiple twins: `--twin github --twin slack` or `--twin github,slack`.
+
+`--task` and a positional scenario argument are mutually exclusive.
+
+## CLI flags reference
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[scenario]` | Positional: scenario file path | |
+| `-c, --config <path>` | Path to `.archal.json` | auto-discovered |
+| `--task <description>` | Inline task (no scenario file) | |
+| `--twin <name>` | Twin(s) for `--task` (repeatable or comma-separated) | |
+| `-n, --runs <count>` | Number of runs | `1` |
+| `-t, --timeout <seconds>` | Timeout per run | `180` |
+| `-m, --model <model>` | Evaluator model | |
+| `-o, --output <format>` | Output format: `terminal` or `json` | `terminal` |
+| `--seed <name-or-path>` | Seed name or file path | |
+| `--tag <tag>` | Only run scenarios with this tag | |
+| `-q, --quiet` | Suppress non-error output | |
+| `-v, --verbose` | Enable debug logging | |
+| `--pass-threshold <score>` | Fail if satisfaction score below this (0-100) | `0` |
+| `--proxy` | Route agent HTTP traffic through TLS proxy to twins | |
+
+## Interpreting results
+
+### Satisfaction score
+
+Archal runs the scenario N times and evaluates each run. The satisfaction score is the percentage of runs that passed all criteria.
+
+- `100%` = every run passed every criterion
+- `80%` = 4 out of 5 runs passed
+- `0%` = no runs passed
+
+### Criterion results
+
+Each criterion reports `pass` or `fail`:
+- `[D]` criteria: checked against twin state (deterministic, no LLM)
+- `[P]` criteria: judged by LLM evaluator from trace and final state
+
+### When a run fails
+
+Re-run with `-v` to see the full trace, then classify the root cause:
+
+- **Agent bug**: agent called the wrong tool, passed wrong arguments, or stopped before completing all actions. Fix the agent code or prompt.
+- **Scenario bug**: criteria are too strict, ambiguous, or contradict each other. Setup says "some issues" but criteria expect exact counts. Fix the scenario -- make Setup more specific, adjust criteria.
+- **Seed mismatch**: twin state doesn't match Setup description. e.g. Setup says "4 stale issues" but the seed has 3. Use a different seed or adjust the Setup/criteria to match.
+
+## CI mode
+
+For CI pipelines, use `--pass-threshold`, `-o json`, and `-q`:
+
+```bash
+archal run scenario.md --runs 3 --pass-threshold 80 -o json -q
+```
+
+Exit codes:
+- `0` = passed (score >= threshold)
+- `1` = failed (score < threshold)
+- `2` = validation error
+
+GitHub Actions example:
+
+```yaml
+- name: Run Archal
+  env:
+    ARCHAL_TOKEN: ${{ secrets.ARCHAL_TOKEN }}
+  run: archal run scenario.md --runs 3 --pass-threshold 80 -o json -q
+```
+
+## Persistent twin sessions
+
+For interactive debugging, start persistent twins:
+
+```bash
+archal twin start github slack
+archal twin status
+archal twin seed github enterprise-repo
+archal twin reset
+archal twin stop
+```
+
+Twin commands:
+
+| Command | Description |
+|---------|-------------|
+| `archal twin start <twins...>` | Start a persistent twin session |
+| `archal twin start --all` | Start all available twins |
+| `archal twin status` | Show active session endpoints |
+| `archal twin list` | List active sessions |
+| `archal twin seed <twin> <seed-name>` | Load a named seed |
+| `archal twin seed <twin> --file <path>` | Load a JSON seed file |
+| `archal twin reset [twin]` | Reset twin state |
+| `archal twin stop` | Tear down the session |
+| `archal twin renew [ttl-seconds]` | Extend session lifetime |
+| `archal twin attach <session-id>` | Attach to existing session |
+
+Seed format for `twin start`: `--seed github:enterprise-repo --seed stripe:small-business`.
+
+## Environment variables set for the agent
+
+When `archal run` spawns the agent process, these env vars are injected:
+
+| Variable | Description |
+|----------|-------------|
+| `ARCHAL_ENGINE_TASK` | The task/prompt text from the scenario |
+| `ARCHAL_TWIN_NAMES` | Comma-separated list of active twin names |
+| `ARCHAL_<TWIN>_URL` | MCP endpoint for a twin (e.g. `ARCHAL_GITHUB_URL`) |
+| `ARCHAL_<TWIN>_BASE_URL` | REST API base URL (e.g. `ARCHAL_GITHUB_BASE_URL`) |
+| `ARCHAL_MCP_CONFIG` | Path to MCP server config JSON file |
+| `ARCHAL_MCP_SERVERS` | MCP servers JSON string |
+| `ARCHAL_TOKEN` | Auth token for twin API calls |
+| `ARCHAL_PREFLIGHT` | Set to `1` during boot check; agent should exit early |
+| `ARCHAL_METRICS_FILE` | Path to write agent metrics JSON |
+| `ARCHAL_AGENT_TRACE_FILE` | Path to write agent trace JSON |
+| `ARCHAL_REST_CONFIG` | Path to REST routing config (when applicable) |
+| `HTTPS_PROXY` | TLS proxy URL (when `--proxy` is active) |
+| `NODE_EXTRA_CA_CERTS` | Path to proxy CA cert (when `--proxy` is active) |
+
+Twin names are uppercased with hyphens replaced by underscores:
+- `github` -> `ARCHAL_GITHUB_URL`, `ARCHAL_GITHUB_BASE_URL`
+- `google-workspace` -> `ARCHAL_GOOGLE_WORKSPACE_URL`, `ARCHAL_GOOGLE_WORKSPACE_BASE_URL`
+
+## Two ways agents connect to twins
+
+**1. Environment variables (default):** Read `ARCHAL_<TWIN>_BASE_URL` and pass to SDK:
+
+```typescript
+const octokit = new Octokit({ baseUrl: process.env.ARCHAL_GITHUB_BASE_URL });
+```
+
+**2. TLS proxy (`--proxy`):** Intercepts HTTPS to real domains and redirects to twins. Agent code runs unmodified:
+
+```bash
+archal run --task "..." --proxy
+```
+
+## Browse scenarios
+
+```bash
+archal scenario list
+archal scenario list --tag security
+archal scenario list --difficulty hard
+archal scenario list --json
+```
+
+## Documentation
+
+- Running with an agent: https://archal.ai/docs/guides/run-with-agent
+- Twins overview and seeds: https://archal.ai/docs/twins/overview
+- CI setup: https://archal.ai/docs/guides/ci