@cursor/july 0.1.73 → 0.1.74

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.
Files changed (99) hide show
  1. package/AGENTS.md +13 -8
  2. package/dist/bin/agent-serve.js +7 -5
  3. package/dist/docs/404.html +2 -2
  4. package/dist/docs/ab.html +3 -3
  5. package/dist/docs/assets/{app.CdbcFD8T.js → app.BETd-WqU.js} +1 -1
  6. package/dist/docs/assets/chunks/@localSearchIndexroot.DM5INS71.js +1 -0
  7. package/dist/docs/assets/chunks/{VPLocalSearchBox.D_NKImM7.js → VPLocalSearchBox.wEaGEmV9.js} +1 -1
  8. package/dist/docs/assets/chunks/{theme.CMvz7cu9.js → theme.DNDicFOP.js} +2 -2
  9. package/dist/docs/assets/{reference_cli.md.Cl14Jfo3.js → reference_cli.md.TAaYU8br.js} +3 -3
  10. package/dist/docs/assets/{reference_cli.md.Cl14Jfo3.lean.js → reference_cli.md.TAaYU8br.lean.js} +1 -1
  11. package/dist/docs/assets/scaffolding-agents.md.CiGsJ1aw.js +1 -0
  12. package/dist/docs/assets/{scaffolding-agents.md.CrWSA0Ko.lean.js → scaffolding-agents.md.CiGsJ1aw.lean.js} +1 -1
  13. package/dist/docs/building-with-agents.html +3 -3
  14. package/dist/docs/concepts.html +3 -3
  15. package/dist/docs/deployment.html +3 -3
  16. package/dist/docs/evals.html +3 -3
  17. package/dist/docs/example-agents/approval-buddy.html +3 -3
  18. package/dist/docs/example-agents/benny.html +3 -3
  19. package/dist/docs/example-agents/bugbot.html +3 -3
  20. package/dist/docs/example-agents/codebase-wiki.html +3 -3
  21. package/dist/docs/example-agents/codeowners-review.html +3 -3
  22. package/dist/docs/example-agents/concierge.html +3 -3
  23. package/dist/docs/example-agents/fsd.html +3 -3
  24. package/dist/docs/example-agents/index.html +3 -3
  25. package/dist/docs/example-agents/knowledge-base.html +3 -3
  26. package/dist/docs/example-agents/oncall.html +3 -3
  27. package/dist/docs/example-agents/security-reviewer.html +3 -3
  28. package/dist/docs/example-agents/slack-agent.html +3 -3
  29. package/dist/docs/example-agents/weather-agent.html +3 -3
  30. package/dist/docs/guides/agent-to-agent.html +3 -3
  31. package/dist/docs/guides/cloud-runtime.html +3 -3
  32. package/dist/docs/guides/convert-automation.html +3 -3
  33. package/dist/docs/guides/github.html +3 -3
  34. package/dist/docs/guides/human-in-the-loop.html +3 -3
  35. package/dist/docs/guides/mcp-oauth.html +3 -3
  36. package/dist/docs/guides/opentelemetry.html +3 -3
  37. package/dist/docs/guides/slack.html +3 -3
  38. package/dist/docs/guides/webhooks.html +3 -3
  39. package/dist/docs/hashmap.json +1 -1
  40. package/dist/docs/hillclimbing.html +3 -3
  41. package/dist/docs/index.html +3 -3
  42. package/dist/docs/quickstart.html +3 -3
  43. package/dist/docs/reference/agent-config.html +3 -3
  44. package/dist/docs/reference/artifacts.html +3 -3
  45. package/dist/docs/reference/channels.html +3 -3
  46. package/dist/docs/reference/cli.html +6 -6
  47. package/dist/docs/reference/connections.html +3 -3
  48. package/dist/docs/reference/hooks.html +3 -3
  49. package/dist/docs/reference/http-api.html +3 -3
  50. package/dist/docs/reference/instructions.html +3 -3
  51. package/dist/docs/reference/playground.html +3 -3
  52. package/dist/docs/reference/project-layout.html +3 -3
  53. package/dist/docs/reference/prompt.html +3 -3
  54. package/dist/docs/reference/schedules.html +3 -3
  55. package/dist/docs/reference/sessions.html +3 -3
  56. package/dist/docs/reference/skills.html +3 -3
  57. package/dist/docs/reference/subagents.html +3 -3
  58. package/dist/docs/reference/tools.html +3 -3
  59. package/dist/docs/scaffolding-agents.html +5 -5
  60. package/dist/docs/storage.html +3 -3
  61. package/dist/docs/templates/agentic-owners.html +3 -3
  62. package/dist/docs/templates/demo.html +3 -3
  63. package/dist/docs/templates/pr-autofixer.html +3 -3
  64. package/dist/docs/templates/security-reviewer.html +3 -3
  65. package/dist/docs/templates/triage.html +3 -3
  66. package/dist/docs/troubleshooting.html +3 -3
  67. package/dist/internal/cli-skills.d.ts +4 -2
  68. package/dist/internal/cli-skills.d.ts.map +1 -1
  69. package/dist/internal/cli-skills.js +8 -3
  70. package/dist/internal/install-cursor-skills.d.ts +71 -16
  71. package/dist/internal/install-cursor-skills.d.ts.map +1 -1
  72. package/dist/internal/install-cursor-skills.js +160 -48
  73. package/dist/internal/sdk-runner.d.ts.map +1 -1
  74. package/dist/internal/sdk-runner.js +6 -2
  75. package/dist/playground/assets/index-D_8I9TM0.js +85 -0
  76. package/dist/playground/assets/index-M3nSMc6_.css +1 -0
  77. package/dist/playground/index.html +2 -2
  78. package/docs/reference/cli.md +16 -8
  79. package/docs/scaffolding-agents.md +14 -6
  80. package/package.json +3 -1
  81. package/scripts/install-cursor-skills.mjs +36 -0
  82. package/skills/ab/SKILL.md +1 -1
  83. package/skills/create-agent/SKILL.md +1 -1
  84. package/skills/debug/SKILL.md +1 -1
  85. package/skills/evals/SKILL.md +1 -1
  86. package/skills/framework-map/SKILL.md +1 -1
  87. package/skills/github/SKILL.md +1 -1
  88. package/skills/hillclimb/SKILL.md +1 -1
  89. package/skills/mcp-auth/SKILL.md +1 -1
  90. package/skills/otel/SKILL.md +1 -1
  91. package/skills/setup-slack/SKILL.md +1 -1
  92. package/src/bin/agent-serve.ts +7 -5
  93. package/src/internal/cli-skills.ts +10 -2
  94. package/src/internal/install-cursor-skills.ts +204 -49
  95. package/src/internal/sdk-runner.ts +6 -3
  96. package/dist/docs/assets/chunks/@localSearchIndexroot.DQad--_z.js +0 -1
  97. package/dist/docs/assets/scaffolding-agents.md.CrWSA0Ko.js +0 -1
  98. package/dist/playground/assets/index-77uhu5Kr.css +0 -1
  99. package/dist/playground/assets/index-D4buox4m.js +0 -85
