AI Context Kit, Evolved: Why I Moved to AGENTS.md + Agent Skills (and how I used the Codex macOS App for the Migration)

When I released the first version of AI Context Kit in early January, I already had a solid foundation: specification, templates, and reusable prompt workflows.

But once the project was “in the wild”, I started to learn more about two standards that are quickly becoming essential for durable AI collaboration:

• AGENTS.md as the operational entrypoint
• Agent Skills as the canonical workflow layer

This post is about that transition, why I made it, and how I executed it test-driving the new Codex macOS App as a real-world test.

What I learned after v1.2

The first release solved a real pain point: context drift across tools and projects. But it also revealed some architectural weaknesses that I needed to address to support my long-term vision of provider-agnostic AI collaboration.

1. AGENTS.md is already the de facto standard for project operation

My first approach to use project-instructions files as the operational entrypoint worked and is still valid. However, I quickly realized that AGENTS.md is already widely adopted as the standard for defining project-level operational rules and information. So I decided to align with that standard to make it easier for users to adopt AI Context Kit without needing to learn a custom structure.

2. Skills should own the workflow logic, not prompt files

In v1.2, prompts still carried too much execution logic. It worked great over all, but the prompts where really big and contained a lot of logic combined, which made them less reusable and more prone to drift. By moving the workflow logic into dedicated Skill definitions, I can make the prompts much thinner and more focused on just being composition wrappers that defer to the Skill for the actual logic. This also makes it easier to evolve the workflow logic without needing to rewrite those big prompt files.

The current structure of AI Context Kit is now much more modular and aligned with these standards, which should make it easier to maintain and evolve over time.

Using Codex for macOS

Around the same time I learned about these standards, OpenAI released the Codex macOS App, which is designed to help developers execute code changes with AI assistance. I thought this would be a perfect opportunity to test-drive the app in a real-world scenario by using it to execute the migration of AI Context Kit to the new architecture.

The process was intentionally strict:

1. Plan the transition in explicit phases.
2. Execute changes step by step.
3. Keep human review gates between meaningful changes.
4. Validate after each major refactor.
5. Run multiple cleanup passes before release readiness.

This gave me two outcomes at once:

• The repository was successfully migrated to the new architecture, with clear separation of concerns and alignment with standards.
• I got a practical test of Codex in a real documentation-governance migration, not just a toy coding task.

My key takeaway: most workflows work best when AI is used as a disciplined execution partner, while architectural decisions and approval gates stay human-led. I found that Codex was great at executing well-defined tasks, but it still required careful chunking, prompting, and review to ensure the changes aligned with my vision and standards.

What the repository looks like now

After the migration, AI Context Kit is now centered around the two standards:

AGENTS.md standard (project operation layer)

• Root AGENTS.md is the primary operational entrypoint.
• It defines precedence rules, session-state behavior, command namespace policy, and drift-control responsibilities.
• Project context moved away from legacy project-instructions artifacts into AGENTS-first guidance.

Agent Skills standard (workflow authority layer)

• skills/ is now the canonical home for create/validate/governance workflows.
• Skill-local references/ hold detailed checklists and rubric logic.
• Composition wrappers in prompts/ are intentionally slim and defer to skills.

Supporting layers

• Spec remains authoritative: specs/context_aware_ai_session_spec.md (v1.3.1).
• Templates remain canonical structures in templates/.
• User context examples and validation artifacts remain in usercontexts/.
• Path stability and update rules are explicit to reduce future drift.

In short: the structure is now clearer, more auditable, and easier to evolve without re-inflating prompts.

Why this matters for provider-agnostic workflows

My goal has never been “tool loyalty.” My goal is durable collaboration patterns that survive tool changes.

This transition helps with exactly that:

• operational rules are explicit and standardized (AGENTS.md)
• workflow logic is reusable and centralized (Skills)
• wrappers stay portable and thin (Prompts)
• updates become easier to reason about (drift-control)

That is a much better fit for both my vision for AI Context Kit and conforms better to the trends towards modular, standards-based AI collaboration.

Conclusion

Getting my AI Context Kit out was just the first step. Even if I had other plans for the next phase, I considered the adoption of these standards to be a necessary evolution to ensure the project’s long-term viability and alignment with the broader ecosystem. I will go through the open issues that I created after releasing v1.2 and update them to reflect the new architecture and standards and remove any that are no longer relevant due to the changes.

AI Context Kit is now less a prompt collection and more a governed collaboration system: explicit contracts, canonical workflows, and predictable behavior across environments. Exactly what I wanted to build from the start, but now with a much clearer path to maintainability and evolution.

If you are building your own AI workflow layer and want it to stay maintainable beyond the first release, AI Context Kit will help you get there faster by providing a tested structure and reusable patterns that are already aligned with the standards that are emerging in the ecosystem.

Until the next post, happy coding, everyone!

---

Title image note: The title image of this post was generated with the help of AI. It visually represents AI Context Kit as structured infrastructure — a stable, secure instruction layer at the center of complex, multi‑model AI workflows.

Disclaimer: This blog post was written with the help of AI. I provided the structure and key points, reviewed the draft, and edited it to fit my style and technical standards.