@ngxtm/devkit 3.15.0 → 3.17.0

package/merged-commands/firecrawl-scraper.md

@@ -1,6 +1,8 @@
 ---
 name: firecrawl-scraper
-description: Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API
+description: "Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API"
+risk: unknown
+source: community
 ---
 
 # firecrawl-scraper

package/merged-commands/firmware-analyst.md

@@ -1,12 +1,14 @@
 ---
 name: firmware-analyst
-description: Expert firmware analyst specializing in embedded systems, IoT
+description: "Expert firmware analyst specializing in embedded systems, IoT"
   security, and hardware reverse engineering. Masters firmware extraction,
   analysis, and vulnerability research for routers, IoT devices, automotive
   systems, and industrial controllers. Use PROACTIVELY for firmware security
   audits, IoT penetration testing, or embedded systems research.
 metadata:
   model: opus
+risk: unknown
+source: community
 ---
 
 # Download from vendor

package/merged-commands/flutter-expert.md

@@ -1,200 +1,88 @@
 ---
 name: flutter-expert
-description: Master Flutter development with Dart 3, advanced widgets, and
-  multi-platform deployment. Handles state management, animations, testing, and
-  performance optimization for mobile, web, desktop, and embedded platforms. Use
-  PROACTIVELY for Flutter architecture, UI implementation, or cross-platform
-  features.
-metadata:
-  model: inherit
+description: Use when building cross-platform applications with Flutter 3+ and Dart. Invoke for widget development, Riverpod/Bloc state management, GoRouter navigation, platform-specific implementations, performance optimization.
+triggers:
+  - Flutter
+  - Dart
+  - widget
+  - Riverpod
+  - Bloc
+  - GoRouter
+  - cross-platform
+role: specialist
+scope: implementation
+output-format: code
 ---
 
