# Nutshell Skills Integration into Investibook - Executive Summary

> **Status**: Added to Worker Backlog
> **Priority**: P1 (High)
> **Estimated Time**: 2–3 days
> **Last Updated**: 2026-03-08

---

## 📋 Executive Summary

Integrate the **nutshell-skills knowledge base** maintained by the TiDB Cloud operations team into the Investibook platform, enabling users to access professional TiDB operations knowledge and tooling through the AI Agent, significantly enhancing the platform's operational insight capabilities.

---

## 🎯 Business Value

### Core Benefits

1. **Professional Knowledge Injection** – 11 battle-tested TiDB operations skills, including:
   - 33 performance-diagnosis Lark documents (covering Premium/Dedicated architecture differences)
   - HPA autoscaler quality-assessment methodology
   - TiKV performance-tuning decision tree
   - Complete Clinic API usage guide

2. **Zero Learning Curve** – Users do not need to learn any CLI tooling; skills are invoked from the Investibook UI via `@skill-name`.

3. **Knowledge Reuse** – nutshell-skills continues to serve CLI users while Investibook reuses the same knowledge base, avoiding dual maintenance.

4. **Continuous Updates** – When skills are updated, Investibook automatically gains the latest knowledge without a service restart.

---

## 🔍 Available Skills

| Skill | Description | Value |
|-------|-------------|-------|
| **tidb-perf-diagnosis** | TiDB performance-diagnosis knowledge base (33 Lark docs) | ⭐⭐⭐⭐⭐ Very High |
| **tikv-fast-tune** | TiKV performance-tuning decision tree | ⭐⭐⭐⭐ High |
| **clinic-api** | Clinic API queries (cluster metadata, topology) | ⭐⭐⭐⭐ High |
| **autoscaler-dashboard** | HPA autoscaler quality assessment and report generation | ⭐⭐⭐ Medium |
| **o11y-metrics-api** | O11Y platform Prometheus metrics queries | ⭐⭐⭐ Medium |
| **tidbcloud-api** | TiDB Cloud TiDBX API (cluster management) | ⭐⭐ Medium-Low |
| **o11y-data** / **o11y-data-export** | O11Y data export tools | ⭐⭐ Medium-Low |

---

## 💡 Technical Approach

### Selected Approach: OpenCode Skills Directory Integration (Recommended)

**Principle**: OpenCode natively supports loading external skills directories via the `skills.paths` field in its configuration file.

**Implementation Steps**:

```
1. Add nutshell-skills to the Dockerfile
   └── Clone to /opt/nutshell-skills/ at build time

2. Update opencode.json.template
   └── Add "skills": {"paths": ["/opt/nutshell-skills/skills"]}

3. Backend configuration injection
   └── Auto-substitute the {{SKILLS_DIR}} template variable

4. User invocation
   └── Type @clinic-api in the chat UI to reference a skill
```

### Advantages

- ✅ **No code changes** – Native OpenCode support; no conversion layer needed
- ✅ **Dynamic loading** – Skills are automatically injected into the Agent context
- ✅ **Live updates** – Modifying skills requires no pod restart
- ✅ **Namespace isolation** – `@skill-name` references are explicit capability names
- ✅ **Backward compatible** – nutshell-skills continues to serve CLI users

---

## 🎬 User Experience

### Usage Examples

**Scenario 1: Performance Diagnosis**

```
User:  Cluster latency suddenly spiked. Can you help diagnose it?
         ↓
Agent: [Automatically matches tidb-perf-diagnosis skill]
       Based on your cluster version (v8.5.x Premium), this is a typical
       Premium-architecture issue...

       Recommended checks:
       1. Verify whether the HPA autoscaler triggered a scale-out
       2. Inspect SharedPool resource contention
       3. Analyze TopSQL to identify slow query sources

[Users need not know the skill name — natural conversation is sufficient]
```

**Scenario 2: Cluster Information Query**

```
User:  Please look up the topology of cluster 10040083716234509777.
         ↓
Agent: [Automatically matches clinic-api skill; knows which bash function to call]
       Sure, let me query the cluster topology...
       [Executes clinic_get_topology("10040083716234509777")]

       Cluster topology:
       - TiDB:  3 nodes, 16C64G
       - TiKV:  6 nodes, 32C128G, 3 replicas
       - PD:    3 nodes

[The Agent automatically knows which bash function to invoke; users need no technical knowledge]
```

---

## 🚀 Implementation Plan

### Phase 1: Core Integration (1 day)

- [ ] Add nutshell-skills to Dockerfile (git clone at build time)
- [ ] Update opencode.json.template (add skills.paths)
- [ ] Inject SKILLS_DIR via backend configuration
- [x] Add skill-routing guidance to the system prompt
- [ ] Test in local development environment

### Phase 2: Validation & Optimization (1 day)

- [ ] Test successful skill execution
- [ ] Test skill failure handling and clear error reporting
- [ ] Create an example workspace demo
- [ ] Update documentation (README + user guide)

### Phase 3: Production Deployment (0.5 day)

- [ ] Build new Docker image
- [ ] Deploy to EKS
- [ ] Verify in production environment

**Total**: 2–2.5 days

**💡 Simplification note**: The System Prompt approach eliminates the need for a dedicated monitor process and extra config files.

---

## ⚠️ Considerations

1. **OpenCode only** – This approach applies only to the OpenCode Agent; Claude Agent does not support skills.
   - Supporting Claude Agent would require a "System Prompt injection" approach (estimated +1 day).

2. **Credential management** – Some skills require access credentials:
   - clinic-api: needs a Clinic API Key or Cookie
   - o11y-metrics-api: needs an Auth0 token
   - Resolution: provide credentials in the workspace's `.env` file or PVC configuration.

3. **Bash dependencies** – Skill scripts depend on tools such as `jq` and `curl`.
   - These tools are already included in the container image; no additional installation needed.

4. **Document size** – The performance-diagnosis skill knowledge base is large (~2,000 lines).
   - This may consume a significant portion of the context window, though OpenCode will intelligently load only the relevant sections.

---

## 📊 Success Metrics

### Technical Metrics

- [ ] Skills load success rate > 99%
- [ ] Agent response-time increase < 500 ms
- [ ] Skills invocation success rate > 95%

### Business Metrics

- [ ] Users invoking skills in > 30% of sessions
- [ ] Improved performance-diagnosis accuracy (measured via user feedback)
- [ ] Reduction in manual on-call interventions

---

## 📚 Related Documents

- **nutshell-skills Repository**: https://github.com/pingcap/nutshell-skills (to be confirmed)
- **OpenCode Skills Docs**: https://docs.opencode.ai/skills (to be confirmed)

---

## 👥 Stakeholders

- **Requester**: User-driven demand
- **Development Team**: Investibook / AIOps Team
- **Related Party**: nutshell-skills maintainers (CLI users)

---

## ✅ Recommendation

**Recommend starting immediately**, for the following reasons:

1. ✅ **Technically mature** – Native OpenCode support; zero risk
2. ✅ **Clear value** – Directly enhances the platform's operational capabilities
3. ✅ **Controlled timeline** – Completable in 2–3 days
4. ✅ **Well-defined requirements** – Driven by real user needs

**Next Steps**:
1. Technical review meeting (0.5 day)
2. Begin development immediately (2–3 days)
3. Production deployment (0.5 day)

Target: complete the full cycle from review to production within **1 week**.