---
slug: "cto-os-skills"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/rinaldofesta/cto-os-skills@main/README.md"
repo: "https://github.com/rinaldofesta/cto-os-skills"
source_file: "README.md"
branch: "main"
---
# CTO OS - Expert CTO Skills for Claude

> **Transform Claude into your expert CTO advisor** with 4 professional skills covering architecture decisions, engineering metrics, technology roadmaps, and risk management.

---

## 🎯 What is CTO OS?

CTO OS is a collection of **4 expert Claude Skills** specifically designed for CTOs and engineering leaders. Each skill embeds proven methodologies and frameworks refined through real-world CTO experience.

Think of it like having an experienced CTO advisor available 24/7:

- 🏗️ **Architecture Decision Expert** - ADRs, tech stack evaluation, migration planning
- 📊 **Engineering Metrics Expert** - DORA metrics, KPIs, team health, executive reporting
- 🔮 **Technology Roadmap Expert** - Strategic planning, business alignment, capacity planning
- 🛡️ **Risk & Resilience Expert** - Security audits, incident response, compliance, disaster recovery

---

## 🚀 Quick Start - Install in 5 Minutes

### What You Need

- **Claude Desktop app** installed on your computer ([Download here](https://claude.ai/download))
- **5 minutes** of your time
- That's it! No coding or technical knowledge required

### Installation Steps

Follow these steps **exactly as written** - it's easier than it looks!

---

#### **Step 1: Open Claude Desktop**

1. Find the **Claude Desktop** app on your computer
   - Mac: Look in your Applications folder
   - Windows: Look in your Start menu
2. **Launch** the app (double-click it)

---

#### **Step 2: Open Settings**

Once Claude Desktop is open:

1. **Mac users**: Press `⌘` + `,` on your keyboard (that's the Command key + comma)

   - Or click **"Claude Desktop"** in the top menu → **"Settings"**

2. **Windows users**: Press `Ctrl` + `,` on your keyboard

   - Or click the **gear icon** ⚙️ in the top-right corner

3. You should now see the Settings window

---

#### **Step 3: Go to Skills Section**

In the Settings window:

1. Look for a tab or option called **"Skills"**
2. **Click on "Skills"**
3. You should see a list (might be empty if you haven't added skills before)

---

#### **Step 4: Add Your First Skill**

Now we'll add the **Architecture Decision Skill** (repeat these steps for each skill):

1. Click the **"Add Skill"** button

   - It might also say **"+"** or **"Add Local Skill"**

2. A file browser window will open

3. Navigate to where you downloaded/extracted the CTO OS skills:

   ```
   📁 cto-os-skills/
   ```

4. **Select this folder**: `cto-architecture-decision-skill`

   - Don't open it, just select the folder itself (it is advice to compress the skill folder in .zip)
   - The folder should have a `SKILL.md` file inside (you don't need to open it)

5. Click **"Open"** or **"Select Folder"**(it is advice to compress the skill folder in .zip) or **"Add"**

6. ✅ You should see "cto-architecture-decision" appear in your skills list!

---

#### **Step 5: Add the Other 3 Skills**

Repeat Step 4 three more times for:

1. **Second skill**: Select folder `cto-engineering-metrics-skill`
2. **Third skill**: Select folder `cto-technology-roadmap-skill`
3. **Fourth skill**: Select folder `cto-risk-resilience-skill`

When you're done, you should see **4 skills** in your Skills list:

- ✅ cto-architecture-decision
- ✅ cto-engineering-metrics
- ✅ cto-technology-roadmap
- ✅ cto-risk-resilience

---

#### **Step 6: Verify Installation**

Let's make sure everything works:

1. **Close** the Settings window
2. Start a **new chat** in Claude Desktop
3. Type this message:

```
Do you have the cto-architecture-decision skill loaded?
```

4. Claude should respond saying **yes** and describe what the skill does

**That's it! You're all set!** 🎉

---

## 🧪 Try Your New Skills

Now that your skills are installed, try these prompts:

### Test Architecture Decision Skill

```
I need to decide between PostgreSQL and MongoDB for our new
analytics feature. Help me create an Architecture Decision Record
evaluating both options based on our query patterns, scalability
needs, and team expertise.
```

### Test Engineering Metrics Skill

```
Set up DORA metrics tracking for my engineering team of 25 people.
We deploy to AWS and use GitHub. Create a dashboard design and
explain what each metric means for our stage (Series B startup).
```

### Test Technology Roadmap Skill

```
Create a 12-month technology roadmap for our B2B SaaS platform.
We need to balance platform modernization, new features, and
technical debt. Current stack: Rails monolith, PostgreSQL, React.
Business goal: prepare for enterprise customers.
```

### Test Risk & Resilience Skill

```
We're preparing for SOC 2 Type II certification. Create a
comprehensive security audit framework and compliance roadmap
with milestones. We're a 40-person startup with $5M ARR.
```

---

## 📚 What Each Skill Does

### 🏗️ Architecture Decision Skill

**What it's for**: Make and document critical architectural decisions systematically

**When to use**:

- Evaluating technology choices (databases, frameworks, cloud providers)
- Planning major migrations or refactoring
- Documenting architectural decisions for team alignment
- Assessing and prioritizing technical debt

**What you get**:

- Architecture Decision Records (ADRs) following best practices
- Trade-off analysis with clear criteria and scoring
- Step-by-step migration plans with risk mitigation
- Technical debt assessment with prioritized remediation roadmap

**Covers**:

- Tech stack evaluation (build vs buy, database selection, cloud architecture)
- Architecture patterns (microservices, event-driven, serverless)
- Migration strategies (big bang, strangler fig, phased approach)
- Technical debt quantification and prioritization

---

### 📊 Engineering Metrics Skill

**What it's for**: Define, track, and interpret engineering performance metrics

**When to use**:

- Setting up metrics and KPIs for your engineering organization
- Preparing board reports or executive updates
- Diagnosing engineering productivity issues
- Demonstrating engineering impact to business stakeholders

**What you get**:

- DORA metrics implementation guide (deployment frequency, lead time, MTTR, change failure rate)
- Custom KPI frameworks tailored to your organization's goals
- Executive dashboard designs with the right metrics for each audience
- Data interpretation playbooks that turn metrics into actionable insights

**Covers**:

- DORA metrics setup and interpretation
- Team health indicators (developer satisfaction, retention risk, velocity)
- Business impact metrics (engineering contribution to revenue, cost efficiency)
- Executive reporting templates by audience (CEO, board, engineering team)

---

### 🔮 Technology Roadmap Skill

**What it's for**: Create strategic technology roadmaps aligned with business goals

**When to use**:

- Annual or quarterly planning cycles
- Preparing for board meetings or investor discussions
- Aligning engineering with business strategy
- Capacity and resource planning

**What you get**:

- Multi-horizon roadmaps (12-month tactical, 3-year strategic)
- Business-engineering alignment frameworks
- Resource and capacity planning models
- Technology radar for tracking emerging technologies

**Covers**:

- Strategic roadmap creation with business alignment
- Innovation vs stability vs technical debt portfolio balancing
- Scenario planning for different growth trajectories
- OKR frameworks for engineering organizations
- Wardley mapping for strategic technology decisions

---

### 🛡️ Risk & Resilience Skill

**What it's for**: Identify, assess, and mitigate technical and operational risks

**When to use**:

- Planning security audits or compliance certifications
- After incidents to improve resilience
- Before major product launches or migrations
- Due diligence for funding rounds or acquisitions

**What you get**:

- Comprehensive risk assessment matrices
- Incident response playbooks and runbooks
- Compliance roadmaps (SOC 2, ISO 27001, GDPR, HIPAA)
- Business continuity and disaster recovery plans

**Covers**:

- Security risk assessment and mitigation
- Incident response planning and post-mortem frameworks
- Compliance certification roadmaps
- SLA/SLO/SLI definition and monitoring
- Chaos engineering and resilience testing
- Vendor risk management

---

## 💼 Common CTO Workflows

### Scenario 1: **Making a Major Technology Decision**

**Steps**:

1. **Architecture Decision Skill** → Create ADR comparing options
2. **Risk & Resilience Skill** → Assess security and operational risks
3. **Technology Roadmap Skill** → Plan migration timeline and milestones
4. **Engineering Metrics Skill** → Define success metrics for the migration

**Example**: "We're considering migrating from monolith to microservices"

---

### Scenario 2: **Preparing for Board Meeting**

**Steps**:

1. **Engineering Metrics Skill** → Generate executive dashboard and metrics report
2. **Technology Roadmap Skill** → Present strategic roadmap for next quarter
3. **Risk & Resilience Skill** → Summarize key risks and mitigation plans
4. **Architecture Decision Skill** → Highlight major technical decisions and rationale

**Example**: "Create board-ready engineering update for Q4"

---

### Scenario 3: **Planning Annual Strategy**

**Steps**:

1. **Technology Roadmap Skill** → Create 12-month strategic roadmap
2. **Architecture Decision Skill** → Document key architectural bets
3. **Engineering Metrics Skill** → Set OKRs and success metrics
4. **Risk & Resilience Skill** → Identify strategic risks and compliance needs

**Example**: "Define 2025 engineering strategy aligned with product roadmap"

---

### Scenario 4: **Scaling Engineering Organization**

**Steps**:

1. **Engineering Metrics Skill** → Benchmark current performance and identify gaps
2. **Technology Roadmap Skill** → Plan infrastructure scaling milestones
3. **Architecture Decision Skill** → Evaluate architecture changes for scale
4. **Risk & Resilience Skill** → Plan for increased operational complexity

**Example**: "We're growing from 20 to 60 engineers this year"

---

## ❓ Troubleshooting

### "I don't see the Skills tab in Settings"

**Solution**: Update Claude Desktop to the latest version

- Go to claude.ai/download and download the newest version
- Skills feature was added recently, older versions don't have it

---

### "I get an error when adding a skill"

**Common causes**:

1. **Wrong folder selected**

   - Make sure you select the folder that contains `SKILL.md`
   - Example: Select `cto-architecture-decision-skill` not just `cto-os-skills`

2. **File permissions**

   - Make sure the folder isn't in a restricted location
   - Try moving the skills folder to your Documents or Desktop

3. **YAML errors** (rare, but possible)
   - If you see "malformed YAML" or similar, report the issue
   - The skills should be pre-validated

---

### "Claude doesn't use the skill when I ask"

**Solutions**:

1. **Be specific in your request**

   - Instead of: "help me with architecture"
   - Try: "Create an ADR for choosing between PostgreSQL and MongoDB"

2. **Mention the skill explicitly** (optional)

   - "Using the cto-architecture-decision skill, help me..."

3. **Restart Claude Desktop**
   - Sometimes skills need a restart to fully activate

---

### "I want to remove a skill"

1. Open Settings → Skills
2. Find the skill in the list
3. Click the **trash/delete icon** next to it
4. Confirm deletion

---

## 💡 Tips for Best Results

### 1. Be Specific and Provide Context

```
❌ "Help me with metrics"
✅ "Set up DORA metrics for my 30-person engineering team. We're
   a Series B SaaS startup deploying to AWS 3x per week. Need to
   improve our lead time and change failure rate."
```

### 2. Share Your Constraints

```
✅ "We have 6 months and a $500K budget to migrate from
   PostgreSQL to a distributed database. We can't have
   downtime during business hours (9am-6pm EST)."
```

### 3. Specify Your Audience

```
✅ "Create a technology roadmap for board presentation -
   needs to be high-level, business-focused, and explain
   why we're prioritizing platform work over features."
```

### 4. Use Follow-ups for Refinement

The skills maintain context, so you can iterate:

```
First: "Create an ADR for microservices vs monolith"
Then: "Add a section on team structure implications"
Then: "Generate a migration plan assuming 12-month timeline"
```

---

## 📦 What's Included

Each skill contains:

```
cto-[name]-skill/
├── SKILL.md              ← Core methodology (150-200 lines)
└── references/           ← Detailed resources (loaded as needed)
    ├── frameworks/       ← Proven methodologies and patterns
    ├── templates/        ← Reusable templates (ADRs, reports, roadmaps)
    └── examples/         ← Real-world examples from successful CTOs
```

**Total**: 40+ files, ~15,000 lines of practical CTO expertise

---

## 🎓 About the Methodology

These skills embed methodologies and frameworks from:

- **Real CTO Experience** across startups to enterprises
- **Industry Best Practices** (DORA, SPACE, Wardley Mapping, ADRs)
- **Modern Engineering** (cloud-native, AI-assisted development, remote teams)
- **Executive Leadership** (board communication, strategic planning, ROI justification)

Each framework has been tested in real engineering organizations and proven to drive results.

---

## 🔐 Privacy & Data

- **Everything runs locally** in your Claude Desktop
- **Your data stays private** - not shared or stored by CTO OS
- **Standard Claude privacy** policies apply
- Skills only access data you explicitly share in conversations

---

## 📄 License

CTO OS Skills are commercial software:

- **License**: Commercial - License Required
- **Usage**: Licensed per user/organization
- **Distribution**: Contact for enterprise/team licensing

---

## 🆘 Support

### Getting Help

- **Documentation**: See individual SKILL.md files for detailed methodology
- **Issues**: Report problems or bugs
- **Questions**: General questions about usage

### Updates

We regularly improve the skills based on:

- User feedback
- Real-world usage
- New best practices and frameworks
- Changes in technology landscape

Check for updates periodically or contact us for the latest version.

---

## 🚀 What's Next

Once you're comfortable with the skills:

1. **Use them on real decisions** - the best way to learn
2. **Combine skills** - use multiple skills together for complex scenarios
3. **Customize outputs** - ask for specific formats or sections
4. **Share with team** - install on your engineering leadership team's Claude Desktop

---

## 🎯 Quick Reference Card

| I need to...                     | Use this skill        | Example prompt                                   |
| -------------------------------- | --------------------- | ------------------------------------------------ |
| Make a tech decision             | Architecture Decision | "Create an ADR for database selection..."        |
| Report to board/CEO              | Engineering Metrics   | "Create executive dashboard for..."              |
| Plan next quarter                | Technology Roadmap    | "Build 12-month roadmap aligned with..."         |
| Prepare for compliance           | Risk & Resilience     | "Create SOC 2 compliance roadmap for..."         |
| Evaluate build vs buy            | Architecture Decision | "Compare building vs buying for..."              |
| Set team goals                   | Engineering Metrics   | "Define OKRs and KPIs for..."                    |
| Plan a migration                 | Architecture Decision | "Create migration plan from X to Y..."           |
| Assess security risks            | Risk & Resilience     | "Conduct security risk assessment for..."        |
| Align engineering with business  | Technology Roadmap    | "Map technical initiatives to business goals..." |
| Improve incident response        | Risk & Resilience     | "Create incident response playbook for..."       |
| Measure engineering productivity | Engineering Metrics   | "Set up DORA metrics for..."                     |
| Plan for scale                   | Architecture Decision | "Evaluate architecture for 10x growth..."        |

---

**Ready to transform Claude into your expert CTO advisor?**

Follow the 5-minute installation guide above and start making better technical decisions! 🎯

---

**Version**: 1.0.0
**Last Updated**: October 18, 2025
**Designed for**: CTOs, VPs of Engineering, Engineering Directors