IntentKit Development Assistant

Expert guidance for working with IntentKit, an autonomous agent framework for creating and managing AI agents with powerful skills.

What This Skill Does

This skill helps you understand and work with the IntentKit codebase, an open framework for building AI agents equipped with capabilities to improve the world. It provides architectural context, development guidelines, and best practices for contributing to IntentKit.

Project Architecture

Core Structure

1. **intentkit/** (Published pip package)

- `core/` - Agent system powered by LangGraph

- `models/` - Entity models (Pydantic for memory, SQLAlchemy for storage)

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

- `skills/` - Skills system using LangChain BaseTool (LLM-callable for data fetching, actions, environment interaction)

- `utils/` - Utility functions (logging, formatting, etc.)

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

2. **app/** - Local deployment

- Local API server

- Autonomous runner

- Background scheduler

- Use for single-user development or no-auth deployments

3. **scripts/** - Operational scripts

- Agent management

- Manual operations

- Migration scripts

4. **tests/** - Integration tests

- `tests/core/` - Core package testing

- `tests/api/` - API server testing

- `tests/skills/` - Skill integration testing

5. **frontend/** - Next.js application

- Agent management UI

- See `frontend/AGENTS.md` for detailed architecture

Technology Stack

Development Guidelines

Package Dependency Order (Avoid Circular Dependencies)

Packages on the left can never import packages on the right:

```

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

```

Code Standards

1. **Always use latest package versions**

2. **English only** for code comments and searches

3. **No auto-commits** unless explicitly requested

4. **Imports at top** of all files

5. **No unnecessary documentation** - focus on implementation (no example scripts unless requested)

Skills Development

When developing or modifying skills, refer to `agent_docs/skill_development.md` for detailed instructions.

Operations & Git Workflow

For commits, pull requests, or releases, consult `agent_docs/ops_guide.md`.

Workflow Instructions

Before Starting Work

1. Activate virtual environment:

```bash

source .venv/bin/activate

```

2. Understand the dependency hierarchy to avoid circular imports

During Development

1. **Follow the tech stack conventions**:

- Use SQLAlchemy 2.0 API (not legacy methods)

- Use Pydantic V2 interfaces only

- Write FastAPI endpoints following framework best practices

2. **Maintain code quality**:

- Write English comments where needed

- Place all imports at the top of files

- Follow the package dependency order

After Implementation

1. **Lint and format**:

```bash

ruff format && ruff check --fix

```

2. **Type check** with BasedPyright (ensure no errors in modified files)

3. **Run tests**:

```bash

pytest

```

4. **Do not commit** unless explicitly asked

Key Concepts

When to Use This Skill

Important Notes