Skip to main content
skill CX Codex

best-practices · acedergren — Claude Code skill: OCI patterns and how to install

best-practices — an OCI architecture skill: sizes VCNs you won't have to rebuild, keeps subnets regional, and warns where Cloud Guard auto-fixes bite.

MIT 121 installs ★ 22 updated 2026-04-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add acedergren/oci-agent-skills --skill best-practices -a claude-code
Open on GitHub

What best-practices does

The skill hands the agent OCI knowledge it otherwise lacks. CLI syntax shifts monthly, so guessing flags is a bad plan. Inside are the anti-patterns with command examples, plus notes on where Oracle Cloud behaves differently from AWS and Azure.

VCN sizing is the first trap. A /24 leaves 256 addresses, and a VCN can't be resized after creation — you build a new network and migrate into it. The skill says start at /16. Keep subnets regional: pinning one to a single availability domain removes the HA story, and AD names differ per tenancy, so query them rather than hardcoding.

On security, security lists apply to a whole subnet while NSGs attach to individual resources, and app-tier to database rules belong in an NSG. Cloud Guard auto-remediation deserves a read-only trial first: a responder that privatises a public bucket takes your site down. For the base layout the skill points at oracle-terraform-modules/landing-zone instead of hand-rolled modules.

What it helps with

  • Size a VCN CIDR that won't need a rebuild later
  • Spread production instances across three availability domains
  • Move app-to-database rules into an NSG
  • Tune Cloud Guard before a responder privatises a public bucket
  • Deploy the base layout from the Oracle landing zone modules

Example prompts for the agent

  • Plan the VCN for our OCI tenancy: which CIDR, and which subnets stay regional
  • Review this OCI Terraform for anti-patterns around availability domains
  • We're moving from AWS to OCI, walk me through the migration traps for the web and database tiers

How to install best-practices

1Skills CLI (Vercel)

npx skills add acedergren/oci-agent-skills --skill best-practices -a claude-code

2Manually: put the files in place

~/.claude/skills/best-practices/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/best-practices/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about best-practices

How do I install best-practices in Claude Code?

Run npx skills add acedergren/oci-agent-skills --skill best-practices -a claude-code. The skill lands at ~/.claude/skills/best-practices/SKILL.md.

What does best-practices do?

Covers OCI architecture calls: how large a VCN should be, why subnets stay regional, when an NSG beats a security list, and how to keep Cloud Guard from breaking production.

Does it work outside Claude?

Yes. There are install commands for Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode as well.

Source text

SKILL.md · MIT
---
name: best-practices
description: Use when architecting OCI solutions, migrating from AWS/Azure, designing multi-AD deployments, or avoiding common OCI anti-patterns. Covers VCN sizing mistakes, Cloud Guard gotchas, free tier specifics, OCI terminology confusion, and multi-AD patterns.
license: MIT
metadata:
  author: alexander-cedergren
  version: "2.0.0"
---

# OCI Best Practices - Expert Knowledge

## 🏗️ Use OCI Landing Zone Terraform Modules

**Don't reinvent the wheel.** Use [oracle-terraform-modules/landing-zone](https://github.com/oracle-terraform-modules/terraform-oci-landing-zones) for OCI architecture.

**Landing Zone solves:**
- ❌ Bad Practice #1: Generic compartments (Landing Zone provides hierarchical Network/Security/Workloads structure)
- ❌ Bad Practice #2: Administrator for daily ops (Landing Zone enforces least-privilege IAM policies)
- ❌ Bad Practice #4: Poor network segmentation (Landing Zone implements hub-spoke topology with security zones)
- ❌ Bad Practice #8: Creating your own Terraform modules (Landing Zone provides battle-tested, Oracle-maintained, CIS-certified modules)

**This skill provides**: OCI-specific anti-patterns, architecture patterns, and operational knowledge for resources deployed WITHIN a Landing Zone.

---

## ⚠️ OCI CLI/API Knowledge Gap