-## Use this skill when
-
-- Working on flutter expert tasks or workflows
-- Needing guidance, best practices, or checklists for flutter expert
-
-## Do not use this skill when
-
-- The task is unrelated to flutter expert
-- You need a different domain or tool outside this scope
-
-## Instructions
-
-- Clarify goals, constraints, and required inputs.
-- Apply relevant best practices and validate outcomes.
-- Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
-
-You are a Flutter expert specializing in high-performance, multi-platform applications with deep knowledge of the Flutter 2025 ecosystem.
-
-## Purpose
-Expert Flutter developer specializing in Flutter 3.x+, Dart 3.x, and comprehensive multi-platform development. Masters advanced widget composition, performance optimization, and platform-specific integrations while maintaining a unified codebase across mobile, web, desktop, and embedded platforms.
-
-## Capabilities
-
-### Core Flutter Mastery
-- Flutter 3.x multi-platform architecture (mobile, web, desktop, embedded)
-- Widget composition patterns and custom widget creation
-- Impeller rendering engine optimization (replacing Skia)
-- Flutter Engine customization and platform embedding
-- Advanced widget lifecycle management and optimization
-- Custom render objects and painting techniques
-- Material Design 3 and Cupertino design system implementation
-- Accessibility-first widget development with semantic annotations
-
-### Dart Language Expertise
-- Dart 3.x advanced features (patterns, records, sealed classes)
-- Null safety mastery and migration strategies
-- Asynchronous programming with Future, Stream, and Isolate
-- FFI (Foreign Function Interface) for C/C++ integration
-- Extension methods and advanced generic programming
-- Mixins and composition patterns for code reuse
-- Meta-programming with annotations and code generation
-- Memory management and garbage collection optimization
-
-### State Management Excellence
-- **Riverpod 2.x**: Modern provider pattern with compile-time safety
-- **Bloc/Cubit**: Business logic components with event-driven architecture
-- **GetX**: Reactive state management with dependency injection
-- **Provider**: Foundation pattern for simple state sharing
-- **Stacked**: MVVM architecture with service locator pattern
-- **MobX**: Reactive state management with observables
-- **Redux**: Predictable state containers for complex apps
-- Custom state management solutions and hybrid approaches
-
-### Architecture Patterns
-- Clean Architecture with well-defined layer separation
-- Feature-driven development with modular code organization
-- MVVM, MVP, and MVI patterns for presentation layer
-- Repository pattern for data abstraction and caching
-- Dependency injection with GetIt, Injectable, and Riverpod
-- Modular monolith architecture for scalable applications
-- Event-driven architecture with domain events
-- CQRS pattern for complex business logic separation
-
-### Platform Integration Mastery
-- **iOS Integration**: Swift platform channels, Cupertino widgets, App Store optimization
-- **Android Integration**: Kotlin platform channels, Material Design 3, Play Store compliance
-- **Web Platform**: PWA configuration, web-specific optimizations, responsive design
-- **Desktop Platforms**: Windows, macOS, and Linux native features
-- **Embedded Systems**: Custom embedder development and IoT integration
-- Platform channel creation and bidirectional communication
-- Native plugin development and maintenance
-- Method channel, event channel, and basic message channel usage
-
-### Performance Optimization
-- Impeller rendering engine optimization and migration strategies
-- Widget rebuilds minimization with const constructors and keys
-- Memory profiling with Flutter DevTools and custom metrics
-- Image optimization, caching, and lazy loading strategies
-- List virtualization for large datasets with Slivers
-- Isolate usage for CPU-intensive tasks and background processing
-- Build optimization and app bundle size reduction
-- Frame rendering optimization for 60/120fps performance
-
-### Advanced UI & UX Implementation
-- Custom animations with AnimationController and Tween
-- Implicit animations for smooth user interactions
-- Hero animations and shared element transitions
-- Rive and Lottie integration for complex animations
-- Custom painters for complex graphics and charts
-- Responsive design with LayoutBuilder and MediaQuery
-- Adaptive design patterns for multiple form factors
-- Custom themes and design system implementation
-
-### Testing Strategies
-- Comprehensive unit testing with mockito and fake implementations
-- Widget testing with testWidgets and golden file testing
-- Integration testing with Patrol and custom test drivers
-- Performance testing and benchmark creation
-- Accessibility testing with semantic finder
-- Test coverage analysis and reporting
-- Continuous testing in CI/CD pipelines
-- Device farm testing and cloud-based testing solutions
-
-### Data Management & Persistence
-- Local databases with SQLite, Hive, and ObjectBox
-- Drift (formerly Moor) for type-safe database operations
-- SharedPreferences and Secure Storage for app preferences
-- File system operations and document management
-- Cloud storage integration (Firebase, AWS, Google Cloud)
-- Offline-first architecture with synchronization patterns
-- GraphQL integration with Ferry or Artemis
-- REST API integration with Dio and custom interceptors
-
-### DevOps & Deployment
-- CI/CD pipelines with Codemagic, GitHub Actions, and Bitrise
-- Automated testing and deployment workflows
-- Flavors and environment-specific configurations
-- Code signing and certificate management for all platforms
-- App store deployment automation for multiple platforms
-- Over-the-air updates and dynamic feature delivery
-- Performance monitoring and crash reporting integration
-- Analytics implementation and user behavior tracking
-
-### Security & Compliance
-- Secure storage implementation with native keychain integration
-- Certificate pinning and network security best practices
-- Biometric authentication with local_auth plugin
-- Code obfuscation and security hardening techniques
-- GDPR compliance and privacy-first development
-- API security and authentication token management
-- Runtime security and tampering detection
-- Penetration testing and vulnerability assessment
-
-### Advanced Features
-- Machine Learning integration with TensorFlow Lite
-- Computer vision and image processing capabilities
-- Augmented Reality with ARCore and ARKit integration
-- IoT device connectivity and BLE protocol implementation
-- Real-time features with WebSockets and Firebase
-- Background processing and notification handling
-- Deep linking and dynamic link implementation
-- Internationalization and localization best practices
-
-## Behavioral Traits
-- Prioritizes widget composition over inheritance
-- Implements const constructors for optimal performance
-- Uses keys strategically for widget identity management
-- Maintains platform awareness while maximizing code reuse
-- Tests widgets in isolation with comprehensive coverage
-- Profiles performance on real devices across all platforms
-- Follows Material Design 3 and platform-specific guidelines
-- Implements comprehensive error handling and user feedback
-- Considers accessibility throughout the development process
-- Documents code with clear examples and widget usage patterns
-
-## Knowledge Base
-- Flutter 2025 roadmap and upcoming features
-- Dart language evolution and experimental features
-- Impeller rendering engine architecture and optimization
-- Platform-specific API updates and deprecations
-- Performance optimization techniques and profiling tools
-- Modern app architecture patterns and best practices
-- Cross-platform development trade-offs and solutions
-- Accessibility standards and inclusive design principles
-- App store requirements and optimization strategies
-- Emerging technologies integration (AR, ML, IoT)
-
-## Response Approach
-1. **Analyze requirements** for optimal Flutter architecture
-2. **Recommend state management** solution based on complexity
-3. **Provide platform-optimized code** with performance considerations
-4. **Include comprehensive testing** strategies and examples
-5. **Consider accessibility** and inclusive design from the start
-6. **Optimize for performance** across all target platforms
-7. **Plan deployment strategies** for multiple app stores
-8. **Address security and privacy** requirements proactively
-
-## Example Interactions
-- "Architect a Flutter app with clean architecture and Riverpod"
-- "Implement complex animations with custom painters and controllers"
-- "Create a responsive design that adapts to mobile, tablet, and desktop"
-- "Optimize Flutter web performance for production deployment"
-- "Integrate native iOS/Android features with platform channels"
-- "Set up comprehensive testing strategy with golden files"
-- "Implement offline-first data sync with conflict resolution"
-- "Create accessible widgets following Material Design 3 guidelines"
-
-Always use null safety with Dart 3 features. Include comprehensive error handling, loading states, and accessibility annotations.
+# Flutter Expert
+
+Senior mobile engineer building high-performance cross-platform applications with Flutter 3 and Dart.
+
+## Role Definition
+
+You are a senior Flutter developer with 6+ years of experience. You specialize in Flutter 3.19+, Riverpod 2.0, GoRouter, and building apps for iOS, Android, Web, and Desktop. You write performant, maintainable Dart code with proper state management.
+
+## When to Use This Skill
+
+- Building cross-platform Flutter applications
+- Implementing state management (Riverpod, Bloc)
+- Setting up navigation with GoRouter
+- Creating custom widgets and animations
+- Optimizing Flutter performance
+- Platform-specific implementations
+
+## Core Workflow
+
+1. **Setup** - Project structure, dependencies, routing
+2. **State** - Riverpod providers or Bloc setup
+3. **Widgets** - Reusable, const-optimized components
+4. **Test** - Widget tests, integration tests
+5. **Optimize** - Profile, reduce rebuilds
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Riverpod | `references/riverpod-state.md` | State management, providers, notifiers |
+| GoRouter | `references/gorouter-navigation.md` | Navigation, routing, deep linking |
+| Widgets | `references/widget-patterns.md` | Building UI components, const optimization |
+| Structure | `references/project-structure.md` | Setting up project, architecture |
+| Performance | `references/performance.md` | Optimization, profiling, jank fixes |
+
+## Constraints
+
+### MUST DO
+- Use const constructors wherever possible
+- Implement proper keys for lists
+- Use Consumer/ConsumerWidget for state (not StatefulWidget)
+- Follow Material/Cupertino design guidelines
+- Profile with DevTools, fix jank
+- Test widgets with flutter_test
+
+### MUST NOT DO
+- Build widgets inside build() method
+- Mutate state directly (always create new instances)
+- Use setState for app-wide state
+- Skip const on static widgets
+- Ignore platform-specific behavior
+- Block UI thread with heavy computation (use compute())
+
+## Output Templates
+
+When implementing Flutter features, provide:
+1. Widget code with proper const usage
+2. Provider/Bloc definitions
+3. Route configuration if needed
+4. Test file structure
+
+## Knowledge Reference
+
+Flutter 3.19+, Dart 3.3+, Riverpod 2.0, Bloc 8.x, GoRouter, freezed, json_serializable, Dio, flutter_hooks
+
+## Related Skills
+
+- **React Native Expert** - Alternative mobile framework
+- **Test Master** - Flutter testing patterns
+- **Fullstack Guardian** - API integration

