nova-pai/.claude/docs/HOW-TO-ADD-SKILLS.md

# Ghid: Cum să Adaugi Noi Skills în Nova

## Procesul de Adăugare Skill Nou

### Pas 1: Creează Directorul Skill-ului

```bash
mkdir -p .claude/skills/[nume-skill]/
```

**Exemple**:
- `.claude/skills/data-analysis/`
- `.claude/skills/code-review/`
- `.claude/skills/email-drafting/`

### Pas 2: Creează SKILL.md cu YAML Frontmatter

**Template**:

```markdown
---
name: [nume-skill]
description: "Descriere concisă ce face skill-ul și când să-l folosești. Maximum 2 fraze."
---

# [Nume Skill] Skill

## Prezentare

[1-2 paragrafe ce este skill-ul și ce face]

## Când să Folosești

[Listă cu situații când acest skill e relevant]
- Situație 1
- Situație 2
- etc.

## Pre-requisite

[Dacă skill-ul depinde de altceva]
- Prerequisit 1
- Prerequisit 2

## Proces de Execuție

### Pas 1: [Nume Pas]

[Descriere detaliată]

**Input necesar**:
- Item 1
- Item 2

**Output așteptat**:
- Rezultat 1
- Rezultat 2

### Pas 2: [Nume Pas]

[Continuă...]

## Tools Necesare

[Ce tools din sistem vei folosi]
- `WebSearch` - pentru X
- `Write` - pentru Y
- etc.

## Template de Lucru

[Dacă există un template util]

```
[Template aici]
```

## Exemple Complete

### Exemplu 1: [Scenariu Simplu]

**Input**: "..."

**Execuție**:
```
1. Pas 1
2. Pas 2
3. Pas 3
```

**Output**: [Descriere rezultat]

### Exemplu 2: [Scenariu Complex]

[Similar...]

## Troubleshooting

### Problem: [Problemă comună]

**Soluție**: [Cum să rezolvi]

### Problem: [Altă problemă]

**Soluție**: [Soluție]

## Best Practices

### ✅ DO
- Practice 1
- Practice 2

### ❌ DON'T
- Anti-pattern 1
- Anti-pattern 2

## Integrare cu Alte Skills

[Dacă skill-ul se combină cu altele]

- Folosește împreună cu `[skill-name]` pentru [use case]
- După `[skill-name]`, folosește acest skill pentru [next step]

## Note Importante

[Orice avertismente sau considerații speciale]

---

**Versiune**: 1.0
**Ultima actualizare**: [DATA]
**Autor**: [NUME]
```

### Pas 3: Actualizează context/claude.md

Adaugă skill-ul în lista de skills disponibile:

```markdown
## Subsisteme Disponibile

### 4. Skills System (`~/.claude/skills/`)

**Skills disponibile**:
- `web-research/` - Cercetare avansată pe web
- `research-report/` - Generare rapoarte profesionale
- `[nou-skill]/` - [Descriere scurtă]  ← ADAUGĂ AICI
```

### Pas 4: (Opțional) Creează Fișiere Suport

În directorul skill-ului poți adăuga:
- `template.md` - Template-uri
- `examples/` - Exemple detaliate
- `reference.md` - Documentație tehnică

---

## Exemple de Skills Noi

### Exemplu 1: Data Analysis Skill

```bash
mkdir -p .claude/skills/data-analysis/
```

**SKILL.md**:
```markdown
---
name: data-analysis
description: "Skill pentru analiza de date folosind pandas, numpy și matplotlib. Folosește pentru task-uri de statistică, vizualizare, și data cleaning."
---

# Data Analysis Skill

## Când să Folosești

- Utilizatorul cere analiza unui CSV/Excel
- Task-uri de statistică descriptivă
- Vizualizare date
- Data cleaning și preprocessing

## Proces de Execuție

### Pas 1: Încărcare Date

Folosește pandas pentru a citi fișierul:

```python
import pandas as pd
df = pd.read_csv('file.csv')
```

### Pas 2: Explorare Inițială

```python
# Overview
df.info()
df.describe()
df.head()

# Check missing values
df.isnull().sum()
```

[...continuă cu pașii]
```

### Exemplu 2: Code Review Skill

```bash
mkdir -p .claude/skills/code-review/
```

**SKILL.md**:
```markdown
---
name: code-review
description: "Skill pentru review profesional de cod: securitate, best practices, performanță, și mentenabilitate."
---

# Code Review Skill

## Când să Folosești

- Utilizatorul cere review la cod
- Pull request review
- Audit de securitate
- Optimizare performanță

## Proces de Execuție

### Pas 1: Citire și Înțelegere

1. Read fișierele de cod
2. Înțelege arhitectura
3. Identifică purpose-ul

### Pas 2: Analiza pe Categorii

**Securitate**:
- [ ] SQL injection
- [ ] XSS vulnerabilities
- [ ] Authentication issues
- [ ] Sensitive data exposure

**Best Practices**:
- [ ] Naming conventions
- [ ] Code organization
- [ ] DRY principle
- [ ] Error handling

[...continuă]
```

### Exemplu 3: Email Drafting Skill

```bash
mkdir -p .claude/skills/email-drafting/
```

