ca2e35c30b
* feat: implement compatibility layer foundation (Issue #141) - Add TypeScript project setup with strict mode and Vitest - Implement 20+ Zod validation schemas for OpenAgent format - Create BaseAdapter abstract class with template method pattern - Add context documentation for compatibility layer workflow - Setup ESLint, TypeScript, and test configuration Phase 1 Foundation: 50% complete (subtasks 01-03) Related: #141 * feat: implement AgentLoader with TypeScript (Issue #141) - Add AgentLoader class for loading OAC agent files - Implement parseFrontmatter() for YAML extraction - Add extractSections() for markdown parsing (skills, examples, commands, workflow) - Create custom error classes: AgentLoadError, FrontmatterParseError, ValidationError - Support single file and recursive directory loading - Add metadata merging from agent-metadata.json - Export convenience functions: loadAgent(), loadAgents() - Full Zod schema validation with descriptive error messages - 386 lines, type-safe with strict mode Phase 1 Foundation: 66.7% complete (subtask 04/06) Related: #141 * feat: implement AdapterRegistry with TypeScript (Issue #141) - Add AdapterRegistry class for managing tool adapters - Implement type-safe registration with Map<string, BaseAdapter> - Add alias support for adapter names (case-insensitive) - Create custom error class: AdapterRegistryError - Implement methods: register(), get(), list(), has(), getAll(), unregister(), clear() - Add capability-based adapter discovery: getCapabilities(), findByFeature() - Export singleton registry instance and convenience functions - Support lazy loading of built-in adapters (placeholder for Phase 2) - 416 lines, fully type-safe with strict mode Features: - Duplicate registration prevention - Alias conflict detection - O(1) adapter lookup - Sorted adapter listings - Comprehensive JSDoc documentation Phase 1 Foundation: 83.3% complete (subtask 05/06) Related: #141 * feat: create main entry point index.ts (Issue #141) - Add comprehensive barrel exports for public API - Export all Zod schemas and TypeScript types - Export AgentLoader class and convenience functions - Export AdapterRegistry, singleton, and helpers - Export error classes: AgentLoadError, FrontmatterParseError, ValidationError, AdapterRegistryError - Export BaseAdapter for custom adapter creation - Add package VERSION constant - Include JSDoc documentation with usage examples - Organized exports by category (types, core, adapters) - 168 lines with comprehensive documentation All exports: - Types: All Zod schemas and inferred TypeScript types - Core: AgentLoader, AdapterRegistry, registry singleton - Adapters: BaseAdapter abstract class - Errors: All custom error classes - Utilities: Convenience functions (loadAgent, getAdapter, etc.) Phase 1 Foundation: 100% COMPLETE! 🎉 (6/6 subtasks) Related: #141 * feat: implement ClaudeAdapter with bidirectional conversion (Issue #141) - Implement ClaudeAdapter extending BaseAdapter - Support toOAC() conversion from Claude Code format to OAC - Support fromOAC() conversion from OAC to Claude Code format - Handle .claude/config.json for primary agents - Handle .claude/agents/*.md for subagents with YAML frontmatter - Map Claude Skills system to/from OAC contexts - Map hooks (PreToolUse, PostToolUse, etc.) bidirectionally - Degrade granular OAC permissions to Claude permissionMode - Add warnings for unsupported features (temperature, maxSteps) - Export ClaudeAdapter from main index.ts Capabilities: - supportsMultipleAgents: true - supportsSkills: true - supportsHooks: true - supportsGranularPermissions: false (binary only) - supportsTemperature: false - Model ID mapping (claude-sonnet-4 <-> claude-sonnet-4-20250514) - Tool access mapping (OAC ToolAccess <-> Claude tools array) Subtask: compatibility-layer-141-07 Phase: 2 (Adapters Migration) * feat: implement CursorAdapter with single-file format support (Issue #141) - Implement CursorAdapter extending BaseAdapter - Support toOAC() conversion from .cursorrules to OAC - Support fromOAC() conversion from OAC to .cursorrules format - Handle single-file limitation (no multiple agents) - Implement mergeAgents() for combining multiple OAC agents - Parse optional YAML frontmatter in .cursorrules - Inline context files into .cursorrules content - Add comprehensive warnings for lost features Key limitations: - supportsMultipleAgents: false (single .cursorrules file) - supportsSkills: false (must inline content) - supportsHooks: false (not supported by Cursor) - supportsGranularPermissions: false (binary only) - supportsTemperature: true (limited support) Features: - Model ID mapping (gpt-4, claude-3-opus, etc.) - Tool access parsing and generation - Context file inlining with references - Multi-agent merge capability - Frontmatter parsing for metadata Export CursorAdapter from main index.ts Subtask: compatibility-layer-141-08 Phase: 2 (Adapters Migration) * feat: implement WindsurfAdapter with bidirectional conversion (Issue #141) - Add WindsurfAdapter.ts (514 lines) extending BaseAdapter - Support bidirectional OAC ↔ Windsurf JSON conversion - Implement toOAC() for Windsurf config → OpenAgent parsing - Implement fromOAC() for OpenAgent → Windsurf config generation - Add temperature ↔ creativity setting mapping (low/medium/high) - Add model ID mapping (claude-sonnet-4 ↔ claude-4-sonnet) - Support multi-agent configuration via .windsurf/agents/ - Support context files via .windsurf/context/ - Implement binary permission mapping with degradation warnings - Add priority level normalization (critical/high/medium/low → high/low) - Export WindsurfAdapter in index.ts - All adapters now complete: Claude, Cursor, Windsurf - Compilation successful: 0 errors, 0 warnings Phase 2 (Adapters): 50% complete (3/6 subtasks) Total progress: 28.13% (9/32 subtasks) Code stats: 3,333 lines TypeScript (Foundation + Adapters) * docs: add compatibility layer context files and progress tracking (Issue #141) - Add baseadapter-implementation.md with detailed adapter pattern and testing examples - Add compatibility-layer-development.md with development workflow and best practices - Add compatibility-layer-adapters.md lookup table with adapter specifications - Add compatibility-layer-progress.md tracking Phase 1 completion and Phase 2 status - Add compatibility-learnings.md documenting implementation learnings - Update compatibility-layer.md with latest architecture insights These context files support Phase 2 adapter unit testing and future adapter development. * test: implement comprehensive unit tests for ClaudeAdapter (Issue #141 - Subtask 10) Implemented 80 test cases covering: - toOAC() parsing of config.json and agent.md (YAML frontmatter) - fromOAC() conversion to config.json and agent.md formats - Capabilities and feature validation - Model, tool, skill, hook, and permission mapping - Skill generation from contexts - Edge cases and error handling - Roundtrip conversion validation Coverage achieved: - 96.32% statements (target: 80%+) ✅ - 100% functions (target: 80%+) ✅ - 82.14% branches (target: 75%+) ✅ All test cases follow AAA pattern (Arrange-Act-Assert) and test standards from .opencode/context/core/standards/test-coverage.md * test: implement comprehensive unit tests for CursorAdapter (Issue #141 - Subtask 11) Implemented 78 test cases covering: - toOAC() parsing of plain .cursorrules and YAML frontmatter - fromOAC() conversion to .cursorrules format - Capabilities and feature validation - Agent merging (CURSOR-SPECIFIC - unique feature) - Model, tool mapping - Context inlining - Temperature and configuration handling - Edge cases and error handling - Roundtrip conversion validation Coverage achieved: - 98.55% statements (target: 80%+) ✅ - 100% functions (target: 80%+) ✅ - 89.65% branches (target: 75%+) ✅ Key test areas: - Plain text .cursorrules parsing (no frontmatter) - YAML frontmatter parsing with type coercion - Agent merging (single, two, three+ agents) - Tool union and temperature MAX behavior - Context inlining with proper formatting - Model mapping (Cursor ↔ OAC) All test cases follow AAA pattern and test standards. * test: implement comprehensive unit tests for WindsurfAdapter (Issue #141 - Subtask 12) * feat: implement Phase 3 mappers and translation engine with tests (Issue #141) - Add ToolMapper: maps tool names between OAC and Claude/Cursor/Windsurf - Add PermissionMapper: translates granular to binary permissions - Add ModelMapper: maps AI model IDs between platforms - Add ContextMapper: maps context file paths between platforms - Add CapabilityMatrix: feature compatibility analysis across platforms - Add TranslationEngine: orchestrates all mappers for complete translation Test coverage: - ToolMapper: 100% statements, 100% branches - PermissionMapper: 98% statements, 96% branches - ModelMapper: 99% statements, 90% branches - ContextMapper: 97% statements, 94% branches - CapabilityMatrix: 99% statements, 96% branches - TranslationEngine: 99% statements, 93% branches Total: 485 tests passing (249 new tests added) * docs: update Issue #141 context files to reflect Phase 3 completion - Update progress from 28% to 59.4% (19/32 subtasks) - Mark Phases 1-3 as complete (Foundation, Adapters, Mappers) - Update code stats: 5,799 source lines, 6,322 test lines - Add test coverage metrics: 485 tests, 97-100% on Phase 3 - Update structure with all implemented files - Add executive summary for token-efficient context loading - Document next steps: Phase 4 CLI implementation * docs(context): harvest Claude Code docs and fix MVI compliance (Phase 1) - Harvest external Claude Code documentation into context system: - hooks-system, agent-skills, subagents-system concepts - hook-events, skill-metadata, builtin-subagents lookups - Example files for hooks, skills, and subagents - Plugin architecture and migration guides - Fix 6 critical MVI violations (files > 200 lines): - Split adding-agent.md → adding-agent-basics.md + adding-agent-testing.md - Split adding-skill.md → 3 files (basics, implementation, example) - Split task-delegation.md → 3 files (basics, specialists, caching) - Split external-libraries.md → 3 files (workflow, scenarios, faq) - Split design-assets.md → 4 files (images, icons, fonts, cdn) - Split navigation-design.md → 2 files (basics, templates) - Update navigation files with new references - Remove consumed source docs from to-be-consumed/ Total: 17 new files created, 6 large files replaced, 5 source docs consumed * docs(context): MVI compliance Phase 2 - split large workflow and UI files Split 3 large files into MVI-compliant modules (< 200 lines each): - design-iteration.md (1058 lines) → 9 files: - design-iteration-overview.md (overview, when to use) - design-iteration-plan-file.md (mandatory plan template) - design-iteration-stage-layout.md (Stage 1) - design-iteration-stage-theme.md (Stage 2) - design-iteration-stage-animation.md (Stage 3) - design-iteration-stage-implementation.md (Stage 4) - design-iteration-visual-content.md (Image Specialist) - design-iteration-best-practices.md (quality, troubleshooting) - design-iteration-plan-iterations.md (managing iterations) - animation-patterns.md (753 lines) → 6 files: - animation-basics.md (fundamentals, timing, easing) - animation-components.md (buttons, cards, modals) - animation-chat.md (message, typing animations) - animation-loading.md (skeleton, spinner, progress) - animation-forms.md (focus, validation, scroll) - animation-advanced.md (recipes, best practices) - premium-dark-ui-quick-start.md (638 lines) → 4 files: - premium-dark-ui-colors.md (palette, typography, spacing) - premium-dark-ui-components.md (core building blocks) - premium-dark-ui-layouts.md (hero, features, CTA) - premium-dark-ui-advanced.md (animations, accessibility) Updated navigation files with new references. * feat(cli): implement CLI scaffolding with Commander.js (Issue #141 - Subtask 20) - Add src/cli/index.ts: CLI entry point with convert, validate, migrate, info commands - Add src/cli/types.ts: TypeScript type definitions for CLI options - Add src/cli/utils.ts: Logging, spinner, and formatting utilities - Add "type": "module" to package.json for ESM support - Global options: --verbose, --quiet, --output-format (json|text) - Commands are placeholders pending implementation in subtasks 21-24 * feat(cli): implement convert command with full format support (Issue #141 - Subtask 21) - Add src/cli/commands/convert.ts: Complete convert command implementation - Auto-detect input format from file path and content - Support bidirectional conversion: OAC <-> Cursor/Claude/Windsurf - Output to stdout by default, file with --output flag - Display warnings for feature loss during conversion - Enable registerBuiltInAdapters in AdapterRegistry - Add public constructors to all adapters (CursorAdapter, ClaudeAdapter, WindsurfAdapter) - Fix ESM imports: add .js extensions to all relative imports across codebase All 485 tests passing. * feat(cli): implement validate and info commands (Issue #141 - Subtasks 22, 24) - validate: Checks agent compatibility with target format - Reports compatibility score (0-100%) - Lists preserved/degraded/lost features - Provides suggestions for unsupported features - Exit codes: 0=compatible, 1=partial, 2=incompatible - Supports --strict and --output-format json - info: Displays tool capabilities and feature parity - Shows feature matrix for all platforms - Detailed view for single platform - Platform comparison with --compare - Documentation links - Supports --output-format json * feat(cli): implement migrate command and add migration guides (Issue #141) - Add migrate command for full project migration with batch conversion - Support --dry-run, --force, and --out-dir options - Generate migration reports with success/failure summaries - Preserve directory structure in output Documentation: - Add 5 migration guides (cursor↔oac, claude↔oac, oac→windsurf) - Add comprehensive feature-matrices.md with platform comparisons - Document lossless vs lossy conversion impacts Completes subtasks: 23, 26, 27, 28, 29, 30, 31 * test(cli): add comprehensive integration tests for all CLI commands (Issue #141) - Add convert.test.ts with 23 tests for format conversions - Add validate.test.ts with 21 tests for compatibility validation - Add migrate.test.ts with 25 tests for batch migration - Add info.test.ts with 30 tests for capability queries - Add test fixtures for OAC, Cursor, and Claude formats - Fix empty directory warning in migrate command All 584 tests passing with full coverage of CLI modules. Completes subtask 25 * docs: update README with comprehensive CLI and API documentation (Issue #141) - Add complete CLI command reference with all options - Add programmatic API usage examples - Add feature parity matrix summary - Add links to all migration guides - Add architecture overview - Add custom adapter creation guide Completes subtask 32 - Feature #141 fully implemented * docs: add visual examples and format improvements to README - Add Cursor IDE screenshot (contextscout-cursor.png) - Add Claude Code validation screenshot (claude-code-validation.png) - Format code examples with consistent double quotes - Align feature parity matrix table - Add .cursorrules and bun.lock to .gitignore * fix(lint): resolve all ESLint errors in compatibility layer - Remove async from methods with no await expressions (toOAC, fromOAC, loadFromFile) - Wrap Promise-returning methods with Promise.resolve/reject - Fix unsafe type assertions (replace 'as any' with proper type validation) - Add missing getConfigPath() method to WindsurfAdapter - Validate AgentCategory enum values before assignment - Fix return type compatibility issues All 584 tests passing, 0 ESLint errors (7 acceptable warnings for missing callback return types) * chore: update package.json author and contributors metadata - Update author from string to object format with name and GitHub URL - Add Alexander Daza as contributor with email and GitHub profile - Maintain npm package.json standard format for author/contributors fields
102 lines
2 KiB
Markdown
102 lines
2 KiB
Markdown
# Skills Troubleshooting
|
|
|
|
**Purpose**: Common skill issues and solutions
|
|
|
|
---
|
|
|
|
## Skill Not Triggering
|
|
|
|
**Symptom**: Claude doesn't use your skill when expected
|
|
|
|
**Cause**: Description doesn't match user requests
|
|
|
|
**Solution**: Write specific descriptions with trigger terms:
|
|
```yaml
|
|
# Bad
|
|
description: Helps with documents
|
|
|
|
# Good
|
|
description: Extract text from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
|
|
```
|
|
|
|
**Tip**: Include keywords users would naturally say
|
|
|
|
---
|
|
|
|
## Skill Doesn't Load
|
|
|
|
**Check file path**:
|
|
| Type | Correct Path |
|
|
|------|--------------|
|
|
| Personal | `~/.claude/skills/my-skill/SKILL.md` |
|
|
| Project | `.claude/skills/my-skill/SKILL.md` |
|
|
| Plugin | `skills/my-skill/SKILL.md` |
|
|
|
|
**Check YAML syntax**:
|
|
- First line must be `---` (no blank lines before)
|
|
- End frontmatter with `---`
|
|
- Use spaces, not tabs
|
|
|
|
**Debug**: Run `claude --debug` to see loading errors
|
|
|
|
---
|
|
|
|
## Skill Has Errors
|
|
|
|
**Dependencies not installed**:
|
|
- List required packages in description
|
|
- User must install before skill works
|
|
|
|
**Script permissions**:
|
|
```bash
|
|
chmod +x scripts/*.py
|
|
```
|
|
|
|
**Path format**: Use forward slashes (Unix style)
|
|
|
|
---
|
|
|
|
## Multiple Skills Conflict
|
|
|
|
**Symptom**: Claude uses wrong skill
|
|
|
|
**Cause**: Similar descriptions
|
|
|
|
**Solution**: Make descriptions distinct:
|
|
```yaml
|
|
# Skill 1
|
|
description: Analyze sales data in Excel files and CRM exports
|
|
|
|
# Skill 2
|
|
description: Analyze log files and system metrics
|
|
```
|
|
|
|
---
|
|
|
|
## Plugin Skills Not Appearing
|
|
|
|
**Solution**: Clear cache and reinstall
|
|
```bash
|
|
rm -rf ~/.claude/plugins/cache
|
|
# Restart Claude Code
|
|
/plugin install plugin-name@marketplace
|
|
```
|
|
|
|
**Verify structure**:
|
|
```
|
|
my-plugin/
|
|
├── .claude-plugin/
|
|
│ └── plugin.json
|
|
└── skills/
|
|
└── my-skill/
|
|
└── SKILL.md
|
|
```
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- `../concepts/agent-skills.md` - Skills overview
|
|
- `../guides/creating-skills.md` - Creation guide
|
|
|
|
**Reference**: https://docs.anthropic.com/en/docs/claude-code/skills
|