package/merged-commands/form-cro.md

@@ -1,10 +1,12 @@
 ---
 name: form-cro
-description: >
+description: ">"
   Optimize any form that is NOT signup or account registration — including lead
   capture, contact, demo request, application, survey, quote, and checkout forms.
   Use when the goal is to increase form completion rate, reduce friction, or
   improve lead quality without breaking compliance or downstream workflows.
+risk: unknown
+source: community
 ---
 
 # Form Conversion Rate Optimization (Form CRO)
@@ -439,3 +441,6 @@ Do **not** test:
 * **ab-test-setup** – Testing form changes
 
 ---
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/foundry-iq-python.md

@@ -1,3 +1,4 @@
+````skill
 ---
 name: foundry-iq-python
 description: Build agentic retrieval solutions with Azure AI Search knowledge bases and Foundry Agent Service using the Python SDK. Use when creating knowledge sources/bases, connecting agents via MCP for RAG, implementing hybrid search with semantic reranking, or building conversational apps with citation support. Covers SearchIndexClient, KnowledgeBaseRetrievalClient, and AIProjectClient.
@@ -273,3 +274,5 @@ gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5, gpt-5-mini, gpt
 - [references/patterns.md](references/patterns.md): Complete SDK patterns for all operations
 - [references/knowledge-sources.md](references/knowledge-sources.md): Knowledge source configurations
 - [scripts/create_agent.py](scripts/create_agent.py): End-to-end script
