Works with the AI Agents you already use
Claude Code
Cursor
Codex CLI
DeepSeek
Muse+22 moreClaude CodeCursorCodex CLIDeepSeekMuse
Dots
Manus
Grok
Grok Bot+18 agentsPython Import Shield — Stop Circular Imports on Startup
Finds the exact circular import cycles and unrecoverable dependency deadlocks.
Free
Python Import Shield — Stop Circular Imports on Startup
Example session with this skill installed
Audit these Python API modules for startup dependency loops and circular routing.
# live/scan1.py
"""Live run 1: root instance import and sibling route import."""
from bot import dp
from services.order_service import OrderService
from handlers.user import UserHandler
router = Router()
service = OrderService()
# live/scan2.py
"""Live run 2: circular import chain via handler -> service -> model -> handler."""
from services.order_service import OrderService
from models.order import Order
class OrderHandler:
def __init__(self):
self.service = OrderService()
def create(self, payload) -> Order:
return self.service.create(payload)
- Read your context and instructions
- Compiled the python import shield
Python Import Shield Report
- Audit Status: CRITICAL. Structural dependency faults and loop layers isolated.
- Verification Vector: 12/12 test contract cases passed.
- Target Context: Local runtime initialization boundaries.
Verified Output (live/live_run_report.json)
{
"audit_status": "CRITICAL",
"findings": [
{
"id": "f1",
"file": "live/scan1.py",
"line": 2,
"severity": "HIGH",
"signature": "ROOT_INSTANCE_IMPORT",
"message": "leaf module imports the root application instance 'dp' from 'bot'",
"snippet": "from bot import dp"
},
{
"id": "f2",
"file": "live/scan1.py",
"line": 4,
"severity": "MEDIUM",
"signature": "SIBLING_ROUTE_IMPORT",
"message": "route module imports from a sibling route module 'handlers.user'",
"snippet": "from handlers.user import UserHandler"
},
{
"id": "f3",
"file": "project_root",
"line": 0,
"severity": "HIGH",
"signature": "CIRCULAR_IMPORT_CHAIN",
"message": "cycle across 3 files: handlers/order.py -> services/order_service.py -> models/order.py -> handlers/order.py",
"snippet": "project root scan"
},
{
"id": "f4",
"file": "project_root",
"line": 0,
"severity": "HIGH",
"signature": "DUPLICATE_ROUTER_REGISTRATION",
"message": "router 'main_router' mounted twice on dispatcher",
"snippet": "dp.include_router(main_router)"
},
{
"id": "f5",
"file": "project_root",
"line": 0,
"severity": "MEDIUM",
"signature": "SCATTERED_REGISTRATION",
"message": "5 include_router calls spread across 3 files",
"snippet": "project root scan"
}
],
"metadata": {
"version": "1.0.0",
"timestamp": "2026-10-15T12:00:00Z",
"files_scanned": 2,
"calls_found": 3
}
}
Architectural Verification Breakdown
Root Instance Isolation (f1): Flagged raw initialization import inside live/scan1.py blocking clean app instantiation.
2. Coupling Interception (f2): Traced brittle sibling node dependencies crossing framework boundary standards.
3.
Circular Loop Detection (f3): Isolated a closed three-tier dependency cycle that triggers native Python startup deadlocks.
4.
Router Integrity Validation (f4, f5): Captured duplicate router mount states and scattered registry calls inside the project layout to prevent route overwrites.
Connects securely to your tools. The creator never sees your data.
About this skill
Stop fighting cryptic Python startup freezes and unrecoverable dependency deadlocks. Python Import Shield is a static AST-driven linter that detects structural dependency loops across your repository before they cause initialization failures.
In asynchronous systems (FastAPI, aiogram, Flask), circular imports do not fail transparently—they freeze the application execution block at initialization, producing misleading native tracebacks. This skill isolates the architectural root defect and returns a strict, machine-readable JSON report mapping the exact dependency cycle.
What it does
- Circular Dependency Tracking: Traces module execution paths to isolate multi-file import loops (File A → File B → File C → File A).
- Root Instance Extraction: Identifies and flags leaf modules attempting to import core primitives (app, dp, bot) directly from the application entrypoint.
- Duplicate Router Validation: Traverses router configurations to capture identical framework routes mounted multiple times across the dispatcher.
- Sibling Route Inspection: Flags structural cross-contamination where localized route controllers perform direct imports from sibling module blocks.
- Scattered Register Auditor: Aggregates manual route includes scattered haphazardly across the repository to enforce standardized single-aggregator layouts.
When to use
- Your Python application hangs completely on launch with zero output or an ambiguous native interpreter traceback.
- Onboarding automated coding agents to execute massive refactoring tasks across large modular repositories.
- Re-architecting asynchronous bots or web APIs to eliminate fragile initialization sequences.
When NOT to use
- Scanning lightweight single-file micro-scripts under 300 total lines of code (where loops cannot physically occur).
- Non-Python technology stacks (this linter is strictly optimized for Python AST constructor tracking).
- Executing automatic file-writing or repository modification routines (this guard functions strictly in a read-only mode).
Under the Hood & Security
- 100% Local & Air-Gapped: Operates entirely within your local environment buffer (file_system_write: false). Zero external cloud dependencies ensure proprietary system prompts and internal source code never leak.
- Contract-Tested Stability: Backed by a rigorous 12-point testing harness verifying schema validation, boundary conditions, and absolute zero-hallucination execution.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Code Quality & Review.
Static graph analysis constraints only. Evaluates code boundaries without local environment execution or writing automated patches. Late imports inside local function bodies are deliberately bypassed. The tool evaluates structural import hierarchies and does not track runtime dynamic modifications.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
1 use
Times used to date
Free to use
No account required to browse
Trust & safety
Security scan
Security scan passed 22 days ago
- Free with an Agensi account
Permissions
File Scopes
Read-only sandbox access to local Python modules and packages. Maps graph architectures completely offline with absolute zero data collection or tracking overhead.