Files
skillkit/packages/core
Rohit Ghumare b3f561dbc9 feat(quality): Quality Evaluation System Enhancements (#21)
* feat(quality): add skill quality evaluation system

- Add quality scoring module with structure, clarity, and specificity metrics
- Evaluate skills for metadata, triggers, boundaries, code examples
- Detect vague terms and penalize overly long skills
- Update validate command to include quality reports
- Add --verbose, --quality, --issues, --json flags
- Quality scores: A (90+), B (80+), C (70+), D (60+), F (<60)

* fix: address CodeRabbit and Devin review suggestions

- Fix JSON output to return exit code 1 on validation failures
- Add --min-score NaN validation with warning message
- Add directory guard for --all flag with .mdc file support
- Fix CRLF handling in frontmatter extraction
- Fix code blocks double-counting in specificity evaluation
- Fix warning message inconsistency for code examples
- Add try/catch error handling in evaluateSkillFile
- Fix isHighQuality threshold to match UI display (80)

* feat(quality): extend quality evaluation system with badges, deeper analysis, and fix command

- Phase 2: Add quality badges to CLI commands (list, recommend, install)
  - formatQualityBadge() helper for color-coded grade badges
  - --quality flag for list command
  - Low-quality skill warnings during install

- Phase 3: Add TUI quality badges
  - Extended SkillItem with quality, grade, warnings fields
  - Quality evaluation in loadSkills()
  - Grade badges in Installed and Recommend screens

- Phase 4: Deeper quality analysis
  - Deprecated pattern detection (CommonJS, class components, var)
  - Security pattern detection (hardcoded credentials, eval, innerHTML)
  - Conflicting instruction detection
  - Completeness assessment (TODOs, empty sections, example coverage)
  - New weight distribution: Structure 35%, Clarity 25%, Specificity 25%, Advanced 15%

- Phase 1: Pre-compute marketplace quality scores
  - Updated schema.json with quality field (0-100)
  - Created scripts/compute-quality.ts for batch computation

- Phase 5: Benchmark against category leaders
  - New benchmark.ts module with category detection
  - Percentile calculation and comparison notes
  - --benchmark flag for validate command

- Phase 6: Fix command for automated quality fixes
  - skillkit fix command with --dry-run and --interactive modes
  - Auto-generates frontmatter, "When to Use", "Boundaries" sections
  - --fix flag alias on validate command

* fix: address CodeRabbit and Devin review suggestions

- Fix .mdc file name extraction in fix.ts (handles both .md and .mdc)
- Add missing advanced field to test fixtures in quality.test.ts
- Fix duplicate header detection in assessCompleteness using regex.exec
- Fix ESM compatibility in compute-quality.ts using import.meta.url
- Add trailing newline to skills.json output

* fix: address remaining CodeRabbit review suggestions

- Escape regex metacharacters in vague term patterns (fix.ts)
- Improve diff algorithm using set-based comparison (fix.ts)
- Fix validateSkill receiving file path instead of directory (validate.ts)
- Check final section in completeness assessment (index.ts)
- Add error handling and empty skills guard (compute-quality.ts)

* fix: address additional review feedback

- validate.ts: Add error when --fix is passed without targets
- index.ts: Skip headers inside fenced code blocks during completeness check
- compute-quality.ts: Use nullish coalescing (??) to preserve zero quality scores
2026-01-28 14:18:42 +00:00
..

@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