Skills

How skills work

The server (MCP server: tools and operations) gives the AI hands: operations that read and change an Enterprise Architect repository. Skills give it judgment: the order to do things in, the mistakes to avoid, and the checks that prove a result. This chapter explains what a skill is, how the assistant picks one, how the 24 skills fit together, which model to run them on, and how to tell whether the work came out right.

Each skill has its own section, and each says which capabilities it uses beyond the server and what happens without them (Capabilities skills use). The material several skills share is in Shared references.

What a skill is

A skill is a folder of written instructions that the AI follows. It does not run by itself, and it adds no operation of its own. It tells the AI how to use the operations that already exist.

Most skills are AI + AI Power Tools checks: the AI plans and drives, and server operations or bundled code compute and check. A few steps are pure judgment (AI) and many are pure computation (Deterministic: given the same inputs and the same model state, the same result, with no AI judgment involved; see section 0.5). Every skill section marks each step AI, AI Power Tools or You, so you can see which parts are repeatable and which depend on the model, and where you must decide or approve. AI Power Tools marks a step that the AI Power Tools MCP Server for Sparx EA carries out through one of its operations, and (AI + AI Power Tools) marks a step the AI drives and the server operations carry out. Two further markers show the capability a step needs. AI with computer use; otherwise you means the AI does the step when it can see and operate EA's window, and hands the step to you when it cannot. Engine means a bundled code engine computes the step, which needs local code execution.

AI Power Tools carries 24 skills: 20 for Sparx EA and 4 for Prolaborate. It also ships one validation ruleset, ruleset-archimate31, which is data used by the validation operation and is not a skill (ArchiMate 3.1 ruleset).

How the assistant picks a skill

Delivery. The skills are delivered as a Claude plugin named ai-power-tools, which carries the skills and no server. You install it once on your Claude account, and it reaches Claude Desktop chat, Claude Cowork and the Code tab. Plugins are the one mechanism that every Claude surface loads for skills. The server is delivered separately, as the Claude Desktop extension. See Claude plugin and Supported clients.

The prefix. A skill loaded from the plugin is namespaced as ai-power-tools:<name>, for example ai-power-tools:ea-start-here. This reference uses the short name.

Choosing from descriptions. The client shows the AI each skill's name and description. The AI picks the skill whose description fits your request, then reads that skill's instructions and, when a step points to one, a reference file. Every description therefore names the situations it covers, and several end with a "use this first" or "never use it for" sentence. How each client weighs descriptions, and when it loads the full text, is client behavior and can differ between clients.

The routing skill. ea-start-here exists so that the choice is made from a table and not from a guess. It runs a short check called the session preflight (is the server alive, which model is open, which technologies are live) and then routes to a skill. The session preflight is not the reporting preflight, which is a dry run of a reporting build and belongs to ea-reporting-database (ea-reporting-database). Seven skills are not in the routing skill's table and are chosen directly from their own descriptions. The tables below give the complete map.

Duplicate copies. A machine that has both the plugin and skills copied into the user's own skills folder by an older installation loads each skill twice, and nothing removes the duplicates. A clean-up script removes older copies. When the plugin is found installed, the server's skills check reports only such leftover copies, with the clean-up script as the remedy. See Moving from an older installation and Skills installer.

Skills and server versions

Skills and the server ship in the same release (3.6.4) and are tested as a set. Each skill states the oldest server that has the operations it calls. The skills and the server update separately, so a mismatch can arise when one is updated and the other is not. At the start of a session ea-start-here passes the skills' release to ping, and the server says when either is behind the current release. It also tells the AI to note the server version from ping, because a version mismatch explains a missing operation faster than debugging does. The Prolaborate skills work through browser control and ea-com works through a local script and COM, so neither needs the server.

Capabilities skills use

The server is one of four capabilities an assistant can have. A skill's work can also depend on seeing EA's window, running code on your machine, or operating a web application. Which capabilities an assistant has depends on the client you use. Section Capabilities and surfaces lists which clients provide which. This chapter is written in terms of capabilities, so it stays correct as more clients gain them.

