magnus919/agent-skills

HubSpot CRM-Operationen

Nutzen Sie diese Fähigkeit, um mit expliziter Bestätigung HubSpot CRM-Daten über die HubSpot CRM v3 API zu lesen und zu aktualisieren: Kontaktdatensätze, Kontaktsuche, Deal-Pipeline-Ansichten und Deal-Stufenänderungen. Dies ist eine Werkzeug-Fähigkeit für einen CRM-Anbieter (HubSpot). Die Entwicklung von HubSpot-Apps oder Workflows ist Anwendungsentwicklung; diese Fähigkeit beherrscht den alltäglichen Agenten-Workflow: Beantwortung von „Wer ist dieser Kontakt?“, „Was ist in der Pipeline?“ und Durchführung einer bestätigten Stufenänderung.

Betriebsvertrag

1. Nur-Lese-Erkundung vor jeder Änderung. Kontakte auflisten und suchen, Deals und Pipelines frei anzeigen. Das gebündelte crm-cli-Skript führt Lesevorgänge durch, ohne etwas zu schreiben.
2. Ziel, Umfang und Rollback-Pfad vor dem Handeln bestätigen. Das Verschieben eines Deals in eine neue Stufe ändert eine gemeinsame Pipeline, die von der Umsatzberichterstattung gelesen wird: Es erfordert eine explizite menschliche Anweisung, die den Deal und die Zielstufe benennt, sowie eine --dry-run-Vorschau und --yes-Bestätigung durch crm-cli. Stufenwechsel sind umkehrbar, hinterlassen jedoch einen Prüfpfad – bestätigen Sie vor dem Handeln.
3. Begrenzte Lesevorgänge respektieren. HubSpot seitiert mit limit; blättern Sie nie über das hinaus, was die Aufgabe benötigt. crm-cli --limit begrenzt jede Auflistung und Suche.
4. Nachweise begrenzt halten. Zitieren Sie kurze Namen, E-Mails, Beträge und Stufenbezeichnungen; geben Sie niemals vollständige Datensätze, Tokens oder rohe Nutzdaten in den Chat aus.
5. Das Objektmodell kennen. Kontakte und Deals sind separate Objekte mit Eigenschaftenzuordnungen; Stufenübergänge müssen eine Stufen-ID aus der Pipeline des Deals (pipelines list) verwenden, nicht eine Stufenbezeichnung.

Das crm-cli-Skript

scripts/crm-cli ist ein agentenorientiertes, nur-stdlib-CLI für die HubSpot CRM v3 API. Es deckt den gesamten Aufgabenbereich ab: Datensätze, Suche und Pipeline-Ansichten.

crm/scripts/crm-cli --help                                # kein Token oder Netzwerk erforderlich
crm/scripts/crm-cli --json --limit 20 contacts list
crm/scripts/crm-cli --json contacts get --id 51
crm/scripts/crm-cli --json contacts search --query "ada"
crm/scripts/crm-cli --json --limit 20 deals list
crm/scripts/crm-cli --json deals list --pipeline default --stage appointmentscheduled
crm/scripts/crm-cli --json pipelines list
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --dry-run   # Vorschau
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes       # bestätigt

Exit-Codes: 0 Erfolg, 1 API-Fehler oder fehlgeschlagene Prüfung, 2 Nutzungsfehler. Stufenänderungen sind geschützt: Ohne --dry-run oder --yes verweigert das Skript mit Exit 1 und ruft niemals die API auf. Lesevorgänge sind durch --limit begrenzt (Standard 20, maximal 100).

Betriebsablauf

1. Die Frage eingrenzen: Handelt es sich um eine Suche (wer/was ist im CRM) oder eine Änderung (Deal verschieben)? Finden Sie das Objekt mit contacts search/contacts list oder deals list.
2. Mit Begrenzung lesen: contacts get für einen einzelnen Datensatz, deals list für die Pipeline-Ansicht (optional gefiltert nach Pipeline und Stufe), pipelines list um Stufenbezeichnungen in IDs aufzulösen.
3. Die Antwort auswerten: Ordnen Sie die Frage den Nachweisen zu (Kontaktdetails, Deal-Betrag/Stufe, Pipeline-Verteilung).
4. Mit Bestätigung handeln: Nur eine menschliche Anweisung zur Änderung, mit --dry-run in der Vorschau und mit --yes bestätigt.
5. Überprüfen: Lesen Sie den Deal erneut (deals list --stage <target>) und bestätigen Sie, dass die Stufe verschoben wurde.

Datensätze, Suche, Pipeline-Ansichten

