systems-architecture
Skill1 starsChanged 10 days agoMITView on GitHub
Generates a high-level system architecture document by analyzing lifecycle documentation and identifying major actors, their interactions, and technologies used.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- vercel-react-best-practices/AGENTS.mdAGENTS.md
- application-lifecycle-traceSkill
- architecture-reviewSkill
- awsSkill
- codebase-mapperSkill
- code-review-frontendSkill
- comment-sickoSkill
- cspSkill
- demo-scriptSkill
- documentation-writerSkill
- dotnetSkill
- feature-orchestratorSkill
- frontend-patternsSkill
- lets-talk-about-itSkill
- nextjs-proxy-csp-hardeningSkill
- owasp-securitySkill
- pr-body-styleSkill
- prd-modeSkill
- prove-it-worksSkill
- security-reviewSkill
- simplifySkill
- sweSkill
- task-generation-modeSkill
- thermo-nuclear-code-quality-reviewSkill
- typescript-react-reviewerSkill
- typescript-strict-styleSkill
- vercel-react-best-practicesSkill
- whats-going-onSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Keep the diagram to major actors only.
- Distinctive: line 17
Do not recommend refactors unless explicitly asked.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Core Objective
Analyze lifecycle documentation and repository structure to generate a high-level system architecture document. The goal is to provide a "bird's-eye view" that identifies major logic centers, dependencies, and core technologies for new engineers.
Guardrails
- Derive architecture from lifecycle docs and source evidence, not guesses.
- Label uncertain ownership, boundaries, or data flow as assumptions.
- Keep the diagram to major actors only. Do not model every file or helper.
- Do not recommend refactors unless explicitly asked.
Mandated Output Structure
1. System Overview Diagram (Mermaid)
- Scale: 5–10 major actors (heavy logic components).
- Visuals: Labeled arrows for data/control flow; subgroups for deployment boundaries (containers, VMs, external services).
- Detail: Annotate with primary technologies or protocols.
2. Component Catalog
A table detailing major actors:
| Component Name | Technology/Framework | Primary Responsibility | Key Files (2-3) | Heavy Logic Description |
| Example: API Gateway | Node.js/Express | Auth and Routing | index.js, auth.js | Token lifecycle/validation |
3. Technology Stack Reference
Categorize keys technologies by layer:
- UI Layer: Frameworks and libraries.
- State/Logic Layer: Management patterns.
- Service/API Layer: Communication frameworks.
- Data Layer: Persistence and caching.
- External Dependencies: Third-party APIs and services.
4. Integration Points
Define communication methods:
- Protocol: (e.g., HTTP, IPC, WebSocket).
- Data Format: (e.g., JSON, Protobuf).
- Nature: Synchronous vs. Asynchronous.
5. Navigation Guide
Explicit pointers for onboarding:
- User Interactions: Reference specific lifecycle docs.
- Data Flow: Identify the starting component.
- Business Logic: Identify the primary logic engine.
Selection Guidelines (Filtering)
To maintain clarity and prioritize impact, follow these constraints:
- Major Actors Only: Include only components where significant logic resides. If its removal would require a major rewrite, include it.
- Exclusions: Omit simple pass-throughs, thin wrappers, utility libraries, pure UI components, and configuration-only files.
- Prioritization: Limit to a maximum of 10 major components.
Install:
npx skills add ChristopherAlphonse/calphonse-skills --skill systems-architecture
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.