@intent-driven-interface/skill 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -2
- package/SKILL.md +35 -0
- package/cli.mjs +103 -0
- package/package.json +20 -4
package/README.md
CHANGED
|
@@ -1,3 +1,24 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @intent-driven-interface/skill
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Agent instructions for authoring IDI components and integrating `@intent-driven-interface/frontend` and `@intent-driven-interface/backend`.
|
|
4
|
+
|
|
5
|
+
## Add to your project
|
|
6
|
+
|
|
7
|
+
Requires Node.js 22+ and npm. Run these commands from the project directory containing your `package.json`:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --save-dev @intent-driven-interface/skill
|
|
11
|
+
npx @intent-driven-interface/skill add-skill --agent codex
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
For Claude Code, use `--agent claude` instead.
|
|
15
|
+
|
|
16
|
+
The command creates a relative symlink at `.agents/skills/intent-driven-interface` for Codex or `.claude/skills/intent-driven-interface` for Claude Code. The link points to the installed package in `node_modules`, so dependency updates update the skill without rerunning the command. Restart your agent session if it has already loaded the previous instructions.
|
|
17
|
+
|
|
18
|
+
There is no `postinstall` script. Repeating `add-skill` leaves a correct link unchanged and refuses to overwrite any other existing path. The command requires an installed dependency; it never links into the temporary npm execution cache.
|
|
19
|
+
|
|
20
|
+
You can commit the symlink so teammates only need to install dependencies, including dev dependencies. Symlink creation and checkout must be supported by their operating system; Windows may require Developer Mode or elevated permissions. Removing `node_modules` leaves the link unavailable until dependencies are reinstalled.
|
|
21
|
+
|
|
22
|
+
## Skill contents
|
|
23
|
+
|
|
24
|
+
See [SKILL.md](SKILL.md) for the instructions. This directory is also the canonical Git-hosted skill source.
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: intent-driven-interface
|
|
3
|
+
description: Authors IDI components, component maps, and IDIAgent routes using @intent-driven-interface/frontend and @intent-driven-interface/backend. Use when integrating Intent Driven Interface or its callback-based persistence.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Intent Driven Interface
|
|
7
|
+
|
|
8
|
+
IDI lets a model open React components as tools. The user interacts with the UI; closing a component supplies its result for the next model turn. Tools have no server-side `execute`.
|
|
9
|
+
|
|
10
|
+
## Integration
|
|
11
|
+
|
|
12
|
+
- Register host-owned views with `defineIDIComponent` and `defineComponentMap` from `@intent-driven-interface/frontend`.
|
|
13
|
+
- Connect `useIDI({ componentMap, idiBackend: { url, requestHeaders } })` to the host's `/api/idi` route. Render the returned messages using their component render parts.
|
|
14
|
+
- Construct `IDIAgent` from `@intent-driven-interface/backend` in the host. Pass parsed request bodies and a host-authorized user ID to `handleChatRequest`; return its streaming response unchanged.
|
|
15
|
+
- Inject `saveMessages`, `loadMessages`, `loadPinnedComponents`, and `pinComponent`. Store message snapshots by ID, return bounded chronological history pages, and preserve original input separately from optional edited input state.
|
|
16
|
+
- Generation saves are awaited unless the host supplies `scheduleTask(task: Promise<void>): void`. The host owns background-task lifetime and error handling.
|
|
17
|
+
- Keep authentication, authorization, credentials, domain prompts, database schema, and persistence adapters in the host. Use the browser-safe `@intent-driven-interface/backend/api-contracts` subpath for wire contracts.
|
|
18
|
+
|
|
19
|
+
## Component authoring
|
|
20
|
+
|
|
21
|
+
- Describe what the user sees, which actions are available, when changes take effect, and which follow-up screens can open. Model-facing descriptions must match implemented behavior, not explain React plumbing.
|
|
22
|
+
- Put meaningful initial display choices in `inputSchema`. Strict tool inputs require every field: use nullable fields for unset values, not optional fields or defaults. Explain ambiguous enum semantics, relative dates, units, and ID selection in field descriptions.
|
|
23
|
+
- Add `inputExamples` only when they teach combinations the schema cannot explain clearly.
|
|
24
|
+
- Live views receive effective `componentInput`. `setComponentInputState` replaces the full editable input and persists it without an agent turn; original invocation input remains unchanged.
|
|
25
|
+
- Components with `outputSchema` receive editable `componentOutputState`. `setComponentOutputState` saves a draft without an agent turn. `closeComponent()` finalizes it; `closeComponent({ setComponentOutput: output })` sets and finalizes output atomically.
|
|
26
|
+
- Closing normally requests the next model turn, except with `agentFollowUp: false` or when resuming a caller. Sending a message or opening another component closes displaced components.
|
|
27
|
+
- `componentSummary` identifies the component and its effective input from the stored snapshot; do not refetch mutable data. Optional `outputSummary` displays the final outcome concisely.
|
|
28
|
+
- Set `followUpComponent: true` for views only another component may open through `callComponent`. These are hidden from the model's tool list.
|
|
29
|
+
- Restore history and pins with `restoreComponent`, preserving original input plus optional input state. Keep asynchronous layouts visually stable in the vertical conversation.
|
|
30
|
+
|
|
31
|
+
## Boundaries
|
|
32
|
+
|
|
33
|
+
Keep component-map schemas serializable. IDI is database-agnostic and has no component schema versioning or migrations. Hosts must avoid breaking stored payloads or handle incompatible data themselves.
|
|
34
|
+
|
|
35
|
+
For full contracts, read the installed `@intent-driven-interface/frontend` and `@intent-driven-interface/backend` package READMEs. For source and examples, see [the IDI repository](https://github.com/futuristic-digital/intent-driven-interface), especially `packages/frontend`, `packages/backend`, and `apps/demo`.
|
package/cli.mjs
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/** Registers the installed IDI skill without copying it or using npm's cache. */
|
|
3
|
+
import { access, lstat, mkdir, readlink, symlink } from 'node:fs/promises';
|
|
4
|
+
import { dirname, join, relative, resolve } from 'node:path';
|
|
5
|
+
import process from 'node:process';
|
|
6
|
+
import { parseArgs } from 'node:util';
|
|
7
|
+
|
|
8
|
+
const packageName = '@intent-driven-interface/skill';
|
|
9
|
+
const usage = `Usage: npx ${packageName} add-skill --agent <codex|claude>
|
|
10
|
+
|
|
11
|
+
Run from your project's package.json directory after installing:
|
|
12
|
+
npm install --save-dev ${packageName}
|
|
13
|
+
|
|
14
|
+
Creates a project-local symlink to the installed skill:
|
|
15
|
+
codex .agents/skills/intent-driven-interface
|
|
16
|
+
claude .claude/skills/intent-driven-interface`;
|
|
17
|
+
|
|
18
|
+
/** Preserve the node_modules path so upgrades keep the link valid, even with hoisting. */
|
|
19
|
+
async function findInstalledSkill(projectDirectory) {
|
|
20
|
+
let directory = projectDirectory;
|
|
21
|
+
while (true) {
|
|
22
|
+
const packageDirectory = join(directory, 'node_modules', packageName);
|
|
23
|
+
try {
|
|
24
|
+
await access(join(packageDirectory, 'SKILL.md'));
|
|
25
|
+
return packageDirectory;
|
|
26
|
+
} catch (error) {
|
|
27
|
+
if (error.code !== 'ENOENT') throw error;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
const parent = dirname(directory);
|
|
31
|
+
if (parent === directory) {
|
|
32
|
+
throw new Error(
|
|
33
|
+
`No installed ${packageName} found. Run npm install --save-dev ${packageName} first.`
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
directory = parent;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Add a relative directory symlink, accepting repeat runs without replacing user files. */
|
|
41
|
+
async function addSkill(agentDirectory) {
|
|
42
|
+
const projectDirectory = process.cwd();
|
|
43
|
+
await access(join(projectDirectory, 'package.json'));
|
|
44
|
+
const packageDirectory = await findInstalledSkill(projectDirectory);
|
|
45
|
+
const skillsDirectory = join(projectDirectory, agentDirectory, 'skills');
|
|
46
|
+
const destination = join(skillsDirectory, 'intent-driven-interface');
|
|
47
|
+
const target = relative(skillsDirectory, packageDirectory);
|
|
48
|
+
|
|
49
|
+
process.stdout.write(`Adding skill: ${destination} → ${target}\n`);
|
|
50
|
+
await mkdir(skillsDirectory, { recursive: true });
|
|
51
|
+
try {
|
|
52
|
+
await symlink(target, destination, 'dir');
|
|
53
|
+
} catch (error) {
|
|
54
|
+
if (error.code !== 'EEXIST') throw error;
|
|
55
|
+
const existing = await lstat(destination);
|
|
56
|
+
if (
|
|
57
|
+
existing.isSymbolicLink() &&
|
|
58
|
+
resolve(skillsDirectory, await readlink(destination)) === packageDirectory
|
|
59
|
+
) {
|
|
60
|
+
process.stdout.write('Skipped: the skill is already linked correctly.\n');
|
|
61
|
+
return;
|
|
62
|
+
}
|
|
63
|
+
throw new Error(`Refusing to replace existing path: ${destination}`, {
|
|
64
|
+
cause: error,
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
process.stdout.write(
|
|
68
|
+
'Skill linked. Dependency updates will update its content automatically.\n'
|
|
69
|
+
);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** Validate the explicit command and agent before making any filesystem changes. */
|
|
73
|
+
async function main() {
|
|
74
|
+
const { values, positionals } = parseArgs({
|
|
75
|
+
options: {
|
|
76
|
+
agent: { type: 'string' },
|
|
77
|
+
help: { type: 'boolean', short: 'h' },
|
|
78
|
+
},
|
|
79
|
+
allowPositionals: true,
|
|
80
|
+
});
|
|
81
|
+
if (values.help) {
|
|
82
|
+
process.stdout.write(`${usage}\n`);
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
if (positionals.length !== 1 || positionals[0] !== 'add-skill') {
|
|
86
|
+
throw new Error(usage);
|
|
87
|
+
}
|
|
88
|
+
switch (values.agent) {
|
|
89
|
+
case 'codex':
|
|
90
|
+
await addSkill('.agents');
|
|
91
|
+
break;
|
|
92
|
+
case 'claude':
|
|
93
|
+
await addSkill('.claude');
|
|
94
|
+
break;
|
|
95
|
+
default:
|
|
96
|
+
throw new Error(`Choose --agent codex or --agent claude.\n\n${usage}`);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
main().catch((error) => {
|
|
101
|
+
process.stderr.write(`Could not add skill: ${error.message}\n`);
|
|
102
|
+
process.exitCode = 1;
|
|
103
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intent-driven-interface/skill",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Agent skill for Intent Driven Interface component authoring and integration.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"publishConfig": {
|
|
7
|
+
"access": "public"
|
|
8
|
+
},
|
|
9
|
+
"bin": {
|
|
10
|
+
"skill": "./cli.mjs"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"SKILL.md",
|
|
14
|
+
"cli.mjs"
|
|
15
|
+
],
|
|
16
|
+
"scripts": {
|
|
17
|
+
"lint": "eslint ."
|
|
18
|
+
},
|
|
19
|
+
"engines": {
|
|
20
|
+
"node": ">=22"
|
|
21
|
+
}
|
|
22
|
+
}
|