Works with the AI tools you already use
Claude Code
Cursor
Codex CLI
Muse
OpenClaw+21 moreClaude CodeCursorCodex CLIMuseOpenClaw
Manus
Grok
Grok Bot+18 agentsImportShield: Circular Import Guard
Detect and resolve circular imports and duplicate router registrations in modular async applications.
$12
ImportShield: Circular Import Guard
Example session with this skill installed
The bot freezes on startup after I refactored the handlers. The traceback points to handlers/user.py but it looks fine. Check for circular imports.
- Read your context and instructions
- Compiled the importshield
DIAGNOSIS — Circular import detected
The application is hanging because the interpreter has encountered a dependency loop. The traceback points to handlers/user.py simply because it was the last module reached before the cycle closed.
Cycle path:
handlers/user.py -> services/auth.py -> models/user.py -> handlers/user.py
Root cause:
The models/user.py file is importing a validation schema UserUpdate from handlers/user.py. Simultaneously, handlers/user.py requires the AuthService from services/auth.py, which in turn depends on the User model. This creates a hard loop that prevents the dispatcher from initializing.
Recommended Fix: Extract Shared Schema
The UserUpdate schema is domain logic that is being shared between the handler and the model. It should not live in the handler layer.
- Create a new file:
schemas/user.py - Move the
UserUpdatePydantic model fromhandlers/user.pytoschemas/user.py. - Update imports in both
models/user.pyandhandlers/user.pyto point to the new schema file.
# models/user.py - Broken
from handlers.user import UserUpdate # DELETE THIS
# models/user.py - Fixed
from schemas.user import UserUpdate # USE THIS
Next steps
- Move the
UserUpdateclass to a newschemas/directory. - Verify that
handlers/user.pyno longer exports items used by the models layer. - Restart the application and monitor the logs for the "Dispatcher started" message.
Connects securely to your tools. The creator never sees your data.
What you get
About this skill
Stop spending hours chasing ghost bugs that freeze your application at startup. Circular imports in modular async codebases like FastAPI or aiogram rarely provide clear tracebacks, often pointing to the last file loaded rather than the actual architectural flaw. This skill acts as a static analysis guard for your AI agent, preventing it from introducing tight coupling and registration loops that break your production environment.
What it does
- Detects Circular Dependencies by mapping the full import graph and identifying cycles across three or more files.
- Bans Root Instance Imports to prevent leaf modules from directly importing the main
app,dp, orbotobjects. - Identifies Duplicate Registrations such as routers mounted multiple times or child routers registered on both a parent and the dispatcher.
- Enforces Module Boundaries ensuring route modules expose a single public interface and do not reach into sibling internals.
- Provides Architectural Fixes by recommending service layer extraction instead of messy late-import workarounds.
How it works
- Identify the Root Instance to establish the boundary between the entry point and the application logic.
- Map the Import Graph to visualize dependencies and flag explicit paths where A imports B, B imports C, and C imports A.
- Verify Registrations by scanning for redundant
.include_router()calls or duplicate mount points. - Apply Fix Logic by moving shared schemas or logic to a lower service layer to break identified cycles.
Frameworks & tools
Optimized for Python-based async frameworks including aiogram, FastAPI, and Flask, as well as Node.js environments using Express.
Why this beats prompting it yourself
Standard LLMs often suggest "late imports" as a quick fix, which masks architectural debt. This skill enforces structural integrity by identifying the root cause of cycles and requiring the extraction of shared logic into appropriate service or schema layers.
Use cases
- Debugging application freezes where the startup log provides no clear error message.
- Auditing a large refactor to ensure modularity hasn't been compromised by cross-module dependencies.
- Preventing duplicate router registration errors in complex web or bot frameworks.
- Onboarding new developers to ensure they follow strict separation of concerns between entry points and handlers.
Known limitations
Requires read access to the full codebase, including __init__.py files. Not designed for single-file projects where module boundaries do not exist.
How to install
Works the same in every agent - Claude, Cursor, Codex, Copilot and 20+ more.
- 1
Download the ZIP
Free skills download straight away. Paid skills unlock right after purchase.
- 2
Unzip into your skills folder
Every agent reads skills from one folder on your machine. Drop the unzipped folder in there.
- 3
Ask your agent to use it
Restart the agent if it was already running. It picks the skill up automatically - no config needed.
Skills folder by agent
Click the path to copy it. Create the folder if it does not exist yet.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill passes our trust checks below.
Security scanned
Passed our 8-point scan before listing
Fresh listing
Recently published to Agensi
30-day refund
Not a fit? Get your money back
Trust & safety
Security scanned
Verified clean 1 day ago
- Passed all security checks, Safe to install