IntentKit Development Assistant

Expert assistant for the IntentKit autonomous agent framework. Provides guidance on architecture, skill development, agent management, and deployment following project conventions.

Overview

IntentKit is an autonomous agent framework enabling creation and management of AI agents with powerful capabilities. This skill helps you navigate the codebase, develop skills, manage agents, and follow established patterns.

Project Structure

Understanding the architecture is critical:

Core Package (`intentkit/`)

Application Layer (`app/`)

Supporting Directories

Technology Stack

**Package Management:**

**Code Quality:**

**Frameworks:**

Development Rules

Follow these strictly:

1. **Always use latest package versions**

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

3. **No automatic git commits** unless explicitly requested

4. **Imports at file beginning** in all new code

5. **No documentation/examples** unless specifically requested

6. **Run `ruff format && ruff check --fix` and `pytest` before completing tasks**

Architecture Patterns

Import Order (Prevent Circular Dependencies)

Packages in `intentkit/` follow strict left-to-right dependency order:

```

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

```

**Left packages can NEVER import right packages.**

Skills Development

When developing or modifying skills:

1. Read `agent_docs/skill_development.md` for detailed patterns

2. Inherit from LangChain's `BaseTool`

3. Place in `intentkit/skills/`

4. Test in `tests/skills/`

Database Models

Use dual-model pattern:

Common Tasks

Starting a New Skill

```python

Example structure (see skill_development.md for details)

from langchain.tools import BaseTool

from pydantic import Field

class MySkill(BaseTool):

name = "my_skill"

description = "Clear description for LLM"

def _run(self, param: str) -> str:

# Implementation

pass

```

Running Tests

```bash

Activate environment first

source .venv/bin/activate

Run all tests

pytest

Run specific test suite

pytest tests/core/

pytest tests/api/

pytest tests/skills/

```

Code Quality Checks

```bash

Format and lint

ruff format

ruff check --fix

Type check (ensure no errors in changed files)

BasedPyright runs in your IDE/editor

```

Running the Application

```bash

Activate environment

source .venv/bin/activate

Start local API server

(see app/ for entry points)

```

Operations & Deployment

For git operations, pull requests, or releases:

Frontend Development

For Next.js interface work:

Best Practices

1. **Respect package boundaries** - follow import order strictly

2. **Use SQLAlchemy 2.0 API** - avoid legacy patterns

3. **Pydantic V2 only** - no V1 interfaces

4. **Type hints everywhere** - BasedPyright must pass

5. **Test after changes** - pytest should pass

6. **Format before committing** - ruff format + check

7. **English documentation** - all comments and docs in English

Troubleshooting

Circular Import Errors

SQLAlchemy Issues

Pydantic Validation Errors

Additional Resources

Notes

This framework enables autonomous agent development with skill-based capabilities. Follow the established patterns, respect architectural boundaries, and prioritize code quality to maintain the framework's integrity.