Skip to content

Commit c9e3887

Browse files
Bulat Skill7claude
andcommitted
feat: progressive skill loading with per-skill events
Remove system prompt injection that dumped all skill content into every LLM turn. Skills are now loaded progressively: descriptions in tool schema, full content only when the model invokes the skill tool. Replace batch `skills_loaded` event with granular per-skill events: - `skill_discovered` — skill registered in tool schema - `skill_loaded` — full SKILL.md content enters context - `skill_resource_loaded` — model reads a file from skill directory Add EVENTS.md documenting all NDJSON events for `--format json`. Co-Authored-By: Claude Opus 4.6 <[email protected]>
1 parent 10d9154 commit c9e3887

8 files changed

Lines changed: 309 additions & 36 deletions

File tree

‎EVENTS.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# NDJSON Events
2+
3+
When running `aictrl run --format json`, the CLI emits newline-delimited JSON (NDJSON) events to stdout. Each line is a self-contained JSON object with the following base shape:
4+
5+
```json
6+
{
7+
"type": "<event_type>",
8+
"timestamp": 1741500000000,
9+
"sessionID": "session_01abc..."
10+
}
11+
```
12+
13+
## Lifecycle Events
14+
15+
### `session_start`
16+
17+
Emitted once when the session begins.
18+
19+
```json
20+
{
21+
"type": "session_start",
22+
"model": "anthropic/claude-sonnet-4-20250514",
23+
"agent": "default"
24+
}
25+
```
26+
27+
### `session_complete`
28+
29+
Emitted once when the session ends (success or failure).
30+
31+
```json
32+
{
33+
"type": "session_complete",
34+
"durationMs": 12345,
35+
"error": null
36+
}
37+
```
38+
39+
`error` is `null` on success, or a string describing the failure.
40+
41+
## Message Events
42+
43+
### `message_complete`
44+
45+
Emitted when an assistant message finishes (one per LLM turn).
46+
47+
```json
48+
{
49+
"type": "message_complete",
50+
"modelID": "claude-sonnet-4-20250514",
51+
"providerID": "anthropic",
52+
"agent": "default",
53+
"cost": { "input": 0.003, "output": 0.012, "cache": { "read": 0, "write": 0 } },
54+
"tokens": { "input": 1024, "output": 512, "cache": { "read": 0, "write": 0 } },
55+
"finish": "tool-calls"
56+
}
57+
```
58+
59+
`finish` values: `"tool-calls"` (model wants to call tools), `"end_turn"` (model is done), `"max_tokens"` (output truncated).
60+
61+
### `text`
62+
63+
Emitted when a text block from the assistant is complete.
64+
65+
```json
66+
{
67+
"type": "text",
68+
"part": {
69+
"type": "text",
70+
"text": "Here is the result...",
71+
"time": { "start": 1741500000, "end": 1741500001 }
72+
}
73+
}
74+
```
75+
76+
### `reasoning`
77+
78+
Emitted when extended thinking content is complete (requires `--thinking` flag).
79+
80+
```json
81+
{
82+
"type": "reasoning",
83+
"part": {
84+
"type": "reasoning",
85+
"text": "Let me think about this...",
86+
"time": { "start": 1741500000, "end": 1741500001 }
87+
}
88+
}
89+
```
90+
91+
## Tool Events
92+
93+
### `tool_use`
94+
95+
Emitted when a tool call completes (success or error).
96+
97+
```json
98+
{
99+
"type": "tool_use",
100+
"part": {
101+
"type": "tool",
102+
"tool": "bash",
103+
"state": {
104+
"status": "completed",
105+
"input": { "command": "ls" },
106+
"metadata": { "exit": 0, "output": "..." }
107+
}
108+
}
109+
}
110+
```
111+
112+
`state.status` is `"completed"` or `"error"`. On error, `state.error` contains the error message.
113+
114+
### `step_start` / `step_finish`
115+
116+
Emitted at step boundaries during multi-step tool use.
117+
118+
```json
119+
{ "type": "step_start", "part": { "type": "step-start" } }
120+
{ "type": "step_finish", "part": { "type": "step-finish" } }
121+
```
122+
123+
## Skill Events
124+
125+
Skills are loaded progressively. The model first sees skill names and descriptions in the tool schema. Full skill content only enters context when the model explicitly invokes the skill tool.
126+
127+
### `skill_discovered`
128+
129+
Emitted per skill when the skill tool is initialized and skill descriptions are registered in the tool schema. This happens at the start of each LLM turn.
130+
131+
```json
132+
{
133+
"type": "skill_discovered",
134+
"name": "commit",
135+
"description": "Create well-structured git commits",
136+
"location": "/home/user/.claude/skills/commit/SKILL.md"
137+
}
138+
```
139+
140+
### `skill_loaded`
141+
142+
Emitted when the model invokes the skill tool and the full SKILL.md content enters context.
143+
144+
```json
145+
{
146+
"type": "skill_loaded",
147+
"name": "commit",
148+
"location": "/home/user/.claude/skills/commit/SKILL.md"
149+
}
150+
```
151+
152+
### `skill_resource_loaded`
153+
154+
Emitted when the model reads a file that belongs to a skill directory (e.g., a script, template, or reference file bundled with the skill).
155+
156+
```json
157+
{
158+
"type": "skill_resource_loaded",
159+
"skillName": "commit",
160+
"filePath": "/home/user/.claude/skills/commit/templates/conventional.md"
161+
}
162+
```
163+
164+
## Subagent Events
165+
166+
### `subagent_start`
167+
168+
Emitted when a child session (subagent) is spawned.
169+
170+
```json
171+
{
172+
"type": "subagent_start",
173+
"subagentSessionID": "session_01xyz...",
174+
"parentSessionID": "session_01abc...",
175+
"title": "Research codebase"
176+
}
177+
```
178+
179+
### `subagent_complete`
180+
181+
Emitted when a child session completes.
182+
183+
```json
184+
{
185+
"type": "subagent_complete",
186+
"subagentSessionID": "session_01xyz...",
187+
"parentSessionID": "session_01abc..."
188+
}
189+
```
190+
191+
## Error Events
192+
193+
### `error`
194+
195+
Emitted when a session error occurs.
196+
197+
```json
198+
{
199+
"type": "error",
200+
"error": {
201+
"name": "Unknown",
202+
"data": { "message": "Something went wrong" }
203+
},
204+
"sourceSessionID": "session_01abc..."
205+
}
206+
```
207+
208+
### `permission_rejected`
209+
210+
Emitted when a permission request is auto-rejected (headless mode has no user to approve).
211+
212+
```json
213+
{
214+
"type": "permission_rejected",
215+
"permission": "bash",
216+
"patterns": ["rm -rf /"]
217+
}
218+
```

