Remove skill content max truncation (#4639)

Remove `max` from the skills metadata contract and stop truncating skill
content in `use_skill`. Agents now receive complete skill instructions
instead of partial directives plus truncation warnings.

## Root Cause

`use_skill` historically sliced skill markdown to `meta.max` before
inserting the skill instructions into context. Long skills therefore
loaded as incomplete directives, causing agents to complain about
truncation and potentially follow partial workflows.

## Approach

- Remove the skill-level `max` field from parsed preamble metadata,
extracted metadata, and `SkillMeta`.
- Remove the `use_skill` truncation branch and the `truncated`
tool-result details.
- Update tests and skill metadata mocks to reflect that large skills
load in full.
- Add a changeset for `@electric-ax/agents-runtime`.

## Key Invariants

- `use_skill` inserts complete skill instructions into context.
- Skill loading no longer reports a `truncated` flag or warning.
- Oversized skills should be fixed at the skill-authoring level rather
than partially loaded by the runtime.

## Non-goals

- This does not change general context assembly/source-budget truncation
behavior.
- This does not add a replacement hard block for large skills.

## Trade-offs

The previous `max` field acted as a hard per-skill safety cap, but it
produced incomplete instructions. This PR removes that contract so
legitimate skills are not silently corrupted; if a skill is too large,
the skill itself should be split or improved.

## Verification

```bash
cd packages/agents-runtime
pnpm vitest run test/skills/tools.test.ts test/skills/preamble.test.ts

cd ../..
pnpm --filter @electric-ax/agents-runtime typecheck
GITHUB_BASE_REF=main node scripts/check-changeset.mjs
```

Results:

- `test/skills/tools.test.ts` and `test/skills/preamble.test.ts`: 17
tests passed.
- `@electric-ax/agents-runtime` typecheck passed.
- Changeset validation passed for `@electric-ax/agents-runtime`.

## Files changed

- `.changeset/remove-skill-content-max.md`: adds a patch changeset.
- `packages/agents-runtime/src/skills/types.ts`: removes
`SkillMeta.max`.
- `packages/agents-runtime/src/skills/extract-meta.ts`: stops
defaulting/extracting skill `max`.
- `packages/agents-runtime/src/skills/preamble.ts`: stops parsing `max`
from skill frontmatter.
- `packages/agents-runtime/src/skills/tools.ts`: removes skill content
truncation and `truncated` details.
- `packages/agents-runtime/test/skills/*.test.ts`: updates tests and
fixtures for full skill loading.

Author: KyleAMathews

.changeset/remove-skill-content-max.md

@@ -0,0 +1,5 @@
+---
+'@electric-ax/agents-runtime': patch
+---
+
+Remove the skill content `max` cap so `use_skill` loads complete skill instructions instead of truncating them.

packages/agents-runtime/src/skills/extract-meta.ts

@@ -7,11 +7,8 @@ interface ExtractedMeta {
   arguments?: Array<string>
   argumentHint?: string
   userInvocable?: boolean
-  max: number
 }
 
-const DEFAULT_MAX = 10_000
-
 export async function extractSkillMeta(
   name: string,
   content: string
@@ -26,7 +23,6 @@ export async function extractSkillMeta(
       ...(preamble.arguments && { arguments: preamble.arguments }),
       ...(preamble.argumentHint && { argumentHint: preamble.argumentHint }),
       ...(preamble.userInvocable && { userInvocable: true }),
-      max: preamble.max ?? DEFAULT_MAX,
     }
   }
 
@@ -35,7 +31,6 @@ export async function extractSkillMeta(
     whenToUse:
       preamble.whenToUse ?? `User asks about ${humanize(name).toLowerCase()}`,
     keywords: preamble.keywords ?? [name],
-    max: preamble.max ?? DEFAULT_MAX,
   }
 }
 

packages/agents-runtime/src/skills/preamble.ts

@@ -5,7 +5,6 @@ export interface PreambleFields {
   arguments?: Array<string>
   argumentHint?: string
   userInvocable?: boolean
-  max?: number
 }
 
 export function parsePreamble(content: string): PreambleFields {
@@ -82,11 +81,6 @@ export function parsePreamble(content: string): PreambleFields {
       case `user-invocable`:
         result.userInvocable = rawValue === `true`
         break
-      case `max`: {
-        const num = parseInt(rawValue, 10)
-        if (!Number.isNaN(num) && num > 0) result.max = num
-        break
-      }
     }
   }
 

packages/agents-runtime/src/skills/tools.ts

@@ -12,7 +12,6 @@ function skillContextId(name: string): string {
 export interface LoadSkillResult {
   loaded: boolean
   alreadyLoaded?: boolean
-  truncated?: boolean
   chars?: number
   message: string
   contextSource?: string
@@ -50,12 +49,6 @@ export async function loadSkillIntoContext(
     }
   }
 
-  let truncated = false
-  if (content.length > meta.max) {
-    truncated = true
-    content = content.slice(0, meta.max)
-  }
-
   if (args) {
     content = substituteArgs(content, args, meta.arguments)
   }
@@ -67,9 +60,6 @@ export async function loadSkillIntoContext(
   })
 
   const skillDir = path.join(path.dirname(meta.source), name)
-  const truncNote = truncated
-    ? `\n\nWARNING: Content was truncated from ${meta.charCount.toLocaleString()} to ${meta.max.toLocaleString()} chars. Inform the user.`
-    : ``
 
   const allRefFiles = listRefFiles(skillDir)
   const mdFiles = allRefFiles.filter((f) => f.endsWith(`.md`))