**You don't know OCI CLI commands or OCI API structure.**

Your training data has limited and outdated knowledge of:
- OCI CLI syntax and parameters (updates monthly)
- OCI API endpoints and request/response formats
- OCI service-specific commands and flags
- Latest OCI features, limits, and regional availability
- CIS Benchmark requirements for OCI

**When OCI operations are needed:**
1. Use exact CLI commands from skill references
2. Do NOT guess OCI CLI syntax or parameters
3. Do NOT assume API endpoint structures
4. Reference landing-zones skill for Terraform modules

**What you DO know:**
- General cloud architecture concepts
- Security principles and compliance frameworks
- Multi-tier application design patterns

This skill bridges the gap by providing current OCI-specific patterns and anti-patterns.

---

You are an OCI architecture expert. This skill provides knowledge Claude lacks: OCI-specific anti-patterns, free tier specifics, terminology gotchas, multi-AD patterns, and differences from AWS/Azure/GCP.

## NEVER Do This

❌ **NEVER use /24 or smaller VCN CIDR (cannot expand)**
```
# WRONG - VCN too small, cannot expand later (OCI limitation)
oci network vcn create --cidr-block "10.0.0.0/24"
# Only 256 IPs total, exhausted quickly

# WRONG - copying AWS habit (/16 VPC default)
# OCI supports larger: /16 to /30

# RIGHT - start with /16, plan for growth
oci network vcn create --cidr-block "10.0.0.0/16"
# 65,536 IPs, room for 256 /24 subnets

# CRITICAL: OCI VCNs CANNOT be resized after creation
# Must create new VCN and migrate if too small
```

**Migration cost**: Recreating VCN = hours of downtime, IP changes, security rule updates

❌ **NEVER use AD-specific subnets (breaks multi-AD HA)**
```
# WRONG - subnet tied to single AD
oci network subnet create \
  --vcn-id <vcn-ocid> \
  --cidr-block "10.0.1.0/24" \
  --availability-domain "fMgC:US-ASHBURN-AD-1"  # AD-specific!

# Problem: Can't launch instances in other ADs, no HA

# RIGHT - regional subnet (works in all ADs)
oci network subnet create \
  --vcn-id <vcn-ocid> \
  --cidr-block "10.0.1.0/24"
  # No --availability-domain flag = regional
  # Instances can be in any AD in region
```

**Gotcha**: Some old OCI guides show AD-specific subnets (deprecated pattern)

❌ **NEVER confuse Security Lists vs NSGs (different use cases)**
```
OCI has TWO network security mechanisms:

Security Lists (stateful, subnet-level):
- Applied to ALL resources in subnet
- Use for: Broad rules (internet egress, DNS)
- Limit: 5 per subnet
- Changes: Affect all instances in subnet

Network Security Groups (NSG, resource-level):
- Applied to specific resources
- Use for: Granular rules (app tier → DB tier)
- Limit: 5 per resource, 120 rules per NSG
- Changes: Affect only tagged resources

# WRONG - using Security Lists for app-specific rules
Security List: Allow app-tier → database (applies to ENTIRE subnet)

# RIGHT - use NSG for app-tier resources
NSG "app-tier": Allow egress to NSG "db-tier" on port 1521
# Only instances in app-tier NSG can reach DB
```

**Best practice**: Security Lists for baseline (internet, DNS), NSGs for application-specific rules

❌ **NEVER assume single-AD deployment is acceptable (no SLA)**
```
OCI Availability Domains (ADs):
- 3 ADs per region (most regions)
- Isolated fault domains
- <1ms latency between ADs

# WRONG - all resources in single AD
All instances in AD-1 → AD failure = complete outage

# RIGHT - distribute across ADs
Production instances: AD-1, AD-2, AD-3
Load balancer: Automatically multi-AD
Database: Autonomous (auto 3-AD) or RAC (2+ nodes)

SLA impact:
Single-AD: NO SLA (OCI doesn't guarantee)
Multi-AD: 99.95% SLA
```