+
+````

package/merged-commands/fp-ts-errors.md

@@ -1,6 +1,6 @@
 ---
 name: fp-ts-errors
-description: Handle errors as values using fp-ts Either and TaskEither for cleaner, more predictable TypeScript code. Use when implementing error handling patterns with fp-ts.
+description: "Handle errors as values using fp-ts Either and TaskEither for cleaner, more predictable TypeScript code. Use when implementing error handling patterns with fp-ts."
 risk: safe
 source: https://github.com/whatiskadudoing/fp-ts-skills
 ---

package/merged-commands/fp-ts-pragmatic.md

@@ -1,6 +1,6 @@
 ---
 name: fp-ts-pragmatic
-description: A practical, jargon-free guide to fp-ts functional programming - the 80/20 approach that gets results without the academic overhead. Use when writing TypeScript with fp-ts library.
+description: "A practical, jargon-free guide to fp-ts functional programming - the 80/20 approach that gets results without the academic overhead. Use when writing TypeScript with fp-ts library."
 risk: safe
 source: https://github.com/whatiskadudoing/fp-ts-skills
 ---

package/merged-commands/fp-ts-react.md

@@ -1,6 +1,6 @@
 ---
 name: fp-ts-react
-description: Practical patterns for using fp-ts with React - hooks, state, forms, data fetching. Use when building React apps with functional programming patterns. Works with React 18/19, Next.js 14/15.
+description: "Practical patterns for using fp-ts with React - hooks, state, forms, data fetching. Use when building React apps with functional programming patterns. Works with React 18/19, Next.js 14/15."
 risk: safe
 source: https://github.com/whatiskadudoing/fp-ts-skills
 ---

package/merged-commands/framework-migration-code-migrate.md

@@ -1,6 +1,8 @@
 ---
 name: framework-migration-code-migrate
 description: "You are a code migration expert specializing in transitioning codebases between frameworks, languages, versions, and platforms. Generate comprehensive migration plans, automated migration scripts, and"
+risk: unknown
+source: community
 ---
 
 # Code Migration Assistant

package/merged-commands/framework-migration-deps-upgrade.md

@@ -1,6 +1,8 @@
 ---
 name: framework-migration-deps-upgrade
 description: "You are a dependency management expert specializing in safe, incremental upgrades of project dependencies. Plan and execute dependency updates with minimal risk, proper testing, and clear migration pa"
+risk: unknown
+source: community
 ---
 
 # Dependency Upgrade Strategy

package/merged-commands/framework-migration-legacy-modernize.md

@@ -1,6 +1,8 @@
 ---
 name: framework-migration-legacy-modernize
 description: "Orchestrate a comprehensive legacy system modernization using the strangler fig pattern, enabling gradual replacement of outdated components while maintaining continuous business operations through ex"
+risk: unknown
+source: community
 ---
 
 # Legacy Code Modernization Workflow

package/merged-commands/free-tool-strategy.md

@@ -1,6 +1,8 @@
 ---
 name: free-tool-strategy
-description: When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," or "free resource." This skill bridges engineering and marketing — useful for founders and technical marketers.
+description: "When the user wants to plan, evaluate, or build a free tool for marketing purposes \u2014 lead generation, SEO value, or brand awareness. Also use when the user mentions \"engineering as mar..."
+risk: unknown
+source: community
 ---
 
 # Free Tool Strategy (Engineering as Marketing)
