skills.rest
daniel-brus
daniel-brusCOMMUNITY
Explore all skills by this author →
GitHub

import-dag

Enforces acyclic package layering rules for Python imports in the chess_teacher codebase.

1|Updated Apr 30, 2026
Search Tags:#architecture#refactoring#python#circular dependency#dag#import#package layering
One-click install
npx skills add https://github.com/daniel-brus/chess_teacher --skill import-dag-daniel-brus
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: import-dag
Source: https://github.com/daniel-brus/chess_teacher/tree/main/.agents/skills/import-dag
Command: npx skills add https://github.com/daniel-brus/chess_teacher --skill import-dag-daniel-brus

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Python codebases grow tangled when modules import across layers without rules, producing circular imports, hidden dependencies, and misplaced utility code. This Skill defines a strict directed acyclic graph of package layers so every new import points downward and cycles are caught before they ship. ## Core Features & Use Cases - Layered architecture rules: Defines top-level layers (utils, platform, pipelines, bots, analytics, orchestration) plus a utils sub-DAG, with explicit rules about which layer may import which. - Placement guidance: Provides a lookup table for where new code belongs (env helpers, logging, storage, DB access, NN training, bots, analytics) and forbids catch-all dump packages. - Third-party import policy: Specifies when to wrap stdlib or heavy libraries (tensorflow, boto3, redis) in utils versus importing domain libraries (chess, polars) directly. - Use Case: When adding a new preprocessing module that needs logging and object storage, use this Skill to verify the import edges point down the layer list and do not create a logging-core-to-storage cycle. ## Quick Start Ask the agent to review whether a planned new import or module placement in the chess_teacher package respects the import DAG layering rules.

Frequently Asked Questions about import-dag

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix circular imports in a Python package?▼

Circular imports are fixed by restructuring modules so dependency edges point downward through defined layers, not by hiding them with lazy or TYPE_CHECKING imports. Identify which module belongs at a lower layer and move shared primitives into a utils package that neither side's higher layers import.

Where should new utility code go in a layered Python project?▼

Place new code at the highest layer that still keeps the dependency graph acyclic, preferring a feature folder over utils. Env, datetime, and YAML helpers go in env_utils or general_utils, while domain-specific code like NN training belongs in its feature package such as pipelines/neural_network.

When should I wrap third-party library imports in a utils module?▼

Wrap stdlib or config calls reused two or more times, such as os.getenv or YAML loading, into named helpers in env_utils or general_utils. Heavy libraries like tensorflow, boto3, or redis should be imported next to the owning module unless the same boilerplate repeats across modules.

Do lazy imports count as fixing a circular dependency?▼

No, lazy or TYPE_CHECKING imports may avoid runtime crashes but do not count as a layering fix unless the dependency genuinely belongs at a higher tier. The preferred approach is restructuring the modules so the import edge points down the layer list.

Why should a utils package never import from feature packages?▼

Utils sits at the bottom of the layer stack, so importing platform, pipelines, bots, or analytics from utils would create an upward edge and likely a cycle. Shared primitives must stay dependency-free so every higher layer can safely consume them.

Related Skills

Explore More Software Engineering Skills→
agentic-cookbookagentic-cookbook

port-swiftui-to-appkit

Analyze macOS SwiftUI codebases to plan migration to native AppKit.

Official
Advanced
JoyJoin-Tech-LimitedJoyJoin-Tech-Limited

process-refactoring

Guides incremental behavior-preserving code refactoring with typecheck and test verification.

Official
Intermediate
Xunzi229Xunzi229

architecture-guard

Enforce Java DDD four-layer architecture rules across Java source files.

Community
Intermediate
xtrm-devxtrm-dev
4

architecture-patterns

Design backend service boundaries and dependency rules for clean, hexagonal, and DDD architectures.

Official
Advanced