Engines need Python 3 on the machine where EA runs. pywin32 is needed only by scripts the AI writes against EA's automation interface (ea-com, and the COM snippets in ea-mdg-deploy), and by no reporting step. The composition engine needs pyyaml, and the Parquet files need pyarrow, which is not bundled. Code engines gives the detail.

The reporting skills need local code execution only for the census, the inclusion choice, the governance gate, the Parquet files and the Power BI project. The AI Power Tools MCP Server for Sparx EA builds the business layer, checks it, replays it and refreshes it (Reporting business layer), so those steps run on any surface that has the server.

What happens when a capability is missing depends on the skill, and each skill section has a "Capabilities it uses" table that says so. There are three outcomes:

• A UI step becomes yours. The AI hands you the step and asks what you see. For a blocking dialog, you take a screenshot of it and paste it into the conversation so the AI can analyze it, then you dismiss the dialog so processing can continue. The AI does not report a hang it has not diagnosed or a diagram it has not seen.
• The AI does the computation itself. Where a skill allows it, the AI works out what an engine would have computed. This costs more tokens and is less consistent between runs.
• Not available. Where a skill has no fallback, such as ea-com without local code execution or a Prolaborate skill without browser control, the AI says so.

The server's limits are not the limits of AI Power Tools as a whole. For example, the server attaches to a running EA and cannot see a dialog EA has opened. An assistant with computer use can start EA, open the model, read the dialog, use its message to correct the call, dismiss it and carry on. Without computer use, you take a screenshot of the dialog and paste it into the conversation so the assistant can analyze it, then you dismiss the dialog so processing can continue.

The routing map

Start with ea-start-here for any Sparx EA task and prol-start-here for any Prolaborate task. The table lists all 24 skills. The last column shows what a skill needs beyond the MCP server. "Optional" means the skill works without it and the AI hands you the step.

ea-help is the last row of the EA set for a reason. It works from Sparx's user guide for the running EA version and drives the interface, which is slower and less verifiable than any operation. It is taken only when no skill covers the task, no operation does the job, and the automation interface has no route either.

Reviews and administration. For Prolaborate reviews (create, take part, approve) and Prolaborate administration (users, groups, access permissions, repository configuration), the assistant may read a review's state, and declines to write. Authoring model content, MDG Technologies, diagrams, validation and baselines is not Prolaborate work, and prol-start-here sends it to ea-start-here.

Routing rules that prevent the common mistakes.

• Writing an MDG Technology directly, or building it from a profile package. Use ea-mdg-author when writing the technology directly. Use ea-mdg-model-build when the stereotypes already exist as a profile package in a repository. Check for the profile package first. ea-mdg-assess is the starting point when the situation is unclear.
• Business layer, then Power BI. ea-reporting-database builds the business layer, the tables the modeling technology defines, and checks it against the technology and against EA. It needs a modeling technology; with none loaded it does not build. For Power BI, build and check the layer there first, then continue with ea-power-bi, which asks where the data should come from before it generates the project. The layer is delivered as views in the EA database (live data), as a separate reporting database (a snapshot) or as Parquet files (a snapshot). Power BI reads the views with DirectQuery or Import, and the other two with Import. For a question or two about counts and roll-ups, use ea-stakeholder-reporting and build no layer. See ea-stakeholder-reporting, ea-reporting-database and ea-power-bi.
• Diagrams. ea-diagram-advisor chooses what to draw, ea-diagram-composition draws it, and ea-navigation-diagrams is the specific click-through pattern. All three end with a render and a look.
• Escalation. Two failures of the same kind send the AI to ea-diagnostic and not to a third guess.

Choosing a model

Skills run on whatever model the client uses. Some work needs a stronger model and some does not. A stronger model costs more and answers more slowly, and a long session multiplies both. Each skill section has a table for that skill. This section is the general guide those tables follow.

