commit 97e5b56214196248b8d98d22a0e7900e6689ce75 Author: KeyInfo Bot Date: Thu Jun 11 16:51:52 2026 +0800 Publish current skill market snapshot Constraint: EAPIL Skill Market is a distribution repository and intentionally does not preserve generated artifact history. Rejected: Preserve generated plugin history | inflates clone and ZIP size for users. Confidence: high Scope-risk: moderate Directive: Collapse market history again after public plugin updates. Tested: python scripts/validate_marketplace.py; validate_plugin.py oh-my-codex; codex plugin add oh-my-codex@eapil-skill-market. Not-tested: PowerShell sync script unavailable locally; Codex model-level smoke invocation timed out on remote request. diff --git a/plugins/codex/plugins/oh-my-codex/skills/skill/SKILL.md b/plugins/codex/plugins/oh-my-codex/skills/skill/SKILL.md new file mode 100644 index 000000000..cc57a6b17 --- /dev/null +++ b/plugins/codex/plugins/oh-my-codex/skills/skill/SKILL.md @@ -0,0 +1,836 @@ +--- +name: skill +description: Manage local skills - list, add, remove, search, edit, setup wizard +argument-hint: " [args]" +--- + +# Skill Management CLI + +Meta-skill for managing oh-my-codex skills via CLI-like commands. + +## Subcommands + +### /skill list + +Show all local skills organized by scope. + +**Behavior:** +1. Scan user skills at `~/.codex/skills/` +2. Scan project skills at `.codex/skills/` +3. Parse YAML frontmatter for metadata +4. Display in organized table format: + +``` +USER SKILLS (~/.codex/skills/): +| Name | Triggers | Quality | Usage | Scope | +|-------------------|--------------------|---------|-------|-------| +| error-handler | fix, error | 95% | 42 | user | +| api-builder | api, endpoint | 88% | 23 | user | + +PROJECT SKILLS (.codex/skills/): +| Name | Triggers | Quality | Usage | Scope | +|-------------------|--------------------|---------|-------|---------| +| test-runner | test, run | 92% | 15 | project | +``` + +**Fallback:** If quality/usage stats not available, show "N/A" + +--- + +### /skill add [name] + +Interactive wizard for creating a new skill. + +**Behavior:** +1. **Ask for skill name** (if not provided in command) + - Validate: lowercase, hyphens only, no spaces +2. **Ask for description** + - Clear, concise one-liner +3. **Ask for triggers** (comma-separated keywords) + - Example: "error, fix, debug" +4. **Ask for argument hint** (optional) + - Example: " [options]" +5. **Ask for scope:** + - `user` → `~/.codex/skills//SKILL.md` + - `project` → `.codex/skills//SKILL.md` +6. **Create skill file** with template: + +```yaml +--- +name: +description: +triggers: + - + - +argument-hint: "" +--- + +# Skill + +## Purpose + +[Describe what this skill does] + +## When to Activate + +[Describe triggers and conditions] + +## Workflow + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Examples + +``` +/oh-my-codex: example-arg +``` + +## Notes + +[Additional context, edge cases, gotchas] +``` + +7. **Report success** with file path +8. **Suggest:** "Edit `/skill edit ` to customize content" + +**Example:** +``` +User: /skill add custom-logger +Assistant: Creating new skill 'custom-logger'... + +Description: Enhanced logging with structured output +Triggers (comma-separated): log, logger, logging +Argument hint (optional): [message] +Scope (user/project): user + +✓ Created skill at ~/.codex/skills/custom-logger/SKILL.md +→ Edit with: /skill edit custom-logger +``` + +--- + +### /skill remove + +Remove a skill by name. + +**Behavior:** +1. **Search for skill** in both scopes: + - `~/.codex/skills//SKILL.md` + - `.codex/skills//SKILL.md` +2. **If found:** + - Display skill info (name, description, scope) + - **Ask for confirmation:** "Delete '' skill from ? (yes/no)" +3. **If confirmed:** + - Delete entire skill directory (e.g., `~/.codex/skills//`) + - Report: "✓ Removed skill '' from " +4. **If not found:** + - Report: "✗ Skill '' not found in user or project scope" + +**Safety:** Never delete without explicit user confirmation. + +**Example:** +``` +User: /skill remove old-logger +Assistant: Found skill 'old-logger' in user scope: + Description: Legacy logging utility + Scope: user (~/.codex/skills/) + +Delete 'old-logger' skill? (yes/no) + +User: yes +Assistant: ✓ Removed skill 'old-logger' from user scope +``` + +--- + +### /skill edit + +Edit an existing skill interactively. + +**Behavior:** +1. **Find skill** by name (search both scopes) +2. **Read current content** via Read tool +3. **Display current values:** + ``` + Current skill 'custom-logger': + - Description: Enhanced logging with structured output + - Triggers: log, logger, logging + - Argument hint: [message] + - Scope: user + ``` +4. **Ask what to change:** + - `description` - Update description + - `triggers` - Update trigger keywords + - `argument-hint` - Update argument hint + - `content` - Edit full markdown content + - `rename` - Rename skill (move file) + - `cancel` - Exit without changes +5. **For selected field:** + - Show current value + - Ask for new value + - Update YAML frontmatter or content + - Write back to file +6. **Report success** with summary of changes + +**Example:** +``` +User: /skill edit custom-logger +Assistant: Current skill 'custom-logger': + - Description: Enhanced logging with structured output + - Triggers: log, logger, logging + - Argument hint: [message] + +What would you like to edit? (description/triggers/argument-hint/content/rename/cancel) + +User: triggers +Assistant: Current triggers: log, logger, logging +New triggers (comma-separated): log, logger, logging, trace + +✓ Updated triggers for 'custom-logger' +``` + +--- + +### /skill search + +Search skills by content, triggers, name, or description. + +**Behavior:** +1. **Scan all skills** in both scopes +2. **Match query** (case-insensitive) against: + - Skill name + - Description + - Triggers + - Full markdown content +3. **Display matches** with context: + +``` +Found 3 skills matching "typescript error": + +1. typescript-fixer (user) + Description: Fix common TypeScript errors + Match: "typescript error handling patterns" + +2. error-handler (user) + Description: Generic error handling utilities + Match: "Supports TypeScript and JavaScript errors" + +3. lint-fix (project) + Description: Auto-fix linting errors + Match: "TypeScript ESLint error resolution" +``` + +**Ranking:** Prioritize matches in name/triggers over content matches + +**Example:** +``` +User: /skill search api endpoint +Assistant: Found 2 skills matching "api endpoint": + +1. api-builder (user) + Description: Generate REST API endpoints + Triggers: api, endpoint, rest + +2. backend-scaffold (project) + Description: Scaffold backend services + Match: "Creates API endpoint boilerplate" +``` + +--- + +### /skill info + +Show detailed information about a skill. + +**Behavior:** +1. **Find skill** by name (search both scopes) +2. **Parse YAML frontmatter** and content +3. **Display complete details:** + +``` +Skill: custom-logger +Scope: user (~/.codex/skills/custom-logger/) +Description: Enhanced logging with structured output +Triggers: log, logger, logging +Argument Hint: [message] +Quality: 95% (if available) +Usage Count: 42 times (if available) +File Path: /home/user/.codex/skills/custom-logger/SKILL.md + +--- FULL CONTENT --- +[entire markdown content] +``` + +**If not found:** Report error with suggestion to use `/skill search` + +**Example:** +``` +User: /skill info custom-logger +Assistant: Skill: custom-logger +Scope: user +Description: Enhanced logging with structured output +Triggers: log, logger, logging +File: ~/.codex/skills/custom-logger/SKILL.md + +--- CONTENT --- +# Custom Logger Skill + +## Purpose +Enhanced logging with structured JSON output... +[rest of content] +``` + +--- + +### /skill sync + +Sync skills between user and project scopes. + +**Behavior:** +1. **Scan both scopes:** + - User skills: `~/.codex/skills/` + - Project skills: `.codex/skills/` +2. **Compare and categorize:** + - User-only skills (not in project) + - Project-only skills (not in user) + - Common skills (in both) +3. **Display sync opportunities:** + +``` +SYNC REPORT: + +User-only skills (5): + - error-handler + - api-builder + - custom-logger + - test-generator + - deploy-helper + +Project-only skills (2): + - test-runner + - backend-scaffold + +Common skills (3): + - design + - frontend-ui-ux (deprecated; use design or visual-ralph) + - git-master + - planner + +Options: + [1] Copy user skill to project + [2] Copy project skill to user + [3] View differences + [4] Cancel +``` + +4. **Handle user choice:** + - Option 1: Select skill(s) to copy to project + - Option 2: Select skill(s) to copy to user + - Option 3: Show side-by-side diff for common skills + - Option 4: Exit + +**Safety:** Never overwrite without confirmation + +**Example:** +``` +User: /skill sync +Assistant: Found 5 user-only skills and 2 project-only skills. + +Copy 'error-handler' from user to project? (yes/no/skip) +User: yes +Assistant: ✓ Copied 'error-handler' to .codex/skills/ + +Copy 'api-builder' from user to project? (yes/no/skip) +User: skip +... +``` + +--- + +### /skill setup + +Interactive wizard for setting up and managing local skills (formerly local-skills-setup). + +**Behavior:** + +#### Step 1: Directory Check and Setup + +First, check if skill directories exist and create them if needed: + +```bash +# Check and create user-level skills directory +USER_SKILLS_DIR="$HOME/.codex/skills" +if [ -d "$USER_SKILLS_DIR" ]; then + echo "User skills directory exists: $USER_SKILLS_DIR" +else + mkdir -p "$USER_SKILLS_DIR" + echo "Created user skills directory: $USER_SKILLS_DIR" +fi + +# Check and create project-level skills directory +PROJECT_SKILLS_DIR=".codex/skills" +if [ -d "$PROJECT_SKILLS_DIR" ]; then + echo "Project skills directory exists: $PROJECT_SKILLS_DIR" +else + mkdir -p "$PROJECT_SKILLS_DIR" + echo "Created project skills directory: $PROJECT_SKILLS_DIR" +fi +``` + +#### Step 2: Skill Scan and Inventory + +Scan both directories and show a comprehensive inventory: + +```bash +# Scan user-level skills +echo "=== USER-LEVEL SKILLS (~/.codex/skills/) ===" +if [ -d "$HOME/.codex/skills" ]; then + USER_COUNT=$(find "$HOME/.codex/skills" -name "*.md" 2>/dev/null | wc -l) + echo "Total skills: $USER_COUNT" + + if [ $USER_COUNT -gt 0 ]; then + echo "" + echo "Skills found:" + find "$HOME/.codex/skills" -name "*.md" -type f -exec sh -c ' + FILE="$1" + NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //") + DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //") + MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null) + echo " - $NAME" + [ -n "$DESC" ] && echo " Description: $DESC" + echo " Modified: $MODIFIED" + echo "" + ' sh {} \; + fi +else + echo "Directory not found" +fi + +echo "" +echo "=== PROJECT-LEVEL SKILLS (.codex/skills/) ===" +if [ -d ".codex/skills" ]; then + PROJECT_COUNT=$(find ".codex/skills" -name "*.md" 2>/dev/null | wc -l) + echo "Total skills: $PROJECT_COUNT" + + if [ $PROJECT_COUNT -gt 0 ]; then + echo "" + echo "Skills found:" + find ".codex/skills" -name "*.md" -type f -exec sh -c ' + FILE="$1" + NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //") + DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //") + MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null) + echo " - $NAME" + [ -n "$DESC" ] && echo " Description: $DESC" + echo " Modified: $MODIFIED" + echo "" + ' sh {} \; + fi +else + echo "Directory not found" +fi + +# Summary +TOTAL=$((USER_COUNT + PROJECT_COUNT)) +echo "=== SUMMARY ===" +echo "Total skills across all directories: $TOTAL" +``` + +#### Step 3: Quick Actions Menu + +After scanning, use the AskUserQuestion tool to offer these options: + +**Question:** "What would you like to do with your local skills?" + +**Options:** +1. **Add new skill** - Start the skill creation wizard (invoke `/skill add`) +2. **List all skills with details** - Show comprehensive skill inventory (invoke `/skill list`) +3. **Scan conversation for patterns** - Analyze current conversation for skill-worthy patterns +4. **Import skill** - Import a skill from URL or paste content +5. **Done** - Exit the wizard + +**Option 3: Scan Conversation for Patterns** + +Analyze the current conversation context to identify potential skill-worthy patterns. Look for: +- Recent debugging sessions with non-obvious solutions +- Tricky bugs that required investigation +- Codebase-specific workarounds discovered +- Error patterns that took time to resolve + +Report findings and ask if user wants to extract any as skills (invoke `/learner` if yes). + +**Option 4: Import Skill** + +Ask user to provide either: +- **URL**: Download skill from a URL (e.g., GitHub gist) +- **Paste content**: Paste skill markdown content directly + +Then ask for scope: +- **User-level** (~/.codex/skills/) - Available across all projects +- **Project-level** (.codex/skills/) - Only for this project + +Validate the skill format and save to the chosen location. + +--- + +### /skill scan + +Quick command to scan both skill directories (subset of `/skill setup`). + +**Behavior:** +Run the scan from Step 2 of `/skill setup` without the interactive wizard. + +--- + +## Skill Templates + +When creating skills via `/skill add` or `/skill setup`, offer quick templates for common skill types: + +### Error Solution Template + +```markdown +--- +id: error-[unique-id] +name: [Error Name] +description: Solution for [specific error in specific context] +source: conversation +triggers: ["error message fragment", "file path", "symptom"] +quality: high +--- + +# [Error Name] + +## The Insight +What is the underlying cause of this error? What principle did you discover? + +## Why This Matters +What goes wrong if you don't know this? What symptom led here? + +## Recognition Pattern +How do you know when this applies? What are the signs? +- Error message: "[exact error]" +- File: [specific file path] +- Context: [when does this occur] + +## The Approach +Step-by-step solution: +1. [Specific action with file/line reference] +2. [Specific action with file/line reference] +3. [Verification step] + +## Example +\`\`\`typescript +// Before (broken) +[problematic code] + +// After (fixed) +[corrected code] +\`\`\` +``` + +### Workflow Skill Template + +```markdown +--- +id: workflow-[unique-id] +name: [Workflow Name] +description: Process for [specific task in this codebase] +source: conversation +triggers: ["task description", "file pattern", "goal keyword"] +quality: high +--- + +# [Workflow Name] + +## The Insight +What makes this workflow different from the obvious approach? + +## Why This Matters +What fails if you don't follow this process? + +## Recognition Pattern +When should you use this workflow? +- Task type: [specific task] +- Files involved: [specific patterns] +- Indicators: [how to recognize] + +## The Approach +1. [Step with specific commands/files] +2. [Step with specific commands/files] +3. [Verification] + +## Gotchas +- [Common mistake and how to avoid it] +- [Edge case and how to handle it] +``` + +### Code Pattern Template + +```markdown +--- +id: pattern-[unique-id] +name: [Pattern Name] +description: Pattern for [specific use case in this codebase] +source: conversation +triggers: ["code pattern", "file type", "problem domain"] +quality: high +--- + +# [Pattern Name] + +## The Insight +What's the key principle behind this pattern? + +## Why This Matters +What problems does this pattern solve in THIS codebase? + +## Recognition Pattern +When do you apply this pattern? +- File types: [specific files] +- Problem: [specific problem] +- Context: [codebase-specific context] + +## The Approach +Decision-making heuristic, not just code: +1. [Principle-based step] +2. [Principle-based step] + +## Example +\`\`\`typescript +[Illustrative example showing the principle] +\`\`\` + +## Anti-Pattern +What NOT to do and why: +\`\`\`typescript +[Common mistake to avoid] +\`\`\` +``` + +### Integration Skill Template + +```markdown +--- +id: integration-[unique-id] +name: [Integration Name] +description: How [system A] integrates with [system B] in this codebase +source: conversation +triggers: ["system name", "integration point", "config file"] +quality: high +--- + +# [Integration Name] + +## The Insight +What's non-obvious about how these systems connect? + +## Why This Matters +What breaks if you don't understand this integration? + +## Recognition Pattern +When are you working with this integration? +- Files: [specific integration files] +- Config: [specific config locations] +- Symptoms: [what indicates integration issues] + +## The Approach +How to work with this integration correctly: +1. [Configuration step with file paths] +2. [Setup step with specific details] +3. [Verification step] + +## Gotchas +- [Integration-specific pitfall #1] +- [Integration-specific pitfall #2] +``` + +--- + +## Error Handling + +**All commands must handle:** +- File/directory doesn't exist +- Permission errors +- Invalid YAML frontmatter +- Duplicate skill names +- Invalid skill names (spaces, special chars) + +**Error format:** +``` +✗ Error: +→ Suggestion: +``` + +--- + +## Usage Examples + +```bash +# List all skills +/skill list + +# Create a new skill +/skill add my-custom-skill + +# Remove a skill +/skill remove old-skill + +# Edit existing skill +/skill edit error-handler + +# Search for skills +/skill search typescript error + +# Get detailed info +/skill info my-custom-skill + +# Sync between scopes +/skill sync + +# Run setup wizard +/skill setup + +# Quick scan +/skill scan +``` + +## Usage Modes + +### Direct Command Mode + +When invoked with an argument, skip the interactive wizard: + +- `/skill list` - Show detailed skill inventory +- `/skill add` - Start skill creation (invoke learner) +- `/skill scan` - Scan both skill directories + +### Interactive Mode + +When invoked without arguments, run the full guided wizard. + +--- + +## Benefits of Local Skills + +**Automatic Application**: Codex detects triggers and applies skills automatically - no need to remember or search for solutions. + +**Version Control**: Project-level skills (.codex/skills/) are committed with your code, so the whole team benefits. + +**Evolving Knowledge**: Skills improve over time as you discover better approaches and refine triggers. + +**Reduced Token Usage**: Instead of re-solving the same problems, Codex applies known patterns efficiently. + +**Codebase Memory**: Preserves institutional knowledge that would otherwise be lost in conversation history. + +--- + +## Skill Quality Guidelines + +Good skills are: + +1. **Non-Googleable** - Can't easily find via search + - BAD: "How to read files in TypeScript" + - GOOD: "This codebase uses custom path resolution requiring fileURLToPath" + +2. **Context-Specific** - References actual files/errors from THIS codebase + - BAD: "Use try/catch for error handling" + - GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError" + +3. **Actionable with Precision** - Tells exactly WHAT to do and WHERE + - BAD: "Handle edge cases" + - GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution" + +4. **Hard-Won** - Required significant debugging effort + - BAD: Generic programming patterns + - GOOD: "Race condition in worker.ts - Promise.all at line 89 needs await" + +--- + +## Related Skills + +- `/learner` - Extract a skill from current conversation +- `/note` - Save quick notes (less formal than skills) + +--- + +## Example Session + +``` +> /skill list + +Checking skill directories... +✓ User skills directory exists: ~/.codex/skills/ +✓ Project skills directory exists: .codex/skills/ + +Scanning for skills... + +=== USER-LEVEL SKILLS === +Total skills: 3 + - async-network-error-handling + Description: Pattern for handling independent I/O failures in async network code + Modified: 2026-01-20 14:32:15 + + - esm-path-resolution + Description: Custom path resolution in ESM requiring fileURLToPath + Modified: 2026-01-19 09:15:42 + +=== PROJECT-LEVEL SKILLS === +Total skills: 5 + - session-timeout-fix + Description: Fix for sessionId undefined after restart in session.ts + Modified: 2026-01-22 16:45:23 + + - build-cache-invalidation + Description: When to clear TypeScript build cache to fix phantom errors + Modified: 2026-01-21 11:28:37 + +=== SUMMARY === +Total skills: 8 + +What would you like to do? +1. Add new skill +2. List all skills with details +3. Scan conversation for patterns +4. Import skill +5. Done +``` + +--- + +## Tips for Users + +- Run `/skill list` periodically to review your skill library +- After solving a tricky bug, immediately run learner to capture it +- Use project-level skills for codebase-specific knowledge +- Use user-level skills for general patterns that apply everywhere +- Review and refine triggers over time to improve matching accuracy + +--- + +## Implementation Notes + +1. **YAML Parsing:** Use frontmatter extraction for metadata +2. **File Operations:** Use Read/Write tools, never Edit for new files +3. **User Confirmation:** Always confirm destructive operations +4. **Clear Feedback:** Use checkmarks (✓), crosses (✗), arrows (→) for clarity +5. **Scope Resolution:** Always check both user and project scopes +6. **Validation:** Enforce naming conventions (lowercase, hyphens only) + +--- + +## Related Skills + +- `/learner` - Extract a skill from current conversation +- `/note` - Save quick notes (less formal than skills) + +--- + +## Future Enhancements + +- `/skill export ` - Export skill as shareable file +- `/skill import ` - Import skill from file +- `/skill stats` - Show usage statistics across all skills +- `/skill validate` - Check all skills for format errors +- `/skill template ` - Create from predefined templates diff --git a/scripts/__pycache__/validate_marketplace.cpython-314.pyc b/scripts/__pycache__/validate_marketplace.cpython-314.pyc new file mode 100644 index 000000000..28c0a5b85 Binary files /dev/null and b/scripts/__pycache__/validate_marketplace.cpython-314.pyc differ