• Kontaktdatensätze (/objects/contacts): Auflisten (GET) oder einen abrufen (GET nach ID); das CLI fasst Vorname/Nachname, E-Mail, Firma und Erstellungsdatum zusammen. Suche (POST /objects/contacts/search) findet Kontakte nach Suchtext, begrenzt durch --limit.
• Deal-Pipeline-Ansichten (/objects/deals): Deals mit Betrag, Pipeline und Stufe auflisten, optional gefiltert nach einer Pipeline oder Stufe. pipelines list (/pipelines/deals) gibt die Pipelines mit ihren Stufen-IDs und Bezeichnungen zurück – verwenden Sie die Stufen-ID beim Filtern oder Aktualisieren.
• Stufenänderungen (PATCH /objects/deals/{id}): Eine geschützte Mutation, die die Eigenschaft dealstage setzt. Zeigen Sie die Zielstufe mit --dry-run in der Vorschau an, bestätigen Sie mit --yes und überprüfen Sie mit einer nachfolgenden Leseoperation. Nur Stufenwechsel sind im Umfang enthalten; andere Bearbeitungen von Deal-Eigenschaften sind Anwendungsarbeit.

Zugriffsmodell

• HubSpot Private-App-Zugriffstoken (pat_...) umfassen pro Objekt Lese- und Schreibberechtigungen. Lesevorgänge benötigen crm.objects.contacts.read und crm.objects.deals.read; Stufenaktualisierungen benötigen crm.objects.deals.write.
• Datensätze enthalten eine properties-Zuordnung, die nach Eigenschaftsnamen (z. B. dealstage, dealname, amount) indiziert ist. Eigenschaftswerte sind Zeichenketten; das CLI fasst die Felder zusammen, die diese Fähigkeit verwendet.
• Token sind Anmeldeinformationen: Speichern Sie sie in HUBSPOT_TOKEN, niemals in Code, Chat oder Commits. Ein durchgesickertes Token in den Private-App-Einstellungen rotieren.

Referenz-Routing

Laden, wenn	Referenz
Quellen, Umfangstabellen, Aktualisierungsverfahren	references/00-source-index.md
Endpunkte, Paginierung, Objektmodell, Stufenaktualisierungen, Fehler	references/01-hubspot-crm-operations.md

Enthaltene Artefakte

• scripts/crm-cli: Begrenztes, nur-stdlib-CLI (contacts list/get/search, deals list/update-stage, pipelines list; --json; --limit; Mutationen geschützt durch --dry-run/--yes).
• tests/test_crm_cli.py: 13 deterministische Tests gegen eine stub HubSpot API, einschließlich des Mutationsschutzes und des Nur-Lese-Vertrags.
• references/: Datierte Quellenübersicht + HubSpot CRM-Operations-Referenz.
• evals/evals.json: Sechs Ausgabequalitäts-Bewertungsfälle für Agentenläufe.

Überprüfungsgrenze

Behauptung	Mindestnachweis
Ein Kontakt existiert	crm-cli contacts search --query ... --json oder contacts get gibt den Datensatz zurück
Eine Pipeline-Ansicht ist korrekt	crm-cli deals list --json gibt Deals mit Stufen-IDs und dem angewendeten Filter zurück
Eine Stufenbezeichnung wird einer ID zugeordnet	crm-cli pipelines list --json gibt die Pipeline-Stufenzuordnung zurück
Eine Stufenänderung wurde durchgeführt	crm-cli deals update-stage --yes beendet mit 0 und eine nachfolgende deals list --stage zeigt den Deal
Eine Mutation ist sicher auszuführen	crm-cli deals update-stage --dry-run gibt den genauen Deal + die Zielstufe aus

Harte Grenzen

• Niemals einen Deal ohne menschliche Anweisung, --dry-run-Vorschau und --yes-Bestätigung verschieben – Pipeline-Änderungen fließen in die Umsatzberichterstattung und den Prüfpfad ein.
• Niemals behaupten, ein Datensatz fehle, wenn das Token möglicherweise keinen Objektumfang hat; überprüfen Sie zuerst das Zugriffsmodell.
• Niemals Lesevorgänge über --limit hinaus blättern; niemals vollständige Datensätze, Tokens oder rohe Nutzdaten in den Chat ausgeben.
• Diese Fähigkeit bedient die HubSpot CRM API. Sie entwickelt keine HubSpot-Apps und deckt keine anderen CRMs ab.

Wann nicht zu verwenden

• Entwicklung von HubSpot-Apps, Workflow-Automatisierungen oder benutzerdefinierten Objekten – das ist HubSpot-App-Entwicklung; siehe backend-engineering für den Service-Entwurf.
• Marketing, Sequenzen und E-Mail-Automatisierung in HubSpot – das ist die HubSpot-Marketing-Oberfläche, nicht die CRM-API, die diese Fähigkeit abdeckt.
• Andere CRMs (Salesforce, Pipedrive, Zoho) – jedes hat seine eigene API und Werkzeuge; diese Fähigkeit deckt HubSpot ab.
• CRM-Strategie, Vertriebsprozessdesign oder Pipeline-Methodik – das ist organisatorische/strategische Arbeit, keine API-Operation.