**Critical**: Oracle **refuses** SLA claims for single-AD deployments in regions with 3 ADs

❌ **NEVER hardcode AD names (tenant-specific)**
```
# WRONG - AD names are tenant-specific, not portable
availability_domain = "fMgC:US-ASHBURN-AD-1"  # Only works in YOUR tenancy!

# Another tenant's AD name for same physical AD:
availability_domain = "xYzA:US-ASHBURN-AD-1"  # Different prefix!

# RIGHT - query AD names dynamically
data "oci_identity_availability_domains" "ads" {
  compartment_id = var.tenancy_ocid
}

resource "oci_core_instance" "web" {
  availability_domain = data.oci_identity_availability_domains.ads.availability_domains[0].name
}
```

**Why**: OCI generates unique AD prefixes per tenant for security isolation

❌ **NEVER enable Cloud Guard auto-remediation without testing**
```
Cloud Guard = OCI threat detection + auto-response

# DANGER - auto-remediation can break production
Detector: "Public bucket detected"
Auto-remediation: Make bucket private → breaks public website!

Detector: "Security list allows 0.0.0.0/0"
Auto-remediation: Remove rule → breaks internet access!

# SAFER approach:
1. Enable detectors (read-only mode first)
2. Review findings for 1-2 weeks
3. Tune responders to avoid false positives
4. Enable auto-remediation for trusted patterns only
```

**Gotcha**: Cloud Guard enabled by default in some tenancies, can auto-break things

❌ **NEVER assume you need Oracle Linux (common misconception)**
```
OCI supports:
✓ Oracle Linux (free, optimized)
✓ Ubuntu, CentOS, Rocky Linux (free)
✓ Windows Server (BYOL or license-included)
✓ Custom images (import your own)

# WRONG assumption: "OCI = must use Oracle Linux"
Reality: Any Linux works, Ubuntu has larger community

# Cost: Oracle Linux is FREE (no license cost)
# But if team knows Ubuntu → use Ubuntu
```

**Marketing confusion**: Oracle pushes Oracle Linux, but it's not required

## OCI Always-Free Tier (Exact Limits)

**Generous permanent free tier** (no credit card trial, no expiration):

### Compute
- **2 AMD VMs**: VM.Standard.E2.1.Micro (1/8 OCPU, 1 GB RAM each)
- **4 Arm OCPUs**: VM.Standard.A1.Flex (allocate as 1×4 OCPU or 4×1 OCPU)
  - Up to 24 GB total RAM (6 GB per OCPU)
  - **Example**: Run 4× 1OCPU/6GB Arm instances free forever

### Database
- **2 Autonomous Databases**: 1 OCPU each, 20 GB storage per ADB
  - Can be ATP or ADW
  - **Limit**: 2 total per tenancy across all regions

### Storage
- **Block volumes**: 200 GB total (2× 100 GB boot volumes + custom)
- **Object storage**: 10 GB Standard tier
- **Archive storage**: 10 GB Archive tier
- **Block volume backups**: 10 GB

### Networking
- **Load balancer**: 1 flexible LB, 10 Mbps bandwidth
- **VCN**: 2 VCNs per region (free, no OCID cost)
- **Public IPv4**: 1 reserved public IP free per region

### Observability
- **Monitoring**: 1 billion data points ingested
- **Logging**: 10 GB ingested per month
- **Notifications**: 1 million emails per month

### Always-Free Gotchas

**CRITICAL limits often missed**:
```
# Gotcha 1: 2 ADB limit is TENANCY-wide, not per region
Can have: 1 ATP in Phoenix + 1 ADW in Ashburn = 2 (limit reached)
Cannot: Add 3rd ADB in any region

# Gotcha 2: Arm instances must be VM.Standard.A1.Flex only
Cannot: Use newer A2 shapes (paid only)

# Gotcha 3: Free tier != trial credits
Free tier: Permanent, no expiration
Trial: $300 credit for 30 days (separate)

# Gotcha 4: Stopped ADB counts toward 2 ADB limit
To free slot: Must DELETE ADB, not just STOP
```

