Where Are the AI Skill Manifests Located in the Diagram-Design Repository?

The cathrynlavery/diagram-design repository stores AI skill manifests in platform-specific hidden directories at the root level, specifically /.factory-plugin/plugin.json, /.claude-plugin/plugin.json, and /.codex-plugin/plugin.json, with automated synchronization maintained by the scripts/bump-plugin-version.py and scripts/verify-plugin-package.py utilities.

The AI skill manifests in the diagram-design repository serve as the single source of truth for plugin metadata across multiple AI platforms. These JSON configuration files reside in dot-prefixed folders that correspond to each target host, enabling consistent deployment to Factory Droid, Claude, and Codex marketplaces. Understanding the exact file paths and synchronization mechanisms is essential for developers maintaining cross-platform AI integrations.

Platform-Specific AI Skill Manifest Locations

The repository organizes AI skill manifests in hidden top-level directories, with each platform receiving its own isolated configuration file:

• Factory Droid: /.factory-plugin/plugin.json — Contains the plugin name, version, author, repository URL, license, and marketplace metadata required by the Factory Droid host runtime.
• Claude: /.claude-plugin/plugin.json — Holds an identical metadata schema formatted specifically for Claude's marketplace ingestion and runtime environment.
• Codex: /.codex-plugin/plugin.json — Mirrors the other manifests to ensure a unified contract for the Codex host, maintaining parity across all supported platforms.

Agent Plugin Marketplace Configuration

For future agent-based consumption patterns, the repository includes a separate marketplace-level file at /.agents/plugins/marketplace.json. This location deliberately separates marketplace aggregation data from individual skill manifests to prevent duplication while supporting extensible agent plugin architectures.

Manifest Synchronization Architecture

Consistency across AI skill manifests relies on a centralized maintenance system. A MANIFEST_PATHS constant enumerates the primary manifest locations, enabling atomic operations across platforms. The repository maintains version parity through two critical scripts in the scripts/ directory:

• scripts/bump-plugin-version.py — Executes atomic version updates across all platform manifests simultaneously
• scripts/verify-plugin-package.py — Performs CI validation to confirm that version numbers, plugin names, and other critical metadata fields match across /.factory-plugin/plugin.json, /.claude-plugin/plugin.json, and /.codex-plugin/plugin.json

Reading and Updating Manifests Programmatically

The repository provides Python utilities for interacting with AI skill manifests during build and verification workflows.

Loading Platform-Specific Manifests

Verification scripts resolve manifest paths relative to the repository root using the following pattern:

import json
from pathlib import Path

def load_manifest(name: str) -> dict:
    """Load a platform‑specific manifest."""
    manifest_path = Path(__file__).parent.parent / f".{name}-plugin" / "plugin.json"
    return json.loads(manifest_path.read_text(encoding="utf-8"))

# Example: load the Claude manifest

claude_manifest = load_manifest("claude")
print(claude_manifest["name"], claude_manifest["version"])

Synchronizing Versions Across Platforms

Version bumping operations target the MANIFESTS list to ensure all AI skill manifests update simultaneously, preventing platform drift:

from pathlib import Path
import json

MANIFESTS = [
    ".factory-plugin/plugin.json",
    ".claude-plugin/plugin.json",
    ".codex-plugin/plugin.json",
]

def bump_version(new_version: str) -> None:
    for rel in MANIFESTS:
        path = Path(rel)
        data = json.loads(path.read_text())
        data["version"] = new_version
        path.write_text(json.dumps(data, indent=2))

Design Rationale for Root-Level Storage

The AI skill manifests are deliberately placed at the repository root in dot-prefixed folders to satisfy three architectural requirements:

• Discovery: The file-tree structure itself declares integration scope without requiring additional import graph analysis or configuration files
• Versioning: Root placement enables atomic updates across all platform manifests during release operations, ensuring consistent versioning across Factory Droid, Claude, and Codex
• Isolation: Each platform reads its dedicated manifest without interference, while the CI pipeline enforces cross-platform consistency through the verification scripts

Summary

• AI skill manifests reside in three hidden top-level directories: /.factory-plugin/plugin.json, /.claude-plugin/plugin.json, and /.codex-plugin/plugin.json
• Future agent plugins use /.agents/plugins/marketplace.json for aggregated marketplace metadata
• The scripts/bump-plugin-version.py utility maintains semantic version consistency across all platform manifests
• scripts/verify-plugin-package.py validates field parity during continuous integration
• Root-level dot-prefix placement enables automatic discovery, atomic versioning, and platform isolation

Frequently Asked Questions

What specific fields are included in each AI skill manifest?

Each AI skill manifest contains the plugin name, semantic version, author attribution, source repository URL, license identifier, and marketplace-specific metadata. These fields provide Factory Droid, Claude, and Codex hosts with the necessary context to load, display, and execute the skill correctly.

How does the repository prevent version drift between platform manifests?

The scripts/bump-plugin-version.py script updates all manifest files simultaneously using the centralized MANIFESTS list, while scripts/verify-plugin-package.py executes during CI to validate that critical fields match across /.factory-plugin/plugin.json, /.claude-plugin/plugin.json, and /.codex-plugin/plugin.json before deployment.

Why are the manifest directories prefixed with dots?

The dot-prefix convention (e.g., /.claude-plugin/) hides these directories from standard file listings while maintaining root-level visibility for build tools. This signals that these are configuration containers rather than source code, and the root placement ensures the MANIFEST_PATHS resolver can locate them without directory traversal.

Can developers add support for new AI platforms?

Yes, extending support requires creating a new dot-prefixed directory at the repository root (e.g., /.new-platform-plugin/plugin.json) and updating the MANIFESTS constant in the synchronization scripts. The load_manifest() function's string-based path resolution supports dynamic loading for arbitrary platform identifiers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}