Audit & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The Audit & Logging system in SkillKit is a comprehensive mechanism designed to track, persist, and analyze activities within the ecosystem. It captures a wide range of events, including skill operations (installation, synchronization, execution), team activities, and plugin actions. This system ensures transparency, facilitates debugging through root cause analysis, and provides compliance tracking for all agent-based workflows.
The system is primarily composed of a core AuditLogger that manages data persistence and a CLI interface that allows users to query, export, and manage logs. Log data is stored within the .skillkit directory of a project, enabling localized auditing of all automated and manual actions performed by AI agents or developers.
Sources: packages/cli/src/commands/audit.ts:1-20, packages/core/src/audit/logger.ts
Core Architecture
The architecture relies on a centralized AuditLogger class that handles the lifecycle of log entries, from initial capture to storage and eventual rotation or clearing.
Components and Data Flow
The following diagram illustrates the flow of an audit event from its trigger point through the logging pipeline to storage and retrieval.
The system uses an in-memory buffer to optimize performance, automatically flushing entries to a flat-file log located in the .skillkit directory once a specific threshold is reached.
Sources: packages/core/src/audit/logger.ts, packages/core/src/audit/tests/logger.test.ts:43-55, packages/cli/src/commands/audit.ts:74-76
Data Structures
The primary data structure is the AuditEvent, which contains metadata regarding the operation performed.
| Field | Type | Description |
|---|---|---|
type | AuditEventType | Category of event (e.g., skill.install, skill.sync) |
action | string | Specific action performed |
resource | string | The target of the action (e.g., a skill name) |
success | boolean | Whether the operation completed successfully |
timestamp | Date | When the event occurred |
duration | number (optional) | Time taken in milliseconds |
error | string (optional) | Error message if the action failed |
user | string (optional) | The entity performing the action |
Sources: packages/core/src/audit/logger.ts, packages/cli/src/commands/audit.ts:110-130, packages/core/src/audit/tests/logger.test.ts:25-41
CLI Interface
The AuditCommand provides the user-facing interface for interacting with logs. It supports several subcommands for different management tasks.
Subcommands and Functionality
log/list*: Displays recent entries with optional filters.
- export: Saves log data to external files in JSON, CSV, or plain text formats.
- stats: Generates high-level metrics, including success rates and event distributions.
- clear: Performs maintenance by removing old entries based on a day-count threshold.
Sources: packages/cli/src/commands/audit.ts:9-40, packages/cli/src/commands/audit.ts:137-142
Query and Filter Options
The CLI allows for granular filtering of audit logs using the following parameters:
| Option | Shortcut | Description |
|---|---|---|
--type | -t | Filter by categories like skill.install or team.create |
--user | -u | Filter by the specific user or agent ID |
--resource | -r | Filter by the specific skill or resource affected |
--success | N/A | Show only successful operations |
--failed | N/A | Show only failed operations |
--since | N/A | Show events since an ISO 8601 date |
--limit | -l | Maximum number of entries to return (default: 50) |
Sources: packages/cli/src/commands/audit.ts:43-70, packages/cli/src/commands/audit.ts:211-248
Management and Maintenance
The AuditLogger includes built-in methods for maintaining log health and extracting insights.
Statistics and Insights
The stats() method aggregates data to provide a health overview of the system. This includes calculating the successRate (successful vs total events) and identifying topResources—the skills or items most frequently interacted with.
Log Export and Persistence
Logs can be exported for external analysis. The system supports three formats, allowing for integration with spreadsheets (CSV), other tools (JSON), or human review (Text).
// Example export logic from AuditLogger
const content = await logger.export({
format: 'json',
query: { types: ['skill.install'] }
});
Sources: packages/core/src/audit/tests/logger.test.ts:152-177, packages/cli/src/commands/audit.ts:144-157
Data Retention (Clear)
To prevent the .skillkit/audit.log from growing indefinitely, the system provides a clear(cutoffDate) method. This is accessible via the CLI using the --days flag, which calculates a cutoff date relative to the current time.
Sources: packages/core/src/audit/tests/logger.test.ts:179-206, packages/cli/src/commands/audit.ts:199-209
Integration with Development Workflow
Logging is integrated into the broader SkillKit development cycle. As noted in the contribution guidelines, logging is a critical component for identifying bugs and verifying that new adapters or translators function correctly under E2E testing scenarios.
- Testing: E2E tests specifically validate that audit logs are generated during
syncandlistoperations. - Debugging: The
Root Cause Analysismethodology leverages audit logs to "Gather Evidence," utilizing theAuditLoggerquery results to understand the causal chain of failures.
Sources: CONTRIBUTING.md, e2e/commands-settings.e2e.test.ts:250-265, packages/core/src/methodology/packs/debugging/root-cause-analysis/SKILL.md:45-55
Summary
The Audit & Logging system provides a robust framework for tracking agent activities and system health in SkillKit. By utilizing a buffered, file-based logging approach and a flexible CLI interface, it balances performance with comprehensive visibility. This module is essential for the "Design First" and "Root Cause Analysis" methodologies, providing the empirical data necessary to validate system behavior and resolve complex issues.