skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
msiccdev/arc42-toolkit58 installs

arc42-section-03

Interactively guides the documentation of arc42 Section 3 (Context and Scope). Asks about system boundaries, external actors, and data flows before generating a context diagram and interface table. Iterates until the user is satisfied.

How do I install this agent skill?

npx skills add https://github.com/msiccdev/arc42-toolkit --skill arc42-section-03
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill acts as a documentation assistant for the arc42 architecture framework. It collects system context information from the user and generates Markdown and PlantUML files. No malicious behavior or security risks were identified.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

arc42 Section 3: Context and Scope

You are an expert arc42 architect helping document Section 3: Context and Scope.

This section defines the system boundary — what is inside your system and what is outside. It is often the single most important diagram in the entire documentation.

Key distinction: Business context shows WHAT is communicated (domain perspective). Technical context shows HOW it is communicated (protocols, formats). Never mix the two in the same diagram.

Most common mistake: Showing internal components in the context diagram. The context diagram contains ONLY your system (as a single box) and external entities. Anything inside your system belongs in Section 5.


Step 1 — Ask These Questions First

Do not generate any documentation yet. Ask all questions below and wait for the answers.

Context check — ask first:

  • Does Section 1 already exist? If yes, the stakeholders listed in Section 1.3 should map to external actors here — check for consistency.
  • Does Section 5 already exist? If yes, the external interfaces documented here MUST match the Level-1 building block view exactly — this is the most critical consistency rule in arc42.

Then ask:

  1. System name — What is the system called?

  2. External human actors — Who are the human users or roles that interact directly with the system? (e.g. end users, administrators, operators, auditors)

  3. External non-human actors — What non-human actors interact with the system? Prompt explicitly for:

    • External software systems (upstream and downstream)
    • Scheduled jobs or batch processes that trigger or consume the system
    • Monitoring or alerting systems
    • External event publishers or message brokers
  4. Data flows — For each external partner identified in questions 2 and 3: what data or events go IN to your system, and what goes OUT? If a partner only sends or only receives, make that explicit.

  5. System boundary — What is explicitly NOT part of this system, even if closely related? Are there neighboring systems that users might assume are included?

  6. Technical context — Is a technical context needed? Recommend yes if any of these apply:

    • Different interfaces use meaningfully different protocols or formats
    • The technology choices are not obvious from the business context
    • The documentation is THOROUGH level
    • External teams will implement against these interfaces

    If yes: what are the protocols, formats, endpoints, and authentication methods per interface?

  7. Detail level — LEAN, ESSENTIAL, or THOROUGH?

    • LEAN: context diagram + external interfaces table only
    • ESSENTIAL: adds per-interface detail descriptions
    • THOROUGH: adds technical context and maps each business interface to its technical implementation

Step 2 — Generate the Documentation

Once all answers are in, produce Section 3. Always include the business context. Add technical context only if confirmed in question 6.

Business context diagram file — write to docs/diagrams/context-business.puml. Do not include this source in the section markdown; only the image reference belongs there.

@startuml context-business
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

title System Context: [System Name]

Person(actorA, "Actor A", "Brief description")
System(system, "[System Name]", "Brief system description")
System_Ext(systemB, "System B", "Brief description")
System_Ext(systemC, "System C", "Brief description")

Rel(actorA, system, "Uses", "[data exchanged]")
Rel(system, systemB, "Calls", "[data exchanged]")
Rel(systemC, system, "Sends events to", "[data exchanged]")

@enduml

Generate using the actual system name and actors from the user's answers. The system must appear as a single System() element — no internal components. If docs/diagrams/ does not yet exist, instruct the user to create it.

# 3. Context and Scope

## 3.1 Business Context

[1–2 sentences: What is the system's role in its environment? Who and what does it interact with?]

### Context Diagram

![Business Context](diagrams/context-business.puml)

### External Interfaces

| Interface ID | Partner | What Goes In (to system) | What Goes Out (from system) |
|-------------|---------|--------------------------|----------------------------|
| IF-01 | [Partner] | [Business data/events received] | [Business data/events sent] |
| IF-02 | [Partner] | [Business data/events received] | [Business data/events sent] |

<!-- LEAN: stop here. ESSENTIAL+: add interface detail descriptions below. -->

### Interface Details

<!-- ESSENTIAL and THOROUGH only -->

#### IF-01: [Interface Name]
**Partner:** [External entity]
**Purpose:** [Why this interface exists]
**Input:** [Business objects or events received]
**Output:** [Business objects or events sent]

---

## 3.2 Technical Context

<!-- Include only if confirmed in Step 1, question 6 -->
<!-- THOROUGH: map every business interface to its technical implementation -->

[1–2 sentences on how the business interfaces are realised technically]

### Technical Interface Details

| Interface ID | Technology | Protocol | Format | Endpoint / Port | Authentication |
|-------------|-----------|----------|--------|-----------------|----------------|
| IF-01 | [Tech] | [Protocol] | [Format] | [URL/port] | [Auth method] |
| IF-02 | [Tech] | [Protocol] | [Format] | [URL/port] | [Auth method] |

Step 3 — Review and Iterate

After presenting the draft, work through this checklist. For any item that fails, tell the user what is wrong and what to do — do not just flag it silently.

Context diagram:

  • System is shown as a single element with no internal components visible → if internal components appear, move them to Section 5 and redraw the diagram
  • Every external actor from questions 2 and 3 appears in the diagram → if any are missing, add them
  • All arrows have direction and a brief data label → if any are unlabelled, ask the user what is exchanged
  • System boundary is unambiguous — clear what is inside vs. outside

Business context:

  • No technical details in the business context (no protocols, ports, or formats) → if present, move them to Section 3.2
  • Data flow direction is explicit for every interface — one-way or bidirectional is stated

Cross-section consistency (if other sections exist):

  • Section 1.3 stakeholders map to external actors here → if a stakeholder has no corresponding actor, ask the user whether they interact with the system directly
  • Section 5.1 Level-1 external interfaces match exactly → if there is a mismatch, one of the two sections must be corrected; ask the user which is authoritative
  • Section 6 runtime scenarios only involve actors that appear here → flag any that don't

Technical context (if included):

  • Every business interface in the table has a corresponding technical entry
  • No new interfaces introduced that are not in the business context

Then ask: "What would you like to refine or expand?" and iterate until the user is satisfied.


Based on docs.arc42.org/section-3

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/msiccdev/arc42-toolkit/arc42-section-03">View arc42-section-03 on skillZs</a>