Skip to content
AIOS

Building Blocks

AIOS is a file-based workflow layer for AI coding agents. It gives your agent durable files to read instead of relying on chat memory. Each artifact type has a specific job. This page explains what each one does and when you should reach for it.

Two Kinds of Files

Section titled “Two Kinds of Files”

When you set up AIOS, two directories appear:

DirectoryWhat It HoldsPurpose
.aios/Skills, templates, prompts, references, workflows, commands, integrationsTells the agent how to work
docs/Vision, PRD, design notes, architecture, ADRs, tasks, reviews, API contracts, context mapsTells the agent what to build

You can reuse the same .aios/ workflow kit across projects. Each project keeps its own docs/ context.

Artifact Types

Section titled “Artifact Types”
ArtifactWhat It IsExample
CLI CommandsNamed actions you run from the terminal. They create files, install kits, or validate projects.aios create task
Command PromptsMarkdown instructions in .aios/commands/ that tell the agent what to do when you invoke a command.Commands Folder
Numbered PromptsStep-by-step workflow prompts in .aios/prompts/. Numbered from 00 to 13 for the full development lifecycle..aios/prompts/01-generate-prd.md
SkillsReusable operating procedures for agents. They define inputs, process, outputs, and quality checks for a specific job.product-discovery, code-review
TemplatesStandard document formats. Fill them in to produce PRDs, ADRs, tasks, reviews, and other artifacts.prd.template.md
WorkflowsStep-by-step flows that orchestrate skills and templates for a lifecycle phase.new-feature.workflow.md
ReferencesStable engineering principles the agent should follow. They stay constant across tasks.testing-principles.md
Project DocsProduct vision, architecture, ADRs, tasks, reviews, and context maps in docs/.docs/product/prd.md
Native Agent FoldersAgent-specific skill copies (optional). The Markdown source remains canonical..agents/skills/, .qwen/skills/, .opencode/skills/, .agent/skills/

CLI Commands vs Prompts vs Skills

Section titled “CLI Commands vs Prompts vs Skills”

These three are easy to confuse:

  • CLI Commands run from your terminal. They create files, install assets, or validate projects. They do not write application code.
  • Command Prompts are Markdown files that tell the agent what procedure to follow when you invoke a command.
  • Skills are reusable agent procedures. You ask the agent to execute a skill (like product-discovery or code-review) and it follows the steps defined in the skill file.

When You Want X, Use Y

Section titled “When You Want X, Use Y”
I Want To…Use This
Start a new projectaios init <project-name> or aios starter <starter-name> <project-name>
Understand how AIOS worksThis guide and How It Works
Clarify a raw product ideaproduct-discovery skill or prompt 00-discover-product.md
Write a PRDprd-generator skill or prompt 01-generate-prd.md
Design architecturearchitecture-design skill or prompt 02-generate-architecture.md
Record a decisionadr-generator skill or prompt 03-generate-adr.md
Break work into taskstask-breakdown skill or prompt 04-generate-tasks.md
Plan implementationimplementation-planner skill or prompt 05-plan-implementation.md
Implement a tasktask-implementation skill or prompt 06-implement-task.md
Review code changescode-review skill or prompt 07-review-code.md
Write teststesting skill or prompt 08-generate-tests.md
Design an API contractapi-contract-design skill or prompt 09-design-api-contract.md
Plan a database migrationdatabase-migration skill or prompt 10-plan-database-migration.md
Do a security reviewsecurity-review skill or prompt 11-review-security.md
Prepare a releaserelease-management skill or prompt 12-plan-release.md
Design UI/UXui-ux-design skill or prompt 13-design-ui-ux.md
Section titled “Related Pages”