feat: overhead-aware section budgets, raise total target to 500 lines

Section budgets now account for actual SKILL.md overhead (frontmatter,
header, search block, footer). The base SKILL.md line count is passed
through to budget functions so sections fill available space rather
than using fixed estimates.

Total target raised from 300 to 500 lines. Per-section limits bumped
proportionally: best-practices 100/250 lines 6/15 items, api-changes
60/130 lines 8/18 items.

Author: harlan-zw

src/agent/clis/index.ts

@@ -561,7 +561,7 @@ function optimizeSection(opts: OptimizeSectionOptions): Promise<SectionResult> {
 // ── Main orchestrator ────────────────────────────────────────────────
 
 export async function optimizeDocs(opts: OptimizeDocsOptions): Promise<OptimizeResult> {
-  const { packageName, skillDir, model = 'sonnet', version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 180000, debug, noCache, sections, customPrompt, features, pkgFiles } = opts
+  const { packageName, skillDir, model = 'sonnet', version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 180000, debug, noCache, sections, customPrompt, features, pkgFiles, overheadLines } = opts
 
   const selectedSections = sections ?? ['api-changes', 'best-practices'] as SkillSection[]
 
@@ -580,6 +580,7 @@ export async function optimizeDocs(opts: OptimizeDocsOptions): Promise<OptimizeR
     customPrompt,
     features,
     pkgFiles,
+    overheadLines,
     sections: selectedSections,
   })
 

src/agent/clis/types.ts

