Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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.

lonely-lockley · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add lonely-lockley/archinsight --skill archinsight

About this skill


name: archinsight description: 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.

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.

Claude Usage Notes

Treat this SKILL.md as the entrypoint and load routed references only when the task needs them. With shell access, run validation directly. Without it, ask the user to run the exact command and paste the output. Do not silently install 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:

archinsight --help
archinsight link . --format text

If archinsight is not available in Claude's environment, 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/<descriptive-name>.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 to inspect the current model before broad edits when the CLI is available.
  11. Validate every Insight change with archinsight link . --format text when shell access is available; otherwise ask the user to run validation.
  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.

Communication

When shell access is unavailable, give the user short copy-pasteable commands:

archinsight link . --format text
archinsight structure . --format text

If rendering is needed, ask for the source file when it is not obvious. The CLI infers the context declared by that source:

archinsight render . -s <source.ai> -v c2 -f svg -o diagram.svg

Report diagnostics by source, line, column, and message. Avoid rewriting large sections of Insight unless the existing layering is already understood.

Reference routing

  • Read references/cli.md when the CLI is missing, its version differs from the generat
Read the complete source ↗