@@ -96,11 +86,10 @@ export async function loadSkillIntoContext(
   const dirNote = hasRefDir ? `\nSkill directory: ${skillDir}` : ``
   const refSection =
     refContents.length > 0 ? `\n\n${refContents.join(`\n\n`)}` : ``
-  const contextSource = `SKILL ACTIVATED: "${name}". The instructions below override your default behavior. Follow them exactly. Do not read any files to find this content — it is all here.\n${dirNote}${truncNote}\n\n${content}${refSection}`
+  const contextSource = `SKILL ACTIVATED: "${name}". The instructions below override your default behavior. Follow them exactly. Do not read any files to find this content — it is all here.\n${dirNote}\n\n${content}${refSection}`
 
   return {
     loaded: true,
-    truncated,
     chars: content.length,
     message: contextSource,
     contextSource,
@@ -136,7 +125,6 @@ export function createSkillTools(
           ...(result.alreadyLoaded
             ? { alreadyLoaded: result.alreadyLoaded }
             : {}),
-          ...(result.truncated ? { truncated: result.truncated } : {}),
           ...(result.chars !== undefined ? { chars: result.chars } : {}),
         },
       }

packages/agents-runtime/src/skills/types.ts

@@ -6,7 +6,6 @@ export interface SkillMeta {
   arguments?: Array<string>
   argumentHint?: string
   userInvocable?: boolean
-  max: number
   charCount: number
   contentHash: string
   source: string

packages/agents-runtime/test/skills/context-loader.test.ts

@@ -17,7 +17,6 @@ function createRegistry(): SkillsRegistry {
           whenToUse: `User wants a tutorial`,
           keywords: [`quickstart`],
           userInvocable: true,
-          max: 1000,
           charCount: 100,
           contentHash: `hash-1`,
           source: `/skills/quickstart.md`,
@@ -33,7 +32,6 @@ function createRegistry(): SkillsRegistry {
           arguments: [`project_name`, `Bad-Arg`],
           argumentHint: `[project-name]`,
           userInvocable: true,
-          max: 1000,
           charCount: 100,
           contentHash: `hash-2`,
           source: `/skills/init.md`,
@@ -47,7 +45,6 @@ function createRegistry(): SkillsRegistry {
           whenToUse: `Never directly`,
           keywords: [],
           userInvocable: false,
-          max: 1000,
           charCount: 100,
           contentHash: `hash-3`,
           source: `/skills/internal.md`,
@@ -61,7 +58,6 @@ function createRegistry(): SkillsRegistry {
           whenToUse: `Never directly`,
           keywords: [],
           userInvocable: true,
-          max: 1000,
           charCount: 100,
           contentHash: `hash-4`,
           source: `/skills/bad.md`,

packages/agents-runtime/test/skills/preamble.test.ts

@@ -7,7 +7,6 @@ describe(`parsePreamble`, () => {
 description: Interactive tutorial guide
 whenToUse: User asks about tutorials or getting started
 keywords: [tutorial, multi-agent, spawn]
-max: 15000
 ---
 
 # Tutorial content here`
@@ -17,7 +16,6 @@ max: 15000
       description: `Interactive tutorial guide`,
       whenToUse: `User asks about tutorials or getting started`,
       keywords: [`tutorial`, `multi-agent`, `spawn`],
-      max: 15000,
     })
   })
 
@@ -69,7 +67,6 @@ keywords:
   - getting started
   - learn
   - multi-agent
-max: 10000
 ---
 
 # Content here`
@@ -81,7 +78,6 @@ max: 10000
       `learn`,
       `multi-agent`,
     ])
-    expect(result.max).toBe(10000)
   })
 
   it(`strips surrounding quotes from description and whenToUse`, () => {

packages/agents-runtime/test/skills/tools.test.ts

@@ -39,7 +39,6 @@ const QUICKSTART_META: SkillMeta = {
   description: `A quickstart`,
   whenToUse: `When learning`,
   keywords: [`quickstart`],
-  max: 10_000,
   charCount: 500,
   contentHash: `abc123`,
   source: `/skills/quickstart.md`,
@@ -112,9 +111,9 @@ describe(`skill tools`, () => {
     })
   })
 
-  it(`use_skill truncates and warns when content exceeds max`, async () => {
+  it(`use_skill loads full content for large skills`, async () => {
     const bigContent = `x`.repeat(15_000)
-    const meta = { ...QUICKSTART_META, max: 10_000, charCount: 15_000 }
+    const meta = { ...QUICKSTART_META, charCount: 15_000 }
     const registry = createMockRegistry({
       quickstart: { meta, content: bigContent },
     })
@@ -125,13 +124,12 @@ describe(`skill tools`, () => {
     const result = await useTool.execute(`tc1`, { name: `quickstart` })
 
     const insertedContent = ctx.insertContext.mock.calls[0]![1].content
-    // Content is truncated to max (10,000) — no wrapper prefix in insertContext
-    expect(insertedContent).toContain(`x`.repeat(100))
-    expect(insertedContent.length).toBe(10_000)
-    // Tool result contains truncation warning
+    expect(insertedContent).toBe(bigContent)
+    expect(result.details).toMatchObject({ loaded: true, chars: 15_000 })
+    expect(result.details).not.toHaveProperty(`truncated`)
     expect(result.content[0]).toMatchObject({
       type: `text`,
-      text: expect.stringContaining(`truncated`),
+      text: expect.not.stringContaining(`truncated`),
     })
   })