[FEATURE] Support interoperable project-level AI configuration conventions

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

AI-assisted development tools are increasingly introducing similar project-level concepts, such as instructions, agents, hooks, skills, plugins, and configuration files. However, the conventions used to structure, discover, configure, and execute these resources can differ between ecosystems.

This makes project-level AI configuration increasingly tied to a specific tool or provider. A project may need to duplicate or adapt the same intent across different AI coding environments, even when those environments support conceptually similar capabilities.

As the number of AI coding tools grows, this fragmentation could make it harder for projects and developers to move between tools or use multiple AI assistants without maintaining provider-specific configuration.

I believe there is an opportunity to explore common conventions for the parts of project-level AI configuration where interoperability is useful, while leaving implementation-specific capabilities to individual tools.

Proposed Solution

I propose that Claude Code consider participating in the exploration of interoperable conventions for project-level AI configuration.

I recently created opinionated-ts/ai-spec as an early, community-driven effort to explore this problem. The specification is intentionally not final and is intended to be shaped through comparison with existing implementations and feedback from AI coding ecosystems.

The project is exploring whether common conventions could be established for areas such as:

• Project-level AI configuration and instructions
• Agents
• Hooks and lifecycle behavior
• Plugins
• Skills and reusable commands
• Discovery and precedence
• Configuration structure and naming

The goal would not be for Claude Code to replace its existing conventions or adopt an external abstraction layer. Instead, Claude Code could help inform and potentially support conventions that provide interoperability where there is a clear benefit.

In particular, I would appreciate consideration of whether Claude Code's existing conventions could serve as prior art, whether there are interoperability problems worth addressing, and which capabilities should remain Claude Code-specific.

The repository is intentionally at an early stage so that existing implementations such as Claude Code can help shape what should and should not become standardized before any convention becomes mature.

Alternative Solutions

One alternative is to continue maintaining provider-specific project configuration for each AI coding tool.

This works within individual ecosystems, but it can require projects to duplicate similar instructions, agents, hooks, skills, or configuration for different tools.

Another approach is for each provider to independently develop conventions for these concepts. This may work well for provider-specific capabilities, but could lead to multiple incompatible conventions for concepts that are fundamentally similar.

I believe a better long-term approach may be to identify a small interoperable core while allowing providers to extend it with implementation-specific capabilities.

The [ai-spec](https://github.com/opinionated-ts/ai-spec) repository is intended to explore this distinction rather than assume that everything should be standardized.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Example scenario:

1. A project defines instructions, agents, hooks, skills, and other AI-assisted development configuration at the repository level.

1. The development team uses Claude Code alongside other AI coding environments.

1. The project needs to express similar development conventions across these environments.

1. Today, some of these concepts may need to be represented using different provider-specific structures or configuration conventions.

1. With interoperable conventions for the common parts, the project could define shared AI configuration once while allowing each provider to retain its own implementation-specific extensions.

This would make it easier for projects to use multiple AI coding environments without unnecessarily duplicating or translating the same project-level configuration.

Additional Context

The repository is intentionally in an early stage. Nothing in the proposed specification is considered final.

Repository: https://github.com/opinionated-ts/ai-spec

Contributing: https://github.com/opinionated-ts/ai-spec/blob/main/CONTRIBUTING.md

Discussions: https://github.com/opinionated-ts/ai-spec/discussions

I would particularly appreciate feedback from the Claude Code team on:

• Which existing Claude Code conventions should be considered prior art.
• Which interoperability problems you believe are worth solving.
• Which areas should remain implementation-specific.
• Whether existing Claude Code work already addresses parts of this problem.
• Whether the team or community would be interested in participating while the conventions are still being shaped.

The goal is not immediate adoption of ai-spec. The goal is to involve existing AI coding ecosystems early enough that real-world implementations can help determine what is useful to standardize and what should remain provider-specific.