i2 Connector Builder — Agent Skill

An Agent Skill that guides AI coding assistants through building i2 Analyze connectors using the i2 Connect Node SDK.

Works with GitHub Copilot agent mode .

What It Does

Point the agent at a REST API — via an OpenAPI spec, a docs URL, or just a description — and it will:

1. Confirm authentication requirements
2. Design an i2 schema (entities, links, properties) from the API's data model
3. Propose a set of services (search, expand, find-like-this) suited to the data
4. Customise the npm init @i2analyze/connector scaffold into a working connector

The agent asks before writing anything — schema and services are confirmed with you before code is generated.

Skill Capabilities

| Capability | Description | |---|---| | Build a connector end-to-end | From API spec/URL/description to a working, tested connector in 8 guided steps | | Progress tracking & resume | Maintains .github/PROGRESS.md so sessions can be resumed days later, across agents | | Schema design | Proposes entity types, link types, and properties with correct logicalType mappings | | Service discovery | Analyses API relationships and proposes search, expand, find-like-this, and fetch-all services | | Auth configuration | Supports 7 auth patterns — generates .env.sample, auth.ts, and settings config | | Debugging assistant | Structured troubleshooting — matches symptoms to known fixes, adds scoped debug logs | | Packaging & deployment | Pre-packaging checks, debug log cleanup, npm pack, and deployment guidance | | Self-review | Verifies generated code against SDK API surface, checks for hardcoded secrets and schema coverage |

Getting Started

Setup

Scaffold a new connector, then run:

npm init @i2analyze/connector my-connector
cd my-connector
npx i2-connector-skills init

This installs all the skill files into the right places:

my-connector/
├── CLAUDE.md                               ← for Claude Code
├── AGENTS.md                               ← for Codex / generic 
└── .github/
    ├── copilot-instructions.md             ← for GitHub Copilot
    ├── instructions/
    │   └── connector-instructions.md       ← always-on code rules (all agents)
    └── skills/
        └── i2-connector/                   ← the skill

Existing files are never overwritten. Run with --force to overwrite.

Usage

"Help me build a connector for <mnai/trm-labs/any-api>."

The skill handles the rest — it asks clarifying questions, proposes a design, and generates code once you confirm.

Workflow

Step 1   Provide an API spec, docs URL, or description
Step 2   Agent confirms auth requirements
Step 3   ✋ You confirm the schema design
Step 4   ✋ You confirm the services in scope
Step 5   Scaffold check
Step 6   Agent writes the connector code
Step 7   Build check + self-review
Step 8   npm start — test in i2 Analyze

The two ✋ stops are hard gates — no code is generated until you explicitly confirm.

Trigger Phrases

Beyond the main build workflow, you can activate specific features with these prompts:

| What you want | Example prompts | |---|---| | Start a new connector | "Help me build a connector for [API name]" / "I want to build a connector" | | Resume a previous session | "Continue where we left off" / "What's the current status?" / (just open the project — auto-resumes) | | Debug a problem | "Help me debug this" / "The service isn't returning results" / "I'm getting a 401" / "It's timing out" | | Package for deployment | "Package this" / "How do I deploy it?" / "Build for production" | | Add a new service | "Add a search service for [entity]" / "I need an expand from Person to Transaction" | | Modify the schema | "Add a new entity type" / "I need to add a property to Person" |

Progress Tracking

The skill maintains a .github/PROGRESS.md file throughout the build process. This enables:

• Session resumption — the agent picks up exactly where you left off
• Multi-agent continuity — switch between Claude Code, Copilot, or Codex mid-project without losing context
• Decision history — every confirmed schema, service list, and auth choice is recorded with timestamps
• Session log — each agent session is tracked with what was accomplished

How it works: At the start of every session, the agent checks for .github/PROGRESS.md. If found, it resumes from the last incomplete step. If not, it creates one from a template.

Debugging Assistant

When something goes wrong, tell the agent — it activates a structured debugging workflow:

"Help me debug this"
"The service returns no results"
"I'm getting an error"
"The service is timing out"

The debugger will:

1. Match known patterns — common issues (timeouts, empty results, duplicates) have instant fixes applied without needing logs
2. Enable debug logging — confirms log.level is set to "debug" in config/server.json
3. Scope narrowly — adds logger.debug(...) calls only to the specific function or file involved
4. Point you to the right log file — each service writes to its own .log file
5. Clean up — after fixing, resets log level and offers to remove AI-added debug lines

| Symptom | What the agent does | |---|---| | Service times out | Adds longRunning: true + substatus progress calls | | Returns no results | Adds targeted debug logs to trace the data flow | | Duplicate records on expand | Fixes seed handling (addEntityFromSeed instead of addEntity) | | 401 / auth errors | Inspects data-access.ts auth header construction | | Connector won't start | Checks server.json and settings.json for config errors |

SDK Reference

• Docs: https://i2group.github.io/analyze-connect-node-sdk/index.html
• Samples: https://github.com/i2group/analyze-connect-node-sdk/tree/main/samples
• Scaffold: npm init @i2analyze/connector my-connector