IntentKit Development Assistant

You are an expert assistant for the IntentKit autonomous agent framework. IntentKit enables creation and management of AI agents with powerful skills and capabilities.

Project Architecture

Package Structure (`intentkit/`)

The `intentkit/` folder is published as a pip package with the following modules:

Application Layer (`app/`)

Scripts (`scripts/`)

Tests (`tests/`)

Frontend (`frontend/`)

Technology Stack

| Technology | Purpose | Documentation |

|------------|---------|---------------|

| **uv** | Package manager | - |

| **.venv** | Virtual environment | Run `source .venv/bin/activate` before commands |

| **ruff** | Linting & formatting | Run `ruff format && ruff check --fix` after edits |

| **BasedPyright** | Type checking | Ensure no errors in changed files |

| **FastAPI** | API framework | https://fastapi.tiangolo.com/ |

| **SQLAlchemy 2.0** | Database ORM | https://docs.sqlalchemy.org/en/20/ (use 2.0 API only, not legacy) |

| **Pydantic V2** | Data validation | https://docs.pydantic.dev/latest/ (avoid obsolete V1 interfaces) |

| **pytest** | Testing framework | Run `pytest` after edits |

Critical Development 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 after coding** (unless specifically requested)

5. **Place all imports at the beginning of files**

6. **Do NOT write dedicated documentation or example scripts** (unless specifically requested)

Import Ordering for Circular Dependency Prevention

**CRITICAL:** To avoid circular dependencies in `intentkit/`, follow this strict left-to-right import order:

```

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

```

**Packages on the left can NEVER import packages on the right.**

For example:

Development Workflows

Working with Skills

When developing or modifying skills, always refer to the detailed guide:

```

agent_docs/skill_development.md

```

Git Operations & Releases

When performing git commits, pull requests, or releases, consult:

```

agent_docs/ops_guide.md

```

Pre-Submit Checklist

Before considering any work complete:

1. ✅ Activate virtual environment: `source .venv/bin/activate`

2. ✅ Run linting: `ruff format && ruff check --fix`

3. ✅ Check types: Ensure no BasedPyright errors in changed files

4. ✅ Run tests: `pytest`

5. ✅ Verify import order follows dependency rules

6. ✅ Use SQLAlchemy 2.0 API (not legacy)

7. ✅ Use Pydantic V2 API (not V1)

8. ✅ All comments and docs in English

Common Patterns

Working with Models

Creating Skills

Configuration

Testing

Additional Resources