AIC: Why Coding Agents Need a Package Interface Standard

When you maintain several tightly coupled SDKs consumed by multiple applications, you eventually notice that your coding agent instructions form a pattern. SDK A changes. You tell the agent to update the corresponding skills, rules, and context in the consuming repository. SDK B changes. Same ritual. After the tenth time, you realize you are manually synchronizing an undocumented protocol.

Takafumi Endo hit this friction point and proposed a solution: Agent Interface Contract (AIC), a standardized manifest format that packages can use to expose agent-specific metadata, skills, and harness context without polluting human-facing documentation.

The Problem: Package Metadata for Agents

Traditional package manifests (package.json, pyproject.toml, Cargo.toml) describe dependencies, entry points, and build steps. They do not describe how a coding agent should use the package. That gap forces developers to maintain parallel documentation in project-local surfaces like .claude/, .codex/, or AGENTS.md.

When an SDK changes, the consuming repository’s agent context must be updated manually. The friction compounds across repositories:

• Which files should change?
• Which source is canonical?
• What should be copied versus referenced?
• What belongs to the package versus the consuming project?
• How do different harnesses (Claude, Cursor, Windsurf) consume the same package knowledge without duplicating it?

This is not a documentation problem. It is a missing interface layer.

What Agents Need from Packages

Coding agents need three categories of information that traditional package metadata does not provide:

Category	Traditional Manifest	Agent Needs
Capabilities	Exported symbols, entry points	Declarative skills, constraints, usage patterns
Context	README, inline comments	Harness-specific instructions, project-local rules
Integration	Dependency graph	Cross-package orchestration hints, state boundaries

The AIC proposal introduces a .aic/ directory at the package root. This directory contains:

• manifest.yaml: Canonical metadata about the package’s agent-facing interface
• skills/: Declarative skill definitions the package exposes
• context/: Harness-specific instructions (e.g., claude.md, cursor.md)
• examples/: Reference implementations showing multi-package orchestration

AIC Manifest Structure

A minimal AIC manifest looks like this:

# .aic/manifest.yaml
version: "1.0"
package:
  name: "@acme/workflow-sdk"
  version: "2.3.1"
  description: "Stateful workflow orchestration primitives"

skills:
  - id: "create-workflow"
    file: "skills/create-workflow.yaml"
    summary: "Initialize a new workflow with state machine definition"
  
  - id: "add-transition"
    file: "skills/add-transition.yaml"
    summary: "Add a state transition with validation hooks"

constraints:
  - "All workflows must define an initial state"
  - "Transition guards must be pure functions"
  - "State machine definitions are immutable after initialization"

harness_context:
  claude: "context/claude.md"
  cursor: "context/cursor.md"
  windsurf: "context/windsurf.md"

integration_hints:
  - package: "@acme/schema-sdk"
    relationship: "Workflow states reference schema definitions"
  - package: "@acme/infra-sdk"
    relationship: "Workflows deploy via infrastructure primitives"

The manifest is the single source of truth. Consuming repositories reference it, not copy it.

Discovery and Consumption Flow

When a coding agent encounters a package with an AIC manifest, the discovery flow looks like this:

1. Package installation: Standard package manager installs the package
2. AIC discovery: Agent scans node_modules/@acme/workflow-sdk/.aic/manifest.yaml
3. Skill registration: Agent loads skill definitions from .aic/skills/
4. Context injection: Agent reads harness-specific context from .aic/context/claude.md
5. Cross-package orchestration: Agent uses integration hints to understand multi-package workflows

The consuming repository’s .claude/ directory no longer duplicates package-specific knowledge. Instead, it references the canonical AIC manifest:

# .claude/project-context.md

## SDK Integration

This project uses three SDKs with AIC manifests:

- @acme/workflow-sdk: See .aic manifest for workflow orchestration skills
- @acme/schema-sdk: See .aic manifest for schema validation constraints
- @acme/infra-sdk: See .aic manifest for deployment primitives

Project-specific rules:
- All workflows must include telemetry hooks
- Schema migrations require manual approval
- Infrastructure changes must pass cost estimation

Harness-Specific Context Without Duplication

Different coding harnesses have different capabilities. Claude supports project-level instructions. Cursor uses .cursorrules. Windsurf has its own context format. AIC allows package authors to provide harness-specific guidance without forcing a single format:

.aic/
├── manifest.yaml
├── skills/
│   ├── create-workflow.yaml
│   └── add-transition.yaml
└── context/
    ├── claude.md        # Claude-specific instructions
    ├── cursor.md        # Cursor-specific rules
    └── windsurf.md      # Windsurf-specific context