## OCI Terminology vs AWS/Azure

Migrating from AWS/Azure? **Terminology traps**:

| OCI Term | AWS Equivalent | Azure Equivalent |
|----------|---------------|------------------|
| **VCN** | VPC | Virtual Network |
| **Subnet** | Subnet | Subnet |
| **Security List** | VPC Security Group | NSG (network-level) |
| **NSG** | Security Group | Application Security Group |
| **DRG** | Virtual Private Gateway | VPN Gateway |
| **Compartment** | Resource Group / OU | Resource Group |
| **Tenancy** | Account | Subscription |
| **Region** | Region | Region |
| **AD (Availability Domain)** | Availability Zone | Availability Zone |
| **Fault Domain** | (within AZ) | Availability Set |
| **Dynamic Group** | IAM Role (for instances) | Managed Identity |
| **Instance Principal** | EC2 Instance Profile | Managed Identity |
| **OCIR** | ECR | Container Registry |
| **OKE** | EKS | AKS |

**Critical difference**: OCI has **both** Security Lists (subnet) **and** NSGs (resource). AWS only has Security Groups (resource-level).

## Multi-AD Architecture Patterns

**OCI multi-AD specifics**:

### AD Distribution Strategy

```
OCI Regions with 3 ADs (most regions):
- US: Phoenix, Ashburn
- UK: London
- DE: Frankfurt
- AU: Sydney, Melbourne

Pattern: Distribute instances across all 3 ADs

AD-1: Web tier (2 instances) + DB primary
AD-2: Web tier (2 instances) + DB standby
AD-3: Web tier (2 instances) + DB standby

Load Balancer: Automatically spans ADs
```

**Gotcha**: Some shapes only available in specific ADs (check first)

```bash
# Check shape availability by AD
oci compute shape list \
  --compartment-id <ocid> \
  --availability-domain "fMgC:US-ASHBURN-AD-1"
```

### Fault Domain Additional Layer

Within each AD, OCI has **Fault Domains** (FD):
- 3 FDs per AD
- Separate power, cooling, network
- <1ms latency within AD

```
Best practice: Spread instances across ADs AND FDs

AD-1:
  FD-1: Web instance 1
  FD-2: Web instance 2
  FD-3: Web instance 3

AD-2:
  FD-1: Web instance 4
  (repeat pattern)

Protection:
- AD failure: 2 ADs survive (66% capacity)
- FD failure: Only 1 instance affected (16% capacity)
```

**When to use FDs**: Only for extra-critical apps (adds complexity)

## Compartment Strategy Best Practices

**Compartment hierarchy** (OCI-specific IAM boundary):

```
Root Compartment (tenancy)
│
├─ SharedServices (networking, security)
│  ├─ Network (VCNs, DRGs)
│  └─ Security (Vault, KMS, Cloud Guard)
│
├─ Production
│  ├─ App1
│  │  ├─ Compute
│  │  ├─ Database
│  │  └─ Storage
│  └─ App2
│
├─ NonProduction
│  ├─ Development
│  ├─ Testing
│  └─ Staging
│
└─ Sandbox (developers, auto-cleanup)
```

**Key principles**:
1. **Billing separation**: Compartment tags enable cost reporting by environment
2. **IAM boundaries**: Policies scoped to compartments (least privilege)
3. **Quota isolation**: Separate limits per compartment
4. **Lifecycle**: Delete entire compartment = deletes all resources inside

**Anti-pattern**: Flat structure with no hierarchy (AWS account-per-env habit)

## Cost Optimization OCI-Specific

### Flex Shape Savings (Unique to OCI)

```
Fixed shapes (legacy):
VM.Standard2.4: 4 OCPUs, 60 GB RAM, $218/month

Flex shapes (right-size RAM independently):
VM.Standard.E4.Flex: 4 OCPUs, 16 GB RAM, $109/month (50% savings)

Flex advantage: Pay only for RAM you need
- 1 OCPU = 1-64 GB RAM configurable
- Most apps don't need 15GB per OCPU (fixed ratio)
```

