# Archinsight > Create, edit, import, analyze, repair, validate, inspect, and render Archinsight Insight architecture-as-code models and custom views. Use when working with .ai models or .aiq queries, migrating architecture from another DSL or diagram, C4-style architecture models, system/container/component/code diagrams, deployment projections, or when the user asks to model or diagnose software architecture with Archinsight. - Skill: `lonely-lockley/archinsight` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add lonely-lockley/archinsight` - Raw SKILL.md: https://api.skillmd.com/api/skills/lonely-lockley/archinsight/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: lonely-lockley (https://skillmd.com/u/lonely-lockley) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/lonely-lockley/archinsight --- # Archinsight Use this skill when creating, analyzing, or repairing Insight `.ai` models and `.aiq` custom views, or when importing an existing architecture description into Insight. Insight is its own typed architecture-as-code language. Do not infer its syntax from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL. ## Codex Usage Notes Treat this `SKILL.md` as the entrypoint and load routed reference files only when the task needs them. Use shell access to run validation. Do not silently install global npm packages or change machine configuration. This package was generated by Archinsight CLI {{CLI_VERSION}}. Run `archinsight --version` before editing. If the installed version differs, regenerate the skill so its references, core sources, examples, and built-in queries match the runtime. ## Required Tool Use the Archinsight CLI as the validation source of truth: ```shell archinsight --help archinsight link . --format text ``` If `archinsight` is not available, read `references/cli.md`. Do not install or update packages without the user's authorization. ## Task modes Choose one mode before acting: - **Analyze:** stay read-only and follow `references/analysis.md`. Inspect sources, run `structure`, `link`, and the relevant query, then separate authored facts, derived relationships, deployment projections, and rendered presentation in the findings. - **Repair:** reproduce the defect first. For a visual defect, inspect `archinsight query ... --format json` before treating the image as evidence that the model is wrong. Request the current image or rendered output when it is not available, make the smallest model or query change, and validate the same semantic path again before rendering. - **Build or rebuild:** perform discovery before editing, then model from the outside inward and validate after each architectural layer. - **Extend an existing model:** inventory existing ids, imports, edges, and view scope; preserve stable identities and compare linked/query results before and after each focused change. - **Import an existing model:** follow `references/importing-models.md`. Establish which source artifacts are authoritative, translate facts rather than drawing layout, record uncertain mappings, and validate one architectural layer at a time. Before any build, rebuild, import, or structural edit, inspect the supplied context and every relevant source already available through the repository, attachments, configured skills, MCP integrations, or other authorized tools. Do not ask the user to repeat information the agent can retrieve reliably on its own. If a material fact is still missing after those sources are exhausted, ask one short, non-repetitive message containing only the one or two questions that could change the model. Do not use a questionnaire or ask about the audience by default. If the available evidence is sufficient, proceed without a discovery question. Use retrieved material as the source of truth; do not invent missing architecture. ## Workflow 1. Read the existing `.ai` and `.aiq` files before editing. 2. Preserve indentation and the project's existing naming style. 3. Model architecture from the outside inward: context, external actors/systems, systems, containers/services, components, project-defined code when needed, and deployment details. 4. Do not ask about deployment depth until the task touches infrastructure, runtime placement, regions, brokers, gateways, storage, or deployment. 5. At that point, decide per system whether pragmatic mixed C2 or explicit deployment modeling is appropriate. For explicit deployment, attach placement/storage to systems and containers (including services); components and code deploy with their container. Attach path infrastructure that needs `$to` to wires, and make pub/sub dependencies consumer-owned. 6. If a diagram becomes noisy, adjust scope/query before changing a correct graph model. 7. Save reusable custom views as `.aiq`. Unless the user specifies another location, create `views/` and write `views/.aiq`. 8. Prefer small, focused files connected by `context`, `import`, and `extend`. 9. Keep definition, context, and environment sources in separate files. 10. Use `archinsight structure . --format text` before broad edits when the project shape is unclear. 11. Validate every Insight change with `archinsight link . --format text`. 12. For C2, C3, C4, Deployment, or query changes, inspect the selected graph with `archinsight query ... --format json` before rendering. 13. If validation fails, fix the first real syntax/type/linking error before adding more model content. ## Reference routing - Read `references/cli.md` when the CLI is missing, its version differs from the generated skill, or the skill package must be regenerated. - Read `references/modeling.md` before creating or extending a model. - Read `references/importing-models.md` when translating an existing architecture description, diagram, inventory, or foreign DSL into Insight. - Read `references/syntax.md` before writing unfamiliar Insight syntax. - Read `references/layered-architecture.md` when decomposing a system across C1, C2, C3, C4, and Deployment views. - Read `references/c1-context.md` when working with system context models. - Read `references/c2-containers.md` when working with containers or services. - Read `references/c3-components.md` when working with component internals. - Infer and reuse an existing C4 Code vocabulary from the repository. Ask the user about entity kinds only when creating the Code layer or extending that vocabulary, unless the current request already makes the choice. - Read `references/c4-code.md` when defining or querying modules, packages, classes, functions, schemas, or other project-specific code concepts. - Read `references/deployment.md` when working with environments, deployments, infrastructure inventory, profiles, or placement. - Read `references/deployment-projections.md` when working with physical paths, projection rules, or a missing or unexpected Deployment edge. - Read `references/scaling.md` when splitting a repository into reusable framework, environment, profile, system, or view files. - Read `references/project-structure.md` before declaration lookup, imports, or broad file changes. - Read `references/core.md` and `.core/*.ai` before assuming built-in types, constructors, attributes, presentations, or projections. - Read `references/queries.md` before writing queries or interpreting query JSON. - Read `references/custom-views.md` before creating a saved `.aiq` view or overriding a built-in query. - Read `references/query-recipes.md` when a view hides expected content, returns unexpected content, or needs customization. - Read `references/validation.md` before validating semantic or rendered results. - Read `references/analysis.md` for read-only architecture analysis, dependency questions, impact exploration, and the boundary between Insight queries and analysis of their JSON output. - Use `examples/layered-architecture.ai` as a compact valid model.