package/dist/playground/index.html CHANGED
@@ -8,8 +8,8 @@
8
8
  />
9
9
  <meta name="viewport" content="width=device-width, initial-scale=1" />
10
10
  <title>agent-serve playground</title>
11
- <script type="module" crossorigin src="./assets/index-D4buox4m.js"></script>
12
- <link rel="stylesheet" crossorigin href="./assets/index-77uhu5Kr.css">
11
+ <script type="module" crossorigin src="./assets/index-D_8I9TM0.js"></script>
12
+ <link rel="stylesheet" crossorigin href="./assets/index-M3nSMc6_.css">
13
13
  </head>
14
14
  <body>
15
15
  <div id="root"></div>
package/docs/reference/cli.md CHANGED
@@ -35,7 +35,7 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
35
35
  | [`trajectory`](#trajectory) | Summarize a saved `events.ndjson` file |
36
36
  | [`init`](#init) | Scaffold a project, or print the setup guide |
37
37
  | [`convert-automation`](#convert-automation) | Export a Cursor Automation into an agent project |
38
- | [`install-skills`](#install-skills) | Install the coding-agent skills without running `init` |
38
+ | [`install-skills`](#install-skills) | Refresh coding-agent skills (`npm install` already copies them) |
39
39
  | [`info`](#info) | Print the discovered agent surface |
40
40
  | [`validate`](#validate) | Check a project and fail on errors |
41
41
  | [`login` / `logout` / `whoami`](#login-logout-whoami) | Manage the host's Cursor credential |
@@ -441,10 +441,11 @@ before writing files. `pr-autofixer` asks for GitHub repos. Repeat
441
441
  `--var id=value` to answer without a prompt.
442
442
  `--json` and non-TTY hosts skip the interview unless `--var` is set.
443
443
 
444
- On a TTY, `init` also asks whether to install or update the coding-agent
445
- skills in `~/.cursor/skills/agentkit/`. If accepted, it overwrites them
446
- with the version bundled in the installed package. The prompt is skipped
447
- for `--json` and non-interactive hosts.
444
+ On a TTY, `init` also asks whether to refresh the coding-agent skills in
445
+ `~/.cursor/skills/agentsdk/`. Installing `@cursor/july` already copies
446
+ them via postinstall (with `alwaysApply: true` so Cursor injects the
447
+ bodies), so this prompt is a chance to overwrite with the package
448
+ version. The prompt is skipped for `--json` and non-interactive hosts.
448
449
 
449
450
  If the host isn't signed in, `init` runs `agent-sdk login` and waits for
450
451
  the browser flow. It then prints the `cd`, `agent-sdk login`, and
@@ -492,8 +493,12 @@ covers generated files and behavior the converter cannot reproduce.
492
493
 
493
494
  ## install-skills
494
495
 
495
- `install-skills` installs the package's coding-agent skills into
496
- `~/.cursor/skills/agentkit/`.
496
+ `install-skills` copies the package's coding-agent skills into
497
+ `~/.cursor/skills/agentsdk/` with `alwaysApply: true` so Cursor loads
498
+ them as global rules. Installing `@cursor/july` already does this in
499
+ postinstall (`npm install`, `npx`, a version bump). Use this command
500
+ to refresh without reinstalling the package, or from a monorepo
501
+ source checkout (postinstall skips that tree).
497
502
 
498
503
  ```bash
499
504
  agent-sdk install-skills [--print] [--json]
@@ -501,11 +506,14 @@ agent-sdk install-skills [--print] [--json]
501
506
 
502
507
  Running the command is the confirmation: it never prompts, and it
503
508
  overwrites the installed skills with the version bundled in the
504
- package. `init` offers the same install once, interactively. `--print`
509
+ package. `init` offers the same refresh once, interactively. `--print`
505
510
  previews the skills, the removals, and the install path without writing
506
511
  anything. `--json` prints
507
512
  `{ ok, dryRun, directory, firstInstall, skills, removed }`.
508
513
 
514
+ Set `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the postinstall copy.
515
+ `CURSOR_JULY_SKILLS_HOME` overrides the `~/.cursor/skills` directory.
516
+
509
517
  ## info
510
518
 
511
519
  `info` prints the discovered agent surface.
package/docs/scaffolding-agents.md CHANGED
@@ -16,13 +16,21 @@ into a small working project. Have Cursor read that file and follow it.
16
16
 
17
17
  Where to find the file depends on how you got the package:
18
18
 
19
- - Reading these docs on a hosted site? Run `agent-sdk install-skills`
20
- to copy every package skill into `~/.cursor/skills/agentkit/`, where
21
- Cursor discovers them by name.
22
- - Installed `@cursor/july` as a dependency? The skill ships inside the
23
- package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
19
+ - Installing `@cursor/july` (`npm install`, `npx @cursor/july`, a
20
+ version bump) copies every package skill into
21
+ `~/.cursor/skills/agentsdk/` with `alwaysApply: true`, so Cursor
22
+ injects the skill body into context instead of waiting for the
23
+ model to pick it from the catalog. The `/` menu lists them as
24
+ `/agentsdk-create-agent`, `/agentsdk-hillclimb`, and the rest. Re-installing overwrites those
25
+ copies with the package version. Set
26
+ `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the copy.
27
+ - Installed `@cursor/july` as a dependency? The skill also ships inside
28
+ the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
24
29
  - Working in the monorepo? It's at
25
- `packages/agent-serve/skills/create-agent/SKILL.md`.
30
+ `packages/agent-serve/skills/create-agent/SKILL.md`. Run
31
+ `agent-sdk install-skills` if you want the same copies in
32
+ `~/.cursor/skills/agentsdk/` (the package postinstall skips the
33
+ source checkout).
26
34
 
27
35
  Cursor will:
28
36
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cursor/july",
3
- "version": "0.1.73",
3
+ "version": "0.1.74",
4
4
  "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "repository": {
@@ -34,6 +34,7 @@
34
34
  "templates/**/*",
35
35
  "docs/**/*.md",
36
36
  "!docs/.cursor/**",
37
+ "scripts/install-cursor-skills.mjs",
37
38
  "package.json",
38
39
  "LICENSE.md",
39
40
  "README.md",
@@ -203,6 +204,7 @@
203
204
  },
204
205
  "scripts": {
205
206
  "build": "tsgo -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && pnpm run build:playground && pnpm run docs:build",
207
+ "postinstall": "node -e \"try{const p='./scripts/install-cursor-skills.mjs';if(require('fs').existsSync(p))require('child_process').execFileSync(process.execPath,[p],{stdio:'inherit'})}catch{}\"",
206
208
  "build:playground": "vite build --config playground/vite.config.ts",
207
209
  "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
208
210
  "dev:playground": "vite --config playground/vite.config.ts",
package/scripts/install-cursor-skills.mjs ADDED
@@ -0,0 +1,36 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * postinstall: copy Agent SDK coding-agent skills into ~/.cursor/skills/agentsdk
4
+ * so Cursor discovers them after `npm install` / `npx @cursor/july`.
5
+ *
6
+ * Never fails the package install. No-op in the monorepo source checkout
7
+ * (package root is not under node_modules) and when dist is missing.
8
+ */
9
+
10
+ import { existsSync } from "node:fs";
11
+ import { dirname, join } from "node:path";
12
+ import { fileURLToPath, pathToFileURL } from "node:url";
13
+
14
+ const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
15
+ const distEntry = join(
16
+ packageRoot,
17
+ "dist",
18
+ "internal",
19
+ "install-cursor-skills.js"
20
+ );
21
+
22
+ try {
23
+ if (!existsSync(distEntry)) {
24
+ process.exit(0);
25
+ }
26
+ // Windows: Node's ESM loader rejects bare drive-letter paths
27
+ // (`ERR_UNSUPPORTED_ESM_URL_SCHEME`). file:// is valid on every platform.
28
+ const { syncCursorSkillsOnPackageInstall } = await import(
29
+ pathToFileURL(distEntry).href
30
+ );
31
+ await syncCursorSkillsOnPackageInstall({ packageRoot });
32
+ } catch {
33
+ // Swallow: a skill copy must not fail `npm install`.
34
+ }
35
+
36
+ process.exit(0);
package/skills/ab/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-ab
2
+ name: agentsdk-ab
3
3
  description: >-
4
4
  Author defineAB live A/B metrics plug-ins under agent/ab. Splits traffic into
5
5
  sticky variants and calls onSample with performance metrics as the agent runs
package/skills/create-agent/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-create-agent
2
+ name: agentsdk-create-agent
3
3
  description: >-
4
4
  Scaffold a new Agent SDK agent through a guided AskQuestion interview —
5
5
  purpose, name, runtime, model, channels, MCP connections, capabilities —
package/skills/debug/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-debug
2
+ name: agentsdk-debug
3
3
  description: >-
4
4
  Diagnose a misbehaving Agent SDK agent, server, or playground — blank
5
5
  playground, sessions missing, HMR not reloading, failing reads/retry
package/skills/evals/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-evals
2
+ name: agentsdk-evals
3
3
  description: >-
4
4
  Author and run Agent SDK defineEval cases (single- or multi-datapoint).
5
5
  Use when writing, fixing, seeding, or hillclimbing evals; AskQuestion
package/skills/framework-map/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-framework-map
2
+ name: agentsdk-framework-map
3
3
  description: >-
4
4
  Orientation for @cursor/july — folder structure, local vs cloud
5
5
  runtimes, sessions, state layout, and invariants (Node not Bun, root
package/skills/github/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-github
2
+ name: agentsdk-github
3
3
  description: >-
4
4
  Build and test GitHub-webhook-driven Agent SDK agents: githubChannel
5
5
  hooks (auth turn vs host task), signature modes, and testing tiers
package/skills/hillclimb/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-hillclimb
2
+ name: agentsdk-hillclimb
3
3
  description: >-
4
4
  Iterate on a specific Agent SDK agent by running the local server,
5
5
  sending real requests, measuring correctness/efficiency, and proposing
package/skills/mcp-auth/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-mcp-auth
2
+ name: agentsdk-mcp-auth
3
3
  description: >-
4
4
  Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
5
5
  agent-sdk mcp oauth, local mcp-auth.json, --store deployment secrets,
package/skills/otel/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-otel
2
+ name: agentsdk-otel
3
3
  description: >-
4
4
  Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
5
5
  traces/metrics/logs, ctx.host.otel). Use when adding observability,
package/skills/setup-slack/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-setup-slack
2
+ name: agentsdk-setup-slack
3
3
  description: >-
4
4
  Wire Slack to an Agent SDK agent. Gate Cursor-hosted vs a dedicated
5
5
  Socket Mode app, then finish that path: cursorAccount sign-in + smoke,
package/src/bin/agent-serve.ts CHANGED
@@ -216,11 +216,13 @@ Commands:
216
216
  -> MCP). Review the project, then run \`validate\` / \`dev\`.
217
217
  Warnings never fail the command.
218
218
  install-skills
219
- Install (or refresh) the Agent SDK skills for coding agents in
220
- ~/.cursor/skills/agentkit and print where they landed. \`init\`
221
- offers this once, interactively, and skips it when the prompt
222
- goes unanswered; this command never asks. --print previews
223
- without writing.
219
+ Refresh the Agent SDK skills for coding agents in
220
+ ~/.cursor/skills/agentsdk and print where they landed.
221
+ Installed copies set alwaysApply so Cursor injects them
222
+ into context. \`npm install\` / \`npx\` already copies them
223
+ (postinstall); this command overwrites with the package
224
+ version without asking. \`init\` also offers a TTY refresh.
225
+ --print previews without writing.
224
226
  mcp Serve this agent's MCP endpoint over stdio for MCP clients
225
227
  that spawn local servers (e.g. Cursor). Proxies
226
228
  newline-delimited JSON-RPC to <target>/v1/mcp. --prod resolves
package/src/internal/cli-skills.ts CHANGED
@@ -1,15 +1,18 @@
1
1
  /**
2
2
  * `install-skills` — install the package's coding-agent skills into
3
- * `~/.cursor/skills/agentkit/` without running `init`.
3
+ * `~/.cursor/skills/agentsdk/` without running `init`.
4
4
  *
5
5
  * Never prompts: running the command is the confirmation. The interactive
6
- * offer lives in `init`.
6
+ * offer lives in `init`. Consumer `npm install` / `npx` copies the same
7
+ * skills in postinstall (with `alwaysApply: true` so Cursor injects them);
8
+ * this command refreshes them without reinstalling.
7
9
  */
8
10
 
9
11
  import { CLI_COMMAND_NAME } from "./distribution.js";
10
12
  import {
11
13
  formatSkillInstall,
12
14
  installCursorSkills,
15
+ LEGACY_CURSOR_SKILLS_NAMESPACE,
13
16
  planSkillInstall,
14
17
  type SkillInstallPlan,
15
18
  } from "./install-cursor-skills.js";
@@ -90,6 +93,11 @@ function previewBlock(plan: SkillInstallPlan): string {
90
93
  if (plan.orphans.length > 0) {
91
94
  lines.push(` removes: ${plan.orphans.join(", ")}`);
92
95
  }
96
+ if (plan.hasLegacyNamespace) {
97
+ lines.push(
98
+ ` removes: ${LEGACY_CURSOR_SKILLS_NAMESPACE}/ (legacy namespace)`
99
+ );
100
+ }
93
101
  lines.push(` location: ${plan.directory}`);
94
102
  return `${lines.join("\n")}\n`;
95
103
  }