@@ -82,6 +82,8 @@ export interface OptimizeDocsOptions {
   features?: FeaturesConfig
   /** Key files from the package (e.g., dist/pkg.d.ts) */
   pkgFiles?: string[]
+  /** Lines consumed by SKILL.md overhead (frontmatter + header + search + footer) */
+  overheadLines?: number
 }
 
 export interface OptimizeResult {

src/agent/prompts/optional/api-changes.ts

@@ -3,7 +3,7 @@ import { resolveSkilldCommand } from '../../../core/shared.ts'
 import { maxItems, maxLines, releaseBoost } from './budget.ts'
 import { checkAbsolutePaths, checkLineCount, checkSourceCoverage, checkSourcePaths, checkSparseness } from './validate.ts'
 
-export function apiChangesSection({ packageName, version, hasReleases, hasChangelog, hasDocs, hasIssues, hasDiscussions, pkgFiles, features, enabledSectionCount, releaseCount }: SectionContext): PromptSection {
+export function apiChangesSection({ packageName, version, hasReleases, hasChangelog, hasDocs, hasIssues, hasDiscussions, pkgFiles, features, enabledSectionCount, releaseCount, overheadLines }: SectionContext): PromptSection {
   const [, major, minor] = version?.match(/^(\d+)\.(\d+)/) ?? []
   const boost = releaseBoost(releaseCount, minor ? Number(minor) : undefined)
 
@@ -69,7 +69,7 @@ export function apiChangesSection({ packageName, version, hasReleases, hasChange
 The "Older" column means ≤ v${Number(major) - 2}.x — these changes are NOT useful because anyone on v${major}.x already migrated past them.`
     : ''
 
-  const apiChangesMaxLines = maxLines(50, Math.round(80 * boost), enabledSectionCount)
+  const apiChangesMaxLines = maxLines(60, Math.round(130 * boost), enabledSectionCount, overheadLines)
 
   return {
     referenceWeights,
@@ -123,7 +123,7 @@ Each item: BREAKING/DEPRECATED/NEW label + API name + what changed + source link
 **Tiered format:** Top-scoring items get full detailed entries. Remaining relevant items go in a compact "**Also changed:**" line at the end — API name + brief label, separated by \` · \`. This surfaces more changes without bloating the section.`,
 
     rules: [
-      `- **API Changes:** ${maxItems(6, Math.round(12 * boost), enabledSectionCount)} detailed items + compact "Also changed" line for remaining, MAX ${apiChangesMaxLines} lines`,
+      `- **API Changes:** ${maxItems(8, Math.round(18 * boost), enabledSectionCount)} detailed items + compact "Also changed" line for remaining, MAX ${apiChangesMaxLines} lines`,
       '- **Every detailed item MUST have a `[source](./.skilld/...#section)` link** with a section anchor (`#heading-slug`) or line reference (`:L<line>` or `:L<start>:<end>`). If you cannot cite a specific location in a release, changelog entry, or migration doc, do NOT include the item',
       '- **Recency:** Only include changes from the current major version and the previous→current migration. Exclude changes from older major versions entirely — users already migrated past them',
       '- Focus on APIs that CHANGED, not general conventions or gotchas',

src/agent/prompts/optional/best-practices.ts

@@ -3,7 +3,7 @@ import { resolveSkilldCommand } from '../../../core/shared.ts'
 import { maxItems, maxLines, releaseBoost } from './budget.ts'
 import { checkAbsolutePaths, checkLineCount, checkSourceCoverage, checkSourcePaths, checkSparseness } from './validate.ts'
 
-export function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, pkgFiles, features, enabledSectionCount, releaseCount, version }: SectionContext): PromptSection {
+export function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, pkgFiles, features, enabledSectionCount, releaseCount, version, overheadLines }: SectionContext): PromptSection {
   const [,, minor] = version?.match(/^(\d+)\.(\d+)/) ?? []
   // Dampened boost — best practices are less directly tied to releases than API changes
   const rawBoost = releaseBoost(releaseCount, minor ? Number(minor) : undefined)
@@ -35,7 +35,7 @@ export function bestPracticesSection({ packageName, hasIssues, hasDiscussions, h
     referenceWeights.push({ name: 'Changelog', path: `./.skilld/${hasChangelog}`, score: 3, useFor: 'Only for new patterns introduced in recent versions' })
   }
 
-  const bpMaxLines = maxLines(80, Math.round(150 * boost), enabledSectionCount)
+  const bpMaxLines = maxLines(100, Math.round(250 * boost), enabledSectionCount, overheadLines)
 
   return {
     referenceWeights,
@@ -86,7 +86,7 @@ const client = createX({ retryDelay: attempt => Math.min(1000 * 2 ** attempt, 30
 Each item: markdown list item (-) + ${packageName}-specific pattern + why it's preferred + \`[source](./.skilld/...#section)\` link. **Prefer concise descriptions over inline code** — the source link points the agent to full examples in the docs. Only add a code block when the pattern genuinely cannot be understood from the description alone (e.g., non-obvious syntax, multi-step wiring). Most items should be description + source link only. All source links MUST use \`./.skilld/\` prefix and include a **section anchor** (\`#heading-slug\`) or **line reference** (\`:L<line>\` or \`:L<start>:<end>\`) to pinpoint the exact location. Do NOT use emoji — use plain text markers only.`,
 
     rules: [
-      `- **${maxItems(4, Math.round(10 * boost), enabledSectionCount)} best practice items**`,
+      `- **${maxItems(6, Math.round(15 * boost), enabledSectionCount)} best practice items**`,
       `- **MAX ${bpMaxLines} lines** for best practices section`,
       '- **Every item MUST have a `[source](./.skilld/...#section)` link** with a section anchor (`#heading-slug`) or line reference (`:L<line>` or `:L<start>:<end>`). If you cannot cite a specific location in a reference file, do NOT include the item — unsourced items risk hallucination and will be rejected',
       '- **Minimize inline code.** Most items should be description + source link only. The source file contains full examples the agent can read. Only add a code block when the pattern is unintuitable from the description (non-obvious syntax, surprising argument order, multi-step wiring). Aim for at most 1 in 4 items having a code block',

src/agent/prompts/optional/budget.ts

@@ -1,15 +1,24 @@
 /**
  * Dynamic budget allocation for skill sections.
  *
- * Total SKILL.md body should stay under ~300 lines (≈5,000 words per Agent Skills guide).
- * When more sections are enabled, each gets proportionally less space.
- * When a package has many releases, API changes budget scales up to capture more churn.
+ * Total SKILL.md target is ~500 lines. Overhead (frontmatter, header, search, footer)
+ * is subtracted to get the available body budget, which is divided among enabled sections.
+ * When a package has many releases, budgets scale up.
  */
 
-/** Scale max lines based on enabled section count. Solo sections get full budget, 4 sections ~60%. */
-export function maxLines(min: number, max: number, sectionCount?: number): number {
+const TOTAL_TARGET = 500
+const DEFAULT_OVERHEAD = 30
+
+/** Available body lines after overhead is subtracted */
+function remainingLines(overheadLines?: number): number {
+  return TOTAL_TARGET - (overheadLines ?? DEFAULT_OVERHEAD)
+}
+
+/** Scale max lines based on enabled section count and available remaining space. */
+export function maxLines(min: number, max: number, sectionCount?: number, overheadLines?: number): number {
+  const remaining = remainingLines(overheadLines)
   const scale = budgetScale(sectionCount)
-  return Math.max(min, Math.round(max * scale))
+  return Math.max(min, Math.min(Math.round(max * scale), remaining))
 }
 
 /** Scale item count based on enabled section count. */

src/agent/prompts/optional/custom.ts

@@ -2,8 +2,8 @@ import type { CustomPrompt, PromptSection, SectionValidationWarning } from './ty
 import { maxLines } from './budget.ts'
 import { checkAbsolutePaths, checkLineCount, checkSourceCoverage, checkSourcePaths, checkSparseness } from './validate.ts'
 
-export function customSection({ heading, body }: CustomPrompt, enabledSectionCount?: number): PromptSection {
-  const customMaxLines = maxLines(50, 80, enabledSectionCount)
+export function customSection({ heading, body }: CustomPrompt, enabledSectionCount?: number, overheadLines?: number): PromptSection {
+  const customMaxLines = maxLines(50, 80, enabledSectionCount, overheadLines)
 
   return {
     validate(content: string): SectionValidationWarning[] {

src/agent/prompts/optional/types.ts

@@ -39,6 +39,8 @@ export interface SectionContext {
   enabledSectionCount?: number
   /** Number of release files — used for adaptive API changes budget */
   releaseCount?: number
+  /** Lines consumed by frontmatter + header + search + footer */
+  overheadLines?: number
 }
 
 export interface CustomPrompt {

src/agent/prompts/prompt.ts

@@ -68,6 +68,8 @@ export interface BuildSkillPromptOptions {
   enabledSectionCount?: number
   /** Key files from the package (e.g., dist/pkg.d.ts) — surfaced in prompt for tool hints */
   pkgFiles?: string[]
+  /** Lines consumed by SKILL.md overhead (frontmatter + header + search + footer) */
+  overheadLines?: number
 }
 
 /**
@@ -178,7 +180,7 @@ function getSectionDef(section: SkillSection, ctx: SectionContext, customPrompt?
   switch (section) {
     case 'api-changes': return apiChangesSection(ctx)
     case 'best-practices': return bestPracticesSection(ctx)
-    case 'custom': return customPrompt ? customSection(customPrompt, ctx.enabledSectionCount) : null
+    case 'custom': return customPrompt ? customSection(customPrompt, ctx.enabledSectionCount, ctx.overheadLines) : null
   }
 }
 
@@ -211,7 +213,7 @@ export function buildSectionPrompt(opts: BuildSkillPromptOptions & { section: Sk
     const m = f.match(/v\d+\.(\d+)\.(\d+)\.md$/)
     return m && (m[1] === '0' || m[2] === '0') // major (x.0.y) or minor (x.y.0)
   }).length
-  const ctx: SectionContext = { packageName, version, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, pkgFiles: opts.pkgFiles, features: opts.features, enabledSectionCount: opts.enabledSectionCount, releaseCount }
+  const ctx: SectionContext = { packageName, version, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, pkgFiles: opts.pkgFiles, features: opts.features, enabledSectionCount: opts.enabledSectionCount, releaseCount, overheadLines: opts.overheadLines }
   const sectionDef = getSectionDef(section, ctx, customPrompt)
   if (!sectionDef)
     return ''

src/commands/sync-parallel.ts

@@ -130,6 +130,8 @@ interface BaseSkillData {
   /** Whether the existing SKILL.md had LLM-generated content */
   wasEnhanced?: boolean
   usedCache: boolean
+  /** Lines consumed by SKILL.md overhead */
+  overheadLines?: number
 }
 
 export async function syncPackagesParallel(config: ParallelSyncConfig): Promise<void> {
@@ -350,6 +352,7 @@ export async function syncPackagesParallel(config: ParallelSyncConfig): Promise<
           sections: llmConfig.sections,
           customPrompt: llmConfig.customPrompt,
           features: data.features,
+          overheadLines: data.overheadLines,
         })
       }
     }
@@ -570,6 +573,7 @@ async function syncBaseSkill(
     features,
   })
   writeFileSync(join(skillDir, 'SKILL.md'), skillMd)
+  const overheadLines = skillMd.split('\n').length
 
   // Link shared dir to per-agent dirs
   const shared = !config.global && getSharedSkillsDir(cwd)
@@ -601,6 +605,7 @@ async function syncBaseSkill(
     oldVersion: preLock?.version,
     oldSyncedAt: preLock?.syncedAt,
     wasEnhanced: preEnhanced,
+    overheadLines,
   }
 }
 
@@ -639,6 +644,7 @@ async function enhanceWithLLM(
     customPrompt,
     features: data.features,
     pkgFiles: data.pkgFiles,
+    overheadLines: data.overheadLines,
     onProgress: (progress) => {
       const isReasoning = progress.type === 'reasoning'
       const status = isReasoning ? 'exploring' : 'generating'

src/commands/sync-shared.ts

@@ -1376,10 +1376,11 @@ export interface EnhanceOptions {
   packages?: Array<{ name: string }>
   features?: FeaturesConfig
   eject?: boolean
+  overheadLines?: number
 }
 
 export async function enhanceSkillWithLLM(opts: EnhanceOptions): Promise<void> {
-  const { packageName, version, skillDir, dirName, model, resolved, relatedSkills, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs: shippedDocs, pkgFiles, force, debug, sections, customPrompt, packages, features, eject } = opts
+  const { packageName, version, skillDir, dirName, model, resolved, relatedSkills, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs: shippedDocs, pkgFiles, force, debug, sections, customPrompt, packages, features, eject, overheadLines } = opts
 
   const effectiveFeatures = features
 
@@ -1403,6 +1404,7 @@ export async function enhanceSkillWithLLM(opts: EnhanceOptions): Promise<void> {
     customPrompt,
     features: effectiveFeatures,
     pkgFiles,
+    overheadLines,
     onProgress: createToolProgress(llmLog),
   })
 
@@ -1467,6 +1469,7 @@ export interface WritePromptFilesOptions {
   sections: SkillSection[]
   customPrompt?: CustomPrompt
   features?: FeaturesConfig
+  overheadLines?: number
 }
 
 /**
@@ -1490,6 +1493,7 @@ export function writePromptFiles(opts: WritePromptFilesOptions): SkillSection[]
     pkgFiles: opts.pkgFiles,
     customPrompt,
     features,
+    overheadLines: opts.overheadLines,
     sections,
   })