**Migration**: Replace fixed shapes with Flex for 30-50% savings

### Arm Instance Savings (Generous Free Tier)

```
AMD instance: VM.Standard.E4.Flex (1 OCPU) = $0.03/hr
Arm instance: VM.Standard.A1.Flex (1 OCPU) = $0.01/hr (67% cheaper)

Always-Free Arm: 4 OCPUs free forever!

Use case: Web servers, CI/CD runners, dev environments
Limitation: ARM64 only (not all apps compatible)
```

**Gotcha**: Free tier is A1 shapes only, newer A2 shapes are paid

### Storage Tiering (Exact Prices)

| Tier | Cost/GB/Month | Use Case | Retrieval |
|------|--------------|----------|-----------|
| **Standard** | $0.0255 | Active data, frequent access | Instant, free |
| **Infrequent Access** | $0.0125 (51% off) | Backups, logs (accessed monthly) | Instant, $0.01/GB |
| **Archive** | $0.0024 (91% off) | Compliance, long-term retention | 1 hour, $0.01/GB |

**Lifecycle policy example**:
```
Day 0-30: Standard ($0.0255/GB/mo)
Day 31-90: Infrequent ($0.0125/GB/mo)
Day 91+: Archive ($0.0024/GB/mo)

1 TB data for 1 year:
Without tiering: $0.0255 × 1000 × 12 = $306/year
With tiering: $0.0255 × 1000 × 1 + $0.0125 × 1000 × 2 + $0.0024 × 1000 × 9 = $72/year
Savings: $234/year (76%)
```

## Security Zones (OCI-Unique)

**OCI Security Zones** = Infrastructure-level policy enforcement:

```
Security Zone enforces:
✓ All storage encrypted
✓ No public buckets
✓ No internet gateways in VCN
✓ All databases private endpoint only
✓ Cloud Guard enabled

Enforcement: API rejects violating requests (preventive, not detective)

Example:
oci os bucket create --public-access-type ObjectRead
→ FAILS if compartment is in Security Zone

Use case: Production, PCI-DSS, healthcare (mandatory controls)
```

**Gotcha**: Security Zones can break existing automation (test in dev first)

## Progressive Loading References

### OCI Well-Architected Checklist

**WHEN TO LOAD** [`oci-well-architected-checklist.md`](references/oci-well-architected-checklist.md):
- Running compliance checks against OCI tenancy
- Preparing for CIS OCI Foundations Benchmark audit
- Implementing automated security scanning
- Creating remediation scripts for common findings
- Setting up monitoring for drift detection

**Do NOT load** for:
- Quick anti-pattern reference (NEVER list above covers it)
- Architecture decisions (covered in this skill)
- Understanding OCI terminology (tables above)

### Official Oracle Documentation Sources

