@winspan/claude-forge 8.41.0 → 8.51.0

package/src/skills/official/planning-with-files.md

@@ -0,0 +1,37 @@
+---
+name: planning-with-files
+description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
+user-invocable: true
+allowed-tools: "Read Write Edit Bash Glob Grep"
+hooks:
+  UserPromptSubmit:
+    - hooks:
+        - type: command
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '=== recent progress ==='; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
+  PreToolUse:
+    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
+      hooks:
+        - type: command
+          command: "cat task_plan.md 2>/dev/null | head -30 || true"
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status.'; fi"
+  Stop:
+    - hooks:
+        - type: command
+          command: "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \\\"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\\\" 2>/dev/null || sh \\\"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\\\" 2>/dev/null || true"
+metadata:
+  version: "2.35.0"
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## FIRST: Restore Context (v2.2.0)
+
+**Before doing anything else**, check if planning files exist and read them:
+
+1. If `

package/src/skills/official/ui-ux-pro-max.md

@@ -0,0 +1,18 @@
+---
+name: ui-ux-pro-max
+version: 2.5.0
+description: "AI 驱动的设计智能工具：67 种 UI 风格、161 种配色、57 种字体搭配、99 条 UX 准则"
+tags: [ui, ux, design, color, typography, accessibility]
+---
+
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Antigravity Kit is an AI-powered design intelligence toolkit providing searchable databases of UI styles, color palettes, font pairings, chart types, and UX guidelines. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
+
+## Search Command
+
+`

package/src/skills/official/webapp-testing.md