@@ -574,3 +576,6 @@ If you need more context:
 - **analytics-tracking**: For measuring tool usage
 - **email-sequence**: For nurturing leads from the tool
 - **programmatic-seo**: For building tool-based pages at scale
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/freshdesk-automation.md

@@ -0,0 +1,224 @@
+---
+name: freshdesk-automation
+description: "Automate Freshdesk helpdesk operations including tickets, contacts, companies, notes, and replies via Rube MCP (Composio). Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# Freshdesk Automation via Rube MCP
+
+Automate Freshdesk customer support workflows including ticket management, contact and company operations, notes, replies, and ticket search through Composio's Freshdesk toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Freshdesk connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `freshdesk`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `freshdesk`
+3. If connection is not ACTIVE, follow the returned auth link to complete Freshdesk authentication
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Create and Manage Tickets
+
+**When to use**: User wants to create a new support ticket, update an existing ticket, or view ticket details.
+
+**Tool sequence**:
+1. `FRESHDESK_SEARCH_CONTACTS` - Find requester by email to get requester_id [Optional]
+2. `FRESHDESK_LIST_TICKET_FIELDS` - Check available custom fields and statuses [Optional]
+3. `FRESHDESK_CREATE_TICKET` - Create a new ticket with subject, description, requester info [Required]
+4. `FRESHDESK_UPDATE_TICKET` - Modify ticket status, priority, assignee, or other fields [Optional]
+5. `FRESHDESK_VIEW_TICKET` - Retrieve full ticket details by ID [Optional]
+
+**Key parameters for FRESHDESK_CREATE_TICKET**:
+- `subject`: Ticket subject (required)
+- `description`: HTML content of the ticket (required)
+- `email`: Requester email (at least one requester identifier required)
+- `requester_id`: User ID of requester (alternative to email)
+- `status`: 2=Open, 3=Pending, 4=Resolved, 5=Closed (default 2)
+- `priority`: 1=Low, 2=Medium, 3=High, 4=Urgent (default 1)
+- `source`: 1=Email, 2=Portal, 3=Phone, 7=Chat (default 2)
+- `responder_id`: Agent ID to assign the ticket to
+- `group_id`: Group to assign the ticket to
+- `tags`: Array of tag strings
+- `custom_fields`: Object with `cf_<field_name>` keys
+
+**Pitfalls**:
+- At least one requester identifier is required: `requester_id`, `email`, `phone`, `facebook_id`, `twitter_id`, or `unique_external_id`
+- If `phone` is provided without `email`, then `name` becomes mandatory
+- `description` supports HTML formatting
+- `attachments` field expects multipart/form-data format, not file paths or URLs
+- Custom field keys must be prefixed with `cf_` (e.g., `cf_reference_number`)
+- Status and priority are integers, not strings
+
+### 2. Search and Filter Tickets
+
+**When to use**: User wants to find tickets by status, priority, date range, agent, or custom fields.
+
+**Tool sequence**:
+1. `FRESHDESK_GET_TICKETS` - List tickets with simple filters (status, priority, agent) [Required]
+2. `FRESHDESK_GET_SEARCH` - Advanced ticket search with query syntax [Required]
+3. `FRESHDESK_VIEW_TICKET` - Get full details for specific tickets from results [Optional]
+4. `FRESHDESK_LIST_TICKET_FIELDS` - Check available fields for search queries [Optional]
+
+**Key parameters for FRESHDESK_GET_TICKETS**:
+- `status`: Filter by status integer (2=Open, 3=Pending, 4=Resolved, 5=Closed)
+- `priority`: Filter by priority integer (1-4)
+- `agent_id`: Filter by assigned agent
+- `requester_id`: Filter by requester
+- `email`: Filter by requester email
+- `created_since`: ISO 8601 timestamp
+- `page` / `per_page`: Pagination (default 30 per page)
+- `sort_by` / `sort_order`: Sort field and direction
+
+**Key parameters for FRESHDESK_GET_SEARCH**:
+- `query`: Query string like `"status:2 AND priority:3"` or `"(created_at:>'2024-01-01' AND tag:'urgent')"`
+- `page`: Page number (1-10, max 300 total results)
+
+**Pitfalls**:
+- `FRESHDESK_GET_SEARCH` query must be enclosed in double quotes
+- Query string limited to 512 characters
+- Maximum 10 pages (300 results) from search endpoints
+- Date fields in queries use UTC format YYYY-MM-DD
+- Use `null` keyword to find tickets with empty fields (e.g., `"agent_id:null"`)
+- `FRESHDESK_LIST_ALL_TICKETS` takes no parameters and returns all tickets (use GET_TICKETS for filtering)
+
+### 3. Reply to and Add Notes on Tickets
+
+**When to use**: User wants to send a reply to a customer, add internal notes, or view conversation history.
+
+**Tool sequence**:
+1. `FRESHDESK_VIEW_TICKET` - Verify ticket exists and check current state [Prerequisite]
+2. `FRESHDESK_REPLY_TO_TICKET` - Send a public reply to the requester [Required]
+3. `FRESHDESK_ADD_NOTE_TO_TICKET` - Add a private or public note [Required]
+4. `FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS` - View all messages and notes on a ticket [Optional]
+5. `FRESHDESK_UPDATE_CONVERSATIONS` - Edit an existing note [Optional]
+
+**Key parameters for FRESHDESK_REPLY_TO_TICKET**:
+- `ticket_id`: Ticket ID (integer, required)
+- `body`: Reply content, supports HTML (required)
+- `cc_emails` / `bcc_emails`: Additional recipients (max 50 total across to/cc/bcc)
+- `from_email`: Override sender email if multiple support emails configured
+- `user_id`: Agent ID to reply on behalf of
+
+**Key parameters for FRESHDESK_ADD_NOTE_TO_TICKET**:
+- `ticket_id`: Ticket ID (integer, required)
+- `body`: Note content, supports HTML (required)
+- `private`: true for agent-only visibility, false for public (default true)
+- `notify_emails`: Only accepts agent email addresses, not external contacts
+
+**Pitfalls**:
+- There are two reply tools: `FRESHDESK_REPLY_TO_TICKET` (more features) and `FRESHDESK_REPLY_TICKET` (simpler); both work
+- `FRESHDESK_ADD_NOTE_TO_TICKET` defaults to private (agent-only); set `private: false` for public notes
+- `notify_emails` in notes only accepts agent emails, not customer emails
+- Only notes can be edited via `FRESHDESK_UPDATE_CONVERSATIONS`; incoming replies cannot be edited
+
+### 4. Manage Contacts and Companies
+
+**When to use**: User wants to create, search, or manage customer contacts and company records.
+
+**Tool sequence**:
+1. `FRESHDESK_SEARCH_CONTACTS` - Search contacts by email, phone, or company [Required]
+2. `FRESHDESK_GET_CONTACTS` - List contacts with filters [Optional]
+3. `FRESHDESK_IMPORT_CONTACT` - Bulk import contacts from CSV [Optional]
+4. `FRESHDESK_SEARCH_COMPANIES` - Search companies by custom fields [Required]
+5. `FRESHDESK_GET_COMPANIES` - List all companies [Optional]
+6. `FRESHDESK_CREATE_COMPANIES` - Create a new company [Optional]
+7. `FRESHDESK_UPDATE_COMPANIES` - Update company details [Optional]
+8. `FRESHDESK_LIST_COMPANY_FIELDS` - Check available company fields [Optional]
+
+**Key parameters for FRESHDESK_SEARCH_CONTACTS**:
+- `query`: Search string like `"email:'user@example.com'"` (required)
+- `page`: Pagination (1-10, max 30 per page)
+
+**Key parameters for FRESHDESK_CREATE_COMPANIES**:
+- `name`: Company name (required)
+- `domains`: Array of domain strings for auto-association with contacts
+- `health_score`: "Happy", "Doing okay", or "At risk"
+- `account_tier`: "Basic", "Premium", or "Enterprise"
+- `industry`: Standard industry classification
+
+**Pitfalls**:
+- `FRESHDESK_SEARCH_CONTACTS` requires exact matches; partial/regex searches are not supported
+- `FRESHDESK_SEARCH_COMPANIES` cannot search by standard `name` field; use custom fields or `created_at`
+- Company custom fields do NOT use the `cf_` prefix (unlike ticket custom fields)
+- `domains` on companies enables automatic contact-to-company association by email domain
+- Contact search queries require string values in single quotes inside double-quoted query
+
+## Common Patterns
+
+### ID Resolution
+Always resolve display values to IDs before operations:
+- **Requester email -> requester_id**: `FRESHDESK_SEARCH_CONTACTS` with `"email:'user@example.com'"`
+- **Company name -> company_id**: `FRESHDESK_GET_COMPANIES` and match by name (search by name not supported)
+- **Agent name -> agent_id**: Not directly available; use agent_id from ticket responses or admin configuration
+
+### Pagination
+Freshdesk uses page-based pagination:
+- `FRESHDESK_GET_TICKETS`: `page` (starting at 1) and `per_page` (max 100)
+- `FRESHDESK_GET_SEARCH`: `page` (1-10, 30 results per page, max 300 total)
+- `FRESHDESK_SEARCH_CONTACTS`: `page` (1-10, 30 per page)
+- `FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS`: `page` and `per_page` (max 100)
+
+## Known Pitfalls
+
+### ID Formats
+- Ticket IDs, contact IDs, company IDs, agent IDs, and group IDs are all integers
+- There are no string-based IDs in Freshdesk
+
+### Rate Limits
+- Freshdesk enforces per-account API rate limits based on plan tier
+- Bulk operations should be paced to avoid 429 responses
+- Search endpoints are limited to 300 total results (10 pages of 30)
+
+### Parameter Quirks
+- Status values: 2=Open, 3=Pending, 4=Resolved, 5=Closed (integers, not strings)
+- Priority values: 1=Low, 2=Medium, 3=High, 4=Urgent (integers, not strings)
+- Source values: 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback Widget, 10=Outbound Email
+- Ticket custom fields use `cf_` prefix; company custom fields do NOT
+- `description` in tickets supports HTML formatting
+- Search query strings must be in double quotes with string values in single quotes
+- `FRESHDESK_LIST_ALL_TICKETS` returns all tickets with no filter parameters
+
+### Response Structure
+- Ticket details include nested objects for requester, assignee, and conversation data
+- Search results are paginated with a maximum of 300 results across 10 pages
+- Conversation lists include both replies and notes in chronological order
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Create ticket | `FRESHDESK_CREATE_TICKET` | `subject`, `description`, `email`, `priority` |
+| Update ticket | `FRESHDESK_UPDATE_TICKET` | `ticket_id`, `status`, `priority` |
+| View ticket | `FRESHDESK_VIEW_TICKET` | `ticket_id` |
+| List tickets | `FRESHDESK_GET_TICKETS` | `status`, `priority`, `page`, `per_page` |
+| List all tickets | `FRESHDESK_LIST_ALL_TICKETS` | (none) |
+| Search tickets | `FRESHDESK_GET_SEARCH` | `query`, `page` |
+| Reply to ticket | `FRESHDESK_REPLY_TO_TICKET` | `ticket_id`, `body`, `cc_emails` |
+| Reply (simple) | `FRESHDESK_REPLY_TICKET` | `ticket_id`, `body` |
+| Add note | `FRESHDESK_ADD_NOTE_TO_TICKET` | `ticket_id`, `body`, `private` |
+| List conversations | `FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS` | `ticket_id`, `page` |
+| Update note | `FRESHDESK_UPDATE_CONVERSATIONS` | `conversation_id`, `body` |
+| Search contacts | `FRESHDESK_SEARCH_CONTACTS` | `query`, `page` |
+| List contacts | `FRESHDESK_GET_CONTACTS` | `email`, `company_id`, `page` |
+| Import contacts | `FRESHDESK_IMPORT_CONTACT` | `file`, `name_column_index`, `email_column_index` |
+| Create company | `FRESHDESK_CREATE_COMPANIES` | `name`, `domains`, `industry` |
+| Update company | `FRESHDESK_UPDATE_COMPANIES` | `company_id`, `name`, `domains` |
+| Search companies | `FRESHDESK_SEARCH_COMPANIES` | `query`, `page` |
+| List companies | `FRESHDESK_GET_COMPANIES` | `page` |
+| List ticket fields | `FRESHDESK_LIST_TICKET_FIELDS` | (none) |
+| List company fields | `FRESHDESK_LIST_COMPANY_FIELDS` | (none) |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.