AI Context Kit
Author: Marco Siccardi (MSiccDev Software Development)
Purpose: An AGENTS-first, skills-first framework for maintaining consistent, context-aware AI collaboration across different LLM providers, projects, and development phases.
Overview
This repository provides a comprehensive AGENTS-first context and workflow system designed to enable consistent, context-aware AI collaboration across multiple projects and platforms.
Primary Agent Entrypoint
- Root
AGENTS.md is the primary operational entrypoint for agents in this repository.
specs/context_aware_ai_session_spec.md is the normative source of truth for the full session model.docs/spec-rationale.md is the companion document with background reasoning, extended examples, and future enhancement notes.
The Evolution
What began as a way to extract and reuse prompts across AI providers has evolved into a sophisticated architecture for AI collaboration:
- Layered architecture – Personal user context + project
AGENTS.md context create complete AI workspace configurations
- Skill-based workflows – Create and validate context files using reusable skills with detailed operational logic
- Provider-agnostic – Works seamlessly across different LLM environments
The System
This framework consists of:
- Personal user context artifacts – Your professional identity, skills, preferences, and working style
- Project-specific
AGENTS.md context – Scope, tech stack, roles, objectives, and operational guidance per project
- Skill workflows in
skills/ – Canonical create/validate/governance operational logic
- Session specification – How AI assistants should maintain and adapt context during work sessions
- Templates in
templates/ – Canonical artifact structures aligned to the spec
All components are designed to work across hosted and local LLM environments, ensuring that every AI assistant understands your background, working style, and project context without repeated explanations. Results may vary by platform, so you may need to adjust your context files accordingly.
See It In Action
The same question, with and without AI Context Kit loaded:
Without AI Context Kit:
User: "Help me add authentication to the app."
AI: "Sure! What framework are you using? What kind of auth — OAuth, JWT, sessions? What's your backend stack?..."
The AI starts from scratch every session.
With AI Context Kit loaded:
User: "Help me add authentication to the app."
AI: "Given your SwiftUI codebase and the TCA architecture you're migrating to, I'd model this as a new AuthenticationFeature reducer rather than adding it to an existing one. Want me to scaffold the reducer and effect first, or start with the SwiftUI view bindings?"
The AI already knows your stack, your existing patterns, and your preferences.
The difference is not magic — it is reduced friction. The AI spends zero turns asking who you are, what you are building, or how you like to work. That adds up significantly across a full development session.
Repository Structure
ai-context-kit/
│
├── AGENTS.md # Primary agent entrypoint for this repository
├── README.md # This file
├── LICENSE # MIT License file
│
├── prompts/ # Composition prompt wrappers
│ ├── create-usercontext-instructions.prompt.md # Generate user context instruction files
│ ├── create-project-instructions.prompt.md # Generate project-context AGENTS.md files
│ ├── create-agents-md.prompt.md # Generate AGENTS.md files
│ ├── create-skill.prompt.md # Generate skill files
│ ├── validate-usercontext-instructions.prompt.md # Validate user context files
│ ├── validate-project-instructions.prompt.md # Validate project-context AGENTS.md files
│ ├── validate-agents-md.prompt.md # Validate AGENTS.md files
│ └── validate-skill.prompt.md # Validate skill files
│
├── specs/
│ └── context_aware_ai_session_spec.md # Specification for AI session management
│
├── templates/
│ ├── usercontext_template.instructions.md # Canonical v1.4.2 user context template (authoritative)
│ ├── AGENTS_template.md # Canonical AGENTS template (authoritative)
│ └── skill_template/SKILL.md # Canonical skill template
│
└── skills/
└── README.md # Canonical location for skill instances
Core Concepts
The AGENTS + Skills Distinction
AGENTS.md files define persistent operational context:
- WHO is collaborating (user/project context)
- WHAT the project scope and constraints are
- HOW collaboration should run (roles, phases, tone, interaction mode)
