Skip to content
Python

Support user-wide skill installation and simplify install commands

Rohit Pa213efe22e96
diff --git a/docs/harness/guides/desktop.md b/docs/harness/guides/desktop.md
index 8b404b8f..16ff393a 100644
--- a/docs/harness/guides/desktop.md
+++ b/docs/harness/guides/desktop.md
@@ -42,31 +42,32 @@ you build. Run the relevant tests and prepare a local package.
<details><summary>Install the skill for this project</summary>
-After npm publication, install the matching skill in your existing app project.
-The candidate below is not published yet; for local archives or checkout installation,
-see the [skill installation guide](../../../skills/README.md).
+Run one of these commands from your app project to install the latest published
+skill. No OpenWorker repository checkout is required.
<!-- sdk-install-tabs -->
### Codex
```sh frame="none"
-npx @openworkerai/[email protected] --agent codex --project .
+npx @openworkerai/build-with-sdk-skills --agent codex --project .
```
### Claude Code
```sh frame="none"
-npx @openworkerai/[email protected] --agent claude --project .
+npx @openworkerai/build-with-sdk-skills --agent claude --project .
```
<!-- /sdk-install-tabs -->
Open a new coding-agent session in that project. The installer copies the same
skill, SDK snippets and Desktop/Web references into the tool's project skills directory.
-It doesn't change global settings or overwrite an existing skill. See the
-[skill installation guide](../../../skills/README.md) for local candidate installation
-and invocation details.
+For all your projects on this machine, replace `--project .` with `--global`.
+That installs to your user skills directory; neither mode overwrites an existing
+skill. The `--global` option is new in the pending skills `0.1.0-beta.2` release.
+See the [skill installation guide](../../../skills/README.md) for availability,
+local candidate installation and invocation details.
</details>
diff --git a/docs/harness/guides/server.md b/docs/harness/guides/server.md
index 933662c7..b4910ee7 100644
--- a/docs/harness/guides/server.md
+++ b/docs/harness/guides/server.md
@@ -42,31 +42,32 @@ agent and session code, and prepare container deployment files.
<details><summary>Install the skill for this project</summary>
-After npm publication, install the matching skill in your existing app project.
-The candidate below is not published yet; for local archives or checkout installation,
-see the [skill installation guide](../../../skills/README.md).
+Run one of these commands from your app project to install the latest published
+skill. No OpenWorker repository checkout is required.
<!-- sdk-install-tabs -->
### Codex
```sh frame="none"
-npx @openworkerai/[email protected] --agent codex --project .
+npx @openworkerai/build-with-sdk-skills --agent codex --project .
```
### Claude Code
```sh frame="none"
-npx @openworkerai/[email protected] --agent claude --project .
+npx @openworkerai/build-with-sdk-skills --agent claude --project .
```
<!-- /sdk-install-tabs -->
Open a new coding-agent session in that project. The installer copies the same
skill, SDK snippets and Desktop/Web references into the tool's project skills directory.
-It doesn't change global settings or overwrite an existing skill. See the
-[skill installation guide](../../../skills/README.md) for local candidate installation
-and invocation details.
+For all your projects on this machine, replace `--project .` with `--global`.
+That installs to your user skills directory; neither mode overwrites an existing
+skill. The `--global` option is new in the pending skills `0.1.0-beta.2` release.
+See the [skill installation guide](../../../skills/README.md) for availability,
+local candidate installation and invocation details.
</details>
diff --git a/harness/release/README.md b/harness/release/README.md
index 093cfa0d..e47b1e34 100644
--- a/harness/release/README.md
+++ b/harness/release/README.md
@@ -24,7 +24,7 @@ Native compilation and clean-machine testing are required on every claimed targe
The npm client is `@openworkerai/harness-sdk`; matching runtime packages are
`@openworkerai/harness-runtime-<platform>-<arch>`. The same candidate includes
`@openworkerai/build-with-sdk-skills`, which installs the shared Desktop/Web
-skill into a Codex or Claude Code project. The skill package has no runtime or
+skill into a Codex or Claude Code project, or user-wide with `--global`. The skill package has no runtime or
SDK dependency. Its package version can advance independently;
`openworkerSdkVersion` declares the compatible SDK release. To prepare just that archive without compiling Rust:
diff --git a/skills/README.md b/skills/README.md
index 7cd0d273..daa6465b 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -6,24 +6,24 @@ snippets and separate Desktop/Web references. No OpenWorker checkout is required
for the packaged skill, and installing it does not install the SDK or a runtime.
**Release candidate:** `@openworkerai/[email protected]` is prepared
-locally. Registry commands below apply after publication; the version in this
-repository does not mean it has been published.
+locally. The new `--global` option and Railway guidance require this release;
+until it is published, use the local candidate instructions below to try them.
-## Install in your app project
+## Install the skill
-After publication, from an existing app project:
+From an existing app project, install the latest published skill:
```sh
-npx @openworkerai/[email protected] --agent codex --project .
+npx @openworkerai/build-with-sdk-skills --agent codex --project .
```
For Claude Code:
```sh
-npx @openworkerai/[email protected] --agent claude --project .
+npx @openworkerai/build-with-sdk-skills --agent claude --project .
```
-The installer creates `.agents/skills/openworker-apps/` for Codex or
+These project commands create `.agents/skills/openworker-apps/` for Codex or
`.claude/skills/openworker-apps/` for Claude Code. It supports quoted project paths
on Windows and macOS, leaves global settings alone, and refuses to overwrite an
existing skill. Review/back up an existing installation before replacing it.
@@ -31,7 +31,30 @@ existing skill. Review/back up an existing installation before replacing it.
checkout paths or credentials. Use `sdkVersion` from that file for the SDK. Skill and SDK package versions may
differ; this skill candidate targets SDK `0.1.0-beta.1`.
-The skill is discoverable in that project. Restart the coding-agent session if it
+### Across your projects
+
+For user-wide installation, use `--global` instead of `--project`:
+
+```sh
+npx @openworkerai/build-with-sdk-skills --agent claude --global
+```
+
+```sh
+npx @openworkerai/build-with-sdk-skills --agent codex --global
+```
+
+This installs into `~/.claude/skills/openworker-apps/` for Claude Code or
+`~/.agents/skills/openworker-apps/` for Codex, making the skill available across
+projects for your user on this machine. It does not install into Claude web or
+Cowork, change account settings, or require `npm install -g` or administrator
+access. Choose either `--global` or `--project`, not both. Both modes preserve an
+existing installation.
+
+Unversioned commands select npm's `latest` release. To pin an installation for
+reproducibility, append `@<version>` to the package name. The installer records
+the compatible SDK version separately; the skill and SDK versions may differ.
+
+The skill is discoverable in the selected scope. Restart the coding-agent session if it
does not appear. Invoke `$openworker-apps` in Codex or `/openworker-apps` in Claude
Code, or ask:
@@ -46,8 +69,17 @@ and Docker assets. The default is one Node service serving the frontend and API,
with the Rust harness running as a managed child process. The recipe has been tested locally and on Railway with the
published SDK, including streamed Claude responses and conversation recovery
after redeployment. Vercel recipes and a cluster-operations skill will
-follow separately. This installer
-targets local Codex and Claude Code projects, not Claude web/Cowork uploads.
+follow separately. This installer targets local Codex and Claude Code sessions.
+
+## Claude workspace uploads
+
+Claude's **Customize → Skills → Upload** is a separate installation route.
+For that flow, zip the complete installed `openworker-apps` directory, including
+its references, Docker assets and `references/installation.json`; uploading only
+`SKILL.md` loses the supporting files. The npm `.tgz` package is not this upload
+format. Uploading a skill provides instructions, not an installed SDK, runtime,
+or permission to deploy an app. The workspace upload flow has not been qualified
+by this package's local installer tests.
## Try the local candidate
diff --git a/skills/install.mjs b/skills/install.mjs
index 2cd651e9..fc22a390 100644
--- a/skills/install.mjs
+++ b/skills/install.mjs
@@ -1,17 +1,31 @@
#!/usr/bin/env node
-// Project-local installation only; never overwrite an existing skill.
+// Project or user-wide installation; never overwrite an existing skill.
import { mkdir, lstat, realpath, readFile, writeFile } from 'node:fs/promises';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { parseArgs } from 'node:util';
const source = dirname(fileURLToPath(import.meta.url));
+const usage = 'build-with-sdk-skills --agent codex|claude (--project /path/to/your-app | --global)';
const files = ['SKILL.md','references/desktop.md','references/web.md','references/sdk.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore','agents/openai.yaml'];
-export async function install({agent, project}) {
- if (!['codex','claude'].includes(agent) || !project) throw Error('Use --agent codex|claude --project /path/to/your-app');
+function validate({agent, project, global: userWide = false}) {
+ if (!['codex','claude'].includes(agent) || typeof userWide !== 'boolean' ||
+ (project !== undefined && (typeof project !== 'string' || !project.trim())) ||
+ userWide === (project !== undefined)) throw Error(`Use ${usage}; choose exactly one installation scope.`);
+}
+export function parseInstallArgs(args) {
+ const {values} = parseArgs({args, options:{agent:{type:'string'}, project:{type:'string'}, global:{type:'boolean'}}});
+ validate(values);
+ return values;
+}
+export async function install(options, {userHome = homedir()} = {}) {
+ validate(options);
+ const {agent, project, global: userWide = false} = options;
const pkg = JSON.parse(await readFile(join(source,'package.json'),'utf8'));
// Validate package completeness before creating an installation directory.
const content = await Promise.all(files.map(name => readFile(join(source,'openworker-apps',name))));
- const root = await realpath(project);
- if (!(await lstat(root)).isDirectory()) throw Error('Project must be an existing directory.');
+ const root = await realpath(userWide ? userHome : project);
+ if (!(await lstat(root)).isDirectory()) throw Error('Installation root must be an existing directory.');
let parent = root;
for (const component of [agent === 'codex' ? '.agents' : '.claude', 'skills']) {
parent = join(parent, component);
@@ -32,11 +46,11 @@ export async function install({agent, project}) {
}
if (process.argv[1] && await realpath(process.argv[1]).catch(() => resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
const args=process.argv.slice(2);
- if(args.length===1 && args[0]==='--help') console.log('build-with-sdk-skills --agent codex|claude --project /path/to/your-app');
+ if(args.length===1 && args[0]==='--help') console.log(`${usage}\n--global installs for your user across projects on this machine (Codex: ~/.agents/skills; Claude Code: ~/.claude/skills).`);
else {
try {
- if(args.length!==4 || args[0]!=='--agent' || args[2]!=='--project') throw Error('Use --agent codex|claude --project /path/to/your-app');
- console.log(`Installed: ${await install({agent:args[1],project:args[3]})}\nOpen a new coding-agent session in that project to use openworker-apps.`);
+ const options = parseInstallArgs(args);
+ console.log(`Installed: ${await install(options)}\nOpen a new coding-agent session${options.global ? '' : ' in that project'} to use openworker-apps.`);
} catch(error) { console.error(error.code==='EEXIST' ? 'An installation already exists. Review or back it up before replacing it.' : error.message);process.exitCode=1; }
}
}
diff --git a/skills/install.test.mjs b/skills/install.test.mjs
index 36c58509..7ce6f040 100644
--- a/skills/install.test.mjs
+++ b/skills/install.test.mjs
@@ -1,9 +1,9 @@
import test from 'node:test';
import assert from 'node:assert/strict';
-import {mkdtemp,readFile,writeFile,rm,mkdir,symlink,readdir} from 'node:fs/promises';
+import {mkdtemp,readFile,writeFile,rm,mkdir,symlink,readdir,realpath} from 'node:fs/promises';
import {tmpdir} from 'node:os';
import {join} from 'node:path';
-import {install} from './install.mjs';
+import {install,parseInstallArgs} from './install.mjs';
for (const agent of ['codex','claude']) test(`install complete ${agent} skill; preserve existing content`, async()=>{
const root=await mkdtemp(join(tmpdir(),'ow skill '));
try {
@@ -22,6 +22,42 @@ for (const agent of ['codex','claude']) test(`install complete ${agent} skill; p
assert.equal(await readFile(join(dest,'SKILL.md'),'utf8'),'local customization');
} finally {await rm(root,{recursive:true,force:true});}
});
+for (const agent of ['codex','claude']) test(`install ${agent} user-wide independently of project installs`,async()=>{
+ const root=await mkdtemp(join(tmpdir(),'ow-global-skill-'));
+ try {
+ const userHome=join(root,'personal home'),project=join(root,'project');
+ await mkdir(userHome);await mkdir(project);
+ const local=await install({agent,project});
+ const destination=await install({agent,global:true},{userHome});
+ assert.equal(destination,join(await realpath(userHome),agent==='codex'?'.agents':'.claude','skills/openworker-apps'));
+ for(const name of ['SKILL.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore'])
+ assert.equal(await readFile(join(destination,name),'utf8'),await readFile(join(local,name),'utf8'));
+ await writeFile(join(destination,'SKILL.md'),'personal customization');
+ await assert.rejects(install({agent,global:true},{userHome}),{code:'EEXIST'});
+ assert.equal(await readFile(join(destination,'SKILL.md'),'utf8'),'personal customization');
+ assert.notEqual(await readFile(join(local,'SKILL.md'),'utf8'),'personal customization');
+ } finally {await rm(root,{recursive:true,force:true});}
+});
+test('require exactly one scope and reject unknown CLI arguments',async()=>{
+ const root=await mkdtemp(join(tmpdir(),'ow-skill-invalid-scope-'));
+ try {
+ assert.deepEqual({...parseInstallArgs(['--global','--agent','claude'])},{global:true,agent:'claude'});
+ assert.deepEqual({...parseInstallArgs(['--project',root,'--agent','codex'])},{project:root,agent:'codex'});
+ for(const args of [[],['--agent','claude'],['--global'],['--agent','claude','--global','--project',root],['--agent','claude','--global','extra'],['--agent','claude','--globall'],['--agent','claude','--project','']])
+ assert.throws(()=>parseInstallArgs(args));
+ await assert.rejects(install({agent:'claude',project:root,global:true},{userHome:root}),/exactly one/);
+ await assert.rejects(install({agent:'claude',global:'yes'},{userHome:root}),/exactly one/);
+ assert.deepEqual(await readdir(root),[]);
+ } finally {await rm(root,{recursive:true,force:true});}
+});
+for(const folder of ['.agents','.claude'])test(`user-wide install refuses a linked ${folder} directory`,async()=>{
+ const root=await mkdtemp(join(tmpdir(),'ow-global-linked-')),outside=await mkdtemp(join(tmpdir(),'ow-global-outside-'));
+ try {
+ await symlink(outside,join(root,folder),'junction');
+ await assert.rejects(install({agent:folder==='.agents'?'codex':'claude',global:true},{userHome:root}),/real directory/);
+ assert.deepEqual(await readdir(outside),[]);
+ } finally {await rm(root,{recursive:true,force:true});await rm(outside,{recursive:true,force:true});}
+});
test('reject invalid agent and linked destination directories',async()=>{
const root=await mkdtemp(join(tmpdir(),'ow-skill-scope-'));const outside=await mkdtemp(join(tmpdir(),'ow-skill-other-'));
try {
diff --git a/skills/package.test.mjs b/skills/package.test.mjs
index 2f2d5ff5..a0acb9c0 100644
--- a/skills/package.test.mjs
+++ b/skills/package.test.mjs
@@ -4,6 +4,7 @@ import { mkdtemp, readFile, mkdir, readdir, rm, writeFile, realpath } from 'node
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
import { prepare } from './prepare.mjs';
test('packed installer works outside the checkout without SDK or native dependencies', {timeout: 60000}, async () => {
@@ -32,6 +33,13 @@ test('packed installer works outside the checkout without SDK or native dependen
? execFileSync(process.execPath,[join(installed,'install.mjs'),...args],{cwd:consumer,encoding:'utf8'})
: execFileSync(bin,args,{cwd:consumer,encoding:'utf8'});
assert.match(run(['--help']), /--agent codex\|claude/);
+ assert.match(run(['--help']), /--global/);
+ // Mock only the child's OS home resolver; never write to the developer's
+ // actual home or override HOME/USERPROFILE while exercising the real CLI.
+ const userHome=join(root,'personal home');await mkdir(userHome);
+ const preload=join(root,'home-fixture.mjs');
+ await writeFile(preload,`import os from 'node:os';import{syncBuiltinESMExports}from'node:module';os.homedir=()=>${JSON.stringify(userHome)};syncBuiltinESMExports();`);
+ const runGlobal=(args)=>execFileSync(process.execPath,['--import',pathToFileURL(preload).href,join(installed,'install.mjs'),...args],{cwd:consumer,encoding:'utf8',stdio:'pipe'});
for (const agent of ['codex','claude']) {
const project = join(root, `new ${agent} app`);
await mkdir(project);
@@ -41,6 +49,15 @@ test('packed installer works outside the checkout without SDK or native dependen
assert.equal(metadata.sdkVersion,pkg.openworkerSdkVersion);
assert.equal(metadata.sdkPackage,'@openworkerai/harness-sdk');
assert.equal(metadata.version,pkg.version);
+ assert.match(runGlobal(['--agent',agent,'--global']),/Installed:/);
+ const globalDest=join(userHome,agent==='codex'?'.agents':'.claude','skills/openworker-apps');
+ assert.deepEqual(JSON.parse(await readFile(join(globalDest,'references/installation.json'),'utf8')),metadata);
+ for(const file of ['SKILL.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore'])
+ assert.equal(await readFile(join(globalDest,file),'utf8'),await readFile(join(dest,file),'utf8'));
+ await assert.rejects(readFile(join(consumer,agent==='codex'?'.agents':'.claude','skills/openworker-apps/SKILL.md')),{code:'ENOENT'});
+ await writeFile(join(globalDest,'SKILL.md'),'personal customization');
+ assert.throws(()=>runGlobal(['--global','--agent',agent]));
+ assert.equal(await readFile(join(globalDest,'SKILL.md'),'utf8'),'personal customization');
for (const folder of ['', 'references', 'agents']) {
for (const file of await readdir(join(dest,folder))) {
if (!/\.(md|json|yaml)$/.test(file)) continue;