‎packages/cli/src/cli/cmd/run.ts‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -552,12 +552,31 @@ export const RunCommand = cmd({
552552
UI.error(err)
553553
}
554554

555-
if (event.type === "session.skills_loaded") {
555+
if (event.type === "session.skill_discovered") {
556556
const props = event.properties
557557
if (props.sessionID !== sessionID) continue
558-
emit("skills_loaded", {
559-
skills: props.skills,
560-
count: props.skills.length,
558+
emit("skill_discovered", {
559+
name: props.name,
560+
description: props.description,
561+
location: props.location,
562+
})
563+
}
564+
565+
if (event.type === "session.skill_loaded") {
566+
const props = event.properties
567+
if (props.sessionID !== sessionID) continue
568+
emit("skill_loaded", {
569+
name: props.name,
570+
location: props.location,
571+
})
572+
}
573+
574+
if (event.type === "session.skill_resource_loaded") {
575+
const props = event.properties
576+
if (props.sessionID !== sessionID) continue
577+
emit("skill_resource_loaded", {
578+
skillName: props.skillName,
579+
filePath: props.filePath,
561580
})
562581
}
563582

‎packages/cli/src/session/index.ts‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -210,16 +210,29 @@ export namespace Session {
210210
error: MessageV2.Assistant.shape.error,
211211
}),
212212
),
213-
SkillsLoaded: BusEvent.define(
214-
"session.skills_loaded",
213+
SkillDiscovered: BusEvent.define(
214+
"session.skill_discovered",
215215
z.object({
216216
sessionID: z.string(),
217-
skills: z.array(
218-
z.object({
219-
name: z.string(),
220-
location: z.string(),
221-
}),
222-
),
217+
name: z.string(),
218+
description: z.string(),
219+
location: z.string(),
220+
}),
221+
),
222+
SkillLoaded: BusEvent.define(
223+
"session.skill_loaded",
224+
z.object({
225+
sessionID: z.string(),
226+
name: z.string(),
227+
location: z.string(),
228+
}),
229+
),
230+
SkillResourceLoaded: BusEvent.define(
231+
"session.skill_resource_loaded",
232+
z.object({
233+
sessionID: z.string(),
234+
skillName: z.string(),
235+
filePath: z.string(),
223236
}),
224237
),
225238
}

‎packages/cli/src/session/prompt.ts‎

Lines changed: 1 addition & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -660,29 +660,6 @@ export namespace SessionPrompt {
660660
// Build system prompt, adding structured output instruction if needed
661661
const system = [...(await SystemPrompt.environment(model)), ...(await InstructionPrompt.system())]
662662

663-
// Automatically load all skills into system prompt
664-
try {
665-
const { Skill } = await import("../skill/skill")
666-
const allSkills = await Skill.all()
667-
for (const skill of allSkills) {
668-
system.unshift(`AVAILABLE SKILL: ${skill.name}\n\n${skill.content}`)
669-
}
670-
Bus.publish(Session.Event.SkillsLoaded, {
671-
sessionID,
672-
skills: allSkills.map((s) => ({ name: s.name, location: s.location })),
673-
})
674-
} catch (e) {
675-
log.warn("failed to auto-load skills", { error: e })
676-
Bus.publish(Session.Event.Error, {
677-
sessionID,
678-
error: new NamedError.Unknown({ message: "Failed to auto-load skills" }).toObject(),
679-
})
680-
Bus.publish(Session.Event.SkillsLoaded, {
681-
sessionID,
682-
skills: [],
683-
})
684-
}
685-
686663
const format = lastUser.format ?? { type: "text" }
687664
if (format.type === "json_schema") {
688665
system.push(STRUCTURED_OUTPUT_SYSTEM_PROMPT)
@@ -815,6 +792,7 @@ export namespace SessionPrompt {
815792
for (const item of await ToolRegistry.tools(
816793
{ modelID: input.model.api.id, providerID: input.model.providerID },
817794
input.agent,
795+
input.session.id,
818796
)) {
819797
const schema = ProviderTransform.schema(input.model, z.toJSONSchema(item.parameters))
820798
tools[item.id] = tool({

‎packages/cli/src/tool/read.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,34 @@ import { Instance } from "../project/instance"
1111
import { assertExternalDirectory } from "./external-directory"
1212
import { InstructionPrompt } from "../session/instruction"
1313
import { Filesystem } from "../util/filesystem"
14+
import { Skill } from "../skill"
15+
import { Bus } from "../bus"
16+
import { Session } from "../session"
1417

1518
const DEFAULT_READ_LIMIT = 2000
1619
const MAX_LINE_LENGTH = 2000
1720
const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`
1821
const MAX_BYTES = 50 * 1024
1922
const MAX_BYTES_LABEL = `${MAX_BYTES / 1024} KB`
2023

24+
async function emitSkillResourceEvent(sessionID: string, filepath: string) {
25+
const skillDirs = await Skill.dirs()
26+
for (const dir of skillDirs) {
27+
if (Filesystem.contains(dir, filepath)) {
28+
const skills = await Skill.all()
29+
const skill = skills.find((s) => Filesystem.contains(path.dirname(s.location), filepath))
30+
if (skill) {
31+
Bus.publish(Session.Event.SkillResourceLoaded, {
32+
sessionID,
33+
skillName: skill.name,
34+
filePath: filepath,
35+
})
36+
}
37+
break
38+
}
39+
}
40+
}
41+
2142
export const ReadTool = Tool.define("read", {
2243
description: DESCRIPTION,
2344
parameters: z.object({
@@ -122,6 +143,7 @@ export const ReadTool = Tool.define("read", {
122143
const isImage = mime.startsWith("image/") && mime !== "image/svg+xml" && mime !== "image/vnd.fastbidsheet"
123144
const isPdf = mime === "application/pdf"
124145
if (isImage || isPdf) {
146+
await emitSkillResourceEvent(ctx.sessionID, filepath)
125147
const msg = `${isImage ? "Image" : "PDF"} read successfully`
126148
return {
127149
title,
@@ -215,6 +237,7 @@ export const ReadTool = Tool.define("read", {
215237
// just warms the lsp client
216238
LSP.touchFile(filepath, false)
217239
FileTime.read(ctx.sessionID, filepath)
240+
await emitSkillResourceEvent(ctx.sessionID, filepath)
218241

219242
if (instructions.length > 0) {
220243
output += `\n\n<system-reminder>\n${instructions.map((i) => i.content).join("\n\n")}\n</system-reminder>`

‎packages/cli/src/tool/registry.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@ export namespace ToolRegistry {
150150
modelID: string
151151
},
152152
agent?: Agent.Info,
153+
sessionID?: string,
153154
) {
154155
const tools = await all()
155156
const result = await Promise.all(
@@ -170,7 +171,7 @@ export namespace ToolRegistry {
170171
})
171172
.map(async (t) => {
172173
using _ = log.time(t.id)
173-
const tool = await t.init({ agent })
174+
const tool = await t.init({ agent, sessionID })
174175
const output = {
175176
description: tool.description,
176177
parameters: tool.parameters,

0 commit comments

Comments
 (0)