Files
skillkit/packages/core/README.md
Rohit Ghumare 1344d65b3d feat: implement phases 12-18 - complete agentic development platform (#6)
* feat: implement phases 12-18 - complete agentic development platform

This comprehensive update implements 7 major phases (12-18) transforming
SkillKit into a universal agentic development platform with methodology
packs, hooks, orchestration, planning, and AI capabilities.

Phase 12: Methodology Framework
- MethodologyManager for pack-based methodology distribution
- 5 methodology packs (testing, debugging, planning, collaboration, meta)
- 13 curated methodology skills
- Pack loader with validation and installation
- 56 comprehensive tests

Phase 13: Hooks & Automatic Triggering System
- HookManager with event-driven skill activation
- 10+ event types (session:start, file:open, task:start, etc.)
- Pattern-based triggers with glob support
- Agent-specific hook generation
- 29 comprehensive tests

Phase 14: Subagent Orchestration
- TeamOrchestrator for multi-agent coordination
- TaskManager with cross-agent assignment
- Plan approval workflow (submit → approve/reject)
- TeamMessageBus for agent communication
- Two-stage review system (spec compliance + code quality)
- 36 comprehensive tests

Phase 15: Structured Plan System
- PlanParser for markdown → structured plan conversion
- PlanValidator for completeness checking
- PlanExecutor with dry-run support
- Bite-sized task format (2-5 min atomic tasks)
- 36 comprehensive tests

Phase 16: Slash Commands & Agent Integration
- CommandRegistry for slash command management
- Agent-specific command generation (Claude, Cursor, OpenCode)
- Command aliases and arguments support
- 42 comprehensive tests

Phase 17: Enhanced Agent Features
- Permission system (allow/deny/ask patterns)
- Glob pattern matching for file-scoped skills
- Bootstrap files (AGENTS.md, SOUL.md, TOOLS.md)
- Multi-mode support (Code/Architect/Debug/Ask)
- Agent feature tests

Phase 18: Advanced Features (AI & Audit)
- AIManager with natural language skill search
- Automatic skill generation from examples/code
- MockAIProvider for testing without API keys
- AuditLogger with complete operation trail
- Query, export (JSON/CSV/text), and statistics
- 37 comprehensive tests (15 AI + 22 audit)

CLI Commands Added:
- skillkit methodology list|install|sync
- skillkit hook add|remove|list|generate
- skillkit plan parse|validate|execute|create
- skillkit commands generate|list
- skillkit ai search|generate|similar
- skillkit audit log|export|stats|clear

TUI Enhancements:
- Methodology screen (o key) for pack browsing
- Plan screen (n key) for plan viewing/execution
- Updated navigation and sidebar

Test Coverage:
- Total: 619 tests passing (582 core + 49 agents + 1 cli + 3 app)
- New: 245+ tests for phases 12-18
- Coverage maintained at 80%+

Breaking Changes: None
Dependencies: No new external dependencies added

* fix: apply CodeRabbit security and quality improvements

Security Fixes:
- Replace custom glob-to-regex with minimatch to prevent ReDoS vulnerabilities
- Fix regex pattern generation in globs.ts using battle-tested library
- Eliminate unsafe regex patterns in modes.ts and permissions.ts

Code Quality Improvements:
- Use shared GlobMatcher utility to eliminate code duplication in modes.ts
- Preserve command metadata on updates to prevent data loss
- Fix single-file vs directory output path handling in command.ts
- Pass --strict flag through to plan validator

Race Condition & Concurrency Fixes:
- Add Promise-based mutex to prevent race condition in audit logger flush()
- Handle both sync and async event listeners to prevent unhandled rejections
- Maintain synchronous event emission while safely handling async listeners

Data Integrity Fixes:
- Fix dependency checking to detect missing dependencies
- Rehydrate Date fields when importing tasks from JSON
- Fix executePlan to properly detect incomplete tasks

State Management:
- Add validation for missing step executor (fail fast)
- Handle cancellation and reset executor state in finally block
- Add 'cancelled' status and event to PlanStatus/PlanEvent types

Dependencies:
- Add minimatch@^10.0.1 to @skillkit/agents package

All 639 tests passing.

* docs: update READMEs with Phase 10-18 features

- Root README: add minimal "What's New in v1.5.0" section with 5 bullet points
- packages/core: add usage examples for Team, Plugin, Methodology, Orchestration, Plan, Hooks
- packages/cli: add command sections for team, plugin, methodology, plan, hook, command
- packages/tui: add screen descriptions for Marketplace, Workflow, Execute, Team, Plugins, Methodology, Plan, Memory
- apps/skillkit: expand with practical usage examples for all new features

All updates are clean, user-focused, and avoid AI marketing fluff.

* fix: resolve multiple code quality and robustness issues

- Fix minimatch dependency: downgrade to ^9.0.0 for Node 18 compatibility
- Fix command.ts export: handle directory paths and ensure parent directories exist
- Fix command.ts merge: preserve curated examples when merging commands
- Fix plan.ts: filter empty entries from comma-separated inputs
- Fix audit logger pagination: respect explicit 0 for limit and offset
- Fix audit logger: gracefully handle malformed JSON lines without data loss
- Fix team orchestrator: prevent task assignment to non-idle agents
- Fix plan executor: unblock waitIfPaused() when cancel() is called

All 639 tests passing.

* fix: additional robustness improvements for plan and executor

- Fix plan.ts createPlan: filter empty strings from techStack after split/trim
- Fix executor.ts: re-check abort signal after waitIfPaused() in both execute() and executeTask()
  to prevent running additional tasks/steps after cancellation during pause

All 639 tests passing.
2026-01-24 11:54:47 +00:00

8.8 KiB

@skillkit/core

npm version License

Core engine for SkillKit - skill discovery, cross-agent translation, recommendations, session memory, testing, and workflow orchestration.

Installation

npm install @skillkit/core

Key Features

  • Skill Discovery: Find and parse SKILL.md files from any source
  • Cross-Agent Translation: Convert skills between 17 agent formats (Claude Code, Cursor, Windsurf, etc.)
  • Project Context Detection: Analyze project stack, dependencies, and configurations
  • Smart Recommendations: AI-powered skill suggestions based on project profile
  • Session Memory: Capture and persist learnings across AI coding sessions
  • Skill Testing: Test framework with assertions for skill validation
  • Workflow Orchestration: Compose skills into multi-step workflows
  • Marketplace Aggregation: Browse and search curated skill repositories
  • Team Collaboration: Share skill bundles with Git-based remote sync
  • Plugin System: Extend with custom translators, providers, and commands
  • Methodologies: 5 development frameworks (Agile, TDD, DevOps, Design Thinking, Feature Flags)
  • Multi-Agent Orchestration: Coordinate teams of AI agents with task assignment
  • Plan System: Parse, validate, and execute structured development plans
  • Hooks & Automation: Auto-trigger skills on file changes, git events

Usage

Skill Discovery

import { findAllSkills, discoverSkills, parseSkill } from '@skillkit/core';

// Find all installed skills
const skills = findAllSkills(['.claude/skills', '.cursor/skills']);

// Discover skills from a repository
const repoSkills = await discoverSkills('anthropics/skills');

// Parse a single skill file
const skill = parseSkill('./my-skill/SKILL.md');

Cross-Agent Translation

import { translateSkill, translateSkillFile, TranslatorRegistry } from '@skillkit/core';

// Translate skill content to Cursor format
const result = translateSkill(skillContent, 'cursor');
console.log(result.content); // MDC format for Cursor

// Translate a skill file
const translated = await translateSkillFile('./skill.md', 'windsurf');

// Get available translators
const registry = new TranslatorRegistry();
const formats = registry.getSupportedFormats();

Project Context & Recommendations

import { ProjectDetector, RecommendationEngine, ContextManager } from '@skillkit/core';

// Detect project context
const detector = new ProjectDetector();
const profile = await detector.analyze('./my-project');
// profile.stack includes: languages, frameworks, libraries, testing tools, etc.

// Get skill recommendations
const engine = new RecommendationEngine();
const recommendations = engine.recommend(profile, availableSkills);
// Returns skills sorted by match score

// Manage project context
const ctx = new ContextManager('./my-project');
await ctx.init();
const context = ctx.getContext();

Session Memory

import {
  createMemoryCompressor,
  createMemoryInjector,
  LearningStore,
  ObservationStore,
} from '@skillkit/core';

// Compress observations into learnings
const compressor = createMemoryCompressor('./my-project');
const learnings = compressor.compress();

// Inject relevant memories into prompts
const injector = createMemoryInjector('./my-project');
const memories = injector.search('authentication patterns');

// Manage learnings directly
const store = new LearningStore('./my-project');
const learning = store.add({
  title: 'React hooks best practices',
  content: 'Always cleanup effects...',
  tags: ['react', 'hooks'],
});

Skill Testing

import { SkillTestRunner, parseTestCases } from '@skillkit/core';

// Run skill tests
const runner = new SkillTestRunner('./my-project');
const results = await runner.runAll();

// Run specific tests
const result = await runner.run('./my-skill', {
  tags: ['unit'],
  verbose: true,
});

// Parse test cases from skill
const testCases = parseTestCases(skillContent);

Workflow Orchestration

import { WorkflowOrchestrator, parseWorkflow, WorkflowStore } from '@skillkit/core';

// Parse and run a workflow
const workflow = parseWorkflow('./workflow.yaml');
const orchestrator = new WorkflowOrchestrator(workflow);
await orchestrator.execute();

// Manage workflows
const store = new WorkflowStore('./my-project');
const workflows = store.list();

Marketplace

import { createMarketplaceAggregator, MarketplaceSource } from '@skillkit/core';

// Browse skill marketplace
const marketplace = createMarketplaceAggregator();
const results = await marketplace.search({ query: 'react' });

// Filter by tags
const filtered = await marketplace.search({
  query: 'authentication',
  tags: ['security', 'auth'],
  limit: 10,
});

Team Collaboration

import { TeamManager, SkillBundle } from '@skillkit/core';

// Initialize team
const teamManager = new TeamManager('./my-project');
await teamManager.init('Engineering Team');

// Create skill bundle
const bundle = await teamManager.createBundle('onboarding', {
  skills: ['git-workflow', 'code-review'],
  description: 'New developer onboarding',
});

// Share bundle
await teamManager.shareBundle(bundle);

// Sync with remote registry
await teamManager.syncWithRemote('https://github.com/myorg/skills');

Plugin System

import { PluginManager, TranslatorPlugin } from '@skillkit/core';

// Load plugins
const pluginManager = new PluginManager('./my-project');
await pluginManager.loadAll();

// Install plugin
await pluginManager.install('custom-translator');

// Create custom plugin
const myPlugin: TranslatorPlugin = {
  name: 'my-agent',
  parse: async (content) => ({ /* canonical skill */ }),
  generate: async (skill) => '/* custom format */',
};

Methodologies

import { MethodologyManager } from '@skillkit/core';

// List available methodologies
const methodologies = await MethodologyManager.list();

// Load methodology
const tdd = await MethodologyManager.load('tdd');
// Returns: { name: 'TDD', skills: ['red-green-refactor', 'test-first'], ... }

Multi-Agent Orchestration

import { TeamOrchestrator, TaskManager } from '@skillkit/core';

// Create agent team
const orchestrator = new TeamOrchestrator();
const team = await orchestrator.createTeam({
  name: 'feature-dev',
  leader: { id: 'architect', name: 'System Architect' },
  teammates: [
    { id: 'frontend', name: 'Frontend Dev', capabilities: ['react'] },
    { id: 'backend', name: 'Backend Dev', capabilities: ['api'] },
  ],
});

// Manage tasks
const taskManager = new TaskManager();
const task = taskManager.createTask('Build login', 'Create login endpoint', spec);
await taskManager.assignTask(task.id, 'backend');

// Get stats
const stats = taskManager.getStats();

Plan System

import { PlanParser, PlanValidator, PlanExecutor } from '@skillkit/core';

// Parse plan from markdown
const parser = new PlanParser();
const plan = await parser.parseFile('./plan.md');

// Validate plan
const validator = new PlanValidator();
const validation = validator.validate(plan);

// Execute plan
const executor = new PlanExecutor();
const result = await executor.execute(plan, { dryRun: false });

Hooks & Automation

import { HookRegistry } from '@skillkit/core';

// Register hooks
const hooks = new HookRegistry('./my-project');
await hooks.register('pre-commit', {
  event: 'pre-commit',
  skill: 'code-review',
  enabled: true,
});

// Trigger hook
await hooks.trigger('pre-commit', { files: ['src/index.ts'] });

Supported Agents

The translator supports all 17 SkillKit-compatible agents:

Agent Format
Claude Code SKILL.md
Cursor MDC (.mdc)
Codex SKILL.md
Gemini CLI SKILL.md
Windsurf Markdown
GitHub Copilot Markdown
OpenCode, Antigravity, Amp, Goose, Kilo, Kiro, Roo, Trae SKILL.md
Universal SKILL.md

API Reference

Skill Types

interface CanonicalSkill {
  name: string;
  description?: string;
  version?: string;
  author?: string;
  tags?: string[];
  globs?: string[];
  alwaysApply?: boolean;
  content: string;
  metadata?: Record<string, unknown>;
}

interface TranslationResult {
  content: string;
  format: string;
  warnings?: string[];
}

Context Types

interface ProjectProfile {
  name: string;
  type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown';
  stack: {
    languages: Detection[];
    frameworks: Detection[];
    libraries: Detection[];
    testing: Detection[];
    databases: Detection[];
  };
}

Documentation

Full documentation: https://github.com/rohitg00/skillkit

License

Apache-2.0