@@ -0,0 +1,12 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
+license: Complete terms in LICENSE.txt
+---
+
+# Web Application Testing
+
+To test local web applications, write native Python Playwright scripts.
+
+**Helper Scripts Available**:
+- `

package/src/skills/official-skills.ts

@@ -0,0 +1,89 @@
+/**
+ * Official built-in skills for claude-forge
+ * Skill content is stored in src/skills/official/*.md files.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+
+export interface OfficialSkill {
+  name: string;
+  version: string;
+  description: string;
+  keywords: string[];
+  content: string;
+}
+
+/**
+ * Official skill keyword mappings
+ * Used for skill matching and orchestration
+ */
+export const OFFICIAL_SKILL_KEYWORDS: Record<string, string[]> = {
+  'official-tdd': ['tdd', 'test-driven', '测试驱动'],
+  'official-debug': ['debug', '调试', 'bug', '修复', 'fix', 'hotfix', '报错', '异常', 'error', '不工作', '失败', 'failed', 'crash', '问题'],
+  'official-refactor': ['refactor', '重构', 'cleanup', 'reorganize', 'restructure'],
+  'official-pr-review': ['review', '审查', 'pr review', 'code review', '检查', '看看代码', '帮我看', '评审'],
+  'official-harness-engineering': ['harness', 'legacy', '遗留代码', '特征测试', 'characterization', '重构', 'refactor', '改造', '老代码'],
+  'official-bmad': ['bmad', 'agile', 'four-role', '敏捷', '四角色', 'story', 'user story', 'sprint', '迭代'],
+  'official-spec-driven-design': ['spec', 'sdd', 'spec-driven', '规格', '需求文档', 'requirements'],
+  'official-architecture-decision': ['adr', 'architecture decision', '架构决策', '技术选型'],
+  'official-api-design': ['api design', 'api 设计', 'restful', 'openapi', '接口设计'],
+  'official-db-schema-design': ['schema', 'database', '数据库设计', 'migration', '迁移', 'sql'],
+  'official-performance-optimization': ['performance', '性能', 'optimize', '优化', 'profiling', '瓶颈', '慢', 'slow', 'timeout', '超时', '卡顿', 'latency'],
+  'official-security-hardening': ['security', '安全', 'owasp', 'hardening', '加固', 'vulnerability', '漏洞', '注入', 'injection', 'xss', 'csrf', '权限', 'auth'],
+  'official-release-checklist': ['release', 'deploy', '发布', '上线', 'checklist', '部署'],
+  'official-doc-driven': ['doc-driven', 'documentation', '文档驱动', '写文档', 'readme'],
+  'planning-with-files': ['plan', 'planning', '规划', 'task plan', 'organize', '组织任务', '怎么做', '方案', '步骤', '计划'],
+  'code-simplifier': ['simplify', 'refine', '简化', 'cleanup', 'code quality'],
+  'find-skills': ['find skill', 'search skill', '查找技能', 'discover', 'install skill'],
+  'webapp-testing': ['test webapp', 'playwright', 'browser test', 'e2e', 'frontend test'],
+  'ui-ux-pro-max': ['ui', 'ux', 'design', 'color', 'typography', 'palette', '设计'],
+};
+
+/**
+ * Load official skills from a directory of .md files.
+ * Each .md file should have frontmatter with at minimum a `name` field.
+ * The `keywords` or `tags` field in frontmatter provides keyword matching hints.
+ *
+ * @param builtinDir - Path to the directory containing official skill .md files
+ * @returns Array of OfficialSkill objects
+ */
+export function loadOfficialSkills(builtinDir: string): OfficialSkill[] {
+  if (!fs.existsSync(builtinDir)) {
+    throw new Error(`Official skills directory not found: ${builtinDir}`);
+  }
+
+  const entries = fs.readdirSync(builtinDir);
+  const skills: OfficialSkill[] = [];
+
+  for (const filename of entries) {
+    if (!filename.endsWith('.md')) continue;
+
+    const filePath = path.join(builtinDir, filename);
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    const { data, content: body } = parsed;
+
+    const id = path.basename(filename, '.md');
+    const name = typeof data.name === 'string' ? data.name : id;
+    const version = typeof data.version === 'string' ? data.version : '1.0.0';
+    const description = typeof data.description === 'string' ? data.description : '';
+
+    // Support both `keywords` (claude-forge standard) and `tags` (Claude Code official skill convention)
+    const rawKeywords: unknown = data.keywords ?? data.tags;
+    const keywords: string[] = Array.isArray(rawKeywords)
+      ? rawKeywords.filter((k): k is string => typeof k === 'string')
+      : [];
+
+    skills.push({
+      name,
+      version,
+      description,
+      keywords,
+      content: raw, // full file content including frontmatter
+    });
+  }
+
+  return skills;
+}

package/src/skills/registry.ts

@@ -0,0 +1,355 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import matter from 'gray-matter';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../core/utils/logger.js';
+import { loadOfficialSkills, OFFICIAL_SKILL_KEYWORDS } from './official-skills.js';
+import { SemanticSkillMatcher } from './semantic-matcher.js';
+
+const SKILLS_DIR = path.join(homedir(), '.claude', 'skills');
+
+export interface Skill {
+  id: string;
+  name: string;
+  keywords: string[];
+  content: string;
+  path: string;
+  isOfficial?: boolean; // Mark official built-in skills
+  description?: string; // Optional description from frontmatter (used by agent-skills format)
+}
+
+/**
+ * Simple skill registry that scans ~/.claude/skills/*.md
+ * and matches by keywords in frontmatter
+ */
+export class SkillRegistry {
+  private skills: Map<string, Skill> = new Map();
+  private semanticMatcher: SemanticSkillMatcher | null = null;
+
+  constructor(apiKey?: string) {
+    this.scan();
+
+    // Initialize semantic matcher if API key is provided
+    if (apiKey) {
+      this.semanticMatcher = new SemanticSkillMatcher(apiKey);
+      logger.info('[SkillRegistry] Semantic matching enabled');
+    } else {
+      logger.debug('[SkillRegistry] Semantic matching disabled (no API key)');
+    }
+  }
+
+  /**
+   * Resolve the directory containing official built-in skill .md files.
+   * Uses import.meta.url for ESM compatibility (works in both dev and npm-installed environments).
+   */
+  private resolveBuiltinDir(): string {
+    const thisFile = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(thisFile), 'official');
+  }
+
+  /**
+   * Scan ~/.claude/skills/ for markdown files with frontmatter
+   * Official skills are loaded first, then user skills (which can override)
+   *
+   * Supports two formats:
+   * 1. Flat format: ~/.claude/skills/skill-name.md
+   * 2. Directory format: ~/.claude/skills/skill-name/SKILL.md (agent-skills format)
+   */
+  private scan(): void {
+    // 1. Load official built-in skills from src/skills/official/*.md
+    let officialCount = 0;
+    try {
+      const officialSkills = loadOfficialSkills(this.resolveBuiltinDir());
+      for (const officialSkill of officialSkills) {
+        // Merge extended keywords from OFFICIAL_SKILL_KEYWORDS if available
+        const extendedKeywords = OFFICIAL_SKILL_KEYWORDS[officialSkill.name] || officialSkill.keywords;
+        this.skills.set(officialSkill.name, {
+          id: officialSkill.name,
+          name: officialSkill.name,
+          keywords: extendedKeywords,
+          content: officialSkill.content,
+          path: this.resolveBuiltinDir() + '/' + officialSkill.name + '.md',
+          isOfficial: true,
+          description: officialSkill.description,
+        });
+        officialCount++;
+      }
+    } catch (err) {
+      logger.warn(`[SkillRegistry] Failed to load official skills: ${err}`);
+    }
+
+    logger.info(`Loaded ${officialCount} official skill(s)`);
+
+    // 2. Load user skills from ~/.claude/skills/ (can override official skills)
+    if (!fs.existsSync(SKILLS_DIR)) {
+      logger.debug(`Skills directory not found: ${SKILLS_DIR}`);
+      return;
+    }
+
+    const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+    let userCount = 0;
+
+    for (const entry of entries) {
+      try {
+        let filePath: string;
+        let id: string;
+
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+          // Format 1: Flat .md file
+          filePath = path.join(SKILLS_DIR, entry.name);
+          id = path.basename(entry.name, '.md');
+        } else if (entry.isDirectory()) {
+          // Format 2: Directory with SKILL.md
+          const skillMdPath = path.join(SKILLS_DIR, entry.name, 'SKILL.md');
+          if (!fs.existsSync(skillMdPath)) {
+            continue; // Skip directories without SKILL.md
+          }
+          filePath = skillMdPath;
+          id = entry.name;
+        } else {
+          continue; // Skip other file types
+        }
+
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = matter(content);
+        const { data, content: body } = parsed;
+
+        const name = typeof data.name === 'string' ? data.name : id;
+        // 兼容两种字段名：keywords（claude-forge 标准）和 tags（Claude Code 官方 skill 约定）
+        const rawKeywords: unknown = data.keywords ?? data.tags;
+        const keywords: string[] = Array.isArray(rawKeywords)
+          ? rawKeywords.filter((k): k is string => typeof k === 'string')
+          : [];
+        const description = typeof data.description === 'string' ? data.description : undefined;
+
+        // User skills override official skills, but merge keywords from OFFICIAL_SKILL_KEYWORDS
+        const extendedKeywords = OFFICIAL_SKILL_KEYWORDS[id];
+        const mergedKeywords = extendedKeywords
+          ? [...new Set([...keywords, ...extendedKeywords])]
+          : keywords;
+
+        this.skills.set(id, {
+          id,
+          name,
+          keywords: mergedKeywords,
+          content: body.trim(),
+          path: filePath,
+          isOfficial: false,
+          description,
+        });
+        userCount++;
+      } catch (err) {
+        logger.warn(`Failed to parse skill ${entry.name}: ${err}`);
+      }
+    }
+
+    if (userCount > 0) {
+      logger.info(`Loaded ${userCount} user skill(s) from ${SKILLS_DIR}`);
+    }
+  }
+
+  /**
+   * Match a prompt against skill keywords with hybrid approach:
+   * 1. Try semantic matching (AI-powered) if available
+   * 2. Fall back to keyword matching if semantic fails or not configured
+   */
+  async match(prompt: string, keywords: string[] = [], context?: { recentFiles?: string[] }): Promise<Skill | null> {
+    const result = await this.matchWithConfidence(prompt, keywords, context);
+    return result?.skill ?? null;
+  }
+
+  /**
+   * Like match(), but also returns the confidence score (0-100) so callers
+   * can compare across alternatives (e.g. agent vs skill routing).
+   */
+  async matchWithConfidence(
+    prompt: string,
+    keywords: string[] = [],
+    context?: { recentFiles?: string[] },
+  ): Promise<{ skill: Skill; confidence: number; source: 'semantic' | 'keyword' } | null> {
+    // Try semantic matching first
+    if (this.semanticMatcher) {
+      try {
+        const semanticResult = await this.semanticMatcher.match(
+          Array.from(this.skills.values()),
+          {
+            prompt,
+            intentKeywords: keywords,
+            recentFiles: context?.recentFiles,
+          }
+        );
+
+        if (semanticResult) {
+          logger.info(`[SkillRegistry] Semantic match: ${semanticResult.skill.id} (${semanticResult.confidence}%)`);
+          return { skill: semanticResult.skill, confidence: semanticResult.confidence, source: 'semantic' };
+        }
+      } catch (err) {
+        logger.warn(`[SkillRegistry] Semantic matching failed, falling back to keyword matching: ${err}`);
+      }
+    }
+
+    // Fall back to keyword matching
+    const kwSkill = await this.matchKeywords(prompt, keywords, context);
+    if (kwSkill) {
+      // Keyword matching has no real confidence; assign a conservative 60%
+      return { skill: kwSkill, confidence: 60, source: 'keyword' };
+    }
+    return null;
+  }
+
+  /**
+   * Keyword-based matching (fallback method)
+   * Supports fallback to description-based substring matching when keywords are empty
+   */
+  private async matchKeywords(
+    prompt: string,
+    keywords: string[] = [],
+    context?: { recentFiles?: string[] }
+  ): Promise<Skill | null> {
+    const promptLower = prompt.toLowerCase();
+    const extraLower = keywords.map(k => k.toLowerCase());
+
+    let bestSkill: Skill | null = null;
+    let bestScore = 0;
+    let bestCandidate: Skill | null = null;
+    let bestCandidateScore = 0;
+
+    for (const skill of this.skills.values()) {
+      let score = 0;
+
+      // If skill has keywords, use keyword matching
+      if (skill.keywords.length > 0) {
+        for (const kw of skill.keywords) {
+          const kwLower = kw.toLowerCase();
+
+          // Check if keyword appears in prompt or intent keywords
+          if (this.matchKeywordFlexible(promptLower, kwLower)) {
+            score += 1;
+          }
+          if (extraLower.some(ek => this.matchKeywordFlexible(ek, kwLower))) {
+            score += 1;
+          }
+        }
+      } else if (skill.description) {
+        // Fallback path 1: Use description substring matching when keywords are empty
+        const descLower = skill.description.toLowerCase();
+        if (descLower.includes(promptLower) || promptLower.includes(descLower)) {
+          score = 1; // Give a base score for description match
+        }
+      }
+      // Fallback path 2: If no keywords and no description, score remains 0
+      // This allows SemanticSkillMatcher to take over
+
+      // Track best candidate regardless of threshold
+      if (score > bestCandidateScore) {
+        bestCandidateScore = score;
+        bestCandidate = skill;
+      }
+
+      // Official skills get priority: require 1+ match, user skills require 2+ matches
+      const threshold = skill.isOfficial ? 1 : 2;
+
+      if (score >= threshold && score > bestScore) {
+        bestScore = score;
+        bestSkill = skill;
+      } else if (
+        score === bestScore &&
+        score >= threshold &&
+        skill.isOfficial &&
+        !bestSkill?.isOfficial
+      ) {
+        // Tie-break: prefer official skill when both meet threshold
+        bestSkill = skill;
+      }
+    }
+
+    if (bestSkill) {
+      logger.info(`[SkillRegistry] Keyword match: ${bestSkill.id} (score: ${bestScore})`);
+    } else {
+      logger.debug(`[SkillRegistry] Best keyword candidate: ${bestCandidate?.id ?? 'none'} (score: ${bestCandidateScore})`);
+    }
+
+    return bestSkill;
+  }
+
+  /**
+   * Flexible keyword matching with word boundary for English, substring for Chinese
+   */
+  private matchKeywordFlexible(text: string, keyword: string): boolean {
+    // For Chinese or multi-word keywords, use simple includes
+    if (/[一-龥]/.test(keyword) || keyword.includes(' ')) {
+      return text.includes(keyword);
+    }
+
+    // For single English words, require word boundaries to avoid false positives
+    // e.g., "test" won't match "latest"
+    const regex = new RegExp(`\\b${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+    return regex.test(text);
+  }
+
+  /**
+   * Match with full result details (for debugging/logging)
+   */
+  async matchWithDetails(prompt: string, keywords: string[] = [], context?: { recentFiles?: string[] }) {
+    const promptLower = prompt.toLowerCase();
+    const extraLower = keywords.map(k => k.toLowerCase());
+
+    const results = [];
+    for (const skill of this.skills.values()) {
+      let score = 0;
+      const matchedKeywords: string[] = [];
+
+      for (const kw of skill.keywords) {
+        const kwLower = kw.toLowerCase();
+
+        if (this.matchKeywordFlexible(promptLower, kwLower)) {
+          score += 1;
+          matchedKeywords.push(kw);
+        }
+        if (extraLower.some(ek => this.matchKeywordFlexible(ek, kwLower))) {
+          score += 1;
+        }
+      }
+
+      if (score >= 1) {
+        results.push({
+          skill,
+          confidence: Math.min(100, score * 20), // Simple scoring: 1 match = 20%, 5 matches = 100%
+          matchedKeywords,
+        });
+      }
+    }
+
+    results.sort((a, b) => b.confidence - a.confidence);
+    return results;
+  }
+
+  /** Return all loaded skills */
+  getAll(): Skill[] {
+    return Array.from(this.skills.values());
+  }
+
+  /** Get a skill by ID */
+  get(id: string): Skill | undefined {
+    return this.skills.get(id);
+  }
+
+  /**
+   * Get skill manifest (id + description + keywords) for Agent pre-declaration
+   */
+  getManifest(): Array<{ id: string; name: string; description: string; keywords: string[] }> {
+    return this.getAll().map(skill => ({
+      id: skill.id,
+      name: skill.name,
+      description: skill.description || '',
+      keywords: skill.keywords,
+    }));
+  }
+
+  /** Re-scan the skills directory */
+  reload(): void {
+    this.skills.clear();
+    this.scan();
+  }
+}