Context Detection

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/context/detector.ts
• packages/core/src/context/manager.ts
• packages/core/src/context/types.ts
• packages/core/src/context/tests/detector.test.ts
• packages/core/src/context/tests/manager.test.ts
• packages/cli/src/commands/context.ts

Context Detection is a core system within SkillKit responsible for automatically identifying the technology stack, project patterns, and development environment of a repository. By analyzing configuration files and directory structures, the system creates a comprehensive ProjectContext that allows SkillKit to synchronize skills across various AI coding agents and provide relevant skill recommendations.

The system operates by scanning for "indicators" such as package.json, tsconfig.json, pyproject.toml, or Cargo.toml. This automated analysis ensures that AI agents have the necessary domain knowledge and specialized capabilities tailored to the specific environment they are operating in.

Sources: packages/core/src/context/types.ts, packages/cli/src/commands/context.ts:16-25

Architecture and Components

The Context Detection system is built around three primary components: the ProjectDetector for analysis, the ContextManager for persistence, and the CLI interface for user interaction.

System Overview Diagram

This diagram illustrates the flow of data from the raw project files through the detection logic to the persisted context file.

Key Classes and Structures

Component	Description
ProjectDetector	Core logic for scanning the filesystem and identifying languages, frameworks, and tools.
ContextManager	Handles loading, saving, importing, and exporting the ProjectContext object.
ProjectContext	The canonical data structure representing the project's state, versioned for compatibility.
ProjectStack	A subset of context containing categorized Detection results (Languages, Frameworks, etc.).

Sources: packages/core/src/context/types.ts:40-95, packages/core/src/context/manager.ts:15-30

Detection Logic

The ProjectDetector performs a multi-phase analysis of the project directory to build a complete profile.

Stack Analysis

The detector identifies technologies by checking for specific configuration files and analyzing dependency manifests.

• Language Detection: Scans for tsconfig.json (TypeScript), pyproject.toml (Python), Cargo.toml (Rust), or go.mod (Go).
• Framework Detection: Inspects package.json dependencies for entries like react, next, vue, or express.
• Tooling Detection: Identifies development tools like eslint, prettier, or vitest.

Sources: packages/core/src/context/tests/detector.test.ts:15-150

Project Type Inference

The system uses PROJECT_TYPE_HINTS to categorize the repository into types such as web-app, api, cli, or library. For example, if react or nextjs is detected, the project is hinted as a web-app.

Sources: packages/core/src/context/types.ts:108-115

Data Structure: ProjectContext

The ProjectContext is a Zod-validated object that acts as the source of truth for the project's environment.

export const ProjectContext = z.object({
  version: z.literal(1),
  project: z.object({
    name: z.string(),
    description: z.string().optional(),
    type: z.string().optional(),
    path: z.string().optional(),
  }),
  stack: ProjectStack,
  patterns: ProjectPatterns.optional(),
  skills: SkillPreferences.optional(),
  agents: AgentConfig.optional(),
});

Sources: packages/core/src/context/types.ts:80-95

Context Management

The ContextManager facilitates the lifecycle of the context data, primarily through the .skillkit/context.yaml file.

Management Workflow Sequence

The following sequence shows how the CLI interacts with the manager to initialize a project.

Persistence Details

• File Location: Context is stored in .skillkit/context.yaml.
• Formats: Supports exporting and importing in both YAML and JSON formats.
• Merging: Allows importing external context files with a merge strategy to combine detected stack items with manually defined ones.

Sources: packages/core/src/context/types.ts:98-100, packages/core/src/context/manager.ts:160-200

CLI Interaction

The context command in the SkillKit CLI provides the primary interface for managing detection.

Subcommand	Description
init	Runs the ProjectDetector and creates the initial context file.
show	Displays the current detected stack and project metadata.
sync	Synchronizes the detected context and skills to all configured AI agents.
detect	Runs a "dry-run" analysis and prints recommended skill tags.

Sources: packages/cli/src/commands/context.ts:35-50

Example: Detection Output

When running skillkit context detect, the system outputs categorized findings:

Languages:
  • typescript (5.0.0)
Frameworks:
  • react (18.2.0)
  • nextjs (14.0.0)
Recommended skill tags:
  typescript, react, nextjs, tailwind

Sources: packages/cli/src/commands/context.ts:250-300

Conclusion

Context Detection provides the foundational intelligence for SkillKit, transforming a raw codebase into a structured set of technical metadata. By automating the identification of languages, frameworks, and tools, it enables seamless skill synchronization across agents, ensuring that the AI has the specific context required to be productive in any given environment.