Learn how to install Omni Architect and set up your development environment.
System Requirements Before installing Omni Architect, ensure your system meets these requirements:
Node.js Version 18.0.0 or higher required
Figma Account Active account with edit permissions
Package Manager npm 5.2+, yarn, or pnpm
Figma Token Personal access token with write permissions
Installation Methods Install via skills CLI (Recommended) npx skills add https://github.com/fabioeloi/omni-architect --skill omni-architect
This automatically installs the orchestrated dependencies:
mermaid-diagrams from softaworks/agent-toolkitfigma from hoodini/ai-agents-skillsprd-generator from jamesrochabrun/skillsfrontend-design from anthropics/skills Install dependencies manually If you prefer to install skills individually: npx skills add https://github.com/softaworks/agent-toolkit --skill mermaid-diagrams npx skills add https://github.com/hoodini/ai-agents-skills --skill figma npx skills add https://github.com/jamesrochabrun/skills --skill prd-generator npx skills add https://github.com/anthropics/skills --skill frontend-design
Install via skills CLI yarn dlx skills add https://github.com/fabioeloi/omni-architect --skill omni-architect
Verify installation yarn skills list | grep omni-architect
Install via skills CLI pnpm dlx skills add https://github.com/fabioeloi/omni-architect --skill omni-architect
Verify installation pnpm skills list | grep omni-architect
Clone and install locally For development or contributing: # Clone the repository git clone https://github.com/fabioeloi/omni-architect.git cd omni-architect # Install dependencies npm install # Run tests npm test # Run example npm run example
Getting Your Figma Access Token Omni Architect requires a Figma personal access token to generate design assets.
Access Settings
Click your profile icon in the top-right corner and select Settings .
Generate Token
Scroll to the Personal access tokens section
Click Create new token
Give it a descriptive name (e.g., “Omni Architect”)
Select the required scopes:
File content (Read and write)File comments (optional)
Keep your token secure and never commit it to version control!
Copy and Store
Copy the generated token and store it securely. You won’t be able to see it again. # Set as environment variable (recommended) export FIGMA_TOKEN = "figd_your_token_here" # Or add to your shell profile (~/.bashrc, ~/.zshrc) echo 'export FIGMA_TOKEN="figd_your_token_here"' >> ~/.zshrc
Finding Your Figma File Key The file key is required to specify where assets should be generated.
Figma URL structure: https://www.figma.com/file/<FILE_KEY>/Project-Name ^^^^^^^^^ This is your file key
Example: URL: https://www.figma.com/file/abc123XYZ/My-Design-System File Key: abc123XYZ
Verifying Installation Confirm everything is set up correctly:
Check Node.js version
node --version # Should output v18.0.0 or higher
Verify skill installation
Test Figma connection
# Test your Figma token curl -H "X-Figma-Token: $FIGMA_TOKEN " \ https://api.figma.com/v1/me # Should return your user info
Run validation
# Navigate to omni-architect directory (if cloned) cd omni-architect npm run validate # Should output: ✓ All validations passed
Configuration File (Optional) Create a persistent configuration file to avoid passing parameters every time:
# Create .omni-architect.yml in your project root touch .omni-architect.yml
Add your default settings:
project_name : "My Project" figma_file_key : "abc123XYZ" design_system : "material-3" locale : "pt-BR" validation_mode : "interactive" validation_threshold : 0.85 diagram_types : - flowchart - sequence - erDiagram - stateDiagram - C4Context design_tokens : colors : primary : "#4A90D9" secondary : "#7B68EE" success : "#2ECC71" error : "#E74C3C" typography : font_family : "Inter" heading_size : 24 body_size : 14 spacing : base : 8 scale : 1.5
With a config file, you can run: skills run omni-architect --prd_source "./prd.md" without specifying other parameters.
Environment Variables Supported environment variables for configuration:
Variable Description Required FIGMA_TOKENYour Figma personal access token Yes FIGMA_FILE_KEYDefault Figma file key No OMNI_LOCALEDefault locale (pt-BR, en-US, etc.) No OMNI_VALIDATION_MODEDefault validation mode No
Troubleshooting
If you see Error: Node.js 18.0.0 or higher is required: # Install Node.js 18+ using nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 18 nvm use 18
If skills command is not found: # Install skills CLI globally npm install -g @skills-sh/cli # Verify installation skills --version
Figma API 401 Unauthorized
If you get authentication errors:
Verify your token is correctly set: echo $FIGMA_TOKEN
Check token hasn’t expired in Figma settings
Ensure token has write permissions
Regenerate token if necessary
If you can’t write to the Figma file:
Verify you have edit permissions on the file
Check the file key is correct
Ensure you’re not using a view-only link
Try creating a new file and using its key
Installation hangs or times out
If installation is taking too long: # Clear npm cache npm cache clean --force # Try with verbose output npx skills add https://github.com/fabioeloi/omni-architect --skill omni-architect --verbose # Or use git clone method instead git clone https://github.com/fabioeloi/omni-architect.git
Uninstallation To remove Omni Architect:
# Remove the skill skills remove omni-architect # Remove configuration file rm .omni-architect.yml # Revoke Figma token (optional) # Go to Figma Settings > Personal access tokens > Delete
Next Steps
Quickstart Guide Run your first PRD transformation in 5 minutes
Configuration Customize diagram types and validation settings
Pipeline Phases Learn about each phase of the pipeline
Examples Explore real-world PRD examples
Getting Help If you encounter issues:
