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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add lonely-lockley/archinsight --skill archinsight技能说明
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.
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:
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, runstructure,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 jsonbefore 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
- Read the existing
.aiand.aiqfiles before editing. - Preserve indentation and the project's existing naming style.
- Model architecture from the outside inward: context, external actors/systems, systems, containers/services, components, project-defined code when needed, and deployment details.
- Do not ask about deployment depth until the task touches infrastructure, runtime placement, regions, brokers, gateways, storage, or deployment.
- 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
$toto wires, and make pub/sub dependencies consumer-owned. - If a diagram becomes noisy, adjust scope/query before changing a correct graph model.
- Save reusable custom views as
.aiq. Unless the user specifies another location, createviews/and writeviews/<descriptive-name>.aiq. - Prefer small, focused files connected by
context,import, andextend. - Keep definition, context, and environment sources in separate files.
- Use
archinsight structure . --format textbefore broad edits when the project shape is unclear. - Validate every Insight change with
archinsight link . --format text. - For C2, C3, C4, Deployment, or query changes, inspect the selected graph with
archinsight query ... --format jsonbefore rendering. - If validation fails, fix the first real syntax/type/linking error before adding more model content.
Reference routing
- Read
references/cli.mdwhen the CLI is missing, its version differs from the generated skill, or the skill package must be regenerated. - Read
references/modeling.mdbefore creating or extending a model. - Read
references/importing-models.mdwhen translating an existing architecture description, diagram, inventory, or foreign DSL into Insight. - Read
references/syntax.mdbefore writing unfamiliar Insight syntax. - Read
references/layered-architecture.mdwhen decomposing a system across C1, C2, C3, C4, and Deployment views. - Read
references/c1-context.mdwhen working with system context models. - Read
references/c2-containers.mdwhen working with containers or services. - Read
references/c3-components.mdwhen working with component internals. - Infer and reuse an existing C4 Code