**Primary References** (50+ official sources scraped):
- [Well-Architected Framework for OCI](https://docs.oracle.com/en/solutions/oci-best-practices/)
- [OCI Architecture Center](https://docs.oracle.com/en/solutions/)
- [CIS OCI Foundations Benchmark](https://www.cisecurity.org/benchmark/oracle_cloud)
- [Security Best Practices](https://docs.oracle.com/en-us/iaas/Content/Security/Reference/security_best_practices.htm)
- [Compartment Design](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/managingcompartments.htm)
- [Network Architecture Patterns](https://docs.oracle.com/en/solutions/oci-best-practices/)

**Note**: All anti-patterns, terminology mappings, and Always-Free limits in this skill are derived from official Oracle documentation and A-Team Oracle blog

---

## When to Use This Skill

- Architecture design: Multi-AD patterns, compartment strategy, VCN sizing
- Migration from AWS/Azure: Terminology mapping, anti-pattern avoidance
- Cost optimization: Free tier planning, Flex shapes, storage tiering
- Security: Cloud Guard tuning, Security Zones, NSG vs Security Lists
- Production readiness: SLA requirements, HA patterns, fault tolerance

© alexander-cedergren · MIT · acedergren/oci-agent-skills

Similar skills

All skills for Cloud: AWS, Azure, GCP →

best-practices by other authors comes first.

best-practices MoizIbnYousaf best-practices transforms vague instructions into detailed coding prompts with verification steps, file context, and explicit constraints. Useful for complex implementation tasks. CX Codex +1 533installs best-practices mobbin The best-practices skill for Claude Code explains what Mobbin can and cannot do and how its skills work together. Read it before other Mobbin skills when asking about capabilities or starting a design task. CX Codex +1 1,800installs best-practices FradSer best-practices enforces language-specific standards and framework rules for TypeScript, Python, Go, Swift, and React. CX Codex +1 115installs best-practices web-quality-skills best-practices is a Claude Code skill for checking web code security, browser compatibility, and code quality. It runs on requests for a security review or code modernization. CX Codex +1 ★ 7,191repo stars cloud-architect josstei cloud-architect designs AWS, GCP, and Azure topologies and reviews infrastructure code for risk. Use it to compare cloud services or assess disaster recovery plans. CX Codex ★ 489repo stars terraform-module-library Seth Hobson terraform-module-library — a skill for writing reusable Terraform modules across AWS, Azure, GCP and OCI. Useful when cloud provisioning needs a consistent shape. CX Codex +1 15,615installs multi-cloud-architecture Seth Hobson The multi-cloud-architecture skill helps design systems across AWS, Azure, GCP, and OCI, compare services, and choose a migration or disaster recovery pattern. CX Codex +1 10,700installs oci oracle oci — a skill for Oracle Cloud Infrastructure tasks: setting up OKE clusters, writing Terraform for IAM, Exadata, networking, Security Zones, deploying Functions, configuring IoT Platform, and building Enterprise AI workflows. CX Codex +1 598installs oracle-cloud DauQuangThanh Guides Oracle Cloud Infrastructure architecture, generates OCI Terraform configurations, and assists with OKE and Autonomous Database setups. CX Codex +1 152installs azure-to-aws aws azure-to-aws is a Claude Code skill that plans moves from Microsoft Azure workloads to AWS. It starts on migration, service-mapping, and cloud-cost requests. CX Codex +1 574installs

From the same set9

monitoring-operations monitoring-operations — a skill for setting up OCI Monitoring metrics and alarms, and for figuring out why data stops showing up. Useful when an alarm stays silent or a metric disappears. CX Codex +1 1,400installs oracle-dba oracle-dba guides Oracle Autonomous Database administration on OCI, covering SQL_ID query tuning, wait events diagnosis, and cloud cost traps. CX Codex +1 145installs networking-management The networking-management skill guides OCI network design, connectivity debugging, VCN security, and egress routing decisions for agents working in infrastructure repositories. CX Codex +1 130installs compute-management compute-management — an OCI Compute skill for the agent: shape choice, service limits, instance costs and what to do when a launch fails. CX Codex +1 118installs database-management database-management — a skill for OCI Autonomous Database work: which connection service name to pick, why a password fails validation, what a stopped database still costs. CX Codex +1 108installs infrastructure-as-code The infrastructure-as-code Claude Code skill helps write Terraform for OCI and diagnose provider errors. It applies to state management, Resource Manager stacks, and OCI Landing Zones. CX Codex +1 106installs finops-cost-optimization The finops-cost-optimization Claude Code skill analyzes OCI spending and points out common sources of waste. It activates for bill investigations, budget planning, and cloud cost reviews. CX Codex +1 104installs iam-identity-management The iam-identity-management Claude Code skill covers OCI IAM policies and permission errors. It activates for dynamic group setup and IDCS integration work. CX Codex +1 104installs

Project sponsors

Companies that keep this analytics open