prjct-cli 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## [1.6.0] - 2026-02-06
+
+### Features
+
+- super context for agents — skills.sh, proactive codebase context, effort/model (#121)
+
+
+## [1.6.0] - 2026-02-06
+
+### Features
+
+- **Skills.sh auto-install**: During `prjct sync`, skills from skills.sh are automatically installed for generated agents. Real packages like `anthropics/skills/frontend-design`, `obra/superpowers/systematic-debugging`, and `obra/superpowers/test-driven-development` are mapped per agent domain.
+- **Proactive codebase context**: The orchestrator now gathers real context before agent execution — git state, relevant files (scored by task relevance), code signatures from top files, and recently changed files. Agents start with a complete briefing instead of exploring first.
+- **Effort/model metadata wiring**: Agent frontmatter `effort` and `model` fields are now extracted and injected into prompts, enabling per-agent reasoning depth control.
+
+### Improved
+
+- **Skill loading warnings**: Missing skills now log visible warnings with the agent that needs them and a hint to run `prjct sync`
+- **Skill content in prompts**: Increased skill content truncation from 1000 to 2000 characters for richer context
+- **Skill mappings v3**: Updated `skill-mappings.json` from generic names to real installable skills.sh packages
+
+### Implementation Details
+
+- `sync-service.ts`: New `autoInstallSkills()` method reads `skill-mappings.json`, checks if each skill is installed, and calls `skillInstaller.install()` for missing ones
+- `orchestrator-executor.ts`: New `gatherRealContext()` calls `findRelevantFiles()`, `getRecentFiles()`, and `extractSignatures()` in parallel to build a proactive briefing
+- `prompt-builder.ts`: New "CODEBASE CONTEXT" section with git state, relevant files table, code signatures, and recently changed files; plus effort/model per agent
+- `agent-loader.ts`: New `extractFrontmatterMeta()` parses YAML frontmatter for effort/model fields
+- `agentic.ts`: New `RealCodebaseContext` interface; `LoadedAgent` extended with `effort?` and `model?`
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` — verify skills auto-install (check `~/.claude/skills/`)
+2. Run `p. task "test"` — verify prompt includes git state, relevant files, signatures, effort/model
+3. Verify warnings for missing skills
+4. Build and all 416 tests pass
+
+#### For Users
+**What changed:** Agents receive proactive codebase context before starting work. Skills auto-install during sync.
+**How to use:** No action needed — automatic during `prjct sync` and `p. task`.
+**Breaking changes:** None
+
+## [1.5.2] - 2026-02-06
+
+### Improved
+
+- **TTY detection for CLI spinners**: Spinner, step, and progress animations now detect non-TTY environments (CI/CD, Claude Code, piped output) and print a single static line instead of animating
+
+### Implementation Details
+
+- Added `process.stdout.isTTY` guard to `spin()`, `step()`, and `progress()` in `core/utils/output.ts`
+- Non-TTY environments get a single line with `\n` instead of `setInterval` with `\r` carriage returns
+- Made `clear()` a no-op in non-TTY (the `\r` + spaces trick doesn't work outside terminals)
+- Updated test for `stop()` to handle non-TTY behavior in test runner
+
+### Learnings
+
+- `process.stdout.isTTY` is the reliable built-in way to detect interactive terminals in Node.js
+- Test suites (bun test) also run as non-TTY, so test assertions need to account for both paths
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` in an interactive terminal — spinner should animate normally
+2. Run `prjct sync --yes > out.txt` — output should show a single static line, no repeated frames
+3. Run inside Claude Code Bash tool — output should be clean, no spinner noise
+4. Verify `step()` and `progress()` behave the same way in both environments
+
+#### For Users
+**What changed:** CLI spinners no longer produce garbage output in non-interactive terminals
+**How to use:** No action needed — automatic TTY detection
+**Breaking changes:** None
+
 ## [1.5.1] - 2026-02-06
 
 ### Refactoring

package/core/__tests__/utils/output.test.ts

@@ -124,7 +124,13 @@ describe('Output Module', () => {
       stdoutWriteSpy.mockClear()
       out.stop()
 
-      expect(stdoutWriteSpy).toHaveBeenCalled()
+      // In TTY, stop() writes a clear sequence; in non-TTY, spinner doesn't
+      // use setInterval so stop() is a no-op (clear skips in non-TTY)
+      if (process.stdout.isTTY) {
+        expect(stdoutWriteSpy).toHaveBeenCalled()
+      } else {
+        expect(stdoutWriteSpy).not.toHaveBeenCalled()
+      }
     })
 
     it('should be safe to call multiple times', () => {

package/core/agentic/orchestrator-executor.ts

@@ -13,16 +13,29 @@
  * @version 1.0.0
  */
 
+import { exec as execCallback } from 'node:child_process'
 import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
+import { promisify } from 'node:util'
+import { findRelevantFiles } from '../context-tools/files-tool'
+import { getRecentFiles } from '../context-tools/recent-tool'
+import { extractSignatures } from '../context-tools/signatures-tool'
 import configManager from '../infrastructure/config-manager'
 import pathManager from '../infrastructure/path-manager'
 import { stateStorage } from '../storage'
-import type { LoadedAgent, LoadedSkill, OrchestratorContext, OrchestratorSubtask } from '../types'
+import type {
+  LoadedAgent,
+  LoadedSkill,
+  OrchestratorContext,
+  OrchestratorSubtask,
+  RealCodebaseContext,
+} from '../types'
 import { isNotFoundError } from '../types/fs'
 import { parseFrontmatter } from './template-loader'
 
+const execAsync = promisify(execCallback)
+
 // =============================================================================
 // Domain Detection Keywords
 // =============================================================================
@@ -201,10 +214,13 @@ export class OrchestratorExecutor {
     // Step 5: Load skills from agent frontmatter
     const skills = await this.loadSkills(agents)
 
-    // Step 6: Determine if fragmentation is needed
+    // Step 6: Gather real codebase context proactively
+    const realContext = await this.gatherRealContext(taskDescription, projectPath)
+
+    // Step 7: Determine if fragmentation is needed
     const requiresFragmentation = this.shouldFragment(domains, taskDescription)
 
-    // Step 7: Create subtasks if fragmentation is required
+    // Step 8: Create subtasks if fragmentation is required
     let subtasks: OrchestratorSubtask[] | null = null
     if (requiresFragmentation && command === 'task') {
       subtasks = await this.createSubtasks(taskDescription, domains, agents, projectId)
@@ -222,6 +238,100 @@ export class OrchestratorExecutor {
         ecosystem: repoAnalysis?.ecosystem || 'unknown',
         conventions: repoAnalysis?.conventions || [],
       },
+      realContext,
+    }
+  }
+
+  /**
+   * Gather real codebase context proactively.
+   *
+   * Calls existing context tools (files-tool, recent-tool, signatures-tool)
+   * to build a briefing so the agent doesn't need to explore first.
+   */
+  private async gatherRealContext(
+    taskDescription: string,
+    projectPath: string
+  ): Promise<RealCodebaseContext | undefined> {
+    try {
+      // Run git state + relevant files + recent files in parallel
+      const [gitResult, filesResult, recentResult] = await Promise.all([
+        this.getGitState(projectPath),
+        findRelevantFiles(taskDescription, projectPath, { maxFiles: 10, minScore: 0.15 }),
+        getRecentFiles(projectPath, { commits: 10, maxFiles: 10 }),
+      ])
+
+      // Extract signatures from top 3 relevant files
+      const topFiles = filesResult.files.slice(0, 3)
+      const signatureResults = await Promise.all(
+        topFiles.map(async (f) => {
+          try {
+            const result = await extractSignatures(f.path, projectPath)
+            if (result.signatures.length === 0) return null
+            const sigContent = result.signatures
+              .map((s) => `${s.exported ? 'export ' : ''}${s.type} ${s.name}: ${s.signature}`)
+              .join('\n')
+            return { path: f.path, content: sigContent }
+          } catch {
+            return null
+          }
+        })
+      )
+
+      return {
+        gitBranch: gitResult.branch,
+        gitStatus: gitResult.status,
+        relevantFiles: filesResult.files.map((f) => ({
+          path: f.path,
+          score: Math.round(f.score * 100),
+          reason: f.reasons.join(', '),
+        })),
+        recentFiles: recentResult.hotFiles.slice(0, 5).map((f) => ({
+          path: f.path,
+          lastChanged: f.lastChanged,
+          changes: f.changes,
+        })),
+        signatures: signatureResults.filter(
+          (s): s is { path: string; content: string } => s !== null
+        ),
+      }
+    } catch {
+      // Non-critical — return undefined if context gathering fails
+      return undefined
+    }
+  }
+
+  /**
+   * Get current git state (branch + short status)
+   */
+  private async getGitState(projectPath: string): Promise<{ branch: string; status: string }> {
+    try {
+      const [branchResult, statusResult] = await Promise.all([
+        execAsync('git branch --show-current', { cwd: projectPath }),
+        execAsync('git status --porcelain', { cwd: projectPath }),
+      ])
+
+      const branch = branchResult.stdout.trim() || 'main'
+      const lines = statusResult.stdout.trim().split('\n').filter(Boolean)
+
+      let modified = 0
+      let untracked = 0
+      let staged = 0
+      for (const line of lines) {
+        const code = line.substring(0, 2)
+        if (code.startsWith('??')) untracked++
+        else if (code[0] !== ' ' && code[0] !== '?') staged++
+        else modified++
+      }
+
+      const parts: string[] = []
+      if (staged > 0) parts.push(`${staged} staged`)
+      if (modified > 0) parts.push(`${modified} modified`)
+      if (untracked > 0) parts.push(`${untracked} untracked`)
+      const status = parts.length > 0 ? parts.join(', ') : 'clean'
+
+      return { branch, status }
+    } catch {
+      return { branch: 'unknown', status: 'git unavailable' }
     }
   }
 
@@ -365,6 +475,8 @@ export class OrchestratorExecutor {
             content: body,
             skills: frontmatter.skills || [],
             filePath,
+            effort: frontmatter.effort as LoadedAgent['effort'],
+            model: frontmatter.model as string | undefined,
           }
         } catch {
           // Try next variation
@@ -409,16 +521,18 @@ export class OrchestratorExecutor {
   async loadSkills(agents: LoadedAgent[]): Promise<LoadedSkill[]> {
     const skillsDir = path.join(os.homedir(), '.claude', 'skills')
 
-    // Collect unique skill names from all agents
-    const uniqueSkillNames = new Set<string>()
+    // Collect unique skill names from all agents, tracking which agents need them
+    const skillToAgents = new Map<string, string[]>()
     for (const agent of agents) {
       for (const skillName of agent.skills) {
-        uniqueSkillNames.add(skillName)
+        const existing = skillToAgents.get(skillName) || []
+        existing.push(agent.name)
+        skillToAgents.set(skillName, existing)
       }
     }
 
     // Load all skills in parallel
-    const skillPromises = Array.from(uniqueSkillNames).map(
+    const skillPromises = Array.from(skillToAgents.keys()).map(
       async (skillName): Promise<LoadedSkill | null> => {
         // Check both patterns: flat file and subdirectory (ecosystem standard)
         const flatPath = path.join(skillsDir, `${skillName}.md`)
@@ -434,7 +548,11 @@ export class OrchestratorExecutor {
             const content = await fs.readFile(flatPath, 'utf-8')
             return { name: skillName, content, filePath: flatPath }
           } catch {
-            // Skill not found - not an error, just skip
+            // Skill not found — log warning with agent context
+            const agentNames = skillToAgents.get(skillName) || []
+            console.warn(
+              `⚠ Skill "${skillName}" not installed (needed by: ${agentNames.join(', ')}). Run \`prjct sync\` to auto-install.`
+            )
             return null
           }
         }

package/core/agentic/prompt-builder.ts

@@ -459,6 +459,8 @@ class PromptBuilder {
         parts.push('### LOADED AGENTS (Project-Specific Specialists)\n\n')
         for (const agent of orchestratorContext.agents) {
           parts.push(`#### Agent: ${agent.name} (${agent.domain})\n`)
+          if (agent.effort) parts.push(`Effort: ${agent.effort}\n`)
+          if (agent.model) parts.push(`Model: ${agent.model}\n`)
           if (agent.skills.length > 0) {
             parts.push(`Skills: ${agent.skills.join(', ')}\n`)
           }
@@ -476,15 +478,50 @@ class PromptBuilder {
         parts.push('### LOADED SKILLS (From Agent Frontmatter)\n\n')
         for (const skill of orchestratorContext.skills) {
           parts.push(`#### Skill: ${skill.name}\n`)
-          // Include first 1000 chars of skill content
+          // Include first 2000 chars of skill content
           const truncatedContent =
-            skill.content.length > 1000
-              ? `${skill.content.substring(0, 1000)}\n... (truncated)`
+            skill.content.length > 2000
+              ? `${skill.content.substring(0, 2000)}\n... (truncated)`
               : skill.content
           parts.push(`\`\`\`markdown\n${truncatedContent}\n\`\`\`\n\n`)
         }
       }
 
+      // Inject real codebase context (proactively gathered)
+      if (orchestratorContext.realContext) {
+        const rc = orchestratorContext.realContext
+        parts.push('### CODEBASE CONTEXT (Real — gathered proactively)\n\n')
+
+        parts.push(`**Git State**: Branch \`${rc.gitBranch}\` | ${rc.gitStatus}\n\n`)
+
+        if (rc.relevantFiles.length > 0) {
+          parts.push('**Relevant Files** (scored by task relevance):\n')
+          parts.push('| Score | File | Why |\n')
+          parts.push('|-------|------|-----|\n')
+          for (const f of rc.relevantFiles.slice(0, 8)) {
+            parts.push(`| ${f.score} | ${f.path} | ${f.reason} |\n`)
+          }
+          parts.push('\n')
+        }
+
+        if (rc.signatures.length > 0) {
+          parts.push('**Code Signatures** (top files):\n')
+          for (const sig of rc.signatures) {
+            parts.push(`\`\`\`typescript\n// ${sig.path}\n${sig.content}\n\`\`\`\n`)
+          }
+          parts.push('\n')
+        }
+
+        if (rc.recentFiles.length > 0) {
+          parts.push('**Recently Changed**: ')
+          const recentSummary = rc.recentFiles
+            .slice(0, 5)
+            .map((f) => `${f.path} (${f.lastChanged})`)
+            .join(', ')
+          parts.push(`${recentSummary}\n\n`)
+        }
+      }
+
       // Inject subtasks if fragmented
       if (orchestratorContext.requiresFragmentation && orchestratorContext.subtasks) {
         parts.push('### SUBTASKS (Execute in Order)\n\n')

package/core/ai-tools/registry.ts

@@ -36,7 +36,7 @@ export const AI_TOOLS: Record<string, AIToolConfig> = {
     name: 'Claude Code',
     outputFile: 'CLAUDE.md',
     outputPath: 'global',
-    maxTokens: 3000,
+    maxTokens: 6000,
     format: 'detailed',
     description: 'Anthropic Claude Code CLI',
   },

package/core/commands/analysis.ts

@@ -516,6 +516,11 @@ export class AnalysisCommands extends PrjctCommandsBase {
       const skillWord = result.skills.length === 1 ? 'skill' : 'skills'
       generatedItems.push(`${result.skills.length} ${skillWord}`)
     }
+    const installed = result.skillsInstalled?.filter((s) => s.status === 'installed') || []
+    if (installed.length > 0) {
+      const word = installed.length === 1 ? 'skill' : 'skills'
+      generatedItems.push(`${installed.length} ${word} auto-installed`)
+    }
 
     out.section('Generated')
     out.list(generatedItems, { bullet: '✓' })

package/core/context-tools/token-counter.ts

@@ -40,6 +40,7 @@ const MODEL_PRICING = {
   'claude-sonnet-4.5': { input: 0.003, output: 0.015 }, // $3/$15 per M
   'claude-haiku-4.5': { input: 0.001, output: 0.005 }, // $1/$5 per M
   'claude-opus-4': { input: 0.015, output: 0.075 }, // $15/$75 per M (legacy)
+  'claude-opus-4-6': { input: 0.015, output: 0.075 }, // $15/$75 per M
   // OpenAI
   'gpt-4o': { input: 0.0025, output: 0.01 }, // $2.50/$10 per M
   'gpt-4-turbo': { input: 0.01, output: 0.03 }, // $10/$30 per M
@@ -78,6 +79,7 @@ export function countTokens(text: string): number {
 const BREAKDOWN_MODELS: ModelName[] = [
   'claude-sonnet-4.5',
   'claude-opus-4.5',
+  'claude-opus-4-6',
   'gpt-4o',
   'gemini-1.5-pro',
 ]

package/core/domain/agent-loader.ts

@@ -25,6 +25,8 @@ interface Agent {
   role: string | null
   domain: string
   skills: string[]
+  effort?: 'low' | 'medium' | 'high' | 'max'
+  model?: string
   modified: Date
   /** Source of this agent: 'file' (generated) or 'hierarchical' (AGENTS.md) */
   source?: 'file' | 'hierarchical'
@@ -69,7 +71,8 @@ class AgentLoader {
       const agentPath = path.join(this.agentsDir, `${agentName}.md`)
       const content = await fs.readFile(agentPath, 'utf-8')
 
-      // Parse agent metadata from content
+      // Parse agent metadata from content (including frontmatter)
+      const { effort, model } = this.extractFrontmatterMeta(content)
       const agent: Agent = {
         name: agentName,
         content,
@@ -77,6 +80,8 @@ class AgentLoader {
         role: this.extractRole(content),
         domain: this.extractDomain(content),
         skills: this.extractSkills(content),
+        effort,
+        model,
         modified: (await fs.stat(agentPath)).mtime,
       }
 
@@ -203,6 +208,35 @@ class AgentLoader {
     return skills
   }
 
+  /**
+   * Extract effort and model from YAML frontmatter
+   */
+  private extractFrontmatterMeta(content: string): {
+    effort?: 'low' | 'medium' | 'high' | 'max'
+    model?: string
+  } {
+    const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/)
+    if (!frontmatterMatch) return {}
+
+    const fm = frontmatterMatch[1]
+    const result: { effort?: 'low' | 'medium' | 'high' | 'max'; model?: string } = {}
+
+    const effortMatch = fm.match(/^effort:\s*(.+)$/m)
+    if (effortMatch) {
+      const val = effortMatch[1].trim().replace(/['"]/g, '') as 'low' | 'medium' | 'high' | 'max'
+      if (['low', 'medium', 'high', 'max'].includes(val)) {
+        result.effort = val
+      }
+    }
+
+    const modelMatch = fm.match(/^model:\s*(.+)$/m)
+    if (modelMatch) {
+      result.model = modelMatch[1].trim().replace(/['"]/g, '')
+    }
+
+    return result
+  }
+
   /**
    * Get agents directory path
    */

package/core/services/context-selector.ts

@@ -29,11 +29,14 @@ export interface SelectedContext {
   }
 }
 
+/** Default token budget for context selection (increased for 200K+ context models) */
+const DEFAULT_TOKEN_BUDGET = 80_000
+
 export interface ContextSelectionOptions {
   maxFiles?: number // Max files to return (default: 50)
   minScore?: number // Min relevance score (default: 30)
   includeGeneral?: boolean // Include 'general' domain files (default: true)
-  tokenBudget?: number // Max estimated tokens (default: 50000)
+  tokenBudget?: number // Max estimated tokens (default: 80000)
 }
 
 // ============================================================================
@@ -173,7 +176,7 @@ export class ContextSelector {
     const maxFiles = options.maxFiles || 50
     const minScore = options.minScore || 30
     const includeGeneral = options.includeGeneral !== false
-    const tokenBudget = options.tokenBudget || 50000
+    const tokenBudget = options.tokenBudget || DEFAULT_TOKEN_BUDGET
 
     // Load index and categories
     const [index, domainsData, categoriesCache] = await Promise.all([
@@ -351,7 +354,7 @@ export class ContextSelector {
   ): SelectedContext {
     const maxFiles = options.maxFiles || 50
     const minScore = options.minScore || 30
-    const tokenBudget = options.tokenBudget || 50000
+    const tokenBudget = options.tokenBudget || DEFAULT_TOKEN_BUDGET
 
     // Filter and sort by score
     const filteredFiles = files.filter((f) => f.score >= minScore).sort((a, b) => b.score - a.score)

package/core/services/hierarchical-agent-resolver.ts

@@ -36,6 +36,8 @@ export interface HierarchicalAgent {
   sources: string[]
   /** Whether this agent was overridden at some level */
   wasOverridden: boolean
+  /** Effort level hint for Claude's adaptive reasoning depth */
+  effort?: 'low' | 'medium' | 'high' | 'max'
 }
 
 export interface AgentResolutionResult {

package/core/services/sync-service.ts

@@ -17,6 +17,7 @@
 
 import { exec } from 'node:child_process'
 import fs from 'node:fs/promises'
+import os from 'node:os'
 import path from 'node:path'
 import { promisify } from 'node:util'
 import {
@@ -26,15 +27,18 @@ import {
   type ProjectContext,
   resolveToolIds,
 } from '../ai-tools'
+import { getErrorMessage } from '../errors'
 import commandInstaller from '../infrastructure/command-installer'
 import configManager from '../infrastructure/config-manager'
 import pathManager from '../infrastructure/path-manager'
 import { metricsStorage } from '../storage/metrics-storage'
 import { type ContextSources, defaultSources, type SourceInfo } from '../utils/citations'
 import dateHelper from '../utils/date-helper'
+import log from '../utils/logger'
 import { ContextFileGenerator } from './context-generator'
 import type { SyncDiff } from './diff-generator'
 import { localStateGenerator } from './local-state-generator'
+import { skillInstaller } from './skill-installer'
 import { type StackDetection, StackDetector } from './stack-detector'
 import { syncVerifier, type VerificationReport } from './sync-verifier'
 
@@ -105,6 +109,7 @@ interface SyncResult {
   stack: StackDetection
   agents: AgentInfo[]
   skills: { agent: string; skill: string }[]
+  skillsInstalled: { name: string; agent: string; status: 'installed' | 'skipped' | 'error' }[]
   contextFiles: string[]
   aiTools: AIToolResult[]
   syncMetrics?: SyncMetrics
@@ -176,6 +181,7 @@ class SyncService {
           stack: this.emptyStack(),
           agents: [],
           skills: [],
+          skillsInstalled: [],
           contextFiles: [],
           aiTools: [],
           error: 'No prjct project. Run p. init first.',
@@ -203,6 +209,7 @@ class SyncService {
       // 4. Generate all files (depends on gathered data)
       const agents = await this.generateAgents(stack, stats)
       const skills = this.configureSkills(agents)
+      const skillsInstalled = await this.autoInstallSkills(agents)
       const sources = this.buildSources(stats, commands)
       const contextFiles = await this.generateContextFiles(git, stats, commands, agents, sources)
 
@@ -274,6 +281,7 @@ class SyncService {
         stack,
         agents,
         skills,
+        skillsInstalled,
         contextFiles,
         aiTools: aiToolResults.map((r) => ({
           toolId: r.toolId,
@@ -294,6 +302,7 @@ class SyncService {
         stack: this.emptyStack(),
         agents: [],
         skills: [],
+        skillsInstalled: [],
         contextFiles: [],
         aiTools: [],
         error: (error as Error).message,
@@ -800,6 +809,109 @@ You are the ${name} expert for this project. Apply best practices for the detect
     return skills
   }
 
+  // ==========================================================================
+  // SKILL AUTO-INSTALLATION
+  // ==========================================================================
+
+  /**
+   * Auto-install skills from skill-mappings.json for generated agents.
+   * Reads the mapping, checks which packages are needed, and installs missing ones.
+   */
+  private async autoInstallSkills(
+    agents: AgentInfo[]
+  ): Promise<{ name: string; agent: string; status: 'installed' | 'skipped' | 'error' }[]> {
+    const results: { name: string; agent: string; status: 'installed' | 'skipped' | 'error' }[] = []
+
+    try {
+      // Load skill mappings
+      const mappingsPath = path.join(
+        __dirname,
+        '..',
+        '..',
+        'templates',
+        'config',
+        'skill-mappings.json'
+      )
+      const mappingsContent = await fs.readFile(mappingsPath, 'utf-8')
+      const mappings = JSON.parse(mappingsContent)
+      const agentToSkillMap = mappings.agentToSkillMap || {}
+
+      // Collect all packages to install, grouped by agent
+      const packagesToInstall: { pkg: string; agent: string }[] = []
+      for (const agent of agents) {
+        const mapping = agentToSkillMap[agent.name]
+        if (mapping?.packages) {
+          for (const pkg of mapping.packages) {
+            packagesToInstall.push({ pkg, agent: agent.name })
+          }
+        }
+      }
+
+      if (packagesToInstall.length === 0) return results
+
+      // Install each package (check if already installed first)
+      const skillsDir = path.join(os.homedir(), '.claude', 'skills')
+      for (const { pkg, agent } of packagesToInstall) {
+        // Extract skill name from package path (e.g., "anthropics/skills/frontend-design" -> "frontend-design")
+        const skillName = pkg.split('/').pop() || pkg
+
+        // Check if already installed
+        const subdirPath = path.join(skillsDir, skillName, 'SKILL.md')
+        const flatPath = path.join(skillsDir, `${skillName}.md`)
+
+        let alreadyInstalled = false
+        try {
+          await fs.access(subdirPath)
+          alreadyInstalled = true
+        } catch {
+          try {
+            await fs.access(flatPath)
+            alreadyInstalled = true
+          } catch {
+            // Not installed
+          }
+        }
+
+        if (alreadyInstalled) {
+          results.push({ name: skillName, agent, status: 'skipped' })
+          continue
+        }
+
+        // Install via skillInstaller (supports owner/repo format)
+        try {
+          // Parse package as owner/repo or owner/repo@skill format
+          // "anthropics/skills/frontend-design" -> owner=anthropics, repo=skills, skill=frontend-design
+          const parts = pkg.split('/')
+          let installSource: string
+          if (parts.length === 3) {
+            // owner/repo/skill -> owner/repo@skill
+            installSource = `${parts[0]}/${parts[1]}@${parts[2]}`
+          } else {
+            installSource = pkg
+          }
+
+          const installResult = await skillInstaller.install(installSource)
+          if (installResult.installed.length > 0) {
+            results.push({ name: skillName, agent, status: 'installed' })
+            log.info(`Installed skill: ${skillName} for agent: ${agent}`)
+          } else if (installResult.errors.length > 0) {
+            results.push({ name: skillName, agent, status: 'error' })
+            log.debug(`Failed to install skill ${skillName}`, { errors: installResult.errors })
+          } else {
+            results.push({ name: skillName, agent, status: 'skipped' })
+          }
+        } catch (error) {
+          results.push({ name: skillName, agent, status: 'error' })
+          log.debug(`Skill install error for ${skillName}`, { error: getErrorMessage(error) })
+        }
+      }
+    } catch (error) {
+      log.debug('Skill auto-installation failed (non-critical)', { error: getErrorMessage(error) })
+    }
+
+    return results
+  }
+
   // ==========================================================================
   // CONTEXT FILE GENERATION
   // ==========================================================================