skills/magnus919_agent-skills
1
0
Fork 0
mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-18 23:16:38 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
dependabot/github_actions/actions/github-script-9
magnus919_agent-skills/crm/SKILL.md
T
Magnus HedemarkGitHubfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
 3256a87bcb feat(skill): add collaboration & business-app tool layer (Slack, Notion, email, CRM, payments) (#269) 
Adds five top-level operational tool skills, one per named tool:

- slack: messages, channels, threads, search, files, and webhook signature
  verification (HMAC-SHA256) via a bounded, stdlib-only slack-cli.
- notion: pages, database queries, search, and guarded page updates via
  notion-cli.
- email: transactional email via Twilio SendGrid (send, deliverability
  bounces/spam reports, Signed Event Webhook verification with a
  self-contained ECDSA P-256 verifier) via email-cli.
- crm: HubSpot CRM records, contact search, and deal pipeline views with
  guarded stage updates via crm-cli.
- stripe: read-only-first balance, payment, and subscription queries with
  a guarded period-end subscription cancellation via stripe-cli.

Each skill ships an executable script (--json output, --limit bounded reads,
--dry-run/--yes mutation gate), a human README with the five required
sections, a schema-v1 evals/evals.json with six output-quality cases, a dated
source index + operations reference, and a deterministic unittest suite run
by check-artifacts. All five are indexed in the top-level README and the
generated catalogs were regenerated. Eval coverage rises from 78/139 to
83/144.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2026-08-03 20:19:26 -04:00

113 lines
8.0 KiB
Markdown
Raw Permalink Blame History

---
name: crm
description: >-
Operate HubSpot CRM from a terminal or agent: list and search contact
records, view deal pipeline stages, and — with explicit confirmation — move
deals between stages, backed by a bundled crm-cli script that is read-only
by default and gates every stage change behind a --dry-run/--yes
confirmation. Use when an agent needs to answer questions about contacts or
deals, produce pipeline views, or apply a confirmed stage change. Do not use
for building HubSpot apps or workflow automations (that is HubSpot app
development), marketing/sequence automation, or other CRMs like Salesforce
(that is their own tooling).
license: MIT
compatibility: >-
The bundled crm-cli script runs on Python 3.9+ with only the standard
library. --help and all reads need no network beyond api.hubapi.com; live
reads require a HubSpot private app access token with the relevant object
scopes (crm.objects.contacts.read, crm.objects.deals.read) and network
access to api.hubapi.com.
metadata:
source: https://developers.hubspot.com/docs/api/crm/understanding-the-crm
source_index: references/00-source-index.md
research_checked: "2026-08-03"
---
# HubSpot CRM Operations
Use this skill to read and, with explicit confirmation, update HubSpot CRM data through the HubSpot CRM v3 API: contact records, contact search, deal pipeline views, and deal stage changes. This is a **tool skill** for one CRM vendor (**HubSpot**). Building HubSpot apps or workflows is application development; this skill owns the everyday agent workflow: answering "who is this contact?", "what is in the pipeline?", and applying a confirmed stage change.
## Operating contract
1. **Read-only discovery before any mutation.** List and search contacts, view deals and pipelines freely. The bundled `crm-cli` script makes reads without writing anything.
2. **Confirm the target, scope, and rollback path before acting.** Moving a deal to a new stage changes a shared pipeline that revenue reporting reads: it requires an explicit human directive naming the deal and the target stage, plus `--dry-run` preview and `--yes` confirmation through `crm-cli`. Stage moves are reversible but leave audit history — confirm before acting.
3. **Respect bounded reads.** HubSpot pages with `limit`; never page past what the task needs. `crm-cli --limit` caps every listing and search.
4. **Keep evidence bounded.** Quote short names, emails, amounts, and stage labels; never dump full records, tokens, or raw payloads into chat.
5. **Know the object model.** Contacts and deals are distinct objects with property maps; stage transitions must use a stage ID from the deal's pipeline (`pipelines list`), not a stage label.
## The crm-cli script
`scripts/crm-cli` is an agent-first, stdlib-only CLI over the HubSpot CRM v3 API. It covers the full issue scope: records, search, and pipeline views.
```bash
crm/scripts/crm-cli --help # no token or network needed
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 # preview
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes # confirmed
```
Exit codes: 0 success, 1 API error or failed check, 2 usage error. Stage changes are guarded: without `--dry-run` or `--yes` the script refuses with exit 1 and never calls the API. Reads are bounded by `--limit` (default 20, max 100).
## Operating loop
1. **Scope the question**: is this a lookup (who/what is in the CRM) or a change (move a deal)? Locate the object with `contacts search`/`contacts list` or `deals list`.
2. **Read with bounds**: `contacts get` for one record, `deals list` for the pipeline view (optionally filtered by pipeline and stage), `pipelines list` to resolve stage labels to IDs.
3. **Triage the answer**: map the question to evidence (contact details, deal amount/stage, pipeline distribution).
4. **Act with confirmation**: only a human directive to change, previewed with `--dry-run` and confirmed with `--yes`.
5. **Verify**: re-read the deal (`deals list --stage <target>`) and confirm the stage moved.
## Records, search, pipeline views
- **Contact records** (`/objects/contacts`): list (GET) or retrieve one (GET by ID); the CLI summarizes first/last name, email, company, and created date. Search (`POST /objects/contacts/search`) finds contacts by query text, bounded by `--limit`.
- **Deal pipeline views** (`/objects/deals`): list deals with amount, pipeline, and stage, optionally filtered to one pipeline or stage. `pipelines list` (`/pipelines/deals`) returns the pipelines with their stage IDs and labels — use the stage ID when filtering or updating.
- **Stage changes** (`PATCH /objects/deals/{id}`): a guarded mutation that sets the `dealstage` property. Preview the target stage with `--dry-run`, confirm with `--yes`, and verify with a follow-up read. Only stage moves are in scope; other deal property edits are application work.
## Access model
- HubSpot private app access tokens (`pat_...`) scope per object and read/write. Reads need `crm.objects.contacts.read` and `crm.objects.deals.read`; stage updates need `crm.objects.deals.write`.
- Records carry a `properties` map keyed by property names (e.g. `dealstage`, `dealname`, `amount`). Property values are strings; the CLI summarizes the fields this skill uses.
- Tokens are credentials: store in `HUBSPOT_TOKEN`, never in code, chat, or commits. Rotate a leaked token in the private app settings.
## Reference routing
| Load when | Reference |
|---|---|
| Sources, scope tables, refresh procedure | `references/00-source-index.md` |
| Endpoints, pagination, object model, stage updates, errors | `references/01-hubspot-crm-operations.md` |
## Included artifacts
- `scripts/crm-cli`: bounded, stdlib-only CLI (contacts list/get/search, deals list/update-stage, pipelines list; `--json`; `--limit`; mutations gated by `--dry-run`/`--yes`).
- `tests/test_crm_cli.py`: 13 deterministic tests against a stub HubSpot API, including the mutation gate and the read-only contract.
- `references/`: dated source index + HubSpot CRM operations reference.
- `evals/evals.json`: six output-quality evaluation cases for agent runs.
## Verification boundary
| Claim | Minimum evidence |
|---|---|
| A contact exists | `crm-cli contacts search --query ... --json` or `contacts get` returns the record |
| A pipeline view is accurate | `crm-cli deals list --json` returns deals with stage IDs and the filter applied |
| A stage label maps to an ID | `crm-cli pipelines list --json` returns the pipeline stage map |
| A stage change landed | `crm-cli deals update-stage --yes` exits 0 and a follow-up `deals list --stage` shows the deal |
| A mutation is safe to run | `crm-cli deals update-stage --dry-run` prints the exact deal + target stage |
## Hard boundaries
- Never move a deal without a human directive, `--dry-run` preview, and `--yes` confirmation — pipeline changes feed revenue reporting and audit history.
- Never claim a record is missing when the token may lack object scope; check the access model first.
- Never page reads past `--limit`; never dump full records, tokens, or raw payloads into chat.
- This skill operates the HubSpot CRM API. It does not build HubSpot apps or cover other CRMs.
## When not to use
- **Building HubSpot apps, workflow automations, or custom objects** — that is HubSpot app development; see [backend-engineering](../backend-engineering/SKILL.md) for service design.
- **Marketing, sequences, and email automation in HubSpot** — that is the HubSpot Marketing surface, not the CRM API this skill covers.
- **Other CRMs** (Salesforce, Pipedrive, Zoho) — each has its own API and tooling; this skill covers HubSpot.
- **CRM strategy, sales process design, or pipeline methodology** — that is organizational/strategy work, not an API operation.
Reference in New Issue View Git Blame Copy Permalink