oh-my-codex 0.20.3 → 0.21.0

package/skills/skill/SKILL.md

@@ -4,833 +4,108 @@ description: Manage local skills - list, add, remove, search, edit, setup wizard
 argument-hint: "<command> [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: "<file> [options]"
-5. **Ask for scope:**
-   - `user` → `~/.codex/skills/<name>/SKILL.md`
-   - `project` → `.codex/skills/<name>/SKILL.md`
-6. **Create skill file** with template:
+# Skill Management
+
+Manage local `SKILL.md` files with `/skill` commands. Shared execution, delegation,
+state, hook, team, cancellation, verification, and escalation invariants live in
+`templates/AGENTS.md`; follow that contract instead of repeating it here.
+
+<Purpose>
+Create, inspect, validate, update, and organize user- or project-scoped skills.
+Keep each skill specific, actionable, evidence-based, and useful to this codebase.
+</Purpose>
+
+<Use_When>
+- The user asks to list, add, edit, remove, search, inspect, sync, set up, scan, or validate skills.
+- A durable, codebase-specific solution or workflow should be captured as a skill.
+</Use_When>
+
+<Do_Not_Use_When>
+- Use `/learner` to extract a skill from a conversation and `/note` for a short note.
+- Do not use this prompt to change runtime code, catalogs, hooks, or installation logic.
+</Do_Not_Use_When>
+
+## Scopes and commands
+
+Canonical roots are `${CODEX_HOME:-$HOME/.codex}/skills/` (user) and `.codex/skills/`
+(project). A skill lives at `<root>/<name>/SKILL.md`.
+
+| Command | Contract |
+|---|---|
+| `/skill list` | Scan both roots, parse frontmatter, and show name, description, triggers, scope, and quality/usage (`N/A` when unavailable). |
+| `/skill add [name]` | Run the authoring wizard, validate the name, choose scope, create `SKILL.md`, and report its path. |
+| `/skill edit <name>` | Find one scope, show metadata, then update description, triggers, argument hint, body, or rename and report the change. |
+| `/skill remove <name>` | Find the skill, show scope and metadata, confirm explicitly, then remove its directory. |
+| `/skill search <query>` | Case-insensitively search name, description, triggers, and body; rank name/trigger matches first and show context. |
+| `/skill info <name>` | Show parsed metadata, scope, path, and full body; suggest `/skill search` when absent. |
+| `/skill sync` | Compare user/project skills, show user-only/project-only/common entries, and confirm every copy or overwrite. |
+| `/skill setup` | Ensure both roots exist, scan them, then offer add, list, pattern scan, import, or done. |
+| `/skill scan` | Run setup's scan/inventory without its interactive menu. |
+| `/skill validate` | Validate every skill in both roots and report each path's pass/fail result; never rewrite files. |
+
+With an argument, use direct command mode; without one, use the guided setup menu.
+
+## Authoring contract
+
+Ask for any missing values:
+1. `name`: lowercase letters/digits separated by single hyphens (`[a-z0-9]+(?:-[a-z0-9]+)*`).
+2. `description`: a concise, non-empty one-line purpose.
+3. `triggers`: comma-separated recognition terms.
+4. `argument-hint`: optional invocation arguments.
+5. `scope`: `user` or `project`.
+
+Write this frontmatter at the start of every skill; optional metadata may add `id`,
+`source`, and `quality` without replacing required fields:
 
 ```yaml
 ---
 name: <name>
-description: <description>
-triggers:
-  - <trigger1>
-  - <trigger2>
+description: <one-line purpose>
+triggers: [<trigger1>, <trigger2>]
 argument-hint: "<args>"
+# optional: id, source, quality
 ---
-
-# <Name> 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:<name> example-arg
-```
-
-## Notes
-
-[Additional context, edge cases, gotchas]
-```
-
-7. **Report success** with file path
-8. **Suggest:** "Edit `/skill edit <name>` 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): <level> [message]
-Scope (user/project): user
-
-✓ Created skill at ~/.codex/skills/custom-logger/SKILL.md
-→ Edit with: /skill edit custom-logger
-```
-
----
-
-### /skill remove <name>
-
-Remove a skill by name.
-
-**Behavior:**
-1. **Search for skill** in both scopes:
-   - `~/.codex/skills/<name>/SKILL.md`
-   - `.codex/skills/<name>/SKILL.md`
-2. **If found:**
-   - Display skill info (name, description, scope)
-   - **Ask for confirmation:** "Delete '<name>' skill from <scope>? (yes/no)"
-3. **If confirmed:**
-   - Delete entire skill directory (e.g., `~/.codex/skills/<name>/`)
-   - Report: "✓ Removed skill '<name>' from <scope>"
-4. **If not found:**
-   - Report: "✗ Skill '<name>' 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 <name>
-
-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: <level> [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: <level> [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 <query>
-
-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 <name>
-
-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: <level> [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
+Use an actionable body. The minimum recommended shape is:
 
 ```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]
-\`\`\`
+# <Skill title>
 
-## 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?
+## Purpose
+What durable, codebase-specific outcome does this skill provide?
 
-## Recognition Pattern
-When are you working with this integration?
-- Files: [specific integration files]
-- Config: [specific config locations]
-- Symptoms: [what indicates integration issues]
+## When to Activate
+Recognition signals, scope, and explicit non-goals.
 
-## The Approach
-How to work with this integration correctly:
-1. [Configuration step with file paths]
-2. [Setup step with specific details]
-3. [Verification step]
+## Workflow
+1. Inspect the named files or inputs.
+2. Apply the precise approach and record important assumptions.
+3. Verify observable behavior and report evidence.
 
-## Gotchas
-- [Integration-specific pitfall #1]
-- [Integration-specific pitfall #2]
+## Examples / Gotchas
+Concrete invocation, edge cases, and failure recovery.
 ```
 
----
+Prefer hard-won, non-obvious knowledge over generic programming advice. Include
+exact paths, commands, error text, and expected evidence when they materially help.
 
-## Error Handling
+## Validation and errors
 
-**All commands must handle:**
-- File/directory doesn't exist
-- Permission errors
-- Invalid YAML frontmatter
-- Duplicate skill names
-- Invalid skill names (spaces, special chars)
+Before reporting success, check that the file exists, starts with `---` frontmatter,
+has non-empty `name` and `description`, uses a valid name, and has a non-empty body.
+Reject malformed or unterminated YAML, multiline required scalar values, duplicate
+names in one scope, missing directories/files, permission failures, and invalid
+arguments. Report errors consistently:
 
-**Error format:**
-```
+```text
 ✗ Error: <clear message>
-→ Suggestion: <helpful next step>
+→ Suggestion: <specific next step>
 ```
 
----
-
-## 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
+## Exit contract
 
-- `/skill export <name>` - Export skill as shareable file
-- `/skill import <file>` - Import skill from file
-- `/skill stats` - Show usage statistics across all skills
-- `/skill validate` - Check all skills for format errors
-- `/skill template <type>` - Create from predefined templates
+Every command ends with one concise result: `✓` plus the affected skill/path and
+next action, or `✗` plus the error and suggestion. Preserve files on cancel or
+validation-only runs. For add/edit/sync, report changed scope and metadata; for
+list/search/info/scan/validate, report counts or matched paths and any failures.