archimate

Overview of archimate skill

What archimate is for

The archimate skill helps you generate ArchiMate diagrams in PlantUML using the !include <archimate/Archimate> stdlib and typed macros. It is best when you need an archimate skill for layered enterprise architecture views: business, application, technology, motivation, and implementation roadmaps. Use it when the job is to turn a rough architecture outline into a structured diagram, not when you just want generic boxes and arrows.

Best-fit use cases

This skill is a strong fit for people creating enterprise architecture deliverables such as capability maps, application integration views, security architecture, or migration plans. It is especially useful when the reader needs traceability between layers and clear semantics for elements and relationships. If you need archimate for Diagramming across TOGAF-style views, this skill gives you a more disciplined starting point than a freeform prompt.

When not to use it

Do not choose archimate for cloud reference diagrams, Kubernetes layouts, or network topology maps unless the goal is explicitly an ArchiMate view of those domains. The repository itself points you away from those cases: use a cloud skill for infrastructure-heavy cloud diagrams and a network skill for topology. That boundary matters because the macros here model enterprise architecture concepts, not general schematic design.

How to Use archimate skill

Install and locate the workflow

Install with npx skills add markdown-viewer/skills --skill archimate. After install, read SKILL.md first to learn the required PlantUML structure, then inspect the example files in examples/ for layer-specific patterns. The most useful files to preview first are examples/enterprise-landscape.md, examples/application-integration.md, examples/business-capability.md, examples/data-architecture.md, and examples/migration-planning.md.

Give the skill the right input

The best archimate usage starts with a clear architecture intent, a target view, and the entities you already know. A weak request says “make an architecture diagram.” A stronger request says: “Create an ArchiMate business-capability view for retail, showing customer engagement, supply chain, and finance capabilities, with 8–10 named elements and relationships between them.” Include the layer, audience, scope, and whether you want motivation or implementation elements.

Follow the PlantUML contract

This skill expects a real PlantUML diagram, not prose. The core pattern is: start with @startuml, include !include <archimate/Archimate>, declare elements with typed macros like Business_Actor(...) or Application_Component(...), connect them with Rel_* macros, and end with @enduml. Use rectangle "Layer Name" { ... } to keep the model readable. If you omit the include or use the wrong fence, the diagram will not render as intended.

Prompting workflow that improves output

For a reliable archimate guide, work in three passes: define the architectural question, list entities and relationships, then ask for a PlantUML diagram only. Good inputs include naming conventions, preferred level of detail, and any must-show relationships such as serving, realization, access, or triggering. If your source material is messy, ask the skill to normalize it into one target view before expanding to multiple layers.

archimate skill FAQ

Is archimate better than a normal prompt?

Yes, when you need consistent ArchiMate syntax and a diagram that can be rendered and edited. A normal prompt may produce plausible architecture prose but miss required macros, layer grouping, or relationship types. The archimate skill is more useful when you care about diagram correctness and reuse.

What should I know before installing?

The main requirement is that you already have a diagram goal that fits ArchiMate semantics. This skill works best if you can name the actors, applications, capabilities, services, and technology nodes you want to model. If you only have a vague idea, you can still use it, but your first output will be better if you provide a scoped view instead of a broad enterprise wishlist.

Can beginners use archimate?

Yes, if they are willing to learn a few macro patterns. The repository is practical because the examples show common views and element types, so beginners can copy the structure without memorizing the full notation. The main beginner mistake is asking for a full enterprise map too early; start with one view, one layer, or one process slice.

When should I choose something else?

Choose another skill if the diagram is mainly about cloud resources, physical network layout, or generic software components without enterprise-architecture semantics. Also avoid it if you need a purely visual sketch with no concern for standardized relationships. Use archimate when the value is in structure, traceability, and stakeholder-readable EA notation.

How to Improve archimate skill

Start with the view, not the theme

The biggest quality jump comes from specifying the exact ArchiMate view you want. “Enterprise architecture for banking” is too broad; “migration-planning view for a legacy billing system with baseline, two plateaus, work packages, and gaps” is actionable. If you want better results from archimate, name the layer set, the audience, and the decision the diagram should support.

Provide complete entities and relationship intent

The skill performs better when you list the important nodes and how they connect. For example, instead of “show login flow,” say “Identity Provider serves Auth Service, Auth Service realizes Access Control, and Users trigger Login Request.” That extra structure reduces hallucinated links and helps the diagram reflect the actual architecture.

Ask for one deliverable and iterate

A common failure mode is asking for too many views at once, which creates clutter and weak relationships. Start with one diagram, review whether the macro choices match your architecture language, then request a revision for missing elements, naming, or grouping. For archimate usage, iterative refinement is usually better than one oversized prompt.

Use the examples as pattern libraries

If you are unsure how to frame a request, mirror the repository examples: business-capability, application-integration, data-architecture, security-architecture, devops-pipeline, and migration-planning. Those examples reveal which macros belong to which concern and how the repository expects layered grouping. Reusing that structure makes your prompt more specific and your diagram more faithful.