Skip to content

Claude Code Plugins & Skills

Three Claude Code plugins: two provide skills that teach Claude best practices for the Affinity SDK and CLI, and one installs the MCP server:

Plugin Best For Key Feature
sdk Python developers Type-safe SDK patterns
cli CLI power users CLI skill + API key guard hook
mcp Agentic workflows The MCP server (tools and guided prompts)

All plugins are installed from the xaffinity marketplace.

What are skills?

Skills are knowledge packages that Claude loads when relevant. They teach Claude domain-specific patterns, best practices, and gotchas—so you don't have to explain them in every prompt.

Looking for MCP?

For agentic workflows (meeting prep, pipeline management, warm intros), see the MCP Server documentation. The MCP server works with any MCP client, not just Claude.

Installation

Add the marketplace (one-time):

/plugin marketplace add yaniv-golan/affinity-sdk

Install the plugin(s) you need:

# For Python SDK development
/plugin install affinity-crm-sdk-unofficial@xaffinity

# For CLI usage + hooks
/plugin install affinity-crm-cli-xaffinity-unofficial@xaffinity

# For the MCP server
/plugin install affinity-crm-mcp-unofficial@xaffinity

You can install any combination. They complement each other.

SDK Plugin (affinity-python-sdk skill)

Teaches Claude the correct patterns for writing Python scripts with the Affinity SDK.

What the skill teaches Claude

Use typed IDs (not raw integers)

from affinity.types import PersonId, CompanyId

client.persons.get(PersonId(123))     # Correct
client.persons.get(123)               # Wrong - type error

Use context managers

with Affinity.from_env() as client:   # Correct
    ...

client = Affinity.from_env()          # May leak resources

Use read-only mode by default

from affinity.policies import Policies, WritePolicy

# Read-only (prevents accidental data modification); the client allows writes unless you set this
with Affinity.from_env(policies=Policies(write=WritePolicy.DENY)) as client:
    ...

Filter persons and companies on fields with find()

from affinity.criteria import Condition

# Affinity's search filters on field values (dropdown values are option ids)
page = client.persons.find(Condition("field-123", "is-any-of", [4]), limit=50)

# persons.list(filter=...) raises ValueError; name/email search is persons.search("jane")

Example prompts

  • "Write a script to export all companies to CSV"
  • "How do I filter persons by a custom field?"
  • "Get all entries from my Deal Pipeline list"

CLI Plugin (xaffinity-cli-usage skill)

Teaches Claude the correct patterns for running xaffinity CLI commands.

What the skill teaches Claude

  • Always use --readonly by default
  • Use --json for structured, parseable output
  • Run xaffinity config check-key --json to verify API key configuration
  • Use --all with caution (can be slow for large datasets)
  • --filter sends what Affinity's search can answer and re-checks the whole filter locally

Example prompts

  • "Export all my contacts to CSV"
  • "Find the company with domain acme.com"
  • "Show me all entries in my Deal Pipeline"

MCP Server

For agentic workflows like meeting preparation, interaction logging, and pipeline management, use the MCP server.

The MCP server is protocol-agnostic and works with any MCP client (Claude Desktop, Cursor, Windsurf, VS Code + Copilot, ChatGPT Desktop, and others).

Install via Claude Code:

/plugin install affinity-crm-mcp-unofficial@xaffinity

Full documentation: MCP Server

Managing Plugins

Updating

/plugin marketplace update
/plugin update affinity-crm-sdk-unofficial@xaffinity
/plugin update affinity-crm-cli-xaffinity-unofficial@xaffinity
/plugin update affinity-crm-mcp-unofficial@xaffinity

Uninstalling

/plugin uninstall affinity-crm-sdk-unofficial@xaffinity
/plugin uninstall affinity-crm-cli-xaffinity-unofficial@xaffinity
/plugin uninstall affinity-crm-mcp-unofficial@xaffinity

Known Issues

Plugin cache may be empty after fresh install

After a fresh install, the plugin cache directory may be empty — skills and hooks won't load. This is a known Claude Code platform issue (#17361, #13799).

Workaround: After installing, click "Update" (in Claude Cowork UI) or run a marketplace update (in Claude Code CLI) to force a cache refresh:

  • Claude Cowork: Go to plugin settings, select the xaffinity marketplace, and click Update
  • Claude Code CLI: 
    /plugin marketplace update xaffinity
/plugin update affinity-crm-cli-xaffinity-unofficial@xaffinity
/plugin update affinity-crm-sdk-unofficial@xaffinity

Then restart the session. You can verify the plugin loaded by checking if skills appear in the session.