@r4-sdk/skill 1.0.0

package/README.md

@@ -0,0 +1,40 @@
+# @r4-sdk/skill
+
+Official R4 OpenClaw skill package. It bundles the maintained `SKILL.md` instructions that teach agent runtimes how to use R4 for:
+
+- zero-trust vault secret retrieval through the `r4` CLI
+- project metadata lookups
+- domain search, purchase, and DNS management through the machine API
+- AGENT feedback submission when a needed R4 capability is missing
+
+## Install
+
+```bash
+npm install @r4-sdk/skill
+```
+
+The package expects the `r4` CLI to be available on the host runtime.
+
+## Usage
+
+```ts
+import { getSkillPath, skillContent } from '@r4-sdk/skill'
+
+console.log(getSkillPath())
+console.log(skillContent)
+```
+
+`getSkillPath()` returns the packaged `SKILL.md` path on disk, and `skillContent`
+returns the same file contents as a string.
+
+## Development
+
+```bash
+pnpm run test
+pnpm run build
+pnpm run test:pack
+pnpm run clean
+```
+
+This package is released in lockstep with `@r4-sdk/sdk`,
+`@r4-sdk/mcp`, and `@r4-sdk/cli` through `pnpm release:sdk`.

package/lib/SKILL.md

@@ -0,0 +1,197 @@
+# R4 Skill
+
+You have access to the **R4 platform** for zero-trust secret retrieval, project metadata, and domain management.
+
+Use R4 first whenever you need:
+
+- credentials, API keys, tokens, passwords, SSH keys, or other secrets
+- project metadata that is already managed in R4
+- domain search, purchase, or DNS management through the R4 machine API
+
+Do not ask the user for credentials that may already be available through R4.
+
+## Setup
+
+The `r4` CLI should already be available on this machine.
+
+- In managed R4 OpenClaw deployments, the runtime is typically preconfigured.
+- In standalone installs, confirm setup with `r4 auth status` and `r4 doctor`.
+- If the runtime still needs bootstrap, use `r4 agent init --credentials-file <path>` or `r4 auth login`.
+
+## Vault Secrets
+
+R4 is your password manager and secret store. Check it before asking the user for credentials.
+
+### Verify local runtime health
+
+```bash
+r4 auth status
+r4 doctor
+```
+
+### List locally decrypted environment variables
+
+```bash
+r4 vault list
+```
+
+### Get one secret value
+
+```bash
+r4 vault get <KEY>
+```
+
+This prints the raw value, so only use it when the output is needed by another command.
+
+### Search vault items by name
+
+```bash
+r4 vault search <query>
+```
+
+### List vault metadata without decryption
+
+```bash
+r4 vault list-vaults
+r4 vault list-items
+r4 vault items --metadata-only
+```
+
+### List grouped item/field data from the decrypted env map
+
+```bash
+r4 vault items
+```
+
+### Run a command with secrets injected
+
+```bash
+r4 run -- <command>
+r4 run --prefix R4 -- <command>
+```
+
+Examples:
+
+```bash
+r4 run -- node deploy.js
+r4 run --prefix R4 -- docker compose up
+```
+
+### Machine-readable output
+
+Most CLI commands support `--json`:
+
+```bash
+r4 auth status --json
+r4 doctor --json
+r4 vault list --json
+r4 vault get DATABASE_PASSWORD --json
+r4 vault items --json
+r4 project list --json
+```
+
+## Projects
+
+Use the CLI when you need project metadata that is already available through R4.
+
+```bash
+r4 project list
+r4 project get <project-id>
+r4 project create
+```
+
+## Domains
+
+Use the R4 machine API for domain search, purchase, and DNS changes.
+
+### Search domains
+
+```bash
+curl -X GET "https://r4.dev/api/v1/machine/domain-manager/search-domains?domain=<domain>" \
+  -H "X-API-Key: $R4_API_KEY"
+```
+
+Examples:
+
+```bash
+curl -X GET "https://r4.dev/api/v1/machine/domain-manager/search-domains?domain=example" \
+  -H "X-API-Key: $R4_API_KEY"
+curl -X GET "https://r4.dev/api/v1/machine/domain-manager/search-domains?domain=example.com" \
+  -H "X-API-Key: $R4_API_KEY"
+```
+
+### Purchase a domain
+
+```bash
+curl -X POST "https://r4.dev/api/v1/machine/domain-manager/purchase-domain" \
+  -H "X-API-Key: $R4_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"domain":"example.com"}'
+```
+
+### List domains
+
+```bash
+curl -X GET "https://r4.dev/api/v1/machine/domain/list" \
+  -H "X-API-Key: $R4_API_KEY"
+```
+
+### Read DNS records
+
+```bash
+curl -X GET "https://r4.dev/api/v1/machine/domain-manager/dns-records?domain=example.com" \
+  -H "X-API-Key: $R4_API_KEY"
+```
+
+### Add a DNS record
+
+```bash
+curl -X POST "https://r4.dev/api/v1/machine/domain-manager/dns-records" \
+  -H "X-API-Key: $R4_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "domain": "example.com",
+    "record": {
+      "type": "A",
+      "name": "@",
+      "value": "192.168.1.1",
+      "ttl": 300
+    }
+  }'
+```
+
+Supported record types: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`.
+
+## Capability Gaps
+
+If you are blocked because R4 is missing a needed feature, submit feedback with the AGENT machine API instead of inventing a workaround:
+
+```bash
+curl -X POST "https://r4.dev/api/v1/machine/feedback" \
+  -H "X-API-Key: $R4_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "surface": "OTHER",
+    "summary": "Missing capability needed to complete the task",
+    "details": "Describe what you tried, what failed, and the capability you need.",
+    "desiredOutcome": "Explain what R4 should support."
+  }'
+```
+
+Use `CLI`, `SDK`, `MCP`, `MACHINE_API`, or `OTHER` for `surface` when you know which product surface is missing.
+
+## Security Rules
+
+- Never hardcode secrets in source code, config files, or commits.
+- Never log secrets, tokens, passwords, or private keys in plaintext.
+- Prefer `r4 run` when a command needs multiple secrets.
+- Prefer `r4 vault list-items` or `r4 vault items --metadata-only` when you only need names or structure.
+- Ask for broader access only when R4 does not already expose what you need.
+
+## Docs
+
+Full public docs:
+
+- https://r4.dev/docs/cli
+- https://r4.dev/docs/sdk
+- https://r4.dev/docs/machine-api

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the absolute path to the R4 vault skill markdown file.
+ * Useful for tools that need to read the skill file directly from disk.
+ */
+export declare function getSkillPath(): string;
+/**
+ * The R4 skill content as a string.
+ * Contains instructions for agents on how to use the current R4
+ * CLI and machine API surface for zero-trust secret retrieval,
+ * project metadata, domain management, and capability feedback.
+ */
+export declare const skillContent: string;

package/lib/index.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Returns the absolute path to the R4 vault skill markdown file.
+ * Useful for tools that need to read the skill file directly from disk.
+ */
+export function getSkillPath() {
+    return path.join(__dirname, 'SKILL.md');
+}
+/**
+ * The R4 skill content as a string.
+ * Contains instructions for agents on how to use the current R4
+ * CLI and machine API surface for zero-trust secret retrieval,
+ * project metadata, domain management, and capability feedback.
+ */
+export const skillContent = fs.readFileSync(getSkillPath(), 'utf8');

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@r4-sdk/skill",
+  "version": "1.0.0",
+  "description": "Official R4 OpenClaw skill — teaches agents how to use R4 vault, project, and domain flows",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/SKILL.md lib/SKILL.md",
+    "clean": "rm -rf lib",
+    "test": "tsx --test test/**/*.test.ts",
+    "test:pack": "tsx --test test/package.smoke.ts"
+  },
+  "keywords": [
+    "r4",
+    "openclaw",
+    "skill",
+    "agent",
+    "vault",
+    "domain"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@r4-sdk/cli": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@r4-sdk/cli": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "requiredCredentials": [
+      {
+        "name": "R4_API_KEY",
+        "description": "AGENT-scoped R4 API key used to authenticate the local runtime against the machine API."
+      }
+    ],
+    "requiredBinaries": [
+      {
+        "name": "r4",
+        "package": "@r4-sdk/cli",
+        "description": "R4 CLI for vault secret access and domain management"
+      }
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "tsx": "^4.20.6",
+    "typescript": "5.5.3"
+  }
+}