V1 API

[ranyitz]

v1.0 Rewrite

Major rewrite shifting from Cursor-specific .mdc rules to an industry-standard instructions system.

Breaking Changes

• Rules replaced by Instructions — .mdc files in rules/ replaced with .md files in instructions/, output inlined into AGENTS.md / CLAUDE.md instead of individual .cursor/rules/ files
• Commands & Assets removed — replaced by Skills
• Windsurf target dropped — replaced with opencode and codex targets
• claude target renamed to claude-code

New Features

• GitHub preset sources — presets can now be loaded directly from GitHub URLs (with sparse checkout for large repos), not just npm packages
• Target presets — each target defines a complete mapping of where instructions, skills, agents, MCP, and hooks get written
• Install cache — skips re-installation when config hasn't changed
• Instruction frontmatter — inline: true/false controls whether content is inlined or linked with progressive disclosure

---

Due to so many changes in functionality, the codebase has been heavily refactored while relaying on the e2e test suite to verify the behavior.

---

To review, start from the new README and go over the migration guide

[eladbej]

Maybe I didn't understand something but shouldn't Skills directory should be .cursor/skills/ instead of the agents parent dict?

[ranyitz]

The industry is moving towards a single .agents/skills directory, this is intentional.

https://x.com/embirico/status/2018415923930206718
agentskills/agentskills#15 (comment)
https://x.com/leerob/status/2018770085956010119

[eladbej]

Our rules are Apply Intelligently which makes them more of skills.
So maybe it worth mentioning this caveat, probably there will be users that won't spot the difference

[ranyitz]

"Apply Intelligently" rules are supported in Skills - https://cursor.com/docs/context/skills#migrating-rules-and-commands-to-skills

