Skip to content
Skills Library
Programming · Writing

system-context-builder

/system-context-builder

Produce a C4 Level 1 (System Context) diagram and description showing the system, its users, and external dependencies. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.

Repository
APES ↗
Licence
MIT
Last repository change
03.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Produce a C4 Level 1 (System Context) diagram and description showing the system, its users, and external dependencies. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.

Original author description

Produce a C4 Level 1 (System Context) diagram and description showing the system, its users, and external dependencies. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.

How it works

  1. Step 1: Identify the system boundary
  2. Step 2: Identify actors (users and personas)
  3. Step 3: Identify external systems
  4. Step 4: Draw context diagram
  5. Step 5: Document trust boundaries
  6. Step 6: Validate
Original SKILL.md headings · 154 lines, 561 words
SKILL.md preview
---
name: system-context-builder
description: >
  Produce a C4 Level 1 (System Context) diagram and description showing the system, its users, and external dependencies. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.
metadata:
  apes-version: "1.1"
  category: architecture
---

# System Context Builder

# Purpose

Produce a C4 Level 1 (System Context) diagram and description showing the system, its users, and external dependencies.

**Input:** Solution architecture or PRD, stakeholder list (optional)  
**Output:** System Context document with Mermaid diagram, actor descriptions, and external system inventory
**Examples:** See [examples.md](examples.md) for worked input/output.

---

# Workflow

## Step 1: Identify the system boundary

Define:

- System name and one-sentence purpose
- What is inside the system boundary
- What is explicitly outside

## Step 2: Identify actors (users and personas)

List all human actors:

| Actor | Type (user/admin/operator) | Goal | Interaction |
|-------|------------------------------|------|-------------|

Map to personas from product skills if available.

## Step 3: Identify external systems

List all external systems the solution interacts with:

| System | Purpose | Protocol | Data exchanged | Owned by |
|--------|---------|----------|----------------|----------|

Include: identity providers, payment, email, analytics, third-party APIs.

## Step 4: Draw context diagram

Use Mermaid C4-style or flowchart:

```mermaid
flowchart LR
    actor1[Actor] --> system[System]
    system --> ext1[External System]
```

Rules:

- One central system node
- Actors on the left/top
- External systems on the right/bottom
- Label every arrow with action or data flow

## Step 5: Document trust boundaries

Identify security boundaries between system and externals.

## Step 6: Validate

Run Validation checklist.

---

# Decision Rules

| Condition | Action |
|-----------|--------|
| No solution architecture or PRD | Stop; request input or run solution-architecture |
| Actor overlaps with external system | Clarify: human actor vs software system |
| More than 10 external systems | Group into categories; detail in appendix |
| Undocumented integration | Mark as "TBD"; add to open questions |
| System boundary unclear | Ask user to confirm scope before diagramming |

---

# Validation

- [ ] System boundary explicitly defined
- [ ] All actors from PRD/user flows represented
- [ ] All external integrations listed
- [ ] Mermaid diagram renders with labeled relationships
- [ ] Trust boundaries identified
- [ ] No container-level detail (defer to container-diagram-builder)
- [ ] Diagram matches written descriptions

---

# Anti-patterns

- **Missing externals** — ignoring auth provider, payment, email services.
- **Container in context** — showing databases or internal services at Level 1.
- **Unlabeled arrows** — relationships without action/data description.
- **Actor = system** — treating batch jobs or admin tools as users without clarity.
- **Scope creep** — including future-phase systems without marking as planned.

---

# Best Practices

- Follow C4 Model Level 1 strictly.
- Use consistent naming from solution architecture components at abstract level.
- Mark planned vs current integrations.
- Align actors with PRD user flows.
- Keep diagram readable: max 7±2 nodes.

---

# Output Structure

```markdown
# System Context: [System Name]

## System
**Name:** [name]
**Purpose:** [one sentence]
**Boundary:** [what's in/out]

## Actors
| Actor | Type | Goal | Interactions |
|-------|------|------|--------------|

## External Systems
| System | Purpose | Protocol | Data | Status |
|--------|---------|----------|------|--------|

## Context Diagram
```mermaid
[diagram]
```

## Trust Boundaries
| Boundary | Controls |
|----------|----------|

## Open Questions
- [ ] [Question]
```

---

# Next Skills

| Outcome | Recommended Skill |
|---------|-------------------|
| Decompose into containers | `architecture/container-diagram-builder` |
| Design APIs for externals | `architecture/api-designer` |
| Update solution architecture | `architecture/solution-architecture` |
| Record integration decisions | `architecture/adr-generator` |
Files in this package (3)
  • README.md 1 KB
  • examples.md 1 KB
  • skill.md 4 KB

Versions

The database has no other skills named system-context-builder.

Database snapshot: 13.11.2026 · package version d523ae888c59 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100component-diagram-builder
    Produce a C4 Level 3 (Component) diagram for a selected container, showing internal components, responsibilities, and dependencies. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.
  • 100container-diagram-builder
    Produce a C4 Level 2 (Container) diagram decomposing the system into deployable/runnable units with technology choices and communication paths. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.
  • 100architecture-diagram
    Generates a Mermaid architecture diagram showing high-level component relationships. Use when visualizing how plugins or modules fit together.
  • 100c4-architecture
    Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include…
  • 100c4-architecture
    Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include…
  • 100033-architecture-diagrams
    Use when you need to generate Java project diagrams — including UML sequence diagrams, UML class diagrams, C4 model diagrams, UML state machine diagrams, UML Deployment Diagrams, ER (Entity Relationship) diagrams, and bounded-context diagrams — through a modular, step-based…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.