Last updated April 21, 2026
Insight Skills
You've mapped your architecture. Sources are connected. Now you want to know: where are the risks? What's strong? What should we tackle next? Insight skills are AI-powered analysis templates that answer those questions and paint the results directly onto your boards.
How insight skills work
An insight skill is a reusable analysis template. It defines what the AI should look for, how to report findings, and which references to consult. When you run a skill against a board, it produces an insight instance — a structured report with findings mapped to specific nodes and edges.
Rendering diagram...
Insight categories
Skills are organized by what they analyze:
| Category | Focus |
|---|---|
| Security | Vulnerabilities, access control, data exposure |
| Reliability | Fault tolerance, redundancy, failure modes |
| Compliance | Regulatory requirements, audit readiness |
Running an insight skill
- Open a board and click the Insights button in the toolbar
- Select a skill from the available list (system skills or your custom ones)
- Click Run — the AI will analyze your board's nodes, edges, and connected sources
- Watch the progress in the Insights Bar at the bottom of the board
Your first insight checklist
- Open a board that has at least a few nodes and edges
- Click the Insights button in the toolbar
- Browse available skills and pick one matching your goal (Security or Architecture Health are good starting points)
- Click Run and wait for the analysis to complete
- Review the signal overlays on your board nodes
- Explore any traced paths or graph suggestions in the results panel
Skills can use template variables — tech stacks detected in your sources, detected languages, node archetypes, the current board — so the same skill adapts automatically to different boards.
Understanding insight results
Each insight instance contains up to four types of findings:
Signals
Individual findings attached to specific nodes or the board as a whole.
| Signal | Visual | Meaning |
|---|---|---|
| Risk | Red | Something that could go wrong |
| Strength | Green | Something working well |
| Opportunity | Purple | Potential improvement |
| Observation | Slate | Neutral finding worth noting |
| Metric | Cyan | Quantitative measurement (0–1 score) |
Signals also carry a priority — critical, high, medium, or low.
Paths
Traced routes through your architecture graph — request flows, blast radius propagation, dependency chains. Each path has ordered steps with optional labels and annotations.
Affected elements
Nodes that should be visually emphasized on the diagram, with relationship hints (primary, dependent, dependency, related, context) and emphasis styles (highlight, pulse, glow, outline, focus).
Graph suggestions
Proposed structural changes — add, remove, or modify nodes, edges, or containers. Each suggestion includes a rationale and priority.
Results mode
When a skill runs multiple times, the results mode determines what happens to previous results:
| Mode | Behavior |
|---|---|
| Replace | New results completely replace existing ones — only the latest run is kept |
| Append | New results are added alongside previous runs — you can compare over time |
Replace mode shows a single latest view in the Insights Bar. Append mode opens a multi-list panel where you pick which run to inspect.
Creating custom skills
- Go to Settings → Insight Skills in your workspace
- Click New Skill
- Fill in the details:
- Name and slug — display name and URL identifier
- Category — pick from the categories above
- Instructions — the primary prompt the AI follows (supports template variables)
- References — named documents the AI reads on demand during execution
- Results mode — replace or append
- Color — visual accent for the UI chip
- Estimated duration — human-readable time hint
Custom skill options
When creating a custom skill, there are additional options for fine-grained control:
- Template variables — placeholders that inject detected tech stacks, languages, node archetypes, the board slug, and any user-selected focus nodes into your instructions
- References — named reference documents (e.g., your team's security standards, cloud best practices) that the AI can read on demand during execution
- Results mode — replace keeps only the latest run visible; append lets you compare runs over time for trend analysis
- Color — pick a visual accent so the skill's chip is distinct in the Insights Bar
- Estimated duration — a hint like "2–5 minutes" shown to users before they run the skill
Troubleshooting
Skill runs but produces no signals?
- Make sure your board has nodes with meaningful names and descriptions — the AI needs context to analyze
- Check that connected sources have been synced recently
Signals seem generic or irrelevant?
- Refine the skill's instructions to be more specific about your tech stack and concerns
- Add references with domain-specific guidelines
Paths don't match expected request flows?
- Verify that edges between nodes represent real dependencies, not just visual groupings
- Add edge labels describing the relationship type (HTTP, gRPC, event, etc.)
Run seems stuck or takes too long?
- Large boards with 50+ nodes take longer — consider running skills on focused sub-layers
- Check the Insights Bar for progress indicators
System skills are provided out of the box and available to all orgs. Your custom skills are scoped to your organization.
Publishing insights with boards
When you publish a board, its latest insight instances are included in the published snapshot. Stakeholders viewing the portal see signal overlays, paths, and suggestions — giving them architectural context without needing editor access.