IntentKit Development Assistant

Expert guidance for building autonomous AI agents with the IntentKit framework.

Overview

IntentKit is an autonomous agent framework that enables creation and management of AI agents with capabilities. This skill provides comprehensive development assistance for working with IntentKit's architecture, skills system, and operational workflows.

Architecture

Package Structure

**IntentKit Package** (`intentkit/`)

Published as a pip package

`intentkit/core/` - Agent system driven by LangGraph

`intentkit/models/` - Entity models (Pydantic + SQLAlchemy)

`intentkit/config/` - System config (database, LLM/skill provider API keys)

`intentkit/skills/` - Skills system using LangChain's BaseTool

`intentkit/utils/` - Utility functions (logging, formatting)

`intentkit/abstracts/` - Interfaces for core and skills

**IntentKit App** (`app/`)

Local API server, autonomous runner, background scheduler

Can be used via package import or standalone local API + frontend

**Scripts** (`scripts/`)

Agent management, manual operations, migrations

**Tests** (`tests/`)

`tests/core/` - Core package testing

`tests/api/` - API server testing

`tests/skills/` - Skill integration testing

**Frontend** (`frontend/`)

Next.js application for agent management

See `frontend/AGENTS.md` for architecture details

Technology Stack

**Package manager:** uv

**Virtual environment:** `.venv` (activate with `source .venv/bin/activate`)

**Linter:** ruff (`ruff format & ruff check --fix`)

**Language Server:** BasedPyright (ensure no errors in changed files)

**API framework:** FastAPI (https://fastapi.tiangolo.com/)

**ORM:** SQLAlchemy 2.0 (https://docs.sqlalchemy.org/en/20/)

**Models:** Pydantic V2 (https://docs.pydantic.dev/latest/)

**Testing:** pytest

Development Guidelines

Core Rules

1. Always use the latest package versions

2. Use English for all code comments

3. Use English for searches

4. Do not git commit unless explicitly requested

5. Place imports at the beginning of files

6. No need to write dedicated documentation or example scripts after implementation

Import Order (Avoiding Circular Dependencies)

Packages in `intentkit/` must follow this order (left can import right, never reverse):

```

utils → config → models → abstracts → clients → skills → core

```

Skills Development

When developing or modifying skills:

1. Read the detailed guide: `agent_docs/skill_development.md`

2. Skills use LangChain's BaseTool interface

3. Skills enable agents to fetch data, perform actions, or interact with environments

4. Follow the established skills/ folder structure

Operations

When performing Git commits, pull requests, or releases:

1. Read the detailed guide: `agent_docs/ops_guide.md`

2. Follow the project's Git workflow conventions

Workflow Instructions

Setup

1. Activate virtual environment:

```bash

source .venv/bin/activate

```

2. Install dependencies using uv

Development Cycle

1. **Make changes** following architecture guidelines

2. **Run linter:**

```bash

ruff format

ruff check --fix

```

3. **Check types** with BasedPyright

4. **Run tests:**

```bash

pytest

```

5. **Commit only if requested** by user

Key Files to Reference

`agent_docs/skill_development.md` - Skills development guide

`agent_docs/ops_guide.md` - Operations and release guide

`frontend/AGENTS.md` - Frontend architecture

Best Practices

**SQLAlchemy:** Use 2.0 API only (avoid legacy patterns)

**Pydantic:** Use V2 API only (avoid obsolete V1 interfaces)

**Code Quality:** Ensure BasedPyright shows no errors before completion

**Testing:** Run pytest after all changes

**Documentation:** Code should be self-documenting with clear English comments

Constraints

Do not create unnecessary documentation files

Do not write example scripts unless requested

Do not perform git operations unless explicitly asked

Always check `agent_docs/` for detailed guidance before making architectural decisions

IntentKit Development Assistant

IntentKit Development Assistant

Overview

Architecture

Package Structure

Technology Stack

Development Guidelines

Core Rules

Import Order (Avoiding Circular Dependencies)

Skills Development

Operations

Workflow Instructions

Setup

Development Cycle

Key Files to Reference

Best Practices

Constraints

Reviews (0)