claudecode-omc 5.6.4 → 5.6.6

package/src/cli/skill-index.js

@@ -0,0 +1,209 @@
+/* eslint-disable no-console */
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const os = require('os');
+const { getProjectRoot } = require('../config/paths');
+
+const INDEX_FILENAME = '_index.md';
+const MAX_DESCRIPTION_CHARS = 280;
+
+/**
+ * Parse YAML frontmatter from a SKILL.md, returning { name, description }.
+ *
+ * Handles:
+ *  - `key: value` single-line
+ *  - `key: >-` or `key: |` folded/literal block scalars (collects indented
+ *    continuation lines, joined with spaces)
+ *  - quoted values: stripped of surrounding quotes
+ *
+ * Returns null if frontmatter is missing or name field is absent.
+ */
+function parseFrontmatter(skillFile) {
+  if (!fs.existsSync(skillFile)) return null;
+
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const lines = match[1].split('\n');
+  const meta = {};
+  let currentKey = null;
+  let blockMode = false; // when value is `>-` or `|`
+
+  for (const raw of lines) {
+    if (!raw.trim()) continue;
+
+    // top-level key: detect by leading non-whitespace + colon
+    const keyMatch = raw.match(/^([a-zA-Z_-][\w-]*)\s*:\s*(.*)$/);
+    const isIndented = /^\s/.test(raw);
+
+    if (keyMatch && !isIndented) {
+      currentKey = keyMatch[1];
+      const valueRaw = keyMatch[2].trim();
+      if (valueRaw === '>-' || valueRaw === '>' || valueRaw === '|' || valueRaw === '|-') {
+        meta[currentKey] = '';
+        blockMode = true;
+      } else {
+        meta[currentKey] = stripQuotes(valueRaw);
+        blockMode = false;
+      }
+    } else if (currentKey && (blockMode || isIndented)) {
+      // continuation line
+      const continued = raw.trim();
+      if (continued) {
+        meta[currentKey] = (meta[currentKey] ? meta[currentKey] + ' ' : '') + continued;
+      }
+    }
+  }
+
+  if (!meta.name) return null;
+  return meta;
+}
+
+function stripQuotes(s) {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function truncateDescription(desc) {
+  if (!desc) return '';
+  // Collapse whitespace
+  const flat = desc.replace(/\s+/g, ' ').trim();
+  if (flat.length <= MAX_DESCRIPTION_CHARS) return flat;
+  // Truncate at sentence boundary if possible
+  const truncated = flat.slice(0, MAX_DESCRIPTION_CHARS);
+  const lastPeriod = truncated.lastIndexOf('.');
+  if (lastPeriod > MAX_DESCRIPTION_CHARS * 0.6) {
+    return truncated.slice(0, lastPeriod + 1);
+  }
+  return truncated + '…';
+}
+
+function escapeTableCell(s) {
+  return (s || '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+/**
+ * Scan a directory of skills (each subdir contains SKILL.md) and return
+ * sorted list of { name, description }.
+ */
+function buildEntries(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  const items = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+
+    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+    const meta = parseFrontmatter(skillFile);
+    if (!meta) {
+      process.stderr.write(`  skipped: ${entry.name} (no frontmatter)\n`);
+      continue;
+    }
+    items.push({
+      name: meta.name,
+      description: truncateDescription(meta.description),
+    });
+  }
+
+  items.sort((a, b) => a.name.localeCompare(b.name));
+  return items;
+}
+
+/**
+ * Render entries as a Markdown table with a header preamble.
+ */
+function renderIndex(skillsDir, entries) {
+  const lines = [];
+  lines.push('# Skill Index');
+  lines.push('');
+  lines.push(`Auto-generated by \`omc-manage skill index\`. Do not edit by hand —`);
+  lines.push(`rerun \`omc-manage skill index\` after adding or removing skills.`);
+  lines.push('');
+  lines.push(`Source directory: \`${skillsDir.replace(os.homedir(), '~')}\``);
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  lines.push(`Entries: ${entries.length}`);
+  lines.push('');
+  lines.push('## Usage for LLMs');
+  lines.push('');
+  lines.push('`grep -i "<keyword>" _index.md` to find skills matching an intent.');
+  lines.push('Each row is `name | description` — both fields searchable.');
+  lines.push('');
+  lines.push('| Skill | Description |');
+  lines.push('|---|---|');
+  for (const e of entries) {
+    lines.push(`| \`${escapeTableCell(e.name)}\` | ${escapeTableCell(e.description)} |`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Build and write the index. Returns { path, count }.
+ */
+async function buildAndWriteIndex(skillsDir, { quiet = false } = {}) {
+  const entries = buildEntries(skillsDir);
+  const indexPath = path.join(skillsDir, INDEX_FILENAME);
+  await fsp.writeFile(indexPath, renderIndex(skillsDir, entries), 'utf8');
+  if (!quiet) {
+    console.log(`  wrote ${indexPath.replace(os.homedir(), '~')} (${entries.length} entries)`);
+  }
+  return { path: indexPath, count: entries.length };
+}
+
+/**
+ * Resolve the skills install directory for the given scope.
+ */
+function resolveSkillsDir(scope) {
+  if (scope === 'project') {
+    const root = getProjectRoot();
+    return path.join(root, '.claude', 'skills');
+  }
+  // default: user scope
+  return path.join(os.homedir(), '.claude', 'skills');
+}
+
+/**
+ * CLI entrypoint: `omc-manage skill index [--scope user|project] [--quiet]`
+ */
+async function indexCommand(args, flags = {}) {
+  const scope = flags.scope || 'user';
+  if (scope !== 'user' && scope !== 'project') {
+    console.error(`Error: invalid --scope "${scope}" (expected user or project)`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const skillsDir = resolveSkillsDir(scope);
+  if (!fs.existsSync(skillsDir)) {
+    console.error(`Error: skills directory not found: ${skillsDir}`);
+    console.error('Run `omc-manage setup` first to install skills.');
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`omc-manage skill index`);
+  console.log(`======================`);
+  console.log(`Scope: ${scope}`);
+  console.log(`Target: ${skillsDir.replace(os.homedir(), '~')}`);
+  console.log('');
+
+  const result = await buildAndWriteIndex(skillsDir, { quiet: flags.quiet });
+
+  console.log('');
+  console.log(`Indexed ${result.count} skills.`);
+}
+
+module.exports = {
+  indexCommand,
+  buildAndWriteIndex,
+  resolveSkillsDir,
+  parseFrontmatter, // exported for tests
+  truncateDescription, // exported for tests
+};

package/src/cli/skill.js

@@ -271,6 +271,10 @@ async function skill(args, flags = {}) {
   if (cmd === 'recommend') {
     return recommend(args, flags);
   }
+  if (cmd === 'index') {
+    const { indexCommand } = require('./skill-index');
+    return indexCommand(args.slice(1), flags);
+  }
 
   // Fall through to artifact subcommands (list, prefer, conflicts)
   flags.type = 'skills';

package/bundled/upstream/anthropic-skills/skills/claude-api/python/agent-sdk/README.md

@@ -1,355 +0,0 @@
-# Agent SDK — Python
-
-The Claude Agent SDK provides a higher-level interface for building AI agents with built-in tools, safety features, and agentic capabilities.
-
-## Installation
-
-```bash
-pip install claude-agent-sdk
-```
-
----
-
-## Quick Start
-
-```python
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async def main():
-    async for message in query(
-        prompt="Explain this codebase",
-        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```
-
----
-
-## Built-in Tools
-
-| Tool      | Description                          |
-| --------- | ------------------------------------ |
-| Read      | Read files in the workspace          |
-| Write     | Create new files                     |
-| Edit      | Make precise edits to existing files |
-| Bash      | Execute shell commands               |
-| Glob      | Find files by pattern                |
-| Grep      | Search files by content              |
-| WebSearch | Search the web for information       |
-| WebFetch        | Fetch and analyze web pages          |
-| AskUserQuestion | Ask user clarifying questions         |
-| Agent           | Spawn subagents                      |
-
----
-
-## Primary Interfaces
-
-### `query()` — Simple One-Shot Usage
-
-The `query()` function is the simplest way to run an agent. It returns an async iterator of messages.
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async for message in query(
-    prompt="Explain this codebase",
-    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
-):
-    if isinstance(message, ResultMessage):
-        print(message.result)
-```
-
-### `ClaudeSDKClient` — Full Control
-
-`ClaudeSDKClient` provides full control over the agent lifecycle. Use it when you need custom tools, hooks, streaming, or the ability to interrupt execution.
-
-```python
-import anyio
-from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
-
-async def main():
-    options = ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
-    async with ClaudeSDKClient(options=options) as client:
-        await client.query("Explain this codebase")
-        async for message in client.receive_response():
-            if isinstance(message, AssistantMessage):
-                for block in message.content:
-                    if isinstance(block, TextBlock):
-                        print(block.text)
-
-anyio.run(main)
-```
-
-`ClaudeSDKClient` supports:
-
-- **Context manager** (`async with`) for automatic resource cleanup
-- **`client.query(prompt)`** to send a prompt to the agent
-- **`receive_response()`** for streaming messages until completion
-- **`interrupt()`** to stop agent execution mid-task
-- **Required for custom tools** (via SDK MCP servers)
-
----
-
-## Permission System
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async for message in query(
-    prompt="Refactor the authentication module",
-    options=ClaudeAgentOptions(
-        allowed_tools=["Read", "Edit", "Write"],
-        permission_mode="acceptEdits"  # Auto-accept file edits
-    )
-):
-    if isinstance(message, ResultMessage):
-        print(message.result)
-```
-
-Permission modes:
-
-- `"default"`: Prompt for dangerous operations
-- `"plan"`: Planning only, no execution
-- `"acceptEdits"`: Auto-accept file edits
-- `"bypassPermissions"`: Skip all prompts (use with caution)
-
----
-
-## MCP (Model Context Protocol) Support
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async for message in query(
-    prompt="Open example.com and describe what you see",
-    options=ClaudeAgentOptions(
-        mcp_servers={
-            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
-        }
-    )
-):
-    if isinstance(message, ResultMessage):
-        print(message.result)
-```
-
----
-
-## Hooks
-
-Customize agent behavior with hooks using callback functions:
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage
-
-async def log_file_change(input_data, tool_use_id, context):
-    file_path = input_data.get('tool_input', {}).get('file_path', 'unknown')
-    print(f"Modified: {file_path}")
-    return {}
-
-async for message in query(
-    prompt="Refactor utils.py",
-    options=ClaudeAgentOptions(
-        permission_mode="acceptEdits",
-        hooks={
-            "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])]
-        }
-    )
-):
-    if isinstance(message, ResultMessage):
-        print(message.result)
-```
-
-Hook callback inputs for tool-lifecycle events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`) include `agent_id` and `agent_type` fields, allowing hooks to identify which agent (main or subagent) triggered the tool call.
-
-Available hook events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PreCompact`, `Notification`, `SubagentStart`, `PermissionRequest`
-
----
-
-## Common Options
-
-`query()` takes a top-level `prompt` (string) and an `options` object (`ClaudeAgentOptions`):
-
-```python
-async for message in query(prompt="...", options=ClaudeAgentOptions(...)):
-```
-
-| Option                              | Type   | Description                                                                |
-| ----------------------------------- | ------ | -------------------------------------------------------------------------- |
-| `cwd`                               | string | Working directory for file operations                                      |
-| `allowed_tools`                     | list   | Tools the agent can use (e.g., `["Read", "Edit", "Bash"]`)                |
-| `tools`                             | list   | Built-in tools to make available (restricts the default set)               |
-| `disallowed_tools`                  | list   | Tools to explicitly disallow                                               |
-| `permission_mode`                   | string | How to handle permission prompts                                           |
-| `mcp_servers`                       | dict   | MCP servers to connect to                                                  |
-| `hooks`                             | dict   | Hooks for customizing behavior                                             |
-| `system_prompt`                     | string | Custom system prompt                                                       |
-| `max_turns`                         | int    | Maximum agent turns before stopping                                        |
-| `max_budget_usd`                    | float  | Maximum budget in USD for the query                                        |
-| `model`                             | string | Model ID (default: determined by CLI)                                      |
-| `agents`                            | dict   | Subagent definitions (`dict[str, AgentDefinition]`)                        |
-| `output_format`                     | dict   | Structured output schema                                                   |
-| `thinking`                          | dict   | Thinking/reasoning control                                                 |
-| `betas`                             | list   | Beta features to enable (e.g., `["context-1m-2025-08-07"]`)               |
-| `setting_sources`                   | list   | Settings to load (e.g., `["project"]`). Default: none (no CLAUDE.md files) |
-| `env`                               | dict   | Environment variables to set for the session                               |
-
----
-
-## Message Types
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
-
-async for message in query(
-    prompt="Find TODO comments",
-    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
-):
-    if isinstance(message, ResultMessage):
-        print(message.result)
-        print(f"Stop reason: {message.stop_reason}")  # e.g., "end_turn", "max_turns"
-    elif isinstance(message, SystemMessage) and message.subtype == "init":
-        session_id = message.data.get("session_id")  # Capture for resuming later
-```
-
-`AssistantMessage` includes per-turn `usage` data (a dict matching the Anthropic API usage shape) for tracking costs:
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage
-
-async for message in query(prompt="...", options=ClaudeAgentOptions()):
-    if isinstance(message, AssistantMessage) and message.usage:
-        print(f"Input: {message.usage['input_tokens']}, Output: {message.usage['output_tokens']}")
-```
-
-Typed task message subclasses are available for better type safety when handling subagent task events:
-- `TaskStartedMessage` — emitted when a subagent task is registered
-- `TaskProgressMessage` — real-time progress updates with cumulative usage metrics
-- `TaskNotificationMessage` — task completion notifications
-
-`RateLimitEvent` is emitted when the rate limit status transitions (e.g., from `allowed` to `allowed_warning` or `rejected`). Use it to warn users or back off gracefully:
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, RateLimitEvent
-
-async for message in query(prompt="...", options=ClaudeAgentOptions()):
-    if isinstance(message, RateLimitEvent):
-        print(f"Rate limit status: {message.rate_limit_info.status}")
-        if message.rate_limit_info.resets_at:
-            print(f"Resets at: {message.rate_limit_info.resets_at}")
-```
-
----
-
-## Subagents
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage
-
-async for message in query(
-    prompt="Use the code-reviewer agent to review this codebase",
-    options=ClaudeAgentOptions(
-        allowed_tools=["Read", "Glob", "Grep", "Agent"],
-        agents={
-            "code-reviewer": AgentDefinition(
-                description="Expert code reviewer for quality and security reviews.",
-                prompt="Analyze code quality and suggest improvements.",
-                tools=["Read", "Glob", "Grep"]
-            )
-        }
-    )
-):
-    if isinstance(message, ResultMessage):
-        print(message.result)
-```
-
----
-
-## Error Handling
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions, CLINotFoundError, CLIConnectionError, ResultMessage
-
-try:
-    async for message in query(
-        prompt="...",
-        options=ClaudeAgentOptions(allowed_tools=["Read"])
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-except CLINotFoundError:
-    print("Claude Code CLI not found. Install with: pip install claude-agent-sdk")
-except CLIConnectionError as e:
-    print(f"Connection error: {e}")
-```
-
----
-
-## Session History
-
-Retrieve past session data with top-level functions:
-
-```python
-from claude_agent_sdk import list_sessions, get_session_messages
-
-# List all past sessions (sync function — no await)
-sessions = list_sessions()
-for session in sessions:
-    print(f"{session.session_id}: {session.cwd}")
-
-# Get messages from a specific session (sync function — no await)
-messages = get_session_messages(session_id="...")
-for msg in messages:
-    print(msg)
-```
-
-### Session Mutations
-
-Rename or tag sessions (sync functions — no await):
-
-```python
-from claude_agent_sdk import rename_session, tag_session
-
-# Rename a session
-rename_session(session_id="...", title="My refactoring session")
-
-# Tag a session (tags are Unicode-sanitized automatically)
-tag_session(session_id="...", tag="experiment")
-
-# Clear a tag
-tag_session(session_id="...", tag=None)
-
-# Optionally scope to a specific project directory
-rename_session(session_id="...", title="New title", directory="/path/to/project")
-```
-
----
-
-## MCP Server Management
-
-Manage MCP servers at runtime using `ClaudeSDKClient`:
-
-```python
-async with ClaudeSDKClient(options=options) as client:
-    # Reconnect a disconnected MCP server
-    await client.reconnect_mcp_server("my-server")
-
-    # Toggle an MCP server on/off
-    await client.toggle_mcp_server("my-server", enabled=False)
-
-    # Get status of all MCP servers
-    status = await client.get_mcp_status()  # returns McpStatusResponse
-```
-
----
-
-## Best Practices
-
-1. **Always specify allowed_tools** — Explicitly list which tools the agent can use
-2. **Set working directory** — Always specify `cwd` for file operations
-3. **Use appropriate permission modes** — Start with `"default"` and only escalate when needed
-4. **Handle all message types** — Check for `ResultMessage` to get agent output
-5. **Limit max_turns** — Prevent runaway agents with reasonable limits