Keep Your Agent's Codebase Clean with the architecture Skill

Where this fits

You're building an Electron app with a renderer, main process, and shared layers. Your agent just generated a new React hook and a bridge module — but where exactly do they live? Misplaced files cause import errors, broken IPC, and painful refactors. The architecture skill gives your agent a decision tree and reference docs so new code lands in the right directory the first time, every time.

Why agents benefit

• Deterministic file placement: Agents consult a decision tree for UI, IPC handlers, business logic, and workers, eliminating guesswork.
• Context-aware references: The skill loads only the relevant layer docs (renderer, process, or project layout), keeping token usage low.
• Structural compliance checks: When reviewing code, the agent can flag files that violate the project's conventions before a human does.
• Refactoring guidance: For converting single-file components to directories, the skill provides step-by-step structure rules.
• Scalable onboarding: New agents working on this repo immediately understand the monorepo layout without reading a 50-page wiki.

Practical scenarios

Adding a new IPC bridge

Your agent needs to expose a native file-picker to the renderer. Instead of dropping a handler into a random utility file, it reads references/process.md, creates the bridge in packages/desktop/src/process/bridge/, and wires the preload script correctly.

Reviewing a pull request for structure drift

A teammate manually placed a service in the renderer folder. Your agent runs a structural review, identifies the violation, and suggests the correct location under packages/desktop/src/process/services/ — citing the skill's reference.

Migrating a monolithic component

A 500-line React component needs splitting into a directory with subcomponents and hooks. The skill's decision tree guides the agent to renderer/components/, then outlines the subfolder pattern, preventing a tangled mess.

Add it to your agent workflow

Install the skill into your agent's skill directory:

npx skills add iOfficeAI/AionUi --skill architecture

Then, when your agent is about to create a new file, simply include in your prompt: "Use the architecture skill to determine placement." The agent will load the relevant reference and act accordingly. For a broader view of agent skills, check the OpenAgentSkill directory.

Compare before adopting

Before committing, compare this skill against your own project's conventions. Check: quality signals — does the repo have active issues and a responsive maintainer? Maintenance freshness — is the skill updated for recent Electron versions? Alternatives — do you already have a custom CONTRIBUTING.md or linting rules that cover this? Workflow fit — does your agent already know your structure from training data? If your project differs significantly from the AionUi layout, you may need to fork or adapt the skill.

Why it is worth tracking

With 32k+ stars on GitHub, this skill comes from a widely used open-source project, signaling real-world validation. The skill is narrowly scoped, well-documented, and actively maintained — exactly what you want for a structural convention. Track it if your agent frequently creates files in multi-process apps; even if you don't adopt it today, its decision-tree approach is a useful template for your own skills. Re-evaluate when your project's architecture evolves or when Electron's recommended patterns shift.