Upsun Agent Skill

A comprehensive agent skill for managing Upsun projects using the Upsun CLI.

Overview

This skill enables AI coding agents to help you manage Upsun projects through the Upsun CLI (v5.6.0+), covering:

• 130+ CLI commands across 30 namespaces
• Deployment workflows with safe production deployment patterns
• Environment management including branching, merging, and synchronization
• Backup and restore operations with verification and safety checks
• Resource scaling and autoscaling configuration
• Database operations for PostgreSQL, MongoDB, Redis, and Valkey
• Security and access management for teams and users
• Development tools including SSH, tunnels, and log access
• 7 helper scripts for health checks, pre-deployment validation, and automation

Installation

Prerequisites

1. Upsun CLI v5.6.0 or higher installed and authenticated

   # Install Upsun CLI (if not already installed)
   curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | VENDOR=upsun bash
   
   # Or via brew
   brew install platformsh/tap/upsun-cli
   
   # Authenticate
   upsun auth:browser-login

2. AI Coding Agent - OpenCode or compatible agent

Install the Skill

Option 1: Personal Skills Directory (Recommended)

Install for all your projects:

# For OpenCode
mkdir -p ~/.config/opencode/skills
cd ~/.config/opencode/skills
git clone https://github.com/upsun/opencode-skill.git upsun

Option 2: Project Skills Directory

Install for a specific project (shared with team via Git):

# From your project directory
mkdir -p .opencode/skills
cd .opencode/skills
git clone https://github.com/upsun/opencode-skill.git upsun

This method is ideal for teams - the skill is committed to Git and automatically available to all team members.

Option 3: Direct Download

Download and place in either skills directory:

1. Download from Releases
2. Extract to ~/.config/opencode/skills/upsun/ or .opencode/skills/upsun/
3. Ensure the SKILL.md file is present in the skill directory

Configure Permissions

OpenCode

Add permissions to your opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "permission": {
    "skill": {
      "upsun": "allow"
    },
    "bash": {
      "upsun *": "allow"
    }
  }
}

For granular control:

{
  "permission": {
    "skill": {
      "upsun": "allow"
    },
    "bash": {
      "upsun auth:*": "allow",
      "upsun environment:*": "allow",
      "upsun activity:*": "allow",
      "upsun backup:*": "allow",
      "upsun project:*": "allow",
      "upsun logs:*": "allow",
      "upsun resources:*": "allow",
      "upsun metrics:*": "allow"
    }
  }
}

Verify Installation

1. Open your AI coding agent in a project or terminal
2. Ask: "Can you help me deploy to Upsun?"
3. The agent should activate the Upsun skill and offer assistance

Usage

The skill activates automatically when you mention Upsun-related tasks:

• "Deploy to Upsun"
• "Create a new Upsun environment"
• "Backup the production environment"
• "Check Upsun environment status"
• "Scale Upsun resources"
• "Manage Upsun users"

Quick Start Examples

Deploy to production:

"Deploy my changes to the production environment on Upsun"

Create and test a feature branch:

"Create a new feature environment for testing my authentication changes"

Health check:

"Check the health of my production Upsun environment"

Backup before changes:

"Create a verified backup of production before I deploy"

Resource optimization:

"Audit resource usage across all my Upsun environments"

Features

Comprehensive Documentation

• 11 reference files covering all aspects of Upsun management
• 130+ commands documented with examples and best practices
• Progressive disclosure - only loads documentation as needed
• Cross-referenced - easy navigation between related topics

Helper Scripts

7 battle-tested scripts for common operations:

1. check-auth.sh - Verify Upsun authentication
2. health-check.sh - 8-step environment health check
3. pre-deploy-check.sh - Pre-deployment validation
4. backup-with-verification.sh - Create and verify backups
5. safe-restore.sh - Safe restore with automatic rollback
6. environment-status.sh - JSON status output for automation
7. resource-audit.sh - Multi-environment resource analysis

Workflow Coverage

• Safe production deployments
• Feature branch development
• Hotfix procedures
• Environment synchronization
• Disaster recovery
• Resource optimization
• Team management
• Database operations

Documentation

• SKILL.md - Main skill navigation and quick reference
• AGENTS.md - Development guide for contributing
• references/ - Detailed command documentation
• COMMAND-INDEX.md - Alphabetical command reference
• environments.md - Environment lifecycle
• deployments.md - Deployment patterns
• backups.md - Backup/restore procedures
• services-databases.md - Database operations
• resources-scaling.md - Resource management
• access-security.md - Security and access control
• integration-variables.md - Configuration
• development-tools.md - Developer tools
• projects-organizations.md - Project management
• troubleshooting.md - Common issues

Architecture

This skill uses a progressive disclosure architecture:

1. SKILL.md (entry point) - Workflow navigation and common operations
2. references/ (on-demand) - Detailed documentation loaded as needed
3. scripts/ (zero-context) - Executable helpers that only output results

This design minimizes context usage while providing comprehensive coverage.

Contributing

Contributions are welcome! See AGENTS.md for development guidelines.

Development Setup

# Clone the repository
git clone https://github.com/upsun/opencode-skill.git
cd opencode-skill

# Test helper scripts (requires Upsun authentication)
./.opencode/skills/upsun/scripts/check-auth.sh
./.opencode/skills/upsun/scripts/health-check.sh PROJECT_ID ENVIRONMENT_NAME

Adding Documentation

1. Update existing reference files in .opencode/skills/upsun/references/
2. Add cross-references to related documents
3. Update SKILL.md if adding commonly-used commands
4. Test that the agent can find and use the new documentation

Creating Scripts

1. Follow the template in existing scripts
2. Include proper error handling and authentication checks
3. Make executable: chmod +x .opencode/skills/upsun/scripts/new-script.sh
4. Test with real Upsun projects
5. Document in relevant reference files

Requirements

• Upsun CLI v5.6.0 or higher
• AI coding agent (OpenCode or compatible)
• Authenticated Upsun account
• Bash shell for helper scripts

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

• Upsun Documentation: https://docs.upsun.com
• Upsun CLI Reference: https://docs.upsun.com/administration/cli/reference.html
• OpenCode Documentation: https://opencode.ai/docs
• Issues: Please report issues on the GitHub repository

Acknowledgments

• Built for the Upsun Platform-as-a-Service
• Designed for OpenCode and compatible AI coding agents
• Utilizes Upsun CLI v5.6.0 command structure