How to read the ratings. A rating is Recommended, Capable or Not recommended. It is guidance drawn from what a task demands, not a benchmark. Treat it as the first thing to try, and use the checks in the next section to see whether the output was right.

The four models, in descending order of reasoning depth and, in general, of cost and delay:

What calls for a stronger model.

What lets a lighter model do the job.

Even when a lighter model is enough for the work, do not use it for the step that checks the work of a stronger one. Verification is where a weak model's habit of accepting a success response does the most damage.

Cost and delay. Three practices keep the bill sensible without lowering quality:

• Split by role. Use the stronger model to design and plan, a lighter one to carry out the plan you approved, and a stronger one again to review the result. A plan a person has reviewed before execution leaves less open-ended reasoning for the execution step.
• Let AI Power Tools do the work. Deterministic operations and bundled engines (see section 0.5) cost the same on any model. Where local code execution is available, a code engine computes in one run what the AI would otherwise work out across many calls, with the same result every time and far fewer tokens (Code engines). Prefer one bulk operation to many single calls, and one counting query to a loop of reads.
• Do not save on checks. A lighter model that skips verification can cost more in rework than a stronger one that does not. Keep the checks below on at every tier.

Context window and long sessions. Everything an operation returns consumes the AI's working context, and a session that builds a large repository can fill it. These habits hold on any model:

• Ask for minimal responses. Operations that change the model return only an identifier, GUID and name unless full detail is requested. A bulk create of ten elements costs roughly 800 to 1,200 tokens in one call, against roughly 3,000 to 5,000 for ten single calls.
• Verify with one counting query, not a read of every element. A ten-row query returns in the order of 300 to 600 tokens, and a full listing of fifty elements can run to 8,000 to 15,000.
• Use the summarize_* operations instead of assembling summaries from many list calls.
• Split large builds by phase: packages, then elements, then connectors, then diagrams, then verification. Start each phase with a clean context and re-orient with get_repository_info and a targeted query. Do not ask the model to recall what it did earlier.
• At a usage limit, finish the current operation, capture state with one query, clear the context, and start the next phase from that short summary. Asking for a summary of everything done so far at that moment is the most expensive thing to do.

These figures are approximations from the ea-modeling references. They vary with the model, the client and the size of the response.

Other clients and other models. The ratings and the skill text were written and tested with Claude models. A client such as VS Code with GitHub Copilot can use a different model, including AI models that run on the device. The model guidance in this document is written for Claude models. The task characteristics carry over: open-ended design, long plans and geometric judgment still call for the strongest model available, and a lighter one is still enough for procedural work. Skills whose work is mostly done by code engines depend least on the model, because the engine gives the same result whichever model drives it. Skills that rely on AI judgment depend most. For those users the accuracy checks below matter more, not less.

Checking results

Every skill section lists the checks that suit that skill. The common method behind them, with the six ways to check, a recipe for any task and the check that fits each kind of task, is in How to trust the result.

Impact and traceability analysis

Questions about the impact of a change, traceability coverage, or as-is to to-be gaps are answered from the graph and traceability operations: trace_connectors, find_paths, get_traceability_tree and traverse_element_subgraph (Graph and traceability). ea-model-hygiene uses them for pre-delete safety.

When you ask such a question:

• Asked "what is affected if we retire this system?", the AI composes the answer from those operations, or from a query. Check that the answer is complete. Assess the impact of retiring a system, Check traceability coverage and Compare the as-is and to-be architecture walk through the three questions.
• Apply the method in How to trust the result. Define the traversal rule in advance (which connector types, which direction, how many hops), count the reachable set with an independent query, and state what the traversal did not follow.
• prol-impact-analysis covers dependency analysis on the Prolaborate side. It reports the depth reached, the relationship types followed and why a search stopped, and never describes a bounded traversal as a complete blast radius.

See Limitations and known issues.