Each harness reads its own context file. The manifest references all of them. Package authors maintain one canonical source. Harness vendors decide how to consume it.

State Boundaries and Orchestration Hints

The most interesting part of AIC is the integration hints section. When multiple packages collaborate, agents need to understand state boundaries and orchestration flow. Traditional dependency graphs show “A depends on B” but not “A’s workflow states reference B’s schema definitions.”

AIC integration hints make these relationships explicit:

integration_hints:
  - package: "@acme/schema-sdk"
    relationship: "Workflow states reference schema definitions"
    state_boundary: "Schema validation happens before state transitions"
    failure_mode: "Invalid schema causes workflow initialization to fail"
  
  - package: "@acme/infra-sdk"
    relationship: "Workflows deploy via infrastructure primitives"
    state_boundary: "Infrastructure provisioning is asynchronous"
    failure_mode: "Deployment failures trigger workflow rollback"

This is not documentation. It is machine-readable orchestration metadata. An agent can use these hints to:

• Validate cross-package state transitions
• Understand failure propagation
• Generate integration tests
• Suggest observability hooks

Likely Failure Modes

AIC introduces new coordination surfaces. Here are the failure modes to watch:

Manifest drift: Package code changes but .aic/manifest.yaml does not update. Mitigation: CI checks that validate manifest against exported symbols.

Harness fragmentation: Each harness vendor invents incompatible extensions to the AIC spec. Mitigation: Version the manifest format and define a minimal compliance surface.

Skill definition bloat: Package authors add too many skills, overwhelming the agent’s context window. Mitigation: Skill definitions should be declarative summaries, not full implementations.

Cross-package version skew: Consuming repository references an outdated AIC manifest. Mitigation: Package managers should surface AIC version mismatches during dependency resolution.

Security boundary leakage: AIC manifests expose internal implementation details that should remain private. Mitigation: Treat .aic/ as public API surface with the same review rigor as exported code.

Comparison to Existing Approaches

Approach	Scope	Synchronization	Harness Support
Project-local context (.claude/, AGENTS.md)	Single repository	Manual	Harness-specific
Inline comments	Per-file	Automatic	Universal but noisy
README-driven	Package-level	Manual	Universal but unstructured
AIC manifest	Package-level	Automatic via package manager	Multi-harness via context files

AIC sits between inline comments (too granular) and README-driven documentation (too unstructured). It provides package-level agent metadata that synchronizes automatically through the package manager.

Implementation Considerations

If you want to adopt AIC in your packages today, here is the minimal path:

1. Create .aic/manifest.yaml with package metadata and skill references
2. Define skills in .aic/skills/ as declarative YAML files
3. Add harness context in .aic/context/ for the harnesses you support
4. Update consuming repositories to reference the AIC manifest instead of duplicating package knowledge
5. Add CI validation to ensure manifest stays synchronized with code

The hardest part is not the manifest format. It is deciding what belongs in the package’s AIC manifest versus the consuming repository’s project context. A useful heuristic: if the knowledge is intrinsic to the package (constraints, capabilities, integration boundaries), it belongs in .aic/. If it is specific to how your project uses the package (business rules, deployment preferences), it belongs in project-local context.

Technical Verdict

Use AIC when:

• You maintain multiple tightly coupled packages consumed by several applications
• You find yourself repeatedly synchronizing agent instructions across repositories
• Different coding harnesses need different context from the same package
• Cross-package orchestration patterns are complex enough to benefit from explicit integration hints

Avoid AIC when:

• You have a single monolithic repository (project-local context is sufficient)
• Your packages are stable and rarely change (manual synchronization is tolerable)
• Your coding agents do not yet support structured skill definitions (wait for harness adoption)
• You are not ready to treat agent-facing metadata as public API surface

AIC is early. No package manager natively discovers .aic/ manifests yet. No coding harness automatically loads skills from .aic/skills/. But the pattern is sound. If you are already maintaining parallel agent context across repositories, formalizing it as an AIC manifest will reduce synchronization friction and make cross-package orchestration more explicit.

The real test will be whether harness vendors adopt a common discovery protocol or fragment into incompatible extensions. Until then, AIC is a useful convention for package authors who want to expose agent-specific metadata without waiting for ecosystem-wide standardization.

---

Source Links

• AIC: Packages Need an Interface for Coding Agents (primary source)