refactor: overhead-aware budgets, drop deps, limit tags (#44)

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,26 @@
 /**
  * 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 sections = Math.max(1, sectionCount ?? 1)
+  const perSection = Math.floor(remaining / sections)
   const scale = budgetScale(sectionCount)
-  return Math.max(min, Math.round(max * scale))
+  return Math.max(min, Math.min(Math.round(max * scale), perSection))
 }
 
 /** 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
 }
 
 /**
@@ -171,7 +173,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
   }
 }
 
@@ -204,7 +206,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/agent/prompts/skill.ts

@@ -13,8 +13,6 @@ export interface SkillOptions {
   name: string
   version?: string
   releasedAt?: string
-  /** Production dependencies with version specifiers */
-  dependencies?: Record<string, string>
   /** npm dist-tags with version and release date */
   distTags?: Record<string, { version: string, releasedAt?: string }>
   globs?: string[]
@@ -70,7 +68,7 @@ function formatShortDate(isoDate: string): string {
   return `${months[date.getUTCMonth()]} ${date.getUTCFullYear()}`
 }
 
-function generatePackageHeader({ name, description, version, releasedAt, dependencies, distTags, repoUrl, hasIssues, hasDiscussions, hasReleases, docsType, pkgFiles, packages, eject }: SkillOptions): string {
+function generatePackageHeader({ name, description, version, releasedAt, distTags, repoUrl, hasIssues, hasDiscussions, hasReleases, docsType, pkgFiles, packages, eject }: SkillOptions): string {
   let title = `# ${name}`
   if (repoUrl) {
     const url = repoUrl.startsWith('http') ? repoUrl : `https://github.com/${repoUrl}`
@@ -89,15 +87,10 @@ function generatePackageHeader({ name, description, version, releasedAt, depende
     lines.push('', `**Version:** ${versionStr}`)
   }
 
-  if (dependencies && Object.keys(dependencies).length > 0) {
-    const deps = Object.entries(dependencies)
-      .map(([n, v]) => `${n}@${v}`)
-      .join(', ')
-    lines.push(`**Deps:** ${deps}`)
-  }
-
   if (distTags && Object.keys(distTags).length > 0) {
     const tags = Object.entries(distTags)
+      .sort(([, a], [, b]) => (b.releasedAt ?? '').localeCompare(a.releasedAt ?? ''))
+      .slice(0, 3)
       .map(([tag, info]) => {
         const relDate = info.releasedAt ? ` (${formatShortDate(info.releasedAt)})` : ''
         return `${tag}: ${info.version}${relDate}`

src/commands/install.ts

@@ -576,13 +576,11 @@ async function enhanceRegenerated(
     const cwd = process.cwd()
     const pkgPath = resolvePkgDir(pkgName, cwd, version)
     let description: string | undefined
-    let dependencies: Record<string, string> | undefined
     if (pkgPath) {
       const pkgJsonPath = join(pkgPath, 'package.json')
       if (existsSync(pkgJsonPath)) {
         const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'))
         description = pkg.description
-        dependencies = pkg.dependencies
       }
     }
 
@@ -600,7 +598,6 @@ async function enhanceRegenerated(
       name: pkgName,
       version,
       description,
-      dependencies,
       body: optimized,
       relatedSkills: [],
       hasIssues,
@@ -659,13 +656,11 @@ function regenerateBaseSkillMd(
   // Read description + deps from local package.json
   const pkgPath = resolvePkgDir(pkgName, cwd, version)
   let description: string | undefined
-  let dependencies: Record<string, string> | undefined
   if (pkgPath) {
     const pkgJsonPath = join(pkgPath, 'package.json')
     if (existsSync(pkgJsonPath)) {
       const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'))
       description = pkg.description
-      dependencies = pkg.dependencies
     }
   }
 
@@ -696,7 +691,6 @@ function regenerateBaseSkillMd(
     name: pkgName,
     version,
     description,
-    dependencies,
     relatedSkills,
     hasIssues,
     hasDiscussions,