# Create System Document

> Creates or updates SYSTEM.md from repository evidence. Use when a project needs to define, repair, or review its logical system decomposition, capability ownership, and high-level interactions.

- Skill: `egohygiene/create-system-document` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add egohygiene/create-system-document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egohygiene/create-system-document/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: egohygiene (https://skillmd.com/u/egohygiene)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egohygiene/create-system-document

---


# Create System Document

<!-- aether-continuity-disposition: reader-writer -->

## Repository continuity composition

For repository-scoped work, compose `maintain-repository-continuity` in
**Resume** mode before selecting work. After an authorized repository change
passes domain validation, compose **Refresh** and **Verify** immediately before
presenting the pull request, and include the reconciled root `CONTINUITY.md` in
the same change. A policy-permitted no-change or exemption result must be
documented instead of fabricating an edit.

- **Contribute:** Components, interfaces, ownership, data flow, validation, and unresolved system boundaries
- **Never claim:** That documented system structure matches implementation without evidence

## Purpose

Create, update, or validate `SYSTEM.md` in conformance with
`architecture-system`.

Primary question:

> What systems make up this project, and what does each one own?

## Use This Skill When

- the canonical document is missing
- major capabilities or ownership boundaries are unclear
- repository structure is misleading the conceptual system model
- new or changed capabilities require the system decomposition to be updated
- architecture work needs a stable upstream inventory of major systems and interactions

## Do Not Use This Skill For

- explaining architectural layers or dependency direction better owned by `ARCHITECTURE.md`
- documenting APIs, modules, packages, or source files in detail
- writing deployment topology or infrastructure configuration
- sequencing future work or release plans
- using framework or vendor boundaries as the system model by default

## Required Inputs

Resolve:

- governing specification and version
- upstream purpose, vision, foundations, ontology, and other domain-defining documents
- the major capabilities the project must provide
- known system boundaries, external relationships, and overlapping ownership conflicts
- contradictions, assumptions, and open questions in the current system model

## Optional Inputs

Use when available:

- `PERSONAL_MODEL.md` or other domain-specific context documents
- existing diagrams or component inventories
- accepted ADRs that constrain capability ownership

Missing evidence must be recorded rather than invented.

## Workflow

1. Read `library/organization/specs/architecture/foundation/system.spec.md`.
2. Read the upstream identity, foundation, and domain documents before naming systems.
3. Identify major capabilities first, then group them into cohesive systems.
4. Assign one primary owner for each capability and make boundaries explicit.
5. Describe major high-level interactions and external relationships without collapsing into implementation or source layout.
6. Keep the decomposition conceptual so temporary repository organization does not dictate the model.
7. If evidence conflicts, preserve the disagreement, label assumptions, and report provisional or blocked completion.
8. Draft or update `SYSTEM.md` using `templates/SYSTEM.template.md`.
9. Validate with `references/validation-checklist.md` and `references/authoring-guide.md`.

## Output Contract

Produce or update:

- `SYSTEM.md`
- governing specification identifier and version
- explicit system inventory, capability ownership, boundaries, and high-level interactions
- assumptions, contradictions, and open questions
- validation results
- downstream review recommendations for `ARCHITECTURE.md`, designs, or implementation planning

## Boundaries

`SYSTEM.md` owns the logical decomposition into major systems, their purposes,
responsibilities, capability ownership, and high-level context.

It does not own module-level structure, architectural layer rules, detailed
APIs, deployment topology, or roadmap sequencing.

## Validation

Use [references/validation-checklist.md](references/validation-checklist.md)
for mandatory checks and
[references/authoring-guide.md](references/authoring-guide.md) for
capability, ownership, and anti-pattern guidance.

## Blocked or Provisional Outcomes

If major capabilities are not yet understood, if ownership boundaries are
contested, or if the evidence only supports an implementation artifact list, do
not fabricate a stable system model. Report whether the outcome is blocked,
provisional, or limited to a partial update.

## Completion Criteria

- [ ] `architecture-system` is identified as the governing specification.
- [ ] Required upstream evidence has been read.
- [ ] The primary question is answered directly.
- [ ] Major systems, capabilities, and ownership boundaries are explicit.
- [ ] Ownership boundaries with `ARCHITECTURE.md` and implementation artifacts are respected.
- [ ] Assumptions, contradictions, and open questions are visible.
- [ ] Acceptance criteria and package-level validation checks pass.