**SKILL.md**:
```markdown
---
name: email-drafting
description: "Skill pentru compunerea de email-uri profesionale: business, recrutare, networking, follow-ups."
---

# Email Drafting Skill

## Când să Folosești

- "Scrie-mi un email către..."
- "Cum răspund la..."
- Networking outreach
- Follow-up messages

## Proces de Execuție

### Pas 1: Înțelege Contextul

**Întrebări cheie**:
- Cui scrii? (rol, relație)
- Ce vrei să obții?
- Ce ton e potrivit?
- Cât de formal?

### Pas 2: Structură Email

**Template standard**:
```
Subject: [Clear, specific, action-oriented]

[Greeting],

[Opening - context/reference]

[Body - main message in 2-3 paragraphs]

[Call to action - specific ask]

[Closing],
[Signature]
```

[...continuă cu exemple]
```

---

## Upgrade Skills Existente

### Adăugare Funcționalitate Nouă

1. **Editează SKILL.md**:
```bash
# Citește skill-ul existent
cat .claude/skills/web-research/SKILL.md

# Editează și adaugă secțiune nouă
```

2. **Adaugă noul proces/pas**

3. **Actualizează versiunea**:
```markdown
**Versiune**: 1.1  ← increment
**Ultima actualizare**: 2025-01-XX
**Changelog**:
- v1.1: Adăugat suport pentru [feature]
- v1.0: Versiune inițială
```

### Îmbunătățire Exemple

Adaugă mai multe exemple în secțiunea "Exemple Complete":

```markdown
### Exemplu 3: [Nou Scenariu]

[Descriere completă]
```

### Adăugare Troubleshooting

În secțiunea "Troubleshooting", adaugă noi probleme rezolvate:

```markdown
### Problem: [Problemă nouă descoperită]

**Cauză**: [De ce se întâmplă]
**Soluție**: [Pași de rezolvare]
**Prevenire**: [Cum să eviți în viitor]
```

---

## Upgrade Sistem General

### 1. Adăugare Nou Subsistem

**Exemplu**: Adăugare "Templates System"

```bash
mkdir -p .claude/context/templates/
```

Creează `templates/claude.md`:
```markdown
# Templates System

## Scop
[Descriere subsistem nou]

## Când să folosești
[Situații]

## Template-uri disponibile
- template-1
- template-2
```

Actualizează `context/claude.md`:
```markdown
### 5. Templates System (`~/.claude/context/templates/`)

**Scop**: [Scurt]
**Când să folosești**: [Scurt]
**Cum să accesezi**: [Instrucțiuni]
```

### 2. Adăugare Nou Tip Proiect

```bash
mkdir -p .claude/context/projects/[new-type]/
```

**Exemple**:
- `projects/finance/` - Analiză financiară
- `projects/marketing/` - Marketing content
- `projects/coding/` - Development projects

Creează `projects/[type]/claude.md` cu workflow specific.

### 3. Upgrade Tools Documentation

Editează `context/tools/claude.md`:

```markdown
### [Număr]. [Nume Tool Nou]

**Scop**: [Ce face]

**Când să folosești**: [Situații]

**Sintaxă**:
```
[Cod exemplu]
```

**Best Practices**:
- Practice 1
- Practice 2
```

---

## Checklist Post-Adăugare

După ce adaugi un skill nou:

- [ ] SKILL.md creat cu YAML frontmatter valid
- [ ] Toate secțiunile completate (minimum: Prezentare, Când să folosești, Proces, Exemple)
- [ ] Minim 2 exemple complete incluse
- [ ] Troubleshooting section adăugată
- [ ] context/claude.md actualizat cu noul skill
- [ ] Testat skill-ul într-o conversație
- [ ] Documentat în memory/learnings.md dacă e relevant

---

## Tips pentru Skills de Calitate

### ✅ Best Practices

1. **Claritate**: Scrie de parcă utilizatorul nu știe nimic despre task
2. **Completitudine**: Include toate edge cases
3. **Exemple**: Minimum 2, ideal 3-4 scenarii diferite
4. **Troubleshooting**: Anticipează problemele comune
5. **Tools specifice**: Listează exact ce tools folosești
6. **Integrare**: Menționează cum se combină cu alte skills

### ❌ Ce să Eviți

1. **Ambiguitate**: "Fă cercetare bună" (prea vag)
2. **Presupuneri**: Nu presupune cunoștințe implicite
3. **Lips exemple**: Skill fără exemple concrete
4. **Overflow**: Nu încărca TOT într-un singur skill (păstrează modular)
5. **Duplicate**: Nu duplica logic din alte skills

---

## Versioning Skills

**Schema**: `MAJOR.MINOR`

- **MAJOR** (1.0 → 2.0): Schimbări majore în proces/workflow
- **MINOR** (1.0 → 1.1): Adăugare features, îmbunătățiri

**Changelog format**:
```markdown
**Changelog**:
- v1.2: Adăugat suport pentru format X
- v1.1: Îmbunătățit troubleshooting section
- v1.0: Versiune inițială
```

---

## Testare Skills Noi

### Test Manual

1. **Citește skill-ul** într-o conversație nouă
2. **Execută task-ul** urmând pașii din skill
3. **Verifică output-ul** vs. așteptări
4. **Documentează** orice probleme în troubleshooting

### Test Integrat

1. **Combină cu alte skills**
2. **Verifică flow-ul** natural între skills
3. **Testează edge cases**

---

## Resurse

- **Template blank**: Vezi secțiunea "Template" de mai sus
- **Exemple existente**: `.claude/skills/web-research/` și `.claude/skills/research-report/`
- **Documentație**: `.claude/context/claude.md`

---

**Întrebări?** Consultă `context/claude.md` sau creează un issue în memory/learnings.md