Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Session Management in SkillKit refers to the structured handling of context, state, and work transitions within AI-driven development workflows. It encompasses the lifecycle of a "Skill" as it is invoked by an agent, the preservation of state through handoff protocols, and the configuration of agent-specific environments to maintain operational context.
The system ensures that when an AI agent transitions between tasks or when a human developer takes over, the relevant technical details, decisions, and "Next Steps" are preserved. This is achieved through a combination of canonical skill representations and standardized handoff documents that prevent information loss during work transfers.
Sources: packages/core/src/skill-translator.ts, packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md:1-12
Work Context and Handoffs
SkillKit utilizes "Handoff Protocols" to manage the transfer of session context between different agents or between agents and humans. The core objective is to allow the recipient to continue work immediately without status ambiguity.
Handoff Structure
A session handoff is formalized via a document that tracks progress across several dimensions:
| Section | Purpose |
|---|---|
| Current Status | Identifies the active phase (Design, Implementation, Testing) and completion percentage. |
| Context | Explains the "What" and "Why" of the current session goals. |
| Technical Details | Lists key files and architectural dependencies involved in the session. |
| Code State | Confirms that the code compiles, tests pass, and defines what is "In Progress." |
| Next Steps | Provides an immediate roadmap for the next agent/developer. |
Sources: packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md:31-90
Handoff Workflow
The following diagram illustrates the lifecycle of a work session transition:
The giver must ensure the working directory is clean and tests pass before the session can be successfully transferred.
Sources: packages/core/src/methodology/packs/collaboration/handoff-protocols/SKILL.md:92-120
Canonical Skill Sessions
The Skill Translator module manages the internal state of a skill as it moves across different AI agent environments. It converts raw SKILL.md files into a CrossAgentSkill format, which serves as the session's data model.
Cross-Agent State Preservation
When a session involves multiple agents (e.g., transitioning from Claude Code to Cursor), SkillKit preserves agent-specific fields to maintain feature parity.
The agentFields property specifically stores session-critical metadata like model versions, hooks, and permissionMode that might only apply to specific agents but must be tracked during translation.
Sources: packages/core/src/skill-translator.ts:54-73, packages/core/src/tests/skill-translator.test.ts:180-195
Session Translation Logic
The translation process ensures that session instructions remain valid for the target agent:
- Parsing: The current skill is parsed into a canonical format.
- Metadata Injection: Optional metadata like
_translated-attimestamps can be added to track session history. - Incompatibility Reporting: The system identifies if features like
hooks(exclusive to Claude Code) are being moved to a session where they cannot execute.
Sources: packages/core/src/skill-translator.ts:186-215, e2e/skill-translator.e2e.test.ts:178-195
Agent Config and Execution
Session management also involves how an agent is "aware" of its available skills within a project. This is controlled by the generateSkillsConfig function, which creates agent-specific configuration files (e.g., CLAUDE.md, .cursorrules).
Config Generation by Agent Type
| Agent | Format | Configuration Purpose |
|---|---|---|
| Claude Code | XML | Defines <available_skills> and <usage> notes for the session. |
| Cursor | MDC | Uses alwaysApply: true to ensure skill context is globally available. |
| Windsurf | Markdown | Lists skills with Invoke commands for on-demand loading. |
| Gemini CLI | JSON | Provides structured skill data for programmatic access. |
Sources: packages/core/src/skill-translator.ts:380-450, packages/core/src/tests/skill-translator.test.ts:255-290
Session Invocation
Skills are typically loaded into a session on-demand to keep the AI's context window clean. The standard invocation command across formats is skillkit read <skill-name>.
Conclusion
Session Management in SkillKit facilitates a seamless flow of information between AI agents and human collaborators. By combining structured handoff protocols with a robust translation engine, the system ensures that project context, technical decisions, and execution instructions remain consistent and actionable throughout the development lifecycle.