The only caveat which should be mentioned (you're right!) is that we won't support Apply to Specific Files rules. The options as I see them:

1. Add specific support for them - not great because it's too cursor specific and won't necessarily withstand the standartization process.
2. Wait for some standard to be added to skills or to some other new concept. In the meanwhile this can be solve via a pattern of explaining the agent to read a certain document in for specific type of files, or in the new API, create an instruction file which is dynamically loaded and add description mentioning to read for a certain type of files (for example, typescript rules relevant to **/*.ts files).

[eladbej]

Thanks for the detailed explanation but actually, I was referring to a different caveat 😖 I wrote it badly.

I'm worried users will mistakenly migrate their Apply Intelligently rules into AGENTS.md.

We need to make sure the distinction is clear: AGENTS.md should technically only replace the Apply Always rules. If it's Apply Intelligently, it belongs in Skills. Otherwise, we risk users cluttering their global context.

[ranyitz]

Oh I see, that's a good point, but to be honest I think having a docs/TESTING.md file which is being mentioned in the AGENTS.md is a very similar concept to Apply Intelligently, even closer in functionality than a skill. Skill is invokable by the user (e.g., /skill) while the intelligently applied rule is not really.
so I think it will be good if I'll mention these 2 options as potential options for migration and let the user choose.

What do you think?

[eladbej]

Sounds good 🤙🏻

[eladbej]

Is there a timeline for this?
Are the breaking changes will delete of current .rules/, .commands/ and .assets/ dir on 'append' installation?

[ranyitz]

@eladbej

Is there a timeline for this?
Are the breaking changes will delete of current .rules/, .commands/ and .assets/ dir on 'append' installation?

No official timeline, but ideally I'd like to merge this in 1-2 weeks in case I get agreement from most users.
We're now on version 0.x, The idea was to create a breaking version 1.0.0 and not to support legacy concepts in the new version, they add a lot of complexity that is no longer needed. For existing packages I would recommend writing a new preset and consume it via GitHub, after all consumers has moved to the new preset the old one can be deleted.

[YoavTarazyWix]

Hey, looks awesome!
moving away from .mdc and commands files really sets AICM as a generic distribution and configuration mechanism for all agents, especially the - loading presets via GITHUB capability.

I have a few questions about the new version

---

Should we really commit AGENTS.md or CLAUDE.md?

The new README says “certain generated files like AGENTS.md and CLAUDE.md should be committed to your repository”. I'd actually push back on that. If we already require devs to run aicm install as an enterprise/team, then committing for example AGENTS.md can introduce a source of different versioning between our repos. This can cause a repo having a stale version which is (for an enterprise at least) more problematic than a specific dev that didn't run aicm install - In general, isn't committing files to the target repos goes against the "single source of truth" that makes AICM so valuable to begin with?

---

A short example showing how a preset repo and a consumer repo should look like?

I think a short end-to-end example would really help - i.e a side-by-side comparison of sorts of a 'live' example of how things look like in the source repo and what needs to be implemented in the target repo/s.

WDYT?

---

Im not sure migration is that straightforward

In the migration section: skills feel like a mix of the old commands and rules. Some rules are more workflow-specific and push the agent into a stricter narrative (which indicate them acting as a SKILL) while others are general guidelines (Which might classify them as a section in AGENTS.md). I think each team should look at their own rules/commands and decide how to classify them - instructions vs skills vs subagents since there’s no single rule for every team.

Its a question though, how much is in the responsibility of your consumers and how much is on ICM - IMO this is a great breakpoint for teams to learn, adapt and overhaul their rules and commands into SKILLS, AGENTS.md & subagents so i wouldn't necessarily change things for them. (AI-RULES repo for example).

---

Where is the AICM block in Agents.md will be located?

I get that we can control inline vs progressive disclosure for instructions but can we choose where the AICM block goes in AGENTS.md, at the top or the bottom? I want to control precedence: when I have my own content in the file (e.g. project-specific instructions above or below the block), I’d like to decide whether the AICM-generated content comes first or last so the agent sees the right priority.

---

[ranyitz]

@YoavTarazyWix thanks for the great review, you have some great points!

Should we really commit AGENTS.md or CLAUDE.md?

Good callout. I was thinking about this in terms of two possible workflows:

1. Commit AGENTS.md / CLAUDE.md

   • Pros: Very straightforward. Teams can edit AGENTS.md directly and keep all instructions in one obvious place.
   • Cons: Even if we run aicm install on every repo setup, committing generated files still means changes in these files can show up in otherwise unrelated PRs.

2. GitIgnore AGENTS.md and generate it locally

   • In this model, AGENTS.md is treated as a generated artifact and ignored by git. The repo instead commits a source file like INSTRUCTIONS.md with the project specific instructions. When aicm install runs, AICM composes AGENTS.md locally by combining third party instructions, and the repo’s own instructions. The file stays up to date, but is never committed.

   • Pros: Cleaner separation of concerns. The repo contains only the intentional, human-authored inputs, while AGENTS.md remains a derived artifact produced by aicm. This keeps commits focused on real code or instruction changes.

   • Cons: Slightly less discoverable workflow for developers. Instead of editing AGENTS.md directly, they need to know to update the source file and regenerate.

I think option (2) aligns better with the mental model of “generated vs source” files, even if it requires a bit more explanation in the README. We could explicitly document this pattern so teams understand where to make changes and why.

A short example showing how a preset repo and a consumer repo should look like?

I agree, I'll add such example right after this is merged and released.

Im not sure migration is that straightforward

You're mainly talking about "apply intelligently" rules right? They can be either skills or progressively discoloured instruction files (see #106 (comment)). I'll make sure to include this in the migration guide.

Where is the AICM block in Agents.md will be located?

Interesting point! Technically speaking the aicm managed content is generated at the end of the file, which I think suite 3rd party content well. After the comments are generated it won't move unless you'll delete it and regenerate, so you can manually control its location.

A point to consider is what to do where there are both 3rd party instructions and local instructions. A good default would be to generate the local one first but we can also introduce a configuration to control this. Since it's quite advanced I think we can definitely open a separate issue to discuss and decide what to do there.

[ranyitz]

Reflections on the design

After some reflection, I have a few important design questions about AICM that I’m still uncertain about, especially given recent changes in the ecosystem.

When AICM was originally created, Claude Code Plugins did not exist. Today, plugins solve much of the same distribution problem by providing a clean mechanism for sharing skills, commands, subagents, hooks, and MCP servers.

However, plugins have two important limitations:

• They do not support managing AGENTS.md or other forms of persistent instruction context.
• They are Claude-specific and do not support multi-target installation such as Cursor, Codex, or OpenCode.

One major advantage of the plugin approach is its simplicity. The plugin itself is installed into a cache directory, while the repository only contains a one-line reference in .claude/settings.json. This sidesteps many of the complexities involved in generating and managing agent configuration files inside the repository.

This raises an important question:

Why don’t plugins allow managing persistent context?

My best explanation is that persistent instructions are intentionally reserved for repository owners. Allowing third-party plugins to “plant” context into every agent interaction would introduce a significant trust and security risk and could easily be abused. This level of control is likely meant to stay with repository maintainers, who are expected to carefully own everything placed in AGENTS.md or CLAUDE.md. The only way to do this is by crafting good descriptions for mcp tools or skill description, which already provides some power to preset/plugin author over the user persistent context.

---

The Problem With Generated Output in AICM Today

In AICM’s current design, running aicm install generates or modifies files such as:

• AGENTS.md
• skills directories
• agent definitions
• MCP configuration
• hooks configuration

Because these files are generated artifacts, the common recommendation is to place them in .gitignore.

This creates a major usability issue:

• Developers must learn a new mental model where the real source of truth lives elsewhere, such as AGENTS.src.md.
• Many tools expect skills and agent content to live directly in well-known locations like .agents/skills, so ignoring these directories feels counterintuitive, for example /create-skill will generate a skill into .cursor/skills.
• It becomes unclear which files are user-authored and which are tool-managed.

---

Two Core Design Questions

1. Should AICM manage AGENTS.md?

Should AICM continue to generate and overwrite persistent instruction files, or should this feature be removed in favor of a simpler interface that more closely matches the Claude Code plugin model?

Removing AGENTS.md support would significantly simplify AICM, but it would also reduce its ability to plant persistent context on consumers' projects, i'm on the fence here, but leaning towards not allowing 3rd parties to control project context in such way.

2. Should installed artifacts be committed or ignored?

Even without AGENTS.md, AICM still needs to install skills, subagents, hooks, and MCP configuration.

This forces a difficult tradeoff:

• Committing generated output requires developers to update and commit agent-related files in unrelated pull requests, which is noisy and frustrating.
• Ignoring generated output means critical functionality depends on remembering to run aicm install, and failures can be silent. This includes remote agents that must run this installation step to have the relevant context at hand.

For skills, namespacing provides a reasonable solution for .gitignore:

• .agents/skills/aicm/...

For subagents, there is no nesting support, which forces patterns such as:

• .cursor/agents/aicm_*

This approach still does not cleanly solve MCP or hooks configuration, which require specific top-level configuration files.

---

Possible Direction: Lockfile-Based Management

One potential solution is introducing a lockfile.

AICM could generate an aicm.lock file that captures:

• resolved preset versions
• npm dependency versions
• GitHub references

Updates would happen explicitly through a command such as:

aicm update

However, it is important to clarify that the lockfile idea is not meant to replace committing generated configuration files.
It is meant to complement them.

The goal is that tools should continue to work out of the box without requiring developers to run aicm install manually. The repository should still contain the necessary agent-facing files so that skills, hooks, and MCP servers function immediately.

In that model, AICM becomes less of a required runtime step and more of an update and distribution mechanism:

• Repositories remain functional without any extra setup
• AICM provides a controlled way to receive newer configuration from presets
• Updates happen explicitly, similar to dependency upgrades

The open question is whether this approach still makes sense given the added complexity, or whether it effectively recreates a package-manager-like workflow for agent configuration.

---

Industry Convergence Toward Plugins

It also seems worth explicitly calling out that the industry will likely converge on Claude Code Plugins like API as a long-term, first-class mechanism for distributing agent capabilities.

Claude Code Plugins already demonstrate a cleaner distribution model, and this mirrors earlier ecosystem shifts:

• MCP becoming a standard
• Skills starting in Claude and becoming a wide adopted standard
• AGENTS.md as an open convention for persistent context

If plugins become standardized across agents and tooling ecosystems, then much of what AICM is solving today may represent a temporary gap rather than a permanent problem.

Viewed through this lens, the solutions we discussed here are most likely a temporary workaround, which is something we should consider choosing our strategy going forward.

[eladbej]

@ranyitz
Big questions.
Thanks for the honest and mature reflection. This is exactly the kind of strategic thinking that makes AICM valuable beyond just a package.

Here's where I land on those questions:

• AICM should continue managing AGENTS.md - for now. I agree the industry is converging toward a plugin-compatible model (Claude Code Plugins being the most mature example), but we're not there yet. Most IDEs don't have a first-class plugin distribution mechanism, and until they do, AICM fills a real gap. Dropping AGENTS.md support prematurely would leave teams without a cross-target way to distribute persistent context. I'd rather keep it and deprecate it gracefully once plugin APIs become widely adopted.
• Separation of concerns is crucial for prod envs. Generated agent config files (AGENTS.md, skills, MCP configs) should be .gitignored. Committing them creates noise in PRs, version drift, and blurs the line between human-authored and tool-managed content. The source of truth should be the preset definitions and aicm.json, not the generated output. The PR is important guardrail IMO.

For the workflow around updates, I think two complementary skills would be valuable:

1. A "push correction" skill - A skill that uses the GitHub MCP to let developers propose fixes and improvements back to the preset source repo. If someone spots a stale or incorrect rule while working, they can use the skill to open a PR upstream without leaving their IDE. This creates a feedback loop that keeps presets accurate over time.
2. An "update AICM" skill/hook - A skill or hook that updates the AICM package and re-installs the latest preset configuration in the current project. This keeps the local agent config fresh without requiring developers to manually track versions or remember to run install steps.

To summarize my take: AICM's role as a bridge is still needed until the plugin ecosystem matures across all targets. The generated files should be ephemeral (.gitignored), and the update/contribution flow should be handled through skills that integrate naturally into the developer's IDE workflow.

[ranyitz]

@eladbej thanks for the response.

AICM should continue managing AGENTS.md

The question we should ask is whether we want to allow teams to inject persistent context, the answer to that is not trivial to me, because it both adds inherent complexity and because it essentially encourages context bloat, which is something I'm generally against. I think that the fact Claude Code doesn't support it, may provide some validation to this idea.

Generated agent config files (AGENTS.md, skills, MCP configs) should be .gitignored

Regarding AGENTS.md, i'm not so sure about it, there are good reasons to have it committed. If it will be autogenerated it means that if we want developers to write their own instructions for agents (and we do!), we'll have to teach them to have another file such as AGENTS.src.md and they would also have to remember to run some command that will output that content to AGENTS.md, in addition the command will also have to be run on remote operations such as code review to have this content available and it's another layer of complexity. All of this will need to be learned by any new member of a repo that uses AICM.

About skills, here we have a choice, we either not committing them, but require a setup command to have an agent ready repo, or do commit them, but we'd have to setup some periodic process that fetches the latest rules and create a PR with them. It reminds me of dependabot or renovate but much simpler. You could setup a github action that runs once a day, pull the latest changes and create a PR if there are changes in source skills. We actually don't have to be opinionated here, we can allow both flows and let the developer choose their preferred way of working with it.

Regarding MCP configurations, we either teach developers to use local aicm preset to manage them and handle the merge on installation, but it does introduce a lot of complexity as well, I would actually consider an approach when you want to see when a new MCP server is being added, here the approached mentioned above with the lock file and periodic PRs that update it works well.