Agent-Skills.md

Agent Skills: Velt Activity Logs Best Practices

Velt Activity Logs implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time activity feeds, custom activity logging, audit trails, CRDT debounce configuration, or server-side activity management via REST API.

UncategorizedID: velt-js/agent-skills/velt-activity-best-practices

Repository

velt-js/agent-skills
velt-js

Install this agent skill to your local

pnpm dlx add-skill https://github.com/velt-js/agent-skills/tree/HEAD/skills/velt-activity-best-practices

Skill Files

Browse the full folder contents for velt-activity-best-practices.

Download Skill

Loading file tree…

skills/velt-activity-best-practices/SKILL.md

Skill Metadata

Name
velt-activity-best-practices
Description
Velt Activity Logs implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time activity feeds, custom activity logging, audit trails, CRDT debounce configuration, server-side activity management via REST API, customizing the Activity Log wireframe with template variables (velt-data, velt-if, velt-class), or composing the VeltActivityLogWireframe sub-component tree (Header, Filter, List, DateGroup, Item, ShowMore, Empty, Loading).

Velt Activity Logs Best Practices

Comprehensive implementation guide for Velt's activity log system in React and Next.js applications. Contains 13 rules across 7 categories, prioritized by impact to guide automated code generation and integration patterns.

When to Apply

Reference these guidelines when:

  • Adding real-time activity feeds to a React/Next.js application
  • Subscribing to collaboration events via useAllActivities or getAllActivities
  • Creating custom activity records for non-Velt events
  • Configuring CRDT activity debounce to reduce feed noise
  • Enabling immutability for compliance audit trails
  • Filtering activities by feature type or action type
  • Managing activity records server-side via REST API
  • Customizing the Activity Log wireframe with template variables (velt-data, velt-if, velt-class)
  • Composing the VeltActivityLogWireframe sub-component tree (Header, Filter, List, DateGroup, Item, ShowMore, Empty, Loading)
  • Debugging activity log issues (records not appearing, null loading states)

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Core Setup | CRITICAL | core- | | 2 | Data Access | HIGH | data- | | 3 | Configuration | MEDIUM | config- | | 4 | Wireframe Variables | MEDIUM | wireframe-variables- | | 5 | UI Wireframes | MEDIUM | ui- | | 6 | REST API | LOW-MEDIUM | rest- | | 7 | Debugging & Testing | LOW-MEDIUM | debug- |

Quick Reference

1. Core Setup (CRITICAL)

  • core-setup — Enable Activity Logs in Velt Console
  • core-activity-log-component — Use VeltActivityLog component to display activity feed UI

2. Data Access (HIGH)

  • data-subscribe-hook — Use useAllActivities hook for real-time activity feeds (React)
  • data-subscribe-api — Use getAllActivities API for real-time activity subscriptions
  • data-create-custom-hook — Use useActivityUtils to create custom activities (React)
  • data-create-custom-api — Use getActivityElement API to create custom activities

3. Configuration (MEDIUM)

  • config-debounce — Configure CRDT activity debounce time
  • config-immutability — Enable immutability for audit trails
  • config-action-type-filters — Use action type constants for type-safe filtering

4. Wireframe Variables (MEDIUM)

  • wireframe-variables-activity-log — Bind Activity Log wireframe slots using velt-data, velt-if, velt-class, the cross-cutting defaultCondition prop, and Angular signal inputs ([componentConfigSignal], [parentLocalUIState])

5. UI Wireframes (MEDIUM)

  • ui-wireframes — Compose the VeltActivityLogWireframe sub-component tree (Header, Filter, List, DateGroup, Item, ShowMore, Empty, Loading) inside VeltWireframe

6. REST API (LOW-MEDIUM)

  • rest-api — Use REST APIs for server-side activity management

7. Debugging & Testing (LOW-MEDIUM)

  • debug-common-issues — Debug common activity log issues

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-setup.md
rules/react/data/data-subscribe-hook.md

Each rule file contains:

  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Source pointers to official documentation

Compiled Documents

  • AGENTS.md — Compressed index of all rules with file paths (start here)
  • AGENTS.full.md — Full verbose guide with all rules expanded inline