移除技能

- 新增 skill: lyxy-reader-html，用于解析 HTML 文件和 URL 网页内容
- 支持 URL 下载（pyppeteer → selenium → httpx → urllib 优先级回退）
- 支持 HTML 解析（trafilatura → domscribe → MarkItDown → html2text 优先级回退）
- 支持查询功能：全文提取、字数统计、行数统计、标题提取、章节提取、正则搜索
- 新增 spec: html-document-parsing
- 归档 change: create-lyxy-reader-html-skill

.claude/commands/opsx/apply.md

@@ -0,0 +1,152 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read the files listed in `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.claude/commands/opsx/archive.md

@@ -0,0 +1,157 @@
+---
+name: "OPSX: Archive"
+description: Archive a completed change in the experimental workflow
+category: Workflow
+tags: [workflow, archive, experimental]
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.claude/commands/opsx/bulk-archive.md

@@ -0,0 +1,242 @@
+---
+name: "OPSX: Bulk Archive"
+description: Archive multiple completed changes at once
+category: Workflow
+tags: [workflow, archive, experimental, bulk]
+---
+
+Archive multiple completed changes in a single operation.
+
+This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
+
+**Input**: None required (prompts for selection)
+
+**Steps**
+
+1. **Get active changes**
+
+   Run `openspec list --json` to get all active changes.
+
+   If no active changes exist, inform user and stop.
+
+2. **Prompt for change selection**
+
+   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   - Show each change with its schema
+   - Include an option for "All changes"
+   - Allow any number of selections (1+ works, 2+ is the typical use case)
+
+   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
+
+3. **Batch validation - gather status for all selected changes**
+
+   For each selected change, collect:
+
+   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+      - Parse `schemaName` and `artifacts` list
+      - Note which artifacts are `done` vs other states
+
+   b. **Task completion** - Read `openspec/changes/<name>/tasks.md`
+      - Count `- [ ]` (incomplete) vs `- [x]` (complete)
+      - If no tasks file exists, note as "No tasks"
+
+   c. **Delta specs** - Check `openspec/changes/<name>/specs/` directory
+      - List which capability specs exist
+      - For each, extract requirement names (lines matching `### Requirement: <name>`)
+
+4. **Detect spec conflicts**
+
+   Build a map of `capability -> [changes that touch it]`:
+
+   ```
+   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
+   api  -> [change-c]            <- OK (only 1 change)
+   ```
+
+   A conflict exists when 2+ selected changes have delta specs for the same capability.
+
+5. **Resolve conflicts agentically**
+
+   **For each conflict**, investigate the codebase:
+
+   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
+
+   b. **Search the codebase** for implementation evidence:
+      - Look for code implementing requirements from each delta spec
+      - Check for related files, functions, or tests
+
+   c. **Determine resolution**:
+      - If only one change is actually implemented -> sync that one's specs
+      - If both implemented -> apply in chronological order (older first, newer overwrites)
+      - If neither implemented -> skip spec sync, warn user
+
+   d. **Record resolution** for each conflict:
+      - Which change's specs to apply
+      - In what order (if both)
+      - Rationale (what was found in codebase)
+
+6. **Show consolidated status table**
+
+   Display a table summarizing all changes:
+
+   ```
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   |---------------------|-----------|-------|---------|-----------|--------|
+   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
+   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
+   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
+   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
+   ```
+
+   For conflicts, show the resolution:
+   ```
+   * Conflict resolution:
+     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
+   ```
+
+   For incomplete changes, show warnings:
+   ```
+   Warnings:
+   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
+   ```
+
+7. **Confirm batch operation**
+
+   Use **AskUserQuestion tool** with a single confirmation:
+
+   - "Archive N changes?" with options based on status
+   - Options might include:
+     - "Archive all N changes"
+     - "Archive only N ready changes (skip incomplete)"
+     - "Cancel"
+
+   If there are incomplete changes, make clear they'll be archived with warnings.
+
+8. **Execute archive for each confirmed change**
+
+   Process changes in the determined order (respecting conflict resolution):
+
+   a. **Sync specs** if delta specs exist:
+      - Use the openspec-sync-specs approach (agent-driven intelligent merge)
+      - For conflicts, apply in resolved order
+      - Track if sync was done
+
+   b. **Perform the archive**:
+      ```bash
+      mkdir -p openspec/changes/archive
+      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      ```
+
+   c. **Track outcome** for each change:
+      - Success: archived successfully
+      - Failed: error during archive (record error)
+      - Skipped: user chose not to archive (if applicable)
+
+9. **Display summary**
+
+   Show final results:
+
+   ```
+   ## Bulk Archive Complete
+
+   Archived 3 changes:
+   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
+   - project-config -> archive/2026-01-19-project-config/
+   - add-oauth -> archive/2026-01-19-add-oauth/
+
+   Skipped 1 change:
+   - add-verify-skill (user chose not to archive incomplete)
+
+   Spec sync summary:
+   - 4 delta specs synced to main specs
+   - 1 conflict resolved (auth: applied both in chronological order)
+   ```
+
+   If any failures:
+   ```
+   Failed 1 change:
+   - some-change: Archive directory already exists
+   ```
+
+**Conflict Resolution Examples**
+
+Example 1: Only one implemented
+```
+Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
+
+Checking add-oauth:
+- Delta adds "OAuth Provider Integration" requirement
+- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
+
+Checking add-jwt:
+- Delta adds "JWT Token Handling" requirement
+- Searching codebase... no JWT implementation found
+
+Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
+```
+
+Example 2: Both implemented
+```
+Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
+
+Checking add-rest-api (created 2026-01-10):
+- Delta adds "REST Endpoints" requirement
+- Searching codebase... found src/api/rest.ts
+
+Checking add-graphql (created 2026-01-15):
+- Delta adds "GraphQL Schema" requirement
+- Searching codebase... found src/api/graphql.ts
+
+Resolution: Both implemented. Will apply add-rest-api specs first,
+then add-graphql specs (chronological order, newer takes precedence).
+```
+
+**Output On Success**
+
+```
+## Bulk Archive Complete
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+- <change-2> -> archive/YYYY-MM-DD-<change-2>/
+
+Spec sync summary:
+- N delta specs synced to main specs
+- No conflicts (or: M conflicts resolved)
+```
+
+**Output On Partial Success**
+
+```
+## Bulk Archive Complete (partial)
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+
+Skipped M changes:
+- <change-2> (user chose not to archive incomplete)
+
+Failed K changes:
+- <change-3>: Archive directory already exists
+```
+
+**Output When No Changes**
+
+```
+## No Changes to Archive
+
+No active changes found. Create a new change to get started.
+```
+
+**Guardrails**
+- Allow any number of changes (1+ is fine, 2+ is the typical use case)
+- Always prompt for selection, never auto-select
+- Detect spec conflicts early and resolve by checking codebase
+- When both changes are implemented, apply specs in chronological order
+- Skip spec sync only when implementation is missing (warn user)
+- Show clear per-change status before confirming
+- Use single confirmation for entire batch
+- Track and report all outcomes (success/skip/fail)
+- Preserve .openspec.yaml when moving to archive
+- Archive directory target uses current date: YYYY-MM-DD-<name>
+- If archive target exists, fail that change but continue with others

.claude/commands/opsx/continue.md

@@ -0,0 +1,114 @@
+---
+name: "OPSX: Continue"
+description: Continue working on a change - create the next artifact (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Continue working on a change by creating the next artifact.
+
+**Input**: Optionally specify a change name after `/opsx:continue` (e.g., `/opsx:continue add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+
+   Present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from `schema` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from `lastModified` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check current status**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand current state. The response includes:
+   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
+   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
+   - `isComplete`: Boolean indicating if all artifacts are complete
+
+3. **Act based on status**:
+
+   ---
+
+   **If all artifacts are complete (`isComplete: true`)**:
+   - Congratulate the user
+   - Show final status including the schema used
+   - Suggest: "All artifacts created! You can now implement this change with `/opsx:apply` or archive it with `/opsx:archive`."
+   - STOP
+
+   ---
+
+   **If artifacts are ready to create** (status shows artifacts with `status: "ready"`):
+   - Pick the FIRST artifact with `status: "ready"` from the status output
+   - Get its instructions:
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+   - Parse the JSON. The key fields are:
+     - `context`: Project background (constraints for you - do NOT include in output)
+     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+     - `template`: The structure to use for your output file
+     - `instruction`: Schema-specific guidance
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - **Create the artifact file**:
+     - Read any completed dependency files for context
+     - Use `template` as the structure - fill in its sections
+     - Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file
+     - Write to the output path specified in instructions
+   - Show what was created and what's now unlocked
+   - STOP after creating ONE artifact
+
+   ---
+
+   **If no artifacts are ready (all blocked)**:
+   - This shouldn't happen with a valid schema
+   - Show status and suggest checking for issues
+
+4. **After creating an artifact, show progress**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After each invocation, show:
+- Which artifact was created
+- Schema workflow being used
+- Current progress (N/M complete)
+- What artifacts are now unlocked
+- Prompt: "Run `/opsx:continue` to create the next artifact"
+
+**Artifact Creation Guidelines**
+
+The artifact types and their purpose depend on the schema. Use the `instruction` field from the instructions output to understand what to create.
+
+Common artifact patterns:
+
+**spec-driven schema** (proposal → specs → design → tasks):
+- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
+  - The Capabilities section is critical - each capability listed will need a spec file.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
+- **design.md**: Document technical decisions, architecture, and implementation approach.
+- **tasks.md**: Break down implementation into checkboxed tasks.
+
+For other schemas, follow the `instruction` field from the CLI output.
+
+**Guardrails**
+- Create ONE artifact per invocation
+- Always read dependency artifacts before creating a new one
+- Never skip artifacts or create out of order
+- If context is unclear, ask the user before creating
+- Verify the artifact file exists after writing before marking progress
+- Use the schema's artifact sequence, don't assume specific artifact names
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output

.claude/commands/opsx/explore.md

@@ -0,0 +1,173 @@
+---
+name: "OPSX: Explore"
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+category: Workflow
+tags: [workflow, explore, experimental, thinking]
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.claude/commands/opsx/ff.md

@@ -0,0 +1,97 @@
+---
+name: "OPSX: Fast Forward"
+description: Create a change and generate all artifacts needed for implementation in one go
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Fast-forward through artifact creation - generate everything needed to start implementation.
+
+**Input**: The argument after `/opsx:ff` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "✓ Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.claude/commands/opsx/new.md

@@ -0,0 +1,69 @@
+---
+name: "OPSX: New"
+description: Start a new change using the experimental artifact workflow (OPSX)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Start a new change using the experimental artifact-driven approach.
+
+**Input**: The argument after `/opsx:new` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Determine the workflow schema**
+
+   Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
+
+   **Use a different schema only if the user mentions:**
+   - A specific schema name → use `--schema <name>`
+   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
+
+   **Otherwise**: Omit `--schema` to use the default.
+
+3. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   Add `--schema <name>` only if the user requested a specific workflow.
+   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
+
+4. **Show the artifact status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+
+5. **Get instructions for the first artifact**
+   The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
+   ```bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   ```
+   This outputs the template and context for creating the first artifact.
+
+6. **STOP and wait for user direction**
+
+**Output**
+
+After completing the steps, summarize:
+- Change name and location
+- Schema/workflow being used and its artifact sequence
+- Current status (0/N artifacts complete)
+- The template for the first artifact
+- Prompt: "Ready to create the first artifact? Run `/opsx:continue` or just describe what this change is about and I'll draft it."
+
+**Guardrails**
+- Do NOT create any artifacts yet - just show the instructions
+- Do NOT advance beyond showing the first artifact template
+- If the name is invalid (not kebab-case), ask for a valid name
+- If a change with that name already exists, suggest using `/opsx:continue` instead
+- Pass --schema if using a non-default workflow

.claude/commands/opsx/onboard.md

@@ -0,0 +1,550 @@
+---
+name: "OPSX: Onboard"
+description: Guided onboarding - walk through a complete OpenSpec workflow cycle with narration
+category: Workflow
+tags: [workflow, onboarding, tutorial, learning]
+---
+
+Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
+
+---
+
+## Preflight
+
+Before starting, check if the OpenSpec CLI is installed:
+
+```bash
+# Unix/macOS
+openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
+# Windows (PowerShell)
+# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
+```
+
+**If CLI not installed:**
+> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`.
+
+Stop here if not installed.
+
+---
+
+## Phase 1: Welcome
+
+Display:
+
+```
+## Welcome to OpenSpec!
+
+I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
+
+**What we'll do:**
+1. Pick a small, real task in your codebase
+2. Explore the problem briefly
+3. Create a change (the container for our work)
+4. Build the artifacts: proposal → specs → design → tasks
+5. Implement the tasks
+6. Archive the completed change
+
+**Time:** ~15-20 minutes
+
+Let's start by finding something to work on.
+```
+
+---
+
+## Phase 2: Task Selection
+
+### Codebase Analysis
+
+Scan the codebase for small improvement opportunities. Look for:
+
+1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files
+2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
+3. **Functions without tests** - Cross-reference `src/` with test directories
+4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
+5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
+6. **Missing validation** - User input handlers without validation
+
+Also check recent git activity:
+```bash
+# Unix/macOS
+git log --oneline -10 2>/dev/null || echo "No git history"
+# Windows (PowerShell)
+# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }
+```
+
+### Present Suggestions
+
+From your analysis, present 3-4 specific suggestions:
+
+```
+## Task Suggestions
+
+Based on scanning your codebase, here are some good starter tasks:
+
+**1. [Most promising task]**
+   Location: `src/path/to/file.ts:42`
+   Scope: ~1-2 files, ~20-30 lines
+   Why it's good: [brief reason]
+
+**2. [Second task]**
+   Location: `src/another/file.ts`
+   Scope: ~1 file, ~15 lines
+   Why it's good: [brief reason]
+
+**3. [Third task]**
+   Location: [location]
+   Scope: [estimate]
+   Why it's good: [brief reason]
+
+**4. Something else?**
+   Tell me what you'd like to work on.
+
+Which task interests you? (Pick a number or describe your own)
+```
+
+**If nothing found:** Fall back to asking what the user wants to build:
+> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
+
+### Scope Guardrail
+
+If the user picks or describes something too large (major feature, multi-day work):
+
+```
+That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
+
+For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
+
+**Options:**
+1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
+2. **Pick something else** - One of the other suggestions, or a different small task?
+3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
+
+What would you prefer?
+```
+
+Let the user override if they insist—this is a soft guardrail.
+
+---
+
+## Phase 3: Explore Demo
+
+Once a task is selected, briefly demonstrate explore mode:
+
+```
+Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
+```
+
+Spend 1-2 minutes investigating the relevant code:
+- Read the file(s) involved
+- Draw a quick ASCII diagram if it helps
+- Note any considerations
+
+```
+## Quick Exploration
+
+[Your brief analysis—what you found, any considerations]
+
+┌─────────────────────────────────────────┐
+│   [Optional: ASCII diagram if helpful]  │
+└─────────────────────────────────────────┘
+
+Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
+
+Now let's create a change to hold our work.
+```
+
+**PAUSE** - Wait for user acknowledgment before proceeding.
+
+---
+
+## Phase 4: Create the Change
+
+**EXPLAIN:**
+```
+## Creating a Change
+
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
+
+Let me create one for our task.
+```
+
+**DO:** Create the change with a derived kebab-case name:
+```bash
+openspec new change "<derived-name>"
+```
+
+**SHOW:**
+```
+Created: `openspec/changes/<name>/`
+
+The folder structure:
+```
+openspec/changes/<name>/
+├── proposal.md    ← Why we're doing this (empty, we'll fill it)
+├── design.md      ← How we'll build it (empty)
+├── specs/         ← Detailed requirements (empty)
+└── tasks.md       ← Implementation checklist (empty)
+```
+
+Now let's fill in the first artifact—the proposal.
+```
+
+---
+
+## Phase 5: Proposal
+
+**EXPLAIN:**
+```
+## The Proposal
+
+The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
+
+I'll draft one based on our task.
+```
+
+**DO:** Draft the proposal content (don't save yet):
+
+```
+Here's a draft proposal:
+
+---
+
+## Why
+
+[1-2 sentences explaining the problem/opportunity]
+
+## What Changes
+
+[Bullet points of what will be different]
+
+## Capabilities
+
+### New Capabilities
+- `<capability-name>`: [brief description]
+
+### Modified Capabilities
+<!-- If modifying existing behavior -->
+
+## Impact
+
+- `src/path/to/file.ts`: [what changes]
+- [other files if applicable]
+
+---
+
+Does this capture the intent? I can adjust before we save it.
+```
+
+**PAUSE** - Wait for user approval/feedback.
+
+After approval, save the proposal:
+```bash
+openspec instructions proposal --change "<name>" --json
+```
+Then write the content to `openspec/changes/<name>/proposal.md`.
+
+```
+Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
+
+Next up: specs.
+```
+
+---
+
+## Phase 6: Specs
+
+**EXPLAIN:**
+```
+## Specs
+
+Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
+
+For a small task like this, we might only need one spec file.
+```
+
+**DO:** Create the spec file:
+```bash
+# Unix/macOS
+mkdir -p openspec/changes/<name>/specs/<capability-name>
+# Windows (PowerShell)
+# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"
+```
+
+Draft the spec content:
+
+```
+Here's the spec:
+
+---
+
+## ADDED Requirements
+
+### Requirement: <Name>
+
+<Description of what the system should do>
+
+#### Scenario: <Scenario name>
+
+- **WHEN** <trigger condition>
+- **THEN** <expected outcome>
+- **AND** <additional outcome if needed>
+
+---
+
+This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
+```
+
+Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
+
+---
+
+## Phase 7: Design
+
+**EXPLAIN:**
+```
+## Design
+
+The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
+
+For small changes, this might be brief. That's fine—not every change needs deep design discussion.
+```
+
+**DO:** Draft design.md:
+
+```
+Here's the design:
+
+---
+
+## Context
+
+[Brief context about the current state]
+
+## Goals / Non-Goals
+
+**Goals:**
+- [What we're trying to achieve]
+
+**Non-Goals:**
+- [What's explicitly out of scope]
+
+## Decisions
+
+### Decision 1: [Key decision]
+
+[Explanation of approach and rationale]
+
+---
+
+For a small task, this captures the key decisions without over-engineering.
+```
+
+Save to `openspec/changes/<name>/design.md`.
+
+---
+
+## Phase 8: Tasks
+
+**EXPLAIN:**
+```
+## Tasks
+
+Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
+
+These should be small, clear, and in logical order.
+```
+
+**DO:** Generate tasks based on specs and design:
+
+```
+Here are the implementation tasks:
+
+---
+
+## 1. [Category or file]
+
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+## 2. Verify
+
+- [ ] 2.1 [Verification step]
+
+---
+
+Each checkbox becomes a unit of work in the apply phase. Ready to implement?
+```
+
+**PAUSE** - Wait for user to confirm they're ready to implement.
+
+Save to `openspec/changes/<name>/tasks.md`.
+
+---
+
+## Phase 9: Apply (Implementation)
+
+**EXPLAIN:**
+```
+## Implementation
+
+Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
+```
+
+**DO:** For each task:
+
+1. Announce: "Working on task N: [description]"
+2. Implement the change in the codebase
+3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
+4. Mark complete in tasks.md: `- [ ]` → `- [x]`
+5. Brief status: "✓ Task N complete"
+
+Keep narration light—don't over-explain every line of code.
+
+After all tasks:
+
+```
+## Implementation Complete
+
+All tasks done:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+The change is implemented! One more step—let's archive it.
+```
+
+---
+
+## Phase 10: Archive
+
+**EXPLAIN:**
+```
+## Archiving
+
+When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
+```
+
+**DO:**
+```bash
+openspec archive "<name>"
+```
+
+**SHOW:**
+```
+Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`
+
+The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
+```
+
+---
+
+## Phase 11: Recap & Next Steps
+
+```
+## Congratulations!
+
+You just completed a full OpenSpec cycle:
+
+1. **Explore** - Thought through the problem
+2. **New** - Created a change container
+3. **Proposal** - Captured WHY
+4. **Specs** - Defined WHAT in detail
+5. **Design** - Decided HOW
+6. **Tasks** - Broke it into steps
+7. **Apply** - Implemented the work
+8. **Archive** - Preserved the record
+
+This same rhythm works for any size change—a small fix or a major feature.
+
+---
+
+## Command Reference
+
+**Core workflow:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:propose` | Create a change and generate all artifacts |
+| `/opsx:explore` | Think through problems before/during work |
+| `/opsx:apply` | Implement tasks from a change |
+| `/opsx:archive` | Archive a completed change |
+
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new` | Start a new change, step through artifacts one at a time |
+| `/opsx:continue` | Continue working on an existing change |
+| `/opsx:ff` | Fast-forward: create all artifacts at once |
+| `/opsx:verify` | Verify implementation matches artifacts |
+
+---
+
+## What's Next?
+
+Try `/opsx:propose` on something you actually want to build. You've got the rhythm now!
+```
+
+---
+
+## Graceful Exit Handling
+
+### User wants to stop mid-way
+
+If the user says they need to stop, want to pause, or seem disengaged:
+
+```
+No problem! Your change is saved at `openspec/changes/<name>/`.
+
+To pick up where we left off later:
+- `/opsx:continue <name>` - Resume artifact creation
+- `/opsx:apply <name>` - Jump to implementation (if tasks exist)
+
+The work won't be lost. Come back whenever you're ready.
+```
+
+Exit gracefully without pressure.
+
+### User just wants command reference
+
+If the user says they just want to see the commands or skip the tutorial:
+
+```
+## OpenSpec Quick Reference
+
+**Core workflow:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:propose <name>` | Create a change and generate all artifacts |
+| `/opsx:explore` | Think through problems (no code changes) |
+| `/opsx:apply <name>` | Implement tasks |
+| `/opsx:archive <name>` | Archive when done |
+
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new <name>` | Start a new change, step by step |
+| `/opsx:continue <name>` | Continue an existing change |
+| `/opsx:ff <name>` | Fast-forward: all artifacts at once |
+| `/opsx:verify <name>` | Verify implementation |
+
+Try `/opsx:propose` to start your first change.
+```
+
+Exit gracefully.
+
+---
+
+## Guardrails
+
+- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
+- **Keep narration light** during implementation—teach without lecturing
+- **Don't skip phases** even if the change is small—the goal is teaching the workflow
+- **Pause for acknowledgment** at marked points, but don't over-pause
+- **Handle exits gracefully**—never pressure the user to continue
+- **Use real codebase tasks**—don't simulate or use fake examples
+- **Adjust scope gently**—guide toward smaller tasks but respect user choice

.claude/commands/opsx/propose.md

@@ -0,0 +1,106 @@
+---
+name: "OPSX: Propose"
+description: Propose a new change - create it and generate all artifacts in one step
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.claude/commands/opsx/sync.md

@@ -0,0 +1,134 @@
+---
+name: "OPSX: Sync"
+description: Sync delta specs from a change to main specs
+category: Workflow
+tags: [workflow, specs, experimental]
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result

.claude/commands/opsx/verify.md

@@ -0,0 +1,164 @@
+---
+name: "OPSX: Verify"
+description: Verify implementation matches change artifacts before archiving
+category: Workflow
+tags: [workflow, verify, experimental]
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv:*)",
+      "Bash(openspec:*)",
+      "WebSearch",
+      "WebFetch(*)",
+      "Bash(pip index:*)",
+      "Bash(pip show:*)",
+      "Bash(mkdir:*)",
+      "Bash(ls:*)",
+      "Bash(git:*)",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__query-docs",
+      "mcp__exa__get_code_context_exa",
+      "mcp__exa__web_search_exa"
+    ]
+  }
+}

.claude/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read the files listed in `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.claude/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.claude/skills/openspec-bulk-archive-change/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: openspec-bulk-archive-change
+description: Archive multiple completed changes at once. Use when archiving several parallel changes.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Archive multiple completed changes in a single operation.
+
+This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
+
+**Input**: None required (prompts for selection)
+
+**Steps**
+
+1. **Get active changes**
+
+   Run `openspec list --json` to get all active changes.
+
+   If no active changes exist, inform user and stop.
+
+2. **Prompt for change selection**
+
+   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   - Show each change with its schema
+   - Include an option for "All changes"
+   - Allow any number of selections (1+ works, 2+ is the typical use case)
+
+   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
+
+3. **Batch validation - gather status for all selected changes**
+
+   For each selected change, collect:
+
+   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+      - Parse `schemaName` and `artifacts` list
+      - Note which artifacts are `done` vs other states
+
+   b. **Task completion** - Read `openspec/changes/<name>/tasks.md`
+      - Count `- [ ]` (incomplete) vs `- [x]` (complete)
+      - If no tasks file exists, note as "No tasks"
+
+   c. **Delta specs** - Check `openspec/changes/<name>/specs/` directory
+      - List which capability specs exist
+      - For each, extract requirement names (lines matching `### Requirement: <name>`)
+
+4. **Detect spec conflicts**
+
+   Build a map of `capability -> [changes that touch it]`:
+
+   ```
+   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
+   api  -> [change-c]            <- OK (only 1 change)
+   ```
+
+   A conflict exists when 2+ selected changes have delta specs for the same capability.
+
+5. **Resolve conflicts agentically**
+
+   **For each conflict**, investigate the codebase:
+
+   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
+
+   b. **Search the codebase** for implementation evidence:
+      - Look for code implementing requirements from each delta spec
+      - Check for related files, functions, or tests
+
+   c. **Determine resolution**:
+      - If only one change is actually implemented -> sync that one's specs
+      - If both implemented -> apply in chronological order (older first, newer overwrites)
+      - If neither implemented -> skip spec sync, warn user
+
+   d. **Record resolution** for each conflict:
+      - Which change's specs to apply
+      - In what order (if both)
+      - Rationale (what was found in codebase)
+
+6. **Show consolidated status table**
+
+   Display a table summarizing all changes:
+
+   ```
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   |---------------------|-----------|-------|---------|-----------|--------|
+   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
+   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
+   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
+   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
+   ```
+
+   For conflicts, show the resolution:
+   ```
+   * Conflict resolution:
+     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
+   ```
+
+   For incomplete changes, show warnings:
+   ```
+   Warnings:
+   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
+   ```
+
+7. **Confirm batch operation**
+
+   Use **AskUserQuestion tool** with a single confirmation:
+
+   - "Archive N changes?" with options based on status
+   - Options might include:
+     - "Archive all N changes"
+     - "Archive only N ready changes (skip incomplete)"
+     - "Cancel"
+
+   If there are incomplete changes, make clear they'll be archived with warnings.
+
+8. **Execute archive for each confirmed change**
+
+   Process changes in the determined order (respecting conflict resolution):
+
+   a. **Sync specs** if delta specs exist:
+      - Use the openspec-sync-specs approach (agent-driven intelligent merge)
+      - For conflicts, apply in resolved order
+      - Track if sync was done
+
+   b. **Perform the archive**:
+      ```bash
+      mkdir -p openspec/changes/archive
+      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      ```
+
+   c. **Track outcome** for each change:
+      - Success: archived successfully
+      - Failed: error during archive (record error)
+      - Skipped: user chose not to archive (if applicable)
+
+9. **Display summary**
+
+   Show final results:
+
+   ```
+   ## Bulk Archive Complete
+
+   Archived 3 changes:
+   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
+   - project-config -> archive/2026-01-19-project-config/
+   - add-oauth -> archive/2026-01-19-add-oauth/
+
+   Skipped 1 change:
+   - add-verify-skill (user chose not to archive incomplete)
+
+   Spec sync summary:
+   - 4 delta specs synced to main specs
+   - 1 conflict resolved (auth: applied both in chronological order)
+   ```
+
+   If any failures:
+   ```
+   Failed 1 change:
+   - some-change: Archive directory already exists
+   ```
+
+**Conflict Resolution Examples**
+
+Example 1: Only one implemented
+```
+Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
+
+Checking add-oauth:
+- Delta adds "OAuth Provider Integration" requirement
+- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
+
+Checking add-jwt:
+- Delta adds "JWT Token Handling" requirement
+- Searching codebase... no JWT implementation found
+
+Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
+```
+
+Example 2: Both implemented
+```
+Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
+
+Checking add-rest-api (created 2026-01-10):
+- Delta adds "REST Endpoints" requirement
+- Searching codebase... found src/api/rest.ts
+
+Checking add-graphql (created 2026-01-15):
+- Delta adds "GraphQL Schema" requirement
+- Searching codebase... found src/api/graphql.ts
+
+Resolution: Both implemented. Will apply add-rest-api specs first,
+then add-graphql specs (chronological order, newer takes precedence).
+```
+
+**Output On Success**
+
+```
+## Bulk Archive Complete
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+- <change-2> -> archive/YYYY-MM-DD-<change-2>/
+
+Spec sync summary:
+- N delta specs synced to main specs
+- No conflicts (or: M conflicts resolved)
+```
+
+**Output On Partial Success**
+
+```
+## Bulk Archive Complete (partial)
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+
+Skipped M changes:
+- <change-2> (user chose not to archive incomplete)
+
+Failed K changes:
+- <change-3>: Archive directory already exists
+```
+
+**Output When No Changes**
+
+```
+## No Changes to Archive
+
+No active changes found. Create a new change to get started.
+```
+
+**Guardrails**
+- Allow any number of changes (1+ is fine, 2+ is the typical use case)
+- Always prompt for selection, never auto-select
+- Detect spec conflicts early and resolve by checking codebase
+- When both changes are implemented, apply specs in chronological order
+- Skip spec sync only when implementation is missing (warn user)
+- Show clear per-change status before confirming
+- Use single confirmation for entire batch
+- Track and report all outcomes (success/skip/fail)
+- Preserve .openspec.yaml when moving to archive
+- Archive directory target uses current date: YYYY-MM-DD-<name>
+- If archive target exists, fail that change but continue with others

.claude/skills/openspec-continue-change/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: openspec-continue-change
+description: Continue working on an OpenSpec change by creating the next artifact. Use when the user wants to progress their change, create the next artifact, or continue their workflow.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Continue working on a change by creating the next artifact.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+
+   Present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from `schema` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from `lastModified` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check current status**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand current state. The response includes:
+   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
+   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
+   - `isComplete`: Boolean indicating if all artifacts are complete
+
+3. **Act based on status**:
+
+   ---
+
+   **If all artifacts are complete (`isComplete: true`)**:
+   - Congratulate the user
+   - Show final status including the schema used
+   - Suggest: "All artifacts created! You can now implement this change or archive it."
+   - STOP
+
+   ---
+
+   **If artifacts are ready to create** (status shows artifacts with `status: "ready"`):
+   - Pick the FIRST artifact with `status: "ready"` from the status output
+   - Get its instructions:
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+   - Parse the JSON. The key fields are:
+     - `context`: Project background (constraints for you - do NOT include in output)
+     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+     - `template`: The structure to use for your output file
+     - `instruction`: Schema-specific guidance
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - **Create the artifact file**:
+     - Read any completed dependency files for context
+     - Use `template` as the structure - fill in its sections
+     - Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file
+     - Write to the output path specified in instructions
+   - Show what was created and what's now unlocked
+   - STOP after creating ONE artifact
+
+   ---
+
+   **If no artifacts are ready (all blocked)**:
+   - This shouldn't happen with a valid schema
+   - Show status and suggest checking for issues
+
+4. **After creating an artifact, show progress**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After each invocation, show:
+- Which artifact was created
+- Schema workflow being used
+- Current progress (N/M complete)
+- What artifacts are now unlocked
+- Prompt: "Want to continue? Just ask me to continue or tell me what to do next."
+
+**Artifact Creation Guidelines**
+
+The artifact types and their purpose depend on the schema. Use the `instruction` field from the instructions output to understand what to create.
+
+Common artifact patterns:
+
+**spec-driven schema** (proposal → specs → design → tasks):
+- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
+  - The Capabilities section is critical - each capability listed will need a spec file.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
+- **design.md**: Document technical decisions, architecture, and implementation approach.
+- **tasks.md**: Break down implementation into checkboxed tasks.
+
+For other schemas, follow the `instruction` field from the CLI output.
+
+**Guardrails**
+- Create ONE artifact per invocation
+- Always read dependency artifacts before creating a new one
+- Never skip artifacts or create out of order
+- If context is unclear, ask the user before creating
+- Verify the artifact file exists after writing before marking progress
+- Use the schema's artifact sequence, don't assume specific artifact names
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output

.claude/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │         CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.claude/skills/openspec-ff-change/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: openspec-ff-change
+description: Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Fast-forward through artifact creation - generate everything needed to start implementation in one go.
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "✓ Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, suggest continuing that change instead
+- Verify each artifact file exists after writing before proceeding to next

.claude/skills/openspec-new-change/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: openspec-new-change
+description: Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Start a new change using the experimental artifact-driven approach.
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Determine the workflow schema**
+
+   Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
+
+   **Use a different schema only if the user mentions:**
+   - A specific schema name → use `--schema <name>`
+   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
+
+   **Otherwise**: Omit `--schema` to use the default.
+
+3. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   Add `--schema <name>` only if the user requested a specific workflow.
+   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
+
+4. **Show the artifact status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+
+5. **Get instructions for the first artifact**
+   The first artifact depends on the schema (e.g., `proposal` for spec-driven).
+   Check the status output to find the first artifact with status "ready".
+   ```bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   ```
+   This outputs the template and context for creating the first artifact.
+
+6. **STOP and wait for user direction**
+
+**Output**
+
+After completing the steps, summarize:
+- Change name and location
+- Schema/workflow being used and its artifact sequence
+- Current status (0/N artifacts complete)
+- The template for the first artifact
+- Prompt: "Ready to create the first artifact? Just describe what this change is about and I'll draft it, or ask me to continue."
+
+**Guardrails**
+- Do NOT create any artifacts yet - just show the instructions
+- Do NOT advance beyond showing the first artifact template
+- If the name is invalid (not kebab-case), ask for a valid name
+- If a change with that name already exists, suggest continuing that change instead
+- Pass --schema if using a non-default workflow

.claude/skills/openspec-onboard/SKILL.md

@@ -0,0 +1,554 @@
+---
+name: openspec-onboard
+description: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
+
+---
+
+## Preflight
+
+Before starting, check if the OpenSpec CLI is installed:
+
+```bash
+# Unix/macOS
+openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
+# Windows (PowerShell)
+# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
+```
+
+**If CLI not installed:**
+> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`.
+
+Stop here if not installed.
+
+---
+
+## Phase 1: Welcome
+
+Display:
+
+```
+## Welcome to OpenSpec!
+
+I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
+
+**What we'll do:**
+1. Pick a small, real task in your codebase
+2. Explore the problem briefly
+3. Create a change (the container for our work)
+4. Build the artifacts: proposal → specs → design → tasks
+5. Implement the tasks
+6. Archive the completed change
+
+**Time:** ~15-20 minutes
+
+Let's start by finding something to work on.
+```
+
+---
+
+## Phase 2: Task Selection
+
+### Codebase Analysis
+
+Scan the codebase for small improvement opportunities. Look for:
+
+1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files
+2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
+3. **Functions without tests** - Cross-reference `src/` with test directories
+4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
+5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
+6. **Missing validation** - User input handlers without validation
+
+Also check recent git activity:
+```bash
+# Unix/macOS
+git log --oneline -10 2>/dev/null || echo "No git history"
+# Windows (PowerShell)
+# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }
+```
+
+### Present Suggestions
+
+From your analysis, present 3-4 specific suggestions:
+
+```
+## Task Suggestions
+
+Based on scanning your codebase, here are some good starter tasks:
+
+**1. [Most promising task]**
+   Location: `src/path/to/file.ts:42`
+   Scope: ~1-2 files, ~20-30 lines
+   Why it's good: [brief reason]
+
+**2. [Second task]**
+   Location: `src/another/file.ts`
+   Scope: ~1 file, ~15 lines
+   Why it's good: [brief reason]
+
+**3. [Third task]**
+   Location: [location]
+   Scope: [estimate]
+   Why it's good: [brief reason]
+
+**4. Something else?**
+   Tell me what you'd like to work on.
+
+Which task interests you? (Pick a number or describe your own)
+```
+
+**If nothing found:** Fall back to asking what the user wants to build:
+> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
+
+### Scope Guardrail
+
+If the user picks or describes something too large (major feature, multi-day work):
+
+```
+That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
+
+For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
+
+**Options:**
+1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
+2. **Pick something else** - One of the other suggestions, or a different small task?
+3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
+
+What would you prefer?
+```
+
+Let the user override if they insist—this is a soft guardrail.
+
+---
+
+## Phase 3: Explore Demo
+
+Once a task is selected, briefly demonstrate explore mode:
+
+```
+Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
+```
+
+Spend 1-2 minutes investigating the relevant code:
+- Read the file(s) involved
+- Draw a quick ASCII diagram if it helps
+- Note any considerations
+
+```
+## Quick Exploration
+
+[Your brief analysis—what you found, any considerations]
+
+┌─────────────────────────────────────────┐
+│   [Optional: ASCII diagram if helpful]  │
+└─────────────────────────────────────────┘
+
+Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
+
+Now let's create a change to hold our work.
+```
+
+**PAUSE** - Wait for user acknowledgment before proceeding.
+
+---
+
+## Phase 4: Create the Change
+
+**EXPLAIN:**
+```
+## Creating a Change
+
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
+
+Let me create one for our task.
+```
+
+**DO:** Create the change with a derived kebab-case name:
+```bash
+openspec new change "<derived-name>"
+```
+
+**SHOW:**
+```
+Created: `openspec/changes/<name>/`
+
+The folder structure:
+```
+openspec/changes/<name>/
+├── proposal.md    ← Why we're doing this (empty, we'll fill it)
+├── design.md      ← How we'll build it (empty)
+├── specs/         ← Detailed requirements (empty)
+└── tasks.md       ← Implementation checklist (empty)
+```
+
+Now let's fill in the first artifact—the proposal.
+```
+
+---
+
+## Phase 5: Proposal
+
+**EXPLAIN:**
+```
+## The Proposal
+
+The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
+
+I'll draft one based on our task.
+```
+
+**DO:** Draft the proposal content (don't save yet):
+
+```
+Here's a draft proposal:
+
+---
+
+## Why
+
+[1-2 sentences explaining the problem/opportunity]
+
+## What Changes
+
+[Bullet points of what will be different]
+
+## Capabilities
+
+### New Capabilities
+- `<capability-name>`: [brief description]
+
+### Modified Capabilities
+<!-- If modifying existing behavior -->
+
+## Impact
+
+- `src/path/to/file.ts`: [what changes]
+- [other files if applicable]
+
+---
+
+Does this capture the intent? I can adjust before we save it.
+```
+
+**PAUSE** - Wait for user approval/feedback.
+
+After approval, save the proposal:
+```bash
+openspec instructions proposal --change "<name>" --json
+```
+Then write the content to `openspec/changes/<name>/proposal.md`.
+
+```
+Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
+
+Next up: specs.
+```
+
+---
+
+## Phase 6: Specs
+
+**EXPLAIN:**
+```
+## Specs
+
+Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
+
+For a small task like this, we might only need one spec file.
+```
+
+**DO:** Create the spec file:
+```bash
+# Unix/macOS
+mkdir -p openspec/changes/<name>/specs/<capability-name>
+# Windows (PowerShell)
+# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"
+```
+
+Draft the spec content:
+
+```
+Here's the spec:
+
+---
+
+## ADDED Requirements
+
+### Requirement: <Name>
+
+<Description of what the system should do>
+
+#### Scenario: <Scenario name>
+
+- **WHEN** <trigger condition>
+- **THEN** <expected outcome>
+- **AND** <additional outcome if needed>
+
+---
+
+This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
+```
+
+Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
+
+---
+
+## Phase 7: Design
+
+**EXPLAIN:**
+```
+## Design
+
+The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
+
+For small changes, this might be brief. That's fine—not every change needs deep design discussion.
+```
+
+**DO:** Draft design.md:
+
+```
+Here's the design:
+
+---
+
+## Context
+
+[Brief context about the current state]
+
+## Goals / Non-Goals
+
+**Goals:**
+- [What we're trying to achieve]
+
+**Non-Goals:**
+- [What's explicitly out of scope]
+
+## Decisions
+
+### Decision 1: [Key decision]
+
+[Explanation of approach and rationale]
+
+---
+
+For a small task, this captures the key decisions without over-engineering.
+```
+
+Save to `openspec/changes/<name>/design.md`.
+
+---
+
+## Phase 8: Tasks
+
+**EXPLAIN:**
+```
+## Tasks
+
+Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
+
+These should be small, clear, and in logical order.
+```
+
+**DO:** Generate tasks based on specs and design:
+
+```
+Here are the implementation tasks:
+
+---
+
+## 1. [Category or file]
+
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+## 2. Verify
+
+- [ ] 2.1 [Verification step]
+
+---
+
+Each checkbox becomes a unit of work in the apply phase. Ready to implement?
+```
+
+**PAUSE** - Wait for user to confirm they're ready to implement.
+
+Save to `openspec/changes/<name>/tasks.md`.
+
+---
+
+## Phase 9: Apply (Implementation)
+
+**EXPLAIN:**
+```
+## Implementation
+
+Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
+```
+
+**DO:** For each task:
+
+1. Announce: "Working on task N: [description]"
+2. Implement the change in the codebase
+3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
+4. Mark complete in tasks.md: `- [ ]` → `- [x]`
+5. Brief status: "✓ Task N complete"
+
+Keep narration light—don't over-explain every line of code.
+
+After all tasks:
+
+```
+## Implementation Complete
+
+All tasks done:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+The change is implemented! One more step—let's archive it.
+```
+
+---
+
+## Phase 10: Archive
+
+**EXPLAIN:**
+```
+## Archiving
+
+When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
+```
+
+**DO:**
+```bash
+openspec archive "<name>"
+```
+
+**SHOW:**
+```
+Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`
+
+The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
+```
+
+---
+
+## Phase 11: Recap & Next Steps
+
+```
+## Congratulations!
+
+You just completed a full OpenSpec cycle:
+
+1. **Explore** - Thought through the problem
+2. **New** - Created a change container
+3. **Proposal** - Captured WHY
+4. **Specs** - Defined WHAT in detail
+5. **Design** - Decided HOW
+6. **Tasks** - Broke it into steps
+7. **Apply** - Implemented the work
+8. **Archive** - Preserved the record
+
+This same rhythm works for any size change—a small fix or a major feature.
+
+---
+
+## Command Reference
+
+**Core workflow:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:propose` | Create a change and generate all artifacts |
+| `/opsx:explore` | Think through problems before/during work |
+| `/opsx:apply` | Implement tasks from a change |
+| `/opsx:archive` | Archive a completed change |
+
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new` | Start a new change, step through artifacts one at a time |
+| `/opsx:continue` | Continue working on an existing change |
+| `/opsx:ff` | Fast-forward: create all artifacts at once |
+| `/opsx:verify` | Verify implementation matches artifacts |
+
+---
+
+## What's Next?
+
+Try `/opsx:propose` on something you actually want to build. You've got the rhythm now!
+```
+
+---
+
+## Graceful Exit Handling
+
+### User wants to stop mid-way
+
+If the user says they need to stop, want to pause, or seem disengaged:
+
+```
+No problem! Your change is saved at `openspec/changes/<name>/`.
+
+To pick up where we left off later:
+- `/opsx:continue <name>` - Resume artifact creation
+- `/opsx:apply <name>` - Jump to implementation (if tasks exist)
+
+The work won't be lost. Come back whenever you're ready.
+```
+
+Exit gracefully without pressure.
+
+### User just wants command reference
+
+If the user says they just want to see the commands or skip the tutorial:
+
+```
+## OpenSpec Quick Reference
+
+**Core workflow:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:propose <name>` | Create a change and generate all artifacts |
+| `/opsx:explore` | Think through problems (no code changes) |
+| `/opsx:apply <name>` | Implement tasks |
+| `/opsx:archive <name>` | Archive when done |
+
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new <name>` | Start a new change, step by step |
+| `/opsx:continue <name>` | Continue an existing change |
+| `/opsx:ff <name>` | Fast-forward: all artifacts at once |
+| `/opsx:verify <name>` | Verify implementation |
+
+Try `/opsx:propose` to start your first change.
+```
+
+Exit gracefully.
+
+---
+
+## Guardrails
+
+- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
+- **Keep narration light** during implementation—teach without lecturing
+- **Don't skip phases** even if the change is small—the goal is teaching the workflow
+- **Pause for acknowledgment** at marked points, but don't over-pause
+- **Handle exits gracefully**—never pressure the user to continue
+- **Use real codebase tasks**—don't simulate or use fake examples
+- **Adjust scope gently**—guide toward smaller tasks but respect user choice

.claude/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.claude/skills/openspec-sync-specs/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: openspec-sync-specs
+description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result

.claude/skills/openspec-verify-change/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: openspec-verify-change
+description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

.gitignore

@@ -41,3 +41,5 @@ $RECYCLE.BIN/
 *.swo
 
 skills/**/test
+__pycache__
+temp

.opencode/command/opsx-archive.md

@@ -56,7 +56,7 @@ Archive a completed change in the experimental workflow.
    - If changes needed: "Sync now (recommended)", "Archive without syncing"
    - If already synced: "Archive now", "Sync anyway", "Cancel"
 
-   If user chooses sync, execute `/opsx-sync` logic. Proceed to archive regardless of choice.
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
 
 5. **Perform the archive**
 
@@ -150,5 +150,5 @@ Target archive directory already exists.
 - Don't block archive on warnings - just inform and confirm
 - Preserve .openspec.yaml when moving to archive (it moves with the directory)
 - Show clear summary of what happened
-- If sync is requested, use /opsx-sync approach (agent-driven)
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
 - If delta specs exist, always run the sync assessment and show the combined summary before prompting

.opencode/command/opsx-bulk-archive.md

@@ -222,7 +222,7 @@ Failed K changes:
 ```
 ## No Changes to Archive
 
-No active changes found. Use `/opsx-new` to create a new change.
+No active changes found. Create a new change to get started.
 ```
 
 **Guardrails**

.opencode/command/opsx-explore.md

@@ -4,7 +4,7 @@ description: Enter explore mode - think through ideas, investigate problems, cla
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx-new` or `/opsx-ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -97,8 +97,7 @@ If the user mentioned a specific change name, read its artifacts for context.
 
 Think freely. When insights crystallize, you might offer:
 
-- "This feels solid enough to start a change. Want me to create one?"
-  → Can transition to `/opsx-new` or `/opsx-ff`
+- "This feels solid enough to start a change. Want me to create a proposal?"
 - Or keep exploring - no pressure to formalize
 
 ### When a change exists
@@ -150,7 +149,7 @@ If the user mentions a change or you detect one is relevant:
 
 There's no required ending. Discovery might:
 
-- **Flow into action**: "Ready to start? `/opsx-new` or `/opsx-ff`"
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
 - **Result in artifact updates**: "Updated design.md with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"

.opencode/command/opsx-ff.md

@@ -81,7 +81,10 @@ After completing all artifacts, summarize:
 - Follow the `instruction` field from `openspec instructions` for each artifact type
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
-- Use the `template` as a starting point, filling in based on context
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
 
 **Guardrails**
 - Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)

.opencode/command/opsx-onboard.md

@@ -8,16 +8,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t
 
 ## Preflight
 
-Before starting, check if OpenSpec is initialized:
+Before starting, check if the OpenSpec CLI is installed:
 
 ```bash
-openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+# Unix/macOS
+openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
+# Windows (PowerShell)
+# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
 ```
 
-**If not initialized:**
-> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx-onboard`.
+**If CLI not installed:**
+> OpenSpec CLI is not installed. Install it first, then come back to `/opsx-onboard`.
 
-Stop here if not initialized.
+Stop here if not installed.
 
 ---
 
@@ -60,7 +63,10 @@ Scan the codebase for small improvement opportunities. Look for:
 
 Also check recent git activity:
 ```bash
+# Unix/macOS
 git log --oneline -10 2>/dev/null || echo "No git history"
+# Windows (PowerShell)
+# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }
 ```
 
 ### Present Suggestions
@@ -255,7 +261,10 @@ For a small task like this, we might only need one spec file.
 
 **DO:** Create the spec file:
 ```bash
+# Unix/macOS
 mkdir -p openspec/changes/<name>/specs/<capability-name>
+# Windows (PowerShell)
+# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"
 ```
 
 Draft the spec content:
@@ -450,21 +459,29 @@ This same rhythm works for any size change—a small fix or a major feature.
 
 ## Command Reference
 
+**Core workflow:**
+
 | Command | What it does |
 |---------|--------------|
+| `/opsx-propose` | Create a change and generate all artifacts |
 | `/opsx-explore` | Think through problems before/during work |
-| `/opsx-new` | Start a new change, step through artifacts |
-| `/opsx-ff` | Fast-forward: create all artifacts at once |
-| `/opsx-continue` | Continue working on an existing change |
 | `/opsx-apply` | Implement tasks from a change |
-| `/opsx-verify` | Verify implementation matches artifacts |
 | `/opsx-archive` | Archive a completed change |
 
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx-new` | Start a new change, step through artifacts one at a time |
+| `/opsx-continue` | Continue working on an existing change |
+| `/opsx-ff` | Fast-forward: create all artifacts at once |
+| `/opsx-verify` | Verify implementation matches artifacts |
+
 ---
 
 ## What's Next?
 
-Try `/opsx-new` or `/opsx-ff` on something you actually want to build. You've got the rhythm now!
+Try `/opsx-propose` on something you actually want to build. You've got the rhythm now!
 ```
 
 ---
@@ -494,17 +511,25 @@ If the user says they just want to see the commands or skip the tutorial:
 ```
 ## OpenSpec Quick Reference
 
+**Core workflow:**
+
 | Command | What it does |
 |---------|--------------|
+| `/opsx-propose <name>` | Create a change and generate all artifacts |
 | `/opsx-explore` | Think through problems (no code changes) |
-| `/opsx-new <name>` | Start a new change, step by step |
-| `/opsx-ff <name>` | Fast-forward: all artifacts at once |
-| `/opsx-continue <name>` | Continue an existing change |
 | `/opsx-apply <name>` | Implement tasks |
-| `/opsx-verify <name>` | Verify implementation |
 | `/opsx-archive <name>` | Archive when done |
 
-Try `/opsx-new` to start your first change, or `/opsx-ff` if you want to move fast.
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx-new <name>` | Start a new change, step by step |
+| `/opsx-continue <name>` | Continue an existing change |
+| `/opsx-ff <name>` | Fast-forward: all artifacts at once |
+| `/opsx-verify <name>` | Verify implementation |
+
+Try `/opsx-propose` to start your first change.
 ```
 
 Exit gracefully.

.opencode/command/opsx-propose.md

@@ -0,0 +1,103 @@
+---
+description: Propose a new change - create it and generate all artifacts in one step
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx-apply
+
+---
+
+**Input**: The argument after `/opsx-propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.opencode/skills/lyxy-reader-office

@@ -0,0 +1 @@
+../../skills/lyxy-reader-office

.opencode/skills/lyxy-runner-js

@@ -0,0 +1 @@
+../../skills/lyxy-runner-js

.opencode/skills/lyxy-runner-python

@@ -0,0 +1 @@
+../../skills/lyxy-runner-python

.opencode/skills/openspec-apply-change/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Implement tasks from an OpenSpec change.

.opencode/skills/openspec-archive-change/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Archive a completed change in the experimental workflow.
@@ -63,7 +63,7 @@ Archive a completed change in the experimental workflow.
    - If changes needed: "Sync now (recommended)", "Archive without syncing"
    - If already synced: "Archive now", "Sync anyway", "Cancel"
 
-   If user chooses sync, execute /opsx-sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice.
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
 
 5. **Perform the archive**
 

.opencode/skills/openspec-bulk-archive-change/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Archive multiple completed changes in a single operation.
@@ -229,7 +229,7 @@ Failed K changes:
 ```
 ## No Changes to Archive
 
-No active changes found. Use `/opsx-new` to create a new change.
+No active changes found. Create a new change to get started.
 ```
 
 **Guardrails**

.opencode/skills/openspec-continue-change/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Continue working on a change by creating the next artifact.

.opencode/skills/openspec-explore/SKILL.md

@@ -6,12 +6,12 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx-new` or `/opsx-ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -95,8 +95,7 @@ This tells you:
 
 Think freely. When insights crystallize, you might offer:
 
-- "This feels solid enough to start a change. Want me to create one?"
-  → Can transition to `/opsx-new` or `/opsx-ff`
+- "This feels solid enough to start a change. Want me to create a proposal?"
 - Or keep exploring - no pressure to formalize
 
 ### When a change exists
@@ -252,7 +251,7 @@ You: That changes everything.
 
 There's no required ending. Discovery might:
 
-- **Flow into action**: "Ready to start? /opsx-new or /opsx-ff"
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
 - **Result in artifact updates**: "Updated design.md with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
@@ -269,8 +268,7 @@ When it feels like things are crystallizing, you might summarize:
 **Open questions**: [if any remain]
 
 **Next steps** (if ready):
-- Create a change: /opsx-new <name>
-- Fast-forward to tasks: /opsx-ff <name>
+- Create a change proposal
 - Keep exploring: just keep talking
 ```
 

.opencode/skills/openspec-ff-change/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Fast-forward through artifact creation - generate everything needed to start implementation in one go.

.opencode/skills/openspec-new-change/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Start a new change using the experimental artifact-driven approach.

.opencode/skills/openspec-onboard/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
@@ -15,16 +15,19 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t
 
 ## Preflight
 
-Before starting, check if OpenSpec is initialized:
+Before starting, check if the OpenSpec CLI is installed:
 
 ```bash
-openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+# Unix/macOS
+openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
+# Windows (PowerShell)
+# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
 ```
 
-**If not initialized:**
-> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx-onboard`.
+**If CLI not installed:**
+> OpenSpec CLI is not installed. Install it first, then come back to `/opsx-onboard`.
 
-Stop here if not initialized.
+Stop here if not installed.
 
 ---
 
@@ -67,7 +70,10 @@ Scan the codebase for small improvement opportunities. Look for:
 
 Also check recent git activity:
 ```bash
+# Unix/macOS
 git log --oneline -10 2>/dev/null || echo "No git history"
+# Windows (PowerShell)
+# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }
 ```
 
 ### Present Suggestions
@@ -262,7 +268,10 @@ For a small task like this, we might only need one spec file.
 
 **DO:** Create the spec file:
 ```bash
+# Unix/macOS
 mkdir -p openspec/changes/<name>/specs/<capability-name>
+# Windows (PowerShell)
+# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"
 ```
 
 Draft the spec content:
@@ -457,21 +466,29 @@ This same rhythm works for any size change—a small fix or a major feature.
 
 ## Command Reference
 
+**Core workflow:**
+
 | Command | What it does |
 |---------|--------------|
+| `/opsx-propose` | Create a change and generate all artifacts |
 | `/opsx-explore` | Think through problems before/during work |
-| `/opsx-new` | Start a new change, step through artifacts |
-| `/opsx-ff` | Fast-forward: create all artifacts at once |
-| `/opsx-continue` | Continue working on an existing change |
 | `/opsx-apply` | Implement tasks from a change |
-| `/opsx-verify` | Verify implementation matches artifacts |
 | `/opsx-archive` | Archive a completed change |
 
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx-new` | Start a new change, step through artifacts one at a time |
+| `/opsx-continue` | Continue working on an existing change |
+| `/opsx-ff` | Fast-forward: create all artifacts at once |
+| `/opsx-verify` | Verify implementation matches artifacts |
+
 ---
 
 ## What's Next?
 
-Try `/opsx-new` or `/opsx-ff` on something you actually want to build. You've got the rhythm now!
+Try `/opsx-propose` on something you actually want to build. You've got the rhythm now!
 ```
 
 ---
@@ -501,17 +518,25 @@ If the user says they just want to see the commands or skip the tutorial:
 ```
 ## OpenSpec Quick Reference
 
+**Core workflow:**
+
 | Command | What it does |
 |---------|--------------|
+| `/opsx-propose <name>` | Create a change and generate all artifacts |
 | `/opsx-explore` | Think through problems (no code changes) |
-| `/opsx-new <name>` | Start a new change, step by step |
-| `/opsx-ff <name>` | Fast-forward: all artifacts at once |
-| `/opsx-continue <name>` | Continue an existing change |
 | `/opsx-apply <name>` | Implement tasks |
-| `/opsx-verify <name>` | Verify implementation |
 | `/opsx-archive <name>` | Archive when done |
 
-Try `/opsx-new` to start your first change, or `/opsx-ff` if you want to move fast.
+**Additional commands:**
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx-new <name>` | Start a new change, step by step |
+| `/opsx-continue <name>` | Continue an existing change |
+| `/opsx-ff <name>` | Fast-forward: all artifacts at once |
+| `/opsx-verify <name>` | Verify implementation |
+
+Try `/opsx-propose` to start your first change.
 ```
 
 Exit gracefully.

.opencode/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx-apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.opencode/skills/openspec-sync-specs/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Sync delta specs from a change to main specs.

.opencode/skills/openspec-verify-change/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.1.1"
+  generatedBy: "1.2.0"
 ---
 
 Verify that an implementation matches the change artifacts (specs, tasks, design).

document/specification.md

@@ -0,0 +1,238 @@
+# 规范说明
+
+> Agent Skills 的完整格式规范。
+
+本文档定义了 Agent Skills 格式规范。
+
+## 目录结构
+
+一个技能是一个目录，至少包含一个 `SKILL.md` 文件：
+
+```
+skill-name/
+└── SKILL.md          # 必需
+```
+
+<Tip>
+  你可以选择性地包含[额外的目录](#可选目录)，如 `scripts/`、`references/` 和 `assets/` 来支持你的技能。
+</Tip>
+
+## SKILL.md 格式
+
+`SKILL.md` 文件必须包含 YAML 前置数据（frontmatter），后跟 Markdown 内容。
+
+### 前置数据（必需）
+
+```yaml
+---
+name: skill-name
+description: A description of what this skill does and when to use it.
+---
+```
+
+包含可选字段：
+
+```yaml
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+license: Apache-2.0
+metadata:
+  author: example-org
+  version: '1.0'
+---
+```
+
+| 字段            | 是否必需 | 约束条件                                                             |
+| --------------- | -------- | -------------------------------------------------------------------- |
+| `name`          | 是       | 最多 64 个字符。仅限小写字母、数字和连字符。不能以连字符开头或结尾。 |
+| `description`   | 是       | 最多 1024 个字符。非空。描述该技能的作用以及何时使用它。             |
+| `license`       | 否       | 许可证名称或对打包许可证文件的引用。                                 |
+| `compatibility` | 否       | 最多 500 个字符。指示环境要求（目标产品、系统包、网络访问等）。      |
+| `metadata`      | 否       | 用于附加元数据的任意键值映射。                                       |
+| `allowed-tools` | 否       | 技能可能使用的预先批准工具的空格分隔列表。（实验性）                 |
+
+#### `name` 字段
+
+必需的 `name` 字段：
+
+- 必须为 1-64 个字符
+- 仅可包含 unicode 小写字母数字字符和连字符（`a-z` 和 `-`）
+- 不能以 `-` 开头或结尾
+- 不能包含连续的连字符（`--`）
+- 必须与父目录名称匹配
+
+有效示例：
+
+```yaml
+name: pdf-processing
+```
+
+```yaml
+name: data-analysis
+```
+
+```yaml
+name: code-review
+```
+
+无效示例：
+
+```yaml
+name: PDF-Processing # 不允许大写字母
+```
+
+```yaml
+name: -pdf # 不能以连字符开头
+```
+
+```yaml
+name: pdf--processing # 不允许连续的连字符
+```
+
+#### `description` 字段
+
+必需的 `description` 字段：
+
+- 必须为 1-1024 个字符
+- 应该描述该技能的作用以及何时使用它
+- 应该包含有助于代理识别相关任务的特定关键字
+
+好的示例：
+
+```yaml
+description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
+```
+
+差的示例：
+
+```yaml
+description: Helps with PDFs.
+```
+
+#### `license` 字段
+
+可选的 `license` 字段：
+
+- 指定应用于该技能的许可证
+- 我们建议保持简短（要么是许可证名称，要么是打包许可证文件的名称）
+
+示例：
+
+```yaml
+license: Proprietary. LICENSE.txt has complete terms
+```
+
+#### `compatibility` 字段
+
+可选的 `compatibility` 字段：
+
+- 如果提供，必须为 1-500 个字符
+- 仅在你的技能具有特定环境要求时才应包含
+- 可以指示目标产品、所需的系统包、网络访问需求等
+
+示例：
+
+```yaml
+compatibility: Designed for Claude Code (or similar products)
+```
+
+```yaml
+compatibility: Requires git, docker, jq, and access to the internet
+```
+
+<Note>
+  大多数技能不需要 `compatibility` 字段。
+</Note>
+
+#### `metadata` 字段
+
+可选的 `metadata` 字段：
+
+- 从字符串键到字符串值的映射
+- 客户端可以使用它来存储未由 Agent Skills 规范定义的附加属性
+- 我们建议使你的键名足够唯一以避免意外冲突
+
+示例：
+
+```yaml
+metadata:
+  author: example-org
+  version: '1.0'
+```
+
+#### `allowed-tools` 字段
+
+可选的 `allowed-tools` 字段：
+
+- 预先批准运行的工具的空格分隔列表
+- 实验性功能。不同代理实现对该字段的支持可能有所不同
+
+示例：
+
+```yaml
+allowed-tools: Bash(git:*) Bash(jq:*) Read
+```
+
+### 正文内容
+
+前置数据后的 Markdown 正文包含技能指令。没有格式限制。编写任何有助于代理有效执行任务的内容。
+
+推荐的部分：
+
+- 分步指令
+- 输入和输出示例
+- 常见边界情况
+
+请注意，代理在决定激活技能后将加载整个文件。考虑将较长的 `SKILL.md` 内容拆分为引用文件。
+
+## 可选目录
+
+### scripts/
+
+包含代理可以运行的可执行代码。脚本应该：
+
+- 自包含或清楚地记录依赖关系
+- 包含有用的错误消息
+- 优雅地处理边界情况
+
+支持的语言取决于代理实现。常见选项包括 Python、Bash 和 JavaScript。
+
+### references/
+
+包含代理可以在需要时阅读的附加文档：
+
+- `REFERENCE.md` - 详细的技术参考
+- `FORMS.md` - 表单模板或结构化数据格式
+- 特定于领域的文件（`finance.md`、`legal.md` 等）
+
+保持单个[参考文件](#文件引用)专注。代理按需加载这些文件，因此较小的文件意味着更少的上下文使用。
+
+### assets/
+
+包含静态资源：
+
+- 模板（文档模板、配置模板）
+- 图像（图表、示例）
+- 数据文件（查找表、模式）
+
+## 渐进式披露
+
+技能的结构应高效利用上下文：
+
+1. **元数据**（~100 tokens）：所有技能在启动时加载 `name` 和 `description` 字段
+2. **指令**（建议 < 5000 tokens）：技能激活时加载完整的 `SKILL.md` 正文
+3. **资源**（按需）：文件（例如 `scripts/`、`references/` 或 `assets/` 中的文件）仅在需要时加载
+
+将主 `SKILL.md` 保持在 500 行以下。将详细参考资料移动到单独的文件中。
+
+## 文件引用
+
+在技能中引用其他文件时，使用从技能根目录开始的相对路径：
+
+```markdown
+Run the extraction script:
+scripts/extract.py
+```
+
+保持文件引用从 `SKILL.md` 开始只有一层深度。避免深度嵌套的引用链。

document/the-complete-guide-to-building-skill.md

@@ -0,0 +1,903 @@
+# Claude 技能构建完全指南
+
+## 引言
+
+[技能（Skill）](https://claude.com/blog/skills)是一组指令——以简单文件夹的形式打包——用于教会 Claude 如何处理特定任务或工作流程。技能是自定义 Claude 以满足特定需求的最强大方式之一。它让你无需在每次对话中反复解释你的偏好、流程和领域专业知识，而是只需教会 Claude 一次，便可持续受益。
+
+当你有可重复的工作流程时，技能尤其强大：根据规格生成前端设计、使用一致的方法论进行研究、创建符合团队风格指南的文档，或者编排多步骤流程。它们与 Claude 的内置功能（如代码执行和文档创建）配合良好。对于正在构建 MCP 集成的开发者来说，技能增加了另一个强大的层次，帮助将原始工具访问转化为可靠、优化的工作流程。
+
+本指南涵盖了构建有效技能所需的一切——从规划、结构到测试和分发。无论你是为自己、团队还是社区构建技能，你都能在全文中找到实用的模式和真实案例。
+
+### 你将学到：
+
+- 技能结构的技术要求和最佳实践
+- 独立技能和 MCP 增强工作流程的模式
+- 我们在不同用例中观察到的有效模式
+- 如何测试、迭代和分发你的技能
+
+### 适用人群：
+
+- 希望 Claude 一致地遵循特定工作流程的开发者
+- 希望 Claude 遵循特定工作流程的高级用户
+- 寻求在整个组织中标准化 Claude 使用方式的团队
+
+### 本指南的两条路径
+
+构建独立技能？重点关注"基础知识"、"规划与设计"以及第 1-2 类。增强 MCP 集成？"技能 + MCP"部分和第 3 类适合你。两条路径共享相同的技术要求，但你可以选择与你的用例相关的内容。
+
+**本指南的收获**：阅读完本指南后，你将能够在一次工作时段内构建一个功能完整的技能。使用 skill-creator 构建和测试你的第一个可用技能大约需要 15-30 分钟。
+
+让我们开始吧。
+
+# 第 1 章：基础知识
+
+## 什么是技能？
+
+技能是一个包含以下内容的文件夹：
+
+- **SKILL.md（必需）**：带有 YAML 前置元数据的 Markdown 格式指令
+- **scripts/（可选）**：可执行代码（Python、Bash 等）
+- **references/（可选）**：按需加载的文档
+- **assets/（可选）**：输出中使用的模板、字体、图标
+
+## 核心设计原则
+
+### 渐进式披露
+
+技能采用三级系统：
+
+- **第一级（YAML 前置元数据）**：始终加载到 Claude 的系统提示中。仅提供足够的信息让 Claude 知道何时应该使用每个技能，而无需将所有内容加载到上下文中。
+- **第二级（SKILL.md 正文）**：当 Claude 认为该技能与当前任务相关时加载。包含完整的指令和指南。
+- **第三级（关联文件）**：技能目录中捆绑的附加文件，Claude 可以根据需要选择导航和发现。
+
+这种渐进式披露在保持专业能力的同时最大限度地减少了 token 使用。
+
+### 可组合性
+
+Claude 可以同时加载多个技能。你的技能应该能够与其他技能良好协作，而不是假设它是唯一可用的能力。
+
+### 可移植性
+
+技能在 Claude.ai、Claude Code 和 API 中的工作方式完全相同。只需创建一次技能，它就可以在所有平台上无需修改地运行，前提是环境支持技能所需的任何依赖项。
+
+## 面向 MCP 构建者：技能 + 连接器
+
+_💡 构建不含 MCP 的独立技能？跳至"规划与设计"——你随时可以回来查阅此部分。_
+
+如果你已经有一个[可用的 MCP 服务器](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)，那么你已经完成了最困难的部分。技能是其上的知识层——捕获你已经了解的工作流程和最佳实践，以便 Claude 能够一致地应用它们。
+
+### 厨房比喻
+
+**MCP 提供专业厨房**：访问工具、食材和设备。
+
+**技能提供食谱**：关于如何创造有价值产出的分步指令。
+
+两者结合，使用户能够完成复杂任务，而无需自己弄清楚每一步。
+
+它们如何协同工作：
+
+| MCP（连接性）                                              | 技能（知识）                 |
+| ---------------------------------------------------------- | ---------------------------- |
+| （Notion、Asana、Linear 等）有效地将 Claude 连接到你的服务 | 教会 Claude 如何使用你的服务 |
+| 提供实时数据访问和工具调用                                 | 捕获工作流程和最佳实践       |
+| Claude 能做什么                                            | Claude 应该怎么做            |
+
+### 这对你的 MCP 用户为何重要
+
+#### 没有技能时：
+
+- 用户连接了你的 MCP 但不知道下一步该做什么
+- 支持工单询问"如何用你的集成做 X"
+- 每次对话都从零开始
+- 结果不一致，因为用户每次的提示方式不同
+- 当真正的问题是工作流程指导时，用户却责怪你的连接器
+
+#### 有技能时：
+
+- 预构建的工作流程在需要时自动激活
+- 一致、可靠的工具使用
+- 最佳实践嵌入到每次交互中
+- 降低你的集成的学习曲线
+
+# 第 2 章：规划与设计
+
+## 从用例开始
+
+在编写任何代码之前，确定 2-3 个你的技能应该支持的具体用例。
+
+### 良好的用例定义：
+
+```
+用例：项目冲刺计划
+触发器：用户说"帮我规划这个冲刺"或"创建冲刺任务"
+步骤：
+1. 从 Linear 获取当前项目状态（通过 MCP）
+2. 分析团队速度和产能
+3. 建议任务优先级
+4. 在 Linear 中创建带有适当标签和估算的任务
+结果：冲刺完全规划完成，任务已创建
+```
+
+### 问问自己：
+
+- 用户想要完成什么？
+- 这需要哪些多步骤工作流程？
+- 需要哪些工具（内置的还是 MCP 的）？
+- 应该嵌入哪些领域知识或最佳实践？
+
+## 常见技能用例类别
+
+在 Anthropic，我们观察到三种常见用例：
+
+### 类别 1：文档与资产创建
+
+用途：创建一致、高质量的输出，包括文档、演示文稿、应用程序、设计、代码等。
+
+_真实案例_：[frontend-design 技能](https://github.com/anthropics/skills/tree/main/skills/frontend-design)（另见 [docx、pptx、xlsx 和 ppt 技能](https://github.com/anthropics/skills/tree/main/skills)）
+
+"创建独特的、生产级的前端界面，具有高设计质量。在构建 Web 组件、页面、产物、海报或应用程序时使用。"
+
+**关键技术**：
+
+- 嵌入式风格指南和品牌标准
+- 用于一致输出的模板结构
+- 最终确定前的质量检查清单
+- 无需外部工具——使用 Claude 的内置功能
+
+### 类别 2：工作流程自动化
+
+用途：受益于一致方法论的多步骤流程，包括跨多个 MCP 服务器的协调。
+
+_真实案例_：[skill-creator 技能](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)
+
+"用于创建新技能的交互式指南。引导用户完成用例定义、前置元数据生成、指令编写和验证。"
+
+**关键技术**：
+
+- 带有验证关卡的分步工作流程
+- 常见结构的模板
+- 内置的审查和改进建议
+- 迭代优化循环
+
+### 类别 3：MCP 增强
+
+用途：增强 MCP 服务器提供的工具访问的工作流程指导。
+
+_真实案例_：[sentry-code-review 技能（来自 Sentry）](https://github.com/getsentry/sentry-for-claude/tree/main/skills)
+
+"使用 Sentry 通过其 MCP 服务器提供的错误监控数据，自动分析和修复 GitHub Pull Request 中检测到的 bug。"
+
+**关键技术**：
+
+- 按顺序协调多个 MCP 调用
+- 嵌入领域专业知识
+- 提供用户原本需要指定的上下文
+- 常见 MCP 问题的错误处理
+
+## 定义成功标准
+
+### 你如何知道你的技能正在工作？
+
+这些是理想目标——粗略的基准而非精确的阈值。追求严谨，但接受会有一定程度的主观评估成分。我们正在积极开发更强大的衡量指导和工具。
+
+### 定量指标：
+
+- 技能在 90% 的相关查询上触发
+  - 如何衡量：运行 10-20 个应该触发你技能的测试查询。跟踪它自动加载的次数与需要显式调用的次数。
+- 在 X 次工具调用内完成工作流程
+  - 如何衡量：比较启用和未启用技能时执行相同任务的情况。计算工具调用次数和消耗的总 token 数。
+- 每个工作流程 0 次失败的 API 调用
+  - 如何衡量：在测试运行期间监控 MCP 服务器日志。跟踪重试率和错误代码。
+
+### 定性指标：
+
+- 用户不需要提示 Claude 下一步
+  - 如何评估：在测试期间，记录你需要重定向或澄清的频率。征求 beta 用户的反馈。
+- 工作流程完成时无需用户纠正
+  - 如何评估：运行相同的请求 3-5 次。比较输出的结构一致性和质量。
+- 跨会话的一致结果
+  - 如何评估：新用户能否在第一次尝试时以最少的指导完成任务？
+
+## 技术要求
+
+### 文件结构
+
+```
+your-skill-name/
+├── SKILL.md               # 必需 - 主技能文件
+├── scripts/               # 可选 - 可执行代码
+│   ├── process_data.py    # 示例
+│   └── validate.sh        # 示例
+├── references/            # 可选 - 文档
+│   ├── api-guide.md       # 示例
+│   └── examples/          # 示例
+└── assets/                # 可选 - 模板等
+    └── report-template.md # 示例
+```
+
+### 关键规则
+
+#### SKILL.md 命名：
+
+- 必须完全是 SKILL.md（区分大小写）
+- 不接受任何变体（skill.md、Skill.md 等）
+
+#### 技能文件夹命名：
+
+- 使用 kebab-case：notion-project-setup ✅
+- 不要有空格：Notion Project Setup ❌
+- 不要有下划线：notion_project_setup ❌
+- 不要有大写字母：NotionProjectSetup ❌
+
+#### 不要包含 README.md：
+
+- 不要在技能文件夹内包含 README.md
+- 所有文档都放在 SKILL.md 或 references/ 中
+- 注意：通过 GitHub 分发时，你仍然需要一个仓库级别的 README 供人类用户阅读——参见"分发与共享"。
+
+### YAML 前置元数据：最重要的部分
+
+YAML 前置元数据是 Claude 决定是否加载你的技能的依据。务必做好这一点。
+
+#### 最小必需格式
+
+```
+name: your-skill-name
+description: 它做什么。当用户要求 [特定短语] 时使用。
+```
+
+这就是你开始所需的全部内容。
+
+### 字段要求
+
+**name**（必需）：
+
+- 仅限 kebab-case
+- 不能有空格或大写字母
+- 应与文件夹名称匹配
+
+**description**（必需）：
+
+- **必须同时包含**：
+  - 技能做什么
+  - 何时使用它（触发条件）
+- 少于 1024 个字符
+- 不能有 XML 标签（< 或 >）
+- 包含用户可能会说的特定任务
+- 如果相关，提及文件类型
+
+**license**（可选）：
+
+- 如果将技能开源则使用
+- 常见：MIT、Apache-2.0
+
+**compatibility**（可选）
+
+- 1-500 个字符
+- 指示环境要求：例如目标产品、所需系统包、网络访问需求等
+
+**metadata**（可选）：
+
+- 任何自定义键值对
+- 建议：author、version、mcp-server
+- 示例：
+
+```YAML
+metadata:
+  author: ProjectHub
+  version: 1.0.0
+  mcp-server: projecthub
+```
+
+#### 安全限制
+
+**前置元数据中禁止的内容**：
+
+- XML 尖括号（< >）
+
+- 名称中包含"claude"或"anthropic"的技能（保留字）
+
+**原因**：前置元数据出现在 Claude 的系统提示中。恶意内容可能注入指令。
+
+### 编写有效的技能
+
+#### description 字段
+
+根据 Anthropic 的[工程博客](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)："此元数据……提供足够的信息让 Claude 知道何时应该使用每个技能，而无需将所有内容加载到上下文中。"这是渐进式披露的第一级。
+
+**结构**：
+
+```
+[它做什么] + [何时使用] + [关键能力]
+```
+
+**好的 description 示例**：
+
+```
+# 好 - 具体且可操作
+description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、要求"设计规格"、"组件文档"或"设计到代码交接"时使用。
+
+# 好 - 包含触发短语
+description: 管理 Linear 项目工作流程，包括冲刺计划、任务创建和状态跟踪。当用户提到"冲刺"、"Linear 任务"、"项目计划"或要求"创建工单"时使用。
+
+# 好 - 清晰的价值主张
+description: PayFlow 的端到端客户入职工作流程。处理账户创建、支付设置和订阅管理。当用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。
+```
+
+**差的 description 示例**：
+
+```
+# 太模糊
+description: 帮助处理项目。
+
+# 缺少触发器
+description: 创建复杂的多页文档系统。
+
+# 太技术化，没有用户触发器
+description: 实现具有层级关系的 Project 实体模型。
+```
+
+#### 编写主要指令
+
+在前置元数据之后，用 Markdown 编写实际的指令。
+
+**推荐结构**：
+
+根据你的技能调整此模板。用你的具体内容替换括号中的部分。
+
+````
+---
+name: your-skill
+description: [...]
+---
+
+# 你的技能名称
+
+## 指令
+
+### 步骤 1：[第一个主要步骤]
+清晰解释会发生什么。
+示例：```bash python scripts/fetch_data.py --project-id PROJECT_ID```
+预期输出：[描述成功的样子]
+````
+
+（根据需要添加更多步骤）
+
+## 示例
+
+### 示例 1：[常见场景]
+
+用户说："设置一个新的营销活动"
+
+操作：
+
+1. 通过 MCP 获取现有活动
+2. 使用提供的参数创建新活动
+
+结果：活动已创建，附带确认链接
+
+（根据需要添加更多示例）
+
+## 故障排除
+
+### 错误：[常见错误消息]
+
+**原因**：[为什么会发生]
+
+**解决方案**：[如何修复]
+
+（根据需要添加更多错误案例）
+
+### 指令最佳实践
+
+#### 具体且可操作
+
+✅ **好**：
+
+```
+运行 python scripts/validate.py --input {filename} 检查数据格式。
+如果验证失败，常见问题包括：
+- 缺少必需字段（将它们添加到 CSV）
+- 无效的日期格式（使用 YYYY-MM-DD）
+```
+
+❌ **差**：
+
+```
+在继续之前验证数据。
+```
+
+#### 包含错误处理
+
+```
+## 常见问题
+
+### MCP 连接失败
+如果你看到"Connection refused"：
+1. 验证 MCP 服务器正在运行：检查设置 > 扩展
+2. 确认 API 密钥有效
+3. 尝试重新连接：设置 > 扩展 > [你的服务] > 重新连接
+```
+
+#### 清晰地引用捆绑资源
+
+```
+在编写查询之前，查阅 `references/api-patterns.md` 了解：
+- 速率限制指南
+- 分页模式
+- 错误代码和处理
+```
+
+#### 使用渐进式披露
+
+保持 SKILL.md 专注于核心指令。将详细文档移至 `references/` 并链接到它。（参见[核心设计原则](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)了解三级系统的工作原理。）
+
+# 第 3 章：测试与迭代
+
+技能可以根据你的需求在不同的严格程度下进行测试：
+
+- **在 Claude.ai 中手动测试** - 直接运行查询并观察行为。快速迭代，无需设置。
+- **在 Claude Code 中脚本化测试** - 自动化测试用例以在更改间进行可重复的验证。
+- **通过技能 API 进行程序化测试** - 构建评估套件，针对定义的测试集系统地运行。
+
+选择与你的质量要求和技能可见度相匹配的方法。一个由小团队内部使用的技能与一个部署给数千企业用户的技能有不同的测试需求。
+
+> **专业提示**：先在单个任务上迭代，然后再扩展
+
+我们发现，最有效的技能创建者会在单个具有挑战性的任务上迭代，直到 Claude 成功，然后将成功的方法提取到技能中。这利用了 Claude 的上下文学习能力，比广泛测试提供更快的信号。一旦你有了一个可用的基础，再扩展到多个测试用例以确保覆盖率。
+
+## 推荐的测试方法
+
+根据早期经验，有效的技能测试通常涵盖三个领域：
+
+### 1: 触发测试
+
+**目标**：确保你的技能在正确的时间加载。
+
+**测试用例**：
+
+- ✅ 在明显任务上触发
+- ✅ 在改述的请求上触发
+- ❌ 不在无关主题上触发
+
+**示例测试套件**：
+
+```
+应该触发：
+- "帮我设置一个新的 ProjectHub 工作区"
+- "我需要在 ProjectHub 中创建一个项目"
+- "为 Q4 计划初始化一个 ProjectHub 项目"
+不应该触发：
+- "旧金山的天气怎么样？"
+- "帮我写 Python 代码"
+- "创建一个电子表格"（除非 ProjectHub 技能处理表格）
+```
+
+### 2: 功能测试
+
+**目标**：验证技能产生正确的输出。
+
+**测试用例**：
+
+- 生成有效输出
+- API 调用成功
+- 错误处理正常工作
+- 覆盖边缘情况
+
+**示例**：
+
+```
+测试：创建包含 5 个任务的项目
+给定：项目名称"Q4 计划"，5 个任务描述
+当：技能执行工作流程
+那么：
+  - 项目在 ProjectHub 中创建
+  - 5 个任务以正确的属性创建
+  - 所有任务链接到项目
+  - 无 API 错误
+```
+
+### 3: 性能比较
+
+**目标**：证明技能相比基线改善了结果。
+
+使用"定义成功标准"中的指标。以下是一个比较可能的样子。
+
+**基线比较**：
+
+```
+没有技能时：
+  - 用户每次都提供指令
+  - 15 次来回消息
+  - 3 次失败的 API 调用需要重试
+  - 消耗 12,000 个 token
+
+有技能时：
+- 自动工作流程执行
+- 仅 2 个澄清问题
+- 0 次失败的 API 调用
+- 消耗 6,000 个 token
+```
+
+## 使用 skill-creator 技能
+
+skill-creator 技能——可在 Claude.ai 通过插件目录获取，或下载用于 Claude Code——可以帮助你构建和迭代技能。如果你有 MCP 服务器并了解你的前 2-3 个工作流程，你可以在一次工作时段内构建和测试一个功能完整的技能——通常在 15-30 分钟内。
+
+### 创建技能：
+
+- 从自然语言描述生成技能
+- 生成带有前置元数据的正确格式 SKILL.md
+- 建议触发短语和结构
+
+### 审查技能：
+
+- 标记常见问题（模糊的描述、缺失的触发器、结构问题）
+- 识别潜在的过度/不足触发风险
+- 根据技能的声明目的建议测试用例
+
+### 迭代改进：
+
+- 使用你的技能并遇到边缘情况或失败后，将这些示例带回 skill-creator
+- 示例："使用此聊天中识别的问题和解决方案来改进技能处理 [特定边缘情况] 的方式"
+
+**使用方法**：
+
+```
+"使用 skill-creator 技能帮我为 [你的用例] 构建一个技能"
+```
+
+_注意：skill-creator 帮助你设计和完善技能，但不执行自动化测试套件或产生定量评估结果。_
+
+## 基于反馈的迭代
+
+技能是活的文档。计划根据以下情况进行迭代：
+
+### 触发不足的信号：
+
+- 技能在应该加载时没有加载
+
+- 用户手动启用它
+
+- 关于何时使用它的支持问题
+
+> **解决方案**：在 description 中添加更多细节和细微差别——这可能包括关键字，特别是技术术语
+
+### 过度触发的信号：
+
+- 技能为无关查询加载
+- 用户禁用它
+- 对目的感到困惑
+
+> **解决方案**：添加负面触发器，更加具体
+
+### 执行问题：
+
+- 结果不一致
+- API 调用失败
+- 需要用户纠正
+
+> **解决方案**：改进指令，添加错误处理
+
+# 第 4 章：模式与故障排除
+
+这些模式来自早期采用者和内部团队创建的技能。它们代表了我们观察到的有效的常见方法，而非规定性模板。
+
+## 选择你的方法：问题优先 vs. 工具优先
+
+可以把它想象成 Home Depot（家得宝）。你可能带着问题走进去——"我需要修理厨房柜子"——然后员工指引你找到合适的工具。或者你可能挑选了一把新电钻，然后询问如何将它用于你的特定工作。
+
+技能的工作方式相同：
+
+- **问题优先**："我需要设置一个项目工作区" → 你的技能按正确的顺序编排正确的 MCP 调用。用户描述结果；技能处理工具。
+
+- **工具优先**："我连接了 Notion MCP" → 你的技能教会 Claude 最佳工作流程和最佳实践。用户有访问权限；技能提供专业知识。
+
+大多数技能倾向于一个方向。知道哪种框架适合你的用例有助于你从下面选择正确的模式。
+
+## 模式 1：顺序工作流程编排
+
+**适用场景**：你的用户需要按特定顺序执行的多步骤流程。
+
+### 示例结构：
+
+```
+## 工作流程：引导新客户
+
+### 步骤 1：创建账户
+调用 MCP 工具：`create_customer`
+参数：name、email、company
+
+### 步骤 2：设置支付
+调用 MCP 工具：`setup_payment_method`
+等待：支付方式验证
+
+### 步骤 3：创建订阅
+调用 MCP 工具：`create_subscription`
+参数：plan_id、customer_id（来自步骤 1）
+
+### 步骤 4：发送欢迎邮件
+调用 MCP 工具：`send_email`
+模板：welcome_email_template
+```
+
+**关键技术**：
+
+- 明确的步骤顺序
+- 步骤之间的依赖关系
+- 每个阶段的验证
+- 失败时的回滚指令
+
+## 模式 2：多 MCP 协调
+
+**适用场景**：工作流程跨越多个服务。
+
+### 示例：设计到开发交接
+
+```
+### 阶段 1：设计导出（Figma MCP）
+1. 从 Figma 导出设计资产
+2. 生成设计规格
+3. 创建资产清单
+
+### 阶段 2：资产存储（Drive MCP）
+1. 在 Drive 中创建项目文件夹
+2. 上传所有资产
+3. 生成可共享链接
+
+### 阶段 3：任务创建（Linear MCP）
+1. 创建开发任务
+2. 将资产链接附加到任务
+3. 分配给工程团队
+
+### 阶段 4：通知（Slack MCP）
+1. 在 #engineering 发布交接摘要
+2. 包含资产链接和任务引用
+```
+
+**关键技术**：
+
+- 清晰的阶段分离
+- MCP 之间的数据传递
+- 进入下一阶段前的验证
+- 集中式错误处理
+
+## 模式 3：迭代优化
+
+**适用场景**：输出质量通过迭代得到改善。
+
+### 示例：报告生成
+
+```
+## 迭代报告创建
+### 初稿
+1. 通过 MCP 获取数据
+2. 生成第一版报告草稿
+3. 保存到临时文件
+
+### 质量检查
+1. 运行验证脚本：`scripts/check_report.py`
+2. 识别问题：
+   - 缺失的章节
+   - 不一致的格式
+   - 数据验证错误
+
+### 优化循环
+1. 解决每个识别的问题
+2. 重新生成受影响的章节
+3. 重新验证
+4. 重复直到达到质量阈值
+
+### 最终化
+1. 应用最终格式
+2. 生成摘要
+3. 保存最终版本
+```
+
+**关键技术**：
+
+- 明确的质量标准
+- 迭代改进
+- 验证脚本
+- 知道何时停止迭代
+
+## 模式 4：上下文感知工具选择
+
+**适用场景**：相同的结果，但根据上下文使用不同的工具。
+
+### 示例：文件存储
+
+```
+## 智能文件存储
+### 决策树
+1. 检查文件类型和大小
+2. 确定最佳存储位置：
+   - 大文件（>10MB）：使用云存储 MCP
+   - 协作文档：使用 Notion/Docs MCP
+   - 代码文件：使用 GitHub MCP
+   - 临时文件：使用本地存储
+
+### 执行存储
+基于决策：
+- 调用适当的 MCP 工具
+- 应用特定于服务的元数据
+- 生成访问链接
+
+### 向用户提供上下文
+解释为什么选择该存储
+```
+
+**关键技术**：
+
+- 清晰的决策标准
+- 备用选项
+- 关于选择的透明度
+
+## 模式 5：领域特定智能
+
+**适用场景**：你的技能添加了超越工具访问的专业知识。
+
+### 示例：金融合规
+
+```
+## 带合规的支付处理
+### 处理前（合规检查）
+1. 通过 MCP 获取交易详情
+2. 应用合规规则：
+   - 检查制裁名单
+   - 验证司法管辖区许可
+   - 评估风险级别
+3. 记录合规决策
+
+### 处理
+如果合规通过：
+- 调用支付处理 MCP 工具
+- 应用适当的欺诈检查
+- 处理交易
+否则：
+- 标记以供审查
+- 创建合规案例
+
+### 审计追踪
+- 记录所有合规检查
+- 记录处理决策
+- 生成审计报告
+```
+
+**关键技术**：
+
+- 领域专业知识嵌入逻辑
+- 行动前的合规性
+- 全面的文档记录
+- 清晰的治理
+
+## 故障排除
+
+### 技能不触发
+
+**症状**：技能从不自动加载
+
+**修复**：
+
+修改你的 description 字段。参见"description 字段"中的好/差示例。
+
+**快速检查清单**：
+
+- 是否太通用？（"帮助处理项目"不会工作）
+- 是否包含用户实际会说的触发短语？
+- 如果适用，是否提到相关文件类型？
+
+**调试方法**：
+
+询问 Claude："你什么时候会使用 [技能名称] 技能？"Claude 会引用 description。根据缺失的内容进行调整。
+
+### 技能触发太频繁
+
+**症状**：技能为无关查询加载
+
+**解决方案**：
+
+1. **添加负面触发器**
+
+```
+description: CSV 文件的高级数据分析。用于统计建模、回归、聚类。不要用于简单的数据探索（改用 data-viz 技能）。
+```
+
+2. **更加具体**
+
+```
+# 太宽泛
+description: 处理文档
+
+# 更具体
+description: 处理用于合同审查的 PDF 法律文档
+```
+
+3. **明确范围**
+
+```
+description: 用于电子商务的 PayFlow 支付处理。专门用于在线支付工作流程，而非一般财务查询。
+```
+
+### MCP 连接问题
+
+**症状**：技能加载但 MCP 调用失败
+
+**检查清单**：
+
+1. **验证 MCP 服务器已连接**
+   - Claude.ai：设置 > 扩展 > [你的服务] 应显示"已连接"状态
+2. **检查身份验证**
+   - API 密钥有效且未过期
+   - 已授予适当的权限/范围
+   - OAuth 令牌已刷新
+3. **独立测试 MCP**
+   - 让 Claude 直接调用 MCP（不使用技能）
+   - "使用 [服务] MCP 获取我的项目"
+   - 如果这失败了，问题在 MCP 而非技能
+4. **验证工具名称**
+   - 技能引用正确的 MCP 工具名称
+   - 检查 MCP 服务器文档
+   - 工具名称区分大小写
+
+### 指令未被遵循
+
+**症状**：技能加载但 Claude 不遵循指令
+
+**常见原因**：
+
+1. **指令太冗长**
+   - 保持指令简洁
+   - 使用项目符号和编号列表
+   - 将详细参考移至单独的文件
+
+2. **指令被埋没**
+   - 将关键指令放在顶部
+   - 使用 ## 重要 或 ## 关键 标题
+   - 如果需要，重复关键点
+
+3. **语言模糊**
+
+```
+# 差
+确保正确验证内容
+
+# 好
+关键：在调用 create_project 之前，验证：
+- 项目名称非空
+- 至少分配一名团队成员
+- 开始日期不在过去
+```
+
+**高级技术**：对于关键验证，考虑捆绑一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的；语言解释不是。参见 Office 技能中此模式的示例。
+
+4. **模型"懒惰"** 添加明确的鼓励：
+
+```
+## 性能说明
+- 花时间彻底完成这项工作
+- 质量比速度更重要
+- 不要跳过验证步骤
+```
+
+注意：将此添加到用户提示中比添加到 SKILL.md 中更有效
+
+### 大上下文问题
+
+**症状**：技能似乎很慢或响应质量下降
+
+**原因**：
+
+- 技能内容太大
+- 同时启用了太多技能
+- 所有内容都被加载而不是渐进式披露
+
+**解决方案**：
+
+1. **优化 SKILL.md 大小**
+   - 将详细文档移至 references/
+   - 链接到引用而不是内联
+   - SKILL.md 保持在 5,000 字以下
+2. **减少启用的技能**
+   - 评估是否同时启用了超过 20-50 个技能
+   - 建议选择性启用
+   - 考虑为相关功能使用技能"包"

document/what-are-skills.md

@@ -0,0 +1,60 @@
+# 什么是技能？
+
+> Agent Skills 是一种轻量级、开放的格式，用于通过专业知识和工作流扩展 AI 代理的能力。
+
+核心来说，一个技能是一个包含 `SKILL.md` 文件的文件夹。该文件包含元数据（至少包括 `name` 和 `description`）以及告诉代理如何执行特定任务的指令。技能还可以打包脚本、模板和参考资料。
+
+```directory theme={null}
+my-skill/
+├── SKILL.md          # 必需：指令 + 元数据
+├── scripts/          # 可选：可执行代码
+├── references/       # 可选：文档
+└── assets/           # 可选：模板、资源
+```
+
+## 技能如何工作
+
+技能使用**渐进式披露**来高效管理上下文：
+
+1. **发现**：在启动时，代理仅加载每个可用技能的名称和描述，足以了解何时可能相关。
+2. **激活**：当任务匹配技能的描述时，代理将完整的 `SKILL.md` 指令读入上下文。
+3. **执行**：代理遵循指令，根据需要可选择性地加载引用文件或执行打包的代码。
+
+这种方法使代理保持快速，同时能够按需访问更多上下文。
+
+## SKILL.md 文件
+
+每个技能都从包含 YAML 前置数据和 Markdown 指令的 `SKILL.md` 文件开始：
+
+```mdx
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+---
+
+# PDF Processing
+
+## When to use this skill
+
+Use this skill when the user needs to work with PDF files...
+
+## How to extract text
+
+1. Use pdfplumber for text extraction...
+
+## How to fill forms
+
+...
+```
+
+以下前置数据在 `SKILL.md` 的顶部是必需的：
+
+- `name`：简短标识符
+- `description`：何时使用此技能
+
+Markdown 正文包含实际指令，对结构或内容没有特定限制。
+这种简单格式具有一些关键优势：
+
+- **自文档化**：技能作者或用户可以阅读 `SKILL.md` 并了解其功能，使技能易于审核和改进。
+- **可扩展**：技能的复杂度可以范围从仅文本指令到可执行代码、资产和模板。
+- **可移植**：技能只是文件，因此易于编辑、版本控制和共享。

openspec/changes/archive/2026-02-04-lyxy-runner-python/design.md

@@ -57,7 +57,7 @@ uv是Astral开发的快速Python包管理器，支持PEP 723内联元数据格
 
 ### Decision 2: 使用辅助脚本实现跨平台临时目录
 
-**决策：** 创建`skills/uv-python-runner/script/get_temp_path.py`辅助脚本，使用Python标准库的`tempfile`模块在系统临时目录中创建空的Python脚本文件，并返回脚本文件路径。**辅助脚本本身也使用uv run执行，保持一致性。**
+**决策：** 创建`skills/lyxy-runner-python/script/get_temp_path.py`辅助脚本，使用Python标准库的`tempfile`模块在系统临时目录中创建空的Python脚本文件，并返回脚本文件路径。**辅助脚本本身也使用uv run执行，保持一致性。**
 
 **理由：**
 - `tempfile.gettempdir()`自动适配所有平台（Windows/macOS/Linux）
@@ -72,7 +72,7 @@ uv是Astral开发的快速Python包管理器，支持PEP 723内联元数据格
 - **功能**：在系统临时目录创建空的Python脚本文件，返回文件路径
 - **无注释**：脚本只包含必要代码，没有文档字符串或注释
 - **PEP 723格式**：包含空的依赖声明`# dependencies = []`
-- **执行方式**：`uv run skills/uv-python-runner/script/get_temp_path.py`
+- **执行方式**：`uv run skills/lyxy-runner-python/script/get_temp_path.py`
 - **输出**：直接在stdout输出临时Python脚本文件的完整路径
   - Linux/macOS: `/tmp/uv_script_xxx.py`
   - Windows: `C:\Users\<username>\AppData\Local\Temp\uv_script_xxx.py`
@@ -220,13 +220,13 @@ uv是Astral开发的快速Python包管理器，支持PEP 723内联元数据格
 这是新skill的首次实现，不存在迁移问题。
 
 **部署步骤：**
-1. 创建skill目录：`skills/uv-python-runner/`
-2. 创建skill文件：`skills/uv-python-runner/SKILL.md`
+1. 创建skill目录：`skills/lyxy-runner-python/`
+2. 创建skill文件：`skills/lyxy-runner-python/SKILL.md`
 3. 编写skill内容（YAML元数据 + Markdown文档）
 4. 测试skill是否可以被正确加载和触发
 
 **回滚策略：**
-- 如有问题，直接删除`skills/uv-python-runner/`目录即可
+- 如有问题，直接删除`skills/lyxy-runner-python/`目录即可
 - skill文件不影响系统或现有代码
 
 ## Open Questions

openspec/changes/archive/2026-02-04-lyxy-runner-python/proposal.md

@@ -9,7 +9,9 @@
 
 ## What Changes
 
-- 创建新的skill：`uv-python-runner`
+**注：** 实现时将技能名称从 `lyxy-runner-python` 简化为 `lyxy-runner-python`，以保持命名更通用和简洁，避免与未来可能的其他 Python runner 实现名称冲突。
+
+- 创建新的skill：`lyxy-runner-python` (proposal中为 `lyxy-runner-python`)
   - 指导大模型按照PEP 723规范编写Python脚本
 - 提供临时文件创建和uv run执行的标准流程
 - 严格错误处理模式
@@ -26,7 +28,7 @@
 
 ### New Capabilities
 
-- `uv-python-runner`: 通用Python脚本执行工具，指导大模型使用uv的隔离环境特性来执行临时Python脚本，无需在系统环境预安装依赖。适用于数据处理、API交互、文件操作、科学计算等各种任务。
+- `lyxy-runner-python`: 通用Python脚本执行工具，指导大模型使用uv的隔离环境特性来执行临时Python脚本，无需在系统环境预安装依赖。适用于数据处理、API交互、文件操作、科学计算等各种任务。
 
 ### Modified Capabilities
 
@@ -34,7 +36,7 @@
 
 ## Impact
 
-- **代码影响**：新增skill文件 `skills/uv-python-runner/SKILL.md`
+- **代码影响**：新增skill文件 `skills/lyxy-runner-python/SKILL.md`
 - **依赖影响**：要求系统安装uv（https://docs.astral.sh/uv/）
 - **系统影响**：无（skill只提供指导，不直接修改系统）
 - **API影响**：无

openspec/changes/archive/2026-02-04-lyxy-runner-python/specs/uv-python-runner/spec.md

@@ -36,7 +36,7 @@ Skill SHALL指导LLM在系统临时目录中创建临时Python文件，并使用
 
 ### 需求：跨平台临时目录支持
 
-Skill SHALL使用`skills/uv-python-runner/script/get_temp_path.py`辅助脚本来获取平台特定的临时目录。Skill SHALL在创建临时Python文件之前，先调用此辅助脚本获取临时目录路径。Skill SHALL支持Windows、macOS、Linux三个平台。
+Skill SHALL使用`skills/lyxy-runner-python/script/get_temp_path.py`辅助脚本来获取平台特定的临时目录。Skill SHALL在创建临时Python文件之前，先调用此辅助脚本获取临时目录路径。Skill SHALL支持Windows、macOS、Linux三个平台。
 
 #### 场景：获取临时目录路径
 - **WHEN** LLM需要为Python脚本创建临时文件

openspec/changes/archive/2026-02-04-lyxy-runner-python/tasks.md

@@ -1,17 +1,17 @@
 ## 1. Skill结构设置
 
- - [x] 1.1 创建skill目录：`skills/uv-python-runner/`
- - [x] 1.2 创建script子目录：`skills/uv-python-runner/script/`
- - [x] 1.3 创建辅助脚本：`skills/uv-python-runner/script/get_temp_path.py`
+ - [x] 1.1 创建skill目录：`skills/lyxy-runner-python/`
+ - [x] 1.2 创建script子目录：`skills/lyxy-runner-python/script/`
+ - [x] 1.3 创建辅助脚本：`skills/lyxy-runner-python/script/get_temp_path.py`
    - [x] 1.3.1 添加PEP 723元数据块（`# dependencies = []`）
    - [x] 1.3.2 在系统临时目录创建空的Python脚本文件并返回路径
    - [x] 1.3.3 直接在stdout输出脚本文件完整路径
    - [x] 1.3.4 添加命令行支持，直接运行脚本
- - [x] 1.4 创建skill文件：`skills/uv-python-runner/SKILL.md`
+ - [x] 1.4 创建skill文件：`skills/lyxy-runner-python/SKILL.md`
 
 ## 2. 编写YAML前置元数据
 
- - [x] 2.1 添加skill名称：`uv-python-runner`
+ - [x] 2.1 添加skill名称：`lyxy-runner-python`
  - [x] 2.2 添加英文skill描述
  - [x] 2.3 添加参数提示（不适用，此skill无参数）
 
@@ -33,7 +33,7 @@
    - [x] 5.1.2 提供包含外部依赖的示例
    - [x] 5.1.3 提供仅使用标准库的示例
  - [x] 5.2 记录步骤2：获取临时目录
-   - [x] 5.2.1 说明调用辅助脚本：`uv run skills/uv-python-runner/script/get_temp_path.py`
+   - [x] 5.2.1 说明调用辅助脚本：`uv run skills/lyxy-runner-python/script/get_temp_path.py`
    - [x] 5.2.2 说明辅助脚本直接在stdout输出临时目录路径
    - [x] 5.2.3 说明大模型捕获stdout输出得到临时目录
    - [x] 5.2.4 说明根据临时目录构造脚本文件路径：`<temp_dir>/uv_script_<timestamp>_<random>.py`

openspec/changes/archive/2026-02-05-lyxy-runner-js/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-05

openspec/changes/archive/2026-02-05-lyxy-runner-js/design.md

@@ -0,0 +1,143 @@
+## Context（背景）
+
+本项目在 `skills/` 目录下开发用于大模型工具的技能（skills），每个子目录代表一个技能。目前，项目已经有一个 `lyxy-runner-python` 技能，它使用 `uv` 提供了隔离的 Python 执行环境，支持依赖管理和临时文件隔离。
+
+`lyxy-runner-js/` 目录已存在但未完成，只包含一个测试文件（`test/axios.js`）。目前项目中还没有功能完整的 JavaScript/TypeScript 执行能力。
+
+**当前状态：**
+- `lyxy-runner-python` 技能已完整实现（基于 uv 的隔离）
+- `lyxy-runner-js` 目录骨架存在但缺少实现
+- 没有 JavaScript/TypeScript 的依赖管理机制
+- 没有 JS/TS 脚本的临时文件生命周期管理
+
+**约束条件：**
+- 必须保持环境隔离（不污染系统包）
+- 应遵循 `lyxy-runner-python` 建立的模式以保持一致性
+- 技能结构必须符合项目规范（`skills/<skill-name>/`）
+- 必须同时支持 JavaScript 和 TypeScript 执行
+
+## Goals / Non-Goals（目标 / 非目标）
+
+**目标：**
+- 提供辅助脚本供大模型调用（使用 JavaScript 编写，与 skill 主题一致）
+- 在 SKILL.md 中清晰描述完整的调用流程
+- 利用 Bun 的自动依赖管理能力
+- 匹配 `lyxy-runner-python` 的工作流程和用户体验，保持一致性
+
+**非目标：**
+- 提供完整的 IDE 或开发环境
+- 脚本的长期存储或持久化
+- 超越 JavaScript/TypeScript 的多语言支持
+- 替换或修改现有的 `lyxy-runner-python` 技能
+- 构建自定义的 Bun 运行时包装器（直接使用 Bun）
+
+## Decisions（技术决策）
+
+### 1. 使用 Bun 作为 JavaScript 运行时
+
+**理由：** Bun 相比替代方案具有显著优势：
+- **Bun：** 比 Node.js 快约 100 倍的冷启动，内置包管理器（bun install），原生 TypeScript 支持，兼容 Node.js API
+- **Node.js + npm/yarn：** 启动慢，需要外部包管理器，没有原生 TypeScript 支持
+- **Deno：** 不同的 API 表面（不兼容 Node.js），生态系统较小，Node.js 用户学习曲线陡峭
+
+**考虑的替代方案：**
+- **Node.js with npm：** 因启动速度慢且无原生 TypeScript 支持而被拒绝
+- **Deno：** 因 API 与 Node.js 生态不兼容且包管理不熟悉而被拒绝
+
+### 2. 基于临时文件的执行模型
+
+**理由：** 遵循 `lyxy-runner-python` 的模式，在临时文件中执行脚本可以：
+- 在执行之间保持干净的隔离
+- 自动清理产物
+- 不需要跨运行的状态管理
+- 比内存执行实现更简单
+
+**考虑的替代方案：**
+- **通过 Bun 的 `Bun.transpileString()` 进行内存执行：** 因对模块导入和外部依赖支持不好而被拒绝
+- **持久化目录结构：** 因避免执行之间的状态泄漏而被拒绝
+
+### 3. 使用 Bun 的自动依赖管理
+
+**理由：** Bun 可以直接运行脚本并自动处理依赖：
+- **自动依赖解析：** 当脚本使用 `import` 或 `require` 引入外部包时，Bun 自动下载并缓存该包
+- **无需手动安装：** 不需要手动运行 `bun install`，Bun 在运行时自动处理
+- **智能缓存：** Bun 全局缓存已下载的包，后续运行无需重复下载
+- **简化实现：** 不需要生成临时的 `package.json`，也不需要管理 `node_modules`
+
+**工作流程：**
+1. 用户直接运行脚本（内联或从文件）
+2. 脚本中使用 `import` 或 `require` 引入依赖（如 `import axios from 'axios'`）
+3. Bun 自动检测到未安装的依赖
+4. Bun 下载并缓存依赖到 Bun 的全局缓存（`~/.bun/install/cache`）
+5. 执行脚本
+6. 清理临时脚本文件（Bun 的缓存保持不变）
+
+**考虑的替代方案：**
+- **手动 package.json + bun install：** 因 Bun 已经提供自动依赖处理而被拒绝（过度设计）
+- **要求用户提供 package.json：** 因增加用户负担而被拒绝
+
+### 4. 用于路径管理的辅助脚本
+
+**理由：** `get_temp_path.js` 辅助脚本将：
+- 为脚本生成唯一的临时文件路径
+- 遵循特定于操作系统的临时目录约定
+- 使用 JavaScript 编写，与 lyxy-runner-js 主题一致
+- 使用 Bun 运行（已确保环境就绪）
+
+**实现方式：**
+```javascript
+import { tmpdir } from "os";
+import { join } from "path";
+
+export function getTempPath(extension) {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(7);
+  return join(tmpdir(), `lyxy-runner-js-${timestamp}-${random}.${extension}`);
+}
+```
+
+## Risks / Trade-offs（风险 / 权衡）
+
+### 风险：需要安装 Bun
+
+**风险：** 用户必须单独安装 Bun，这增加了设置障碍。
+
+**缓解措施：**
+- 在 SKILL.md 中清晰记录安装过程（`curl -fsSL https://bun.sh/install | bash`）
+- 如果未找到 Bun，提供有用的错误消息
+- 考虑添加 "check" 命令来验证 Bun 安装
+
+## Migration Plan（迁移计划）
+
+由于这是一个没有现有生产使用的新技能：
+
+1. **第一阶段：实现**
+   - 创建 `scripts/get_temp_path.js` 辅助脚本（使用 JavaScript 编写）
+   - 编写完整的 `SKILL.md` 文档，包含必要的 frontmatter
+   - 描述完整调用流程
+
+2. **第二阶段：验证**
+   - 验证 `get_temp_path.js` 辅助脚本工作正常
+   - 验证 SKILL.md 格式符合 Agent Skills 规范
+   - 验证 SKILL.md 中的调用流程准确无误
+
+3. **第三阶段：文档**
+   - 确保 SKILL.md 涵盖所有用例
+   - 为常见场景提供示例
+   - 记录错误处理和故障排除
+
+**回滚策略：**
+- 如果实现有问题，删除 `skills/lyxy-runner-js/` 目录
+- 对项目其他部分无影响，因为这是一个新的隔离技能
+
+## Open Questions（待解决的问题）
+
+1. **我们是否应该支持持久化项目目录？**
+   - 当前方法：只有临时文件
+   - 考虑：允许用户指定工作目录
+   - 决策：推迟到未来增强；首先专注于简单的脚本执行
+
+2. **需要什么级别的错误报告？**
+   - 当前计划：按原样转发 Bun 的 stderr 输出
+   - 考虑：解析并美化常见错误
+   - 决策：从原始输出开始，根据用户需求增强

openspec/changes/archive/2026-02-05-lyxy-runner-js/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+当前项目已有基于uv的Python执行环境(lyxy-runner-python)，但缺少相应的JavaScript/TypeScript执行能力。Bun作为现代JavaScript运行时，具有极快的启动速度、内置包管理器和对标准库的完整支持，非常适合创建一个类似lyxy-runner-python的隔离式JS/TS执行环境，保持系统环境整洁。
+
+## What Changes
+
+- 完善现有的`skills/lyxy-runner-js/`目录（目前仅有test/axios.js文件）
+- 基于Bun实现JavaScript/TypeScript脚本执行能力，使用临时文件和环境隔离
+- 参考lyxy-runner-python的工作流，支持依赖管理（通过package.json或内联声明）
+- 提供辅助脚本生成临时文件路径
+- 创建完整的SKILL.md文档
+
+## Capabilities
+
+### New Capabilities
+- `lyxy-runner-js`: 提供基于Bun的JavaScript/TypeScript脚本执行能力，支持依赖管理、环境隔离和临时文件清理
+
+### Modified Capabilities
+- None
+
+## Impact
+
+**新增文件**:
+- `skills/lyxy-runner-js/SKILL.md` - Skill文档
+- `skills/lyxy-runner-js/scripts/get_temp_path.js` - 临时路径生成辅助脚本
+
+**外部依赖**:
+- 需要安装Bun运行时（https://bun.sh）
+
+**不影响的范围**:
+- 不影响现有的lyxy-runner-python skill
+- 不修改其他skill的实现

openspec/changes/archive/2026-02-05-lyxy-runner-js/specs/lyxy-runner-js/spec.md

@@ -0,0 +1,101 @@
+## ADDED Requirements
+
+### Requirement: 生成临时文件路径
+辅助脚本 MUST 提供为脚本生成唯一临时文件路径的功能。
+
+#### Scenario: 生成 JavaScript 临时路径
+- **WHEN** 调用 `scripts/get_temp_path.js` 并传入参数 `'js'`
+- **THEN** 返回操作系统的临时目录路径
+- **THEN** 路径包含时间戳和随机字符串以确保唯一性
+- **THEN** 文件扩展名为 `.js`
+
+#### Scenario: 生成 TypeScript 临时路径
+- **WHEN** 调用 `scripts/get_temp_path.js` 并传入参数 `'ts'`
+- **THEN** 返回操作系统的临时目录路径
+- **THEN** 路径包含时间戳和随机字符串以确保唯一性
+- **THEN** 文件扩展名为 `.ts`
+
+### Requirement: 文档描述完整调用流程
+SKILL.md MUST 清晰描述大模型如何使用 lyxy-runner-js 技能执行 JavaScript/TypeScript 脚本的完整流程。
+
+#### Scenario: 执行脚本的标准流程
+- **WHEN** 大模型阅读 SKILL.md
+- **THEN** 文档描述以下标准流程：
+  1. 执行 `bun --version` 检查环境
+  2. 调用 `scripts/get_temp_path.js` 生成临时文件路径
+  3. 将脚本内容写入临时文件
+  4. 使用 `bun <temp-file>` 执行脚本
+  5. Bun 自动处理依赖和 TypeScript 转译
+  6. 临时文件由系统自动清理
+
+#### Scenario: 文档中的示例代码
+- **WHEN** 大模型阅读 SKILL.md
+- **THEN** 文档提供完整的示例代码，展示：
+  - 如何检查 Bun 安装（`bun --version`）
+  - 如何调用辅助脚本生成临时文件路径
+  - 如何执行脚本
+  - 如何处理输出和错误
+
+### Requirement: 错误处理和诊断
+系统 MUST 提供清晰的错误信息和诊断功能，帮助用户识别和解决问题。
+
+#### Scenario: 未安装 Bun 时的错误
+- **WHEN** 系统未检测到 Bun 运行时
+- **THEN** 系统输出友好的错误消息，说明需要安装 Bun
+- **THEN** 系统提供安装指令（`curl -fsSL https://bun.sh/install | bash`）
+- **THEN** 退出码指示依赖缺失
+
+#### Scenario: 脚本语法错误
+- **WHEN** 脚本包含语法错误
+- **THEN** Bun 输出详细的语法错误信息（包括文件名、行号、错误描述）
+- **THEN** 系统将这些信息传递给用户
+- **THEN** 退出码指示语法错误
+
+#### Scenario: 运行时错误
+- **WHEN** 脚本执行过程中抛出运行时错误
+- **THEN** 系统输出完整的错误堆栈跟踪
+- **THEN** 临时文件路径被正确映射以便用户调试
+- **THEN** 退出码指示运行时错误
+
+### Requirement: 输出处理
+系统 MUST 正确处理脚本的 stdout 和 stderr 输出，将其传递给用户终端。
+
+#### Scenario: 标准输出
+- **WHEN** 脚本使用 `console.log()` 或 `console.error()` 输出
+- **THEN** 系统将输出实时传递到用户终端的 stdout 或 stderr
+- **THEN** 不修改或过滤输出内容
+
+#### Scenario: 退出码传递
+- **WHEN** 脚本使用 `process.exit(n)` 显式退出
+- **THEN** 系统使用该退出码
+- **WHEN** 脚本正常完成且不调用 `process.exit()`
+- **THEN** 系统使用退出码 0
+
+### Requirement: 文档完整性
+系统 MUST 包含完整的 SKILL.md 文档，说明如何使用 lyxy-runner-js。
+
+#### Scenario: SKILL.md 包含必要的 frontmatter
+- **WHEN** 大模型阅读 SKILL.md
+- **THEN** 文档顶部包含 YAML frontmatter
+- **THEN** 包含 `name` 字段，值为 `lyxy-runner-js`
+- **THEN** 包含 `description` 字段，描述技能的功能和使用场景
+- **THEN** 可选包含 `compatibility` 字段，说明 Bun 依赖
+
+#### Scenario: 安装说明
+- **WHEN** 用户阅读 SKILL.md
+- **THEN** 文档包含 Bun 的安装说明和命令
+- **THEN** 文档说明 lyxy-runner-js 的依赖要求
+
+#### Scenario: 使用示例
+- **WHEN** 用户阅读 SKILL.md
+- **THEN** 文档提供基本使用示例（执行简单脚本）
+- **THEN** 文档提供使用外部依赖的示例（通过 import 直接引入，Bun 自动处理）
+- **THEN** 文档提供 JavaScript 和 TypeScript 执行示例（同样流程）
+- **THEN** 文档提供错误处理示例
+
+#### Scenario: API 参考
+- **WHEN** 用户阅读 SKILL.md
+- **THEN** 文档列出所有可用命令行标志
+- **THEN** 文档说明每个标志的作用和用法
+- **THEN** 文档说明 `get_temp_path()` 辅助函数的用法
+- **THEN** 文档说明 Bun 的自动依赖管理机制

openspec/changes/archive/2026-02-05-lyxy-runner-js/tasks.md

@@ -0,0 +1,51 @@
+## 1. 项目设置和目录结构
+
+- [x] 1.1 验证 `skills/lyxy-runner-js/` 目录结构
+- [x] 1.2 创建 `skills/lyxy-runner-js/scripts/` 目录（注意是复数 scripts/）
+- [x] 1.3 确认现有测试文件 `skills/lyxy-runner-js/test/axios.js` 的状态
+- [x] 1.4 验证 Bun 运行时是否已安装（本地开发环境）
+
+## 2. 实现临时路径生成辅助脚本
+
+- [x] 2.1 创建 `skills/lyxy-runner-js/scripts/get_temp_path.js` 文件（使用 JavaScript）
+- [x] 2.2 实现 `getTempPath(extension)` 函数
+- [x] 2.3 确保函数生成唯一路径（包含时间戳和随机字符串）
+- [x] 2.4 测试辅助脚本的输出格式正确性
+- [x] 2.5 使用 `bun scripts/get_temp_path.js` 验证脚本可执行
+
+## 3. 编写 SKILL.md 文档
+
+- [x] 3.1 创建 `skills/lyxy-runner-js/SKILL.md` 文档
+- [x] 3.2 添加必要的 YAML frontmatter：
+  - `name: lyxy-runner-js`
+  - `description` 描述功能和场景
+  - 可选 `compatibility` 说明 Bun 依赖
+- [x] 3.3 编写 Bun 安装说明和先决条件
+- [x] 3.4 描述完整的调用流程（供大模型使用）：
+  - 执行 `bun --version` 检查环境
+  - 调用 `scripts/get_temp_path.js` 生成临时文件路径
+  - 写入脚本内容到临时文件
+  - 使用 `bun <temp-file>` 执行脚本
+  - 输出结果到 stdout/stderr
+- [x] 3.5 添加调用流程的完整示例代码
+- [x] 3.6 添加依赖管理示例（通过 import 直接引入，Bun 自动处理）
+- [x] 3.7 添加 JavaScript 和 TypeScript 执行示例（同样流程）
+- [x] 3.8 添加错误处理和故障排除指南
+- [x] 3.9 添加辅助函数 API 参考
+- [x] 3.10 说明不主动清理临时文件，由系统自动处理
+
+## 4. 验证 SKILL.md 格式
+
+- [x] 4.1 使用 `skills-ref validate ./skills/lyxy-runner-js` 验证格式（如果可用）
+- [x] 4.2 确认 frontmatter 符合 Agent Skills 规范
+- [x] 4.3 确认 name 字段格式正确（小写、数字、连字符）
+- [x] 4.4 确认 description 字段长度在 1024 字符以内
+- [x] 4.5 确认文档内容清晰且易于理解
+
+## 5. 集成和最终验证
+
+- [x] 5.1 手动测试 `scripts/get_temp_path.js` 辅助脚本
+- [x] 5.2 验证 SKILL.md 格式符合规范
+- [x] 5.3 验证调用流程的可行性
+- [x] 5.4 验证与 `lyxy-runner-python` 模式的一致性
+- [x] 5.5 提交所有更改到版本控制（如适用）

openspec/changes/archive/2026-02-06-lyxy-runner-js-custom-path/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-06

openspec/changes/archive/2026-02-06-lyxy-runner-js-custom-path/design.md

@@ -0,0 +1,100 @@
+## Context
+
+lyxy-runner-js 技能目前的标准流程假设所有脚本都需要通过临时文件执行。这种设计确保了脚本的隔离性和自动清理，但牺牲了灵活性。用户可能希望：
+1. 执行已存在的脚本文件
+2. 将脚本持久化到项目中的特定位置
+3. 利用大模型已有的文件操作工具（Write）直接创建脚本
+
+当前实现强制所有场景都通过 `get_temp_path.js` 生成临时路径，限制了这些使用场景。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 在文档中增加条件判断逻辑，根据用户输入选择不同的执行路径
+- 保持向后兼容：未指定路径时仍使用临时文件路径（场景3）
+- 支持直接执行已存在的脚本文件（场景1）
+- 支持使用大模型工具在指定路径创建脚本（场景2）
+
+**Non-Goals:**
+- 不修改 `get_temp_path.js` 的实现
+- 不改变 Bun 运行时的行为
+- 不增加新的辅助脚本或工具
+
+## Decisions
+
+### 决策1：文档驱动的实现方案
+
+**决策选择：** 通过更新 SKILL.md 文档来定义新的使用流程，而不是修改代码实现。
+
+**理由：**
+- lyxy-runner-js 的核心功能（脚本执行）已经完全由 Bun 运行时提供
+- 大模型根据 SKILL.md 的描述来选择操作方式
+- 当前代码（`get_temp_path.js`）在临时路径场景下已经完全满足需求
+- 直接使用大模型的 Write 工具创建文件比通过辅助脚本更灵活
+
+**替代方案考虑：**
+- 方案A：修改 `get_temp_path.js` 增加路径参数 → 拒绝，因为增加了不必要的复杂性，大模型已有 Write 工具
+- 方案B：创建新的辅助脚本用于自定义路径 → 拒绝，重复造轮子，大模型工具已覆盖此需求
+
+### 决策2：场景优先级的设计
+
+**决策选择：** 在文档中将场景分为明确的优先级，确保大模型在处理用户请求时有清晰的决策树。
+
+**决策树：**
+1. 用户是否提供了要执行的脚本文件路径？
+   - 是 → 直接执行（场景1）
+   - 否 → 进入下一步
+2. 用户是否指定了脚本的生成路径？
+   - 是 → 用 Write 工具在指定路径创建脚本，然后执行（场景2）
+   - 否 → 使用 `get_temp_path.js` 生成临时路径，创建脚本，执行（场景3）
+
+**理由：**
+- 优先处理用户明确指定的意图（已有脚本或自定义路径）
+- 临时路径作为兜底方案，确保未指定路径时仍能工作
+- 决策树简单清晰，大模型易于理解和执行
+
+### 决策3：保持 `get_temp_path.js` 不变
+
+**决策选择：** 不修改任何现有代码，仅更新文档。
+
+**理由：**
+- 临时路径生成逻辑在场景3中仍然必需
+- 增加参数会增加代码维护成本
+- 文档更新比代码修改更容易审查和回滚
+
+## Risks / Trade-offs
+
+### 风险1：大模型可能不理解优先级逻辑
+
+**风险：** 如果文档描述不够清晰，大模型可能在场景选择上出错。
+
+**缓解措施：**
+- 在文档中使用明确的"决策树"或"流程图"形式
+- 为每个场景提供清晰的示例代码
+- 在 SKILL.md 顶部使用简洁的"快速参考"部分总结三种场景
+
+### 权衡：文档复杂度 vs 灵活性
+
+**权衡：** 增加文档的复杂度来提供更高的灵活性。
+
+**说明：**
+- 用户获得了更多控制权（直接指定路径）
+- 文档需要更详细地解释不同场景
+- 但这符合 lyxy-runner-js 作为"技能工具"的定位——为大模型提供灵活的执行选项
+
+## Migration Plan
+
+本变更仅涉及文档更新，无需代码迁移或部署步骤。
+
+**更新步骤：**
+1. 更新 `skills/lyxy-runner-js/SKILL.md`，增加三种使用场景的说明
+2. 更新 `openspec/specs/lyxy-runner-js/spec.md`，增加新的需求场景
+3. 验证文档描述是否清晰，易于理解和执行
+
+**回滚策略：**
+- 使用 git 版本控制可以轻松回滚文档修改
+- 不涉及代码修改，回滚风险极低
+
+## Open Questions
+
+无。本变更的范围明确，技术实现路径清晰。

openspec/changes/archive/2026-02-06-lyxy-runner-js-custom-path/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+当前 lyxy-runner-js 技能的标准流程中，所有脚本执行都必须使用 `get_temp_path.js` 生成临时文件路径。这导致当用户想要运行已存在的脚本文件或希望将脚本持久化到特定位置时，流程不够灵活。大模型已经拥有可以直接创建文件的工具（如 Write 工具），不需要强制通过临时路径生成脚本。
+
+## What Changes
+
+- 增加条件判断逻辑：只有当用户没有指定脚本文件或没有指定脚本生成路径时，才使用 `get_temp_path.js` 生成临时路径
+- 增加直接执行已存在脚本文件的使用场景
+- 增加使用大模型工具在指定路径创建脚本的使用场景
+- 保持向后兼容：不提供路径或脚本时，仍使用原有的临时文件路径生成逻辑
+
+## Capabilities
+
+### New Capabilities
+无 - 本变更是在现有 lyxy-runner-js 技能基础上的增强
+
+### Modified Capabilities
+- `lyxy-runner-js`: 增加条件性使用临时路径的需求。这将修改现有的"文档描述完整调用流程"需求，增加新的场景：
+  - 场景1：用户提供已存在的脚本文件路径 → 直接执行
+  - 场景2：用户提供脚本生成路径 → 用大模型工具创建脚本到指定路径，然后执行
+  - 场景3：用户未提供任何路径信息 → 使用 `get_temp_path.js` 生成临时路径（现有流程）
+
+## Impact
+
+- **文档更新**: `skills/lyxy-runner-js/SKILL.md` 需要重新组织调用流程说明，增加条件判断逻辑和新的使用场景
+- **规范更新**: `openspec/specs/lyxy-runner-js/spec.md` 需要增加新的需求场景，描述不同条件下的执行路径选择
+- **代码**: `get_temp_path.js` 保持不变，仅在未提供路径时调用

openspec/changes/archive/2026-02-06-lyxy-runner-js-custom-path/specs/lyxy-runner-js/spec.md

@@ -0,0 +1,77 @@
+## ADDED Requirements
+
+### Requirement: 环境检查前置条件
+在任何场景执行脚本之前，大模型 MUST 先检查 Bun 运行时是否可用。
+
+#### Scenario: 所有场景的环境检查
+- **WHEN** 大模型准备执行脚本（无论使用哪种场景）
+- **THEN** 必须在执行任何脚本之前先运行 `bun --version`
+- **THEN** 如果 `bun --version` 失败或未找到命令，必须输出友好的错误信息
+- **THEN** 错误信息必须明确说明 "Bun 运行时未安装" 或类似提示
+- **THEN** 错误信息必须包含 Bun 安装说明（如 `curl -fsSL https://bun.sh/install | bash`）
+- **THEN** 环境检查失败时必须停止后续执行
+- **THEN** 大模型禁止自动尝试使用 nodejs、npm、yarn、pnpm 等其他 JavaScript 运行时或包管理工具
+- **THEN** 大模型禁止建议用户将脚本转换为其他运行时格式
+- **WHEN** `bun --version` 成功
+- **THEN** 可以继续执行脚本的相应场景流程
+
+## MODIFIED Requirements
+
+### Requirement: 文档描述完整调用流程
+SKILL.md MUST 清晰描述大模型如何使用 lyxy-runner-js 技能执行 JavaScript/TypeScript 脚本的完整流程，并根据用户提供的路径信息选择不同的执行方式。
+
+#### Scenario: 执行已存在的脚本文件
+- **WHEN** 用户提供已存在的脚本文件路径
+- **THEN** 首先执行 `bun --version` 检查环境
+- **THEN** 如果环境检查失败，输出错误信息并停止执行
+- **THEN** 环境检查通过后，大模型直接使用 `bun <script-file>` 执行该脚本
+- **THEN** 跳过 `get_temp_path.js` 调用
+- **THEN** 不创建任何新文件
+- **THEN** 使用脚本的 stdout 和 stderr 作为输出
+
+#### Scenario: 在指定路径创建并执行脚本
+- **WHEN** 用户提供脚本生成路径（但脚本文件不存在）
+- **THEN** 首先执行 `bun --version` 检查环境
+- **THEN** 如果环境检查失败，输出错误信息并停止执行
+- **THEN** 环境检查通过后，大模型使用 Write 工具在指定路径创建脚本文件
+- **THEN** 使用 `bun <specified-path>` 执行该脚本
+- **THEN** 跳过 `get_temp_path.js` 调用
+- **THEN** 脚本文件持久化到指定位置
+
+#### Scenario: 使用临时路径执行脚本（默认流程）
+- **WHEN** 大模型阅读 SKILL.md 且用户未提供脚本路径或生成路径
+- **THEN** 文档描述以下标准流程：
+  1. 执行 `bun --version` 检查环境
+  2. 调用 `scripts/get_temp_path.js` 生成临时文件路径
+  3. 将脚本内容写入临时文件
+  4. 使用 `bun <temp-file>` 执行脚本
+  5. Bun 自动处理依赖和 TypeScript 转译
+  6. 临时文件由系统自动清理
+
+#### Scenario: 文档包含场景选择决策树
+- **WHEN** 大模型阅读 SKILL.md
+- **THEN** 文档提供清晰的执行流程决策树：
+  1. 首先执行 `bun --version` 检查环境
+     - 失败 → 输出错误信息并停止
+     - 成功 → 进入下一步
+  2. 用户是否提供了已存在的脚本文件路径？
+     - 是 → 场景1：直接执行
+     - 否 → 进入下一步
+  3. 用户是否指定了脚本的生成路径？
+     - 是 → 场景2：在指定路径创建脚本，然后执行
+     - 否 → 场景3：使用临时路径（默认）
+
+#### Scenario: 文档中的示例代码（三种场景）
+- **WHEN** 大模型阅读 SKILL.md
+- **THEN** 文档提供完整的示例代码，展示：
+  - 场景1示例：直接执行已存在的脚本文件
+  - 场景2示例：在指定路径创建脚本并执行
+  - 场景3示例：使用临时路径执行脚本（包含如何调用辅助脚本生成临时文件路径）
+  - 如何检查 Bun 安装（`bun --version`）
+  - 如何处理输出和错误
+
+#### Scenario: 快速参考部分
+- **WHEN** 大模型阅读 SKILL.md
+- **THEN** 文档顶部包含快速参考部分
+- **THEN** 快速参考简洁地总结三种使用场景的关键命令
+- **THEN** 快速参考帮助大模型快速选择正确的执行方式

openspec/changes/archive/2026-02-06-lyxy-runner-js-custom-path/tasks.md

@@ -0,0 +1,46 @@
+## 1. 文档准备工作
+
+- [x] 1.1 读取当前的 `skills/lyxy-runner-js/SKILL.md` 文件，了解现有结构
+- [x] 1.2 确认文档中现有的安装说明和基本使用流程
+
+## 2. 文档结构调整
+
+- [x] 2.1 在 SKILL.md 顶部添加"快速参考"部分，总结三种使用场景
+- [x] 2.2 在"使用流程"章节添加场景选择决策树
+- [x] 2.3 将原有的"完整示例"重新组织为场景3的示例（临时路径）
+
+## 3. 场景1：执行已存在的脚本文件
+
+- [x] 3.1 添加场景1的使用说明章节
+- [x] 3.2 编写场景1的完整示例代码（包含 `bun --version` 检查）
+- [x] 3.3 说明场景1不调用 `get_temp_path.js`
+- [x] 3.4 说明场景1不创建新文件
+
+## 4. 场景2：在指定路径创建并执行脚本
+
+- [x] 4.1 添加场景2的使用说明章节
+- [x] 4.2 编写场景2的完整示例代码（包含 `bun --version` 检查和 Write 工具使用）
+- [x] 4.3 说明场景2使用大模型的 Write 工具创建文件
+- [x] 4.4 说明场景2脚本持久化到指定位置
+
+## 5. 环境检查和错误处理
+
+- [x] 5.1 在所有场景的示例中确保第一步都是 `bun --version` 检查
+- [x] 5.2 添加环境检查失败的错误处理说明
+- [x] 5.3 明确说明当 Bun 未安装时的错误提示内容（包含安装命令）
+- [x] 5.4 添加禁止条款：禁止使用 nodejs/npm/yarn/pnpm 等其他工具
+- [x] 5.5 添加禁止条款：禁止建议用户转换为其他运行时格式
+
+## 6. 文档验证
+
+- [x] 6.1 验证决策树的逻辑正确性
+- [x] 6.2 验证所有三个场景的示例代码完整且可执行
+- [x] 6.3 验证快速参考部分简洁明了
+- [x] 6.4 验证文档保持向后兼容（原有临时路径流程仍然可用）
+
+## 7. 最终检查
+
+- [x] 7.1 检查文档格式和排版
+- [x] 7.2 确认所有章节的标题层级正确
+- [x] 7.3 确认文档使用中文面向中文开发者
+- [x] 7.4 验证 frontmatter 保持完整

openspec/changes/archive/2026-02-06-optimize-lyxy-runner-python-uv-syntax/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-06

openspec/changes/archive/2026-02-06-optimize-lyxy-runner-python-uv-syntax/design.md

@@ -0,0 +1,254 @@
+## Context
+
+当前lyxy-runner-python skill要求用户在Python脚本顶部添加PEP 723元数据块来声明依赖，这需要修改用户现有的脚本文件，降低了使用便利性。此外，现有实现总是使用临时文件，即使在用户明确指定路径时也是如此。
+
+该skill目前的工作流程：
+1. 要求LLM生成包含PEP 723元数据的Python脚本
+2. 使用辅助脚本创建临时文件
+3. 写入脚本内容（包含元数据块）
+4. 使用`uv run <temp_file_path>`执行
+
+现有实现的限制：
+- 用户必须修改现有脚本以添加PEP 723元数据
+- 总是使用临时文件，即使用户指定了存储路径
+- 无法智能识别uv项目，每次都创建新的虚拟环境
+
+## Goals / Non-Goals
+
+**Goals:**
+- 无需修改用户现有Python脚本即可使用uv执行
+- 自动解析脚本依赖并使用`--with`语法传递
+- 智能检测uv项目，复用项目虚拟环境
+- 尊重用户指定的脚本路径，仅在未指定时使用临时文件
+- 保持跨平台兼容性（Windows/macOS/Linux）
+- 保持严格错误处理和调试支持
+
+**Non-Goals:**
+- 不修改用户现有的脚本文件
+- 不实现复杂版本约束或依赖冲突解决（交给uv）
+- 不支持命令行参数或stdin输入（保持现有限制）
+- 不持久化虚拟环境（每次执行都是新的）
+
+## Decisions
+
+### 决策1：项目检测方法
+
+**选择：** 使用`uv sync --dry-run`命令检测当前目录是否为uv项目
+
+**原因：**
+- `uv sync --dry-run`是uv提供的官方方法，能准确判断目录是否为有效的uv项目
+- 不仅检查pyproject.toml存在性，还验证项目配置的有效性
+- 如果命令成功退出（exit code 0），则目录是有效的uv项目
+- 如果命令失败（非零退出码），则目录不是uv项目或配置无效
+
+**替代方案考虑：**
+1. 仅检查pyproject.toml文件存在
+   - 优点：简单快速
+   - 缺点：无法验证文件有效性，可能误判
+   - **拒绝理由**：不够可靠，可能导致误判
+
+2. 检查.venv目录存在
+   - 优点：可以检测已初始化的虚拟环境
+   - 缺点：uv项目可能尚未运行过sync，没有.venv目录
+   - **拒绝理由**：对未初始化的uv项目不友好
+
+**实现细节：**
+```bash
+# 检测当前目录是否为uv项目
+if uv sync --dry-run > /dev/null 2>&1; then
+  # 是uv项目，使用项目环境
+  uv run <script_path>
+else
+  # 不是uv项目，使用--with语法
+  uv run --with package1 --with package2 <script_path>
+fi
+```
+
+### 决策2：依赖解析策略
+
+**选择：** 使用大模型的分析能力直接从脚本内容提取import语句，而非使用外部工具
+
+**原因：**
+- 大模型已经理解脚本内容，可以直接提取import语句
+- 避免引入新的依赖（如ast模块解析工具）
+- 大模型可以理解各种import语法变体（import x, from x import y, import x as z等）
+- 可以排除Python标准库模块，只需检查是否为常见标准库名称
+
+**实现细节：**
+1. 大模型分析脚本中的所有import语句
+2. 提取包名（import pandas → pandas, from numpy import array → numpy）
+3. 排除已知的标准库名称（os, sys, json, pathlib, re等）
+4. 去重后生成依赖列表
+
+**限制：**
+- 大模型需要维护标准库列表（可基于Python 3.10+标准库）
+- 对于动态导入（__import__）和条件导入，可能无法识别
+- 不支持解析requirements.txt或其他依赖文件（只解析脚本内容）
+
+### 决策3：路径处理策略
+
+**选择：** 三层路径处理逻辑（用户指定 → 现有脚本 → 临时文件）
+
+**原因：**
+- 优先尊重用户明确指定的路径
+- 对现有脚本直接执行，无需修改
+- 仅在大模型自主生成且未指定路径时使用临时文件
+
+**决策树：**
+
+```
+用户是否指定脚本存储路径？
+├─ 是：写入用户指定路径 → 执行
+└─ 否：
+    ├─ 用户是否指定现有脚本路径？
+    │   ├─ 是：直接执行该脚本
+    │   └─ 否：创建临时文件 → 执行
+```
+
+**实现细节：**
+- 用户指定路径示例："在scripts/data.py中写入" → 写入`scripts/data.py`
+- 用户指定现有脚本："运行analyze.py" → 执行`analyze.py`（读取内容解析依赖）
+- 大模型自主生成：使用`get_temp_path.py`辅助脚本创建临时文件
+
+### 决策4：执行命令构造
+
+**选择：** 根据项目检测和依赖解析结果动态构造`uv run`命令
+
+**命令模式：**
+
+| 场景 | 命令格式 |
+|------|----------|
+| uv项目内脚本 | `uv run <script_path>` |
+| 非uv项目，有依赖 | `uv run --with pkg1 --with pkg2 <script_path>` |
+| 非uv项目，无依赖 | `uv run <script_path>` |
+
+**原因：**
+- uv项目：依赖已在pyproject.toml中管理，不需要`--with`
+- 非uv项目：使用`--with`逐个指定依赖，uv自动处理隔离环境
+- 无依赖：不需要`--with`，使用标准库环境
+
+### 决策5：不使用辅助脚本进行项目检测
+
+**选择：** 直接使用大模型的命令行工具执行`uv sync --dry-run`进行项目检测
+
+**原因：**
+- 大模型可以直接执行bash命令，无需额外的辅助脚本
+- 简化实现，减少维护成本
+- 避免辅助脚本的版本管理问题
+
+**实现细节：**
+```bash
+# 使用大模型的命令行工具执行项目检测
+uv sync --dry-run
+```
+
+- 如果命令返回exit code 0，则当前目录是有效的uv项目
+- 如果命令返回非零退出码，则当前目录不是uv项目
+- 检测结果直接由大模型判断，无需解析辅助脚本输出
+
+## Risks / Trade-offs
+
+### 风险1：uv项目检测失败
+
+**描述：** `uv sync --dry-run`在某些情况下可能误判（如网络问题、依赖解析错误）
+
+**缓解措施：**
+- 检测失败时回退到非uv项目模式（使用`--with`语法）
+- 记录检测失败日志，但不阻塞脚本执行
+- 用户可以手动指定使用项目环境（通过注释或显式指令）
+
+### 风险2：依赖解析不完整
+
+**描述：** 大模型可能遗漏某些import语句或误判标准库模块
+
+**缓解措施：**
+- 在SKILL.md中提供常见标准库列表供参考
+- 当脚本执行失败时，检查是否为缺失依赖，提示用户
+- 允许用户手动指定依赖（通过参数或注释）
+
+### 风险3：路径冲突和权限问题
+
+**描述：** 用户指定的路径可能不存在、无写入权限或与现有文件冲突
+
+**缓解措施：**
+- 写入前检查目录是否存在，不存在则创建（如果允许）
+- 写入前检查文件权限，失败时提示用户
+- 支持覆盖提示（如果文件已存在）
+
+### 风险4：跨平台路径处理复杂
+
+**描述：** Windows和Unix系统的路径分隔符、路径长度限制不同
+
+**缓解措施：**
+- 使用Python的`pathlib`或`os.path`处理路径，而非字符串拼接
+- 保持辅助脚本使用标准库路径处理函数
+- 测试覆盖Windows、macOS、Linux三个平台
+
+### 权衡1：自动依赖解析 vs 用户显式声明
+
+**当前选择：** 自动解析import语句
+
+**权衡：**
+- 优点：用户无需手动声明依赖，开箱即用
+- 缺点：可能遗漏某些隐式依赖（如动态导入）
+
+**缓解：** 支持用户通过参数或注释显式指定依赖
+
+### 权衡2：项目检测成本 vs 准确性
+
+**当前选择：** 使用`uv sync --dry-run`（准确但较慢）
+
+**权衡：**
+- 优点：准确判断uv项目，避免误判
+- 缺点：每次执行都需要运行检测命令（约几百毫秒）
+
+**缓解：** 可以考虑缓存检测结果（在同一工作目录内）
+
+## Migration Plan
+
+### 步骤1：更新SKILL.md文档
+
+1. 移除PEP 723相关内容
+2. 添加依赖解析指导
+3. 添加项目检测流程
+4. 更新路径处理说明
+5. 更新执行命令示例
+6. 保持错误处理和调试支持部分
+
+### 步骤2：更新工作流示例
+
+在SKILL.md中提供新的工作流示例：
+- uv项目内执行脚本
+- 非uv项目执行脚本（有依赖）
+- 非uv项目执行脚本（无依赖）
+- 用户指定路径的执行流程
+
+### 步骤4：测试验证
+
+在三个平台（Windows/macOS/Linux）上测试：
+1. uv项目检测
+2. 依赖解析准确性
+3. 路径处理（临时/指定/现有）
+4. 跨平台兼容性
+5. 错误处理
+
+### 回滚策略
+
+如果新实现存在问题，可以直接回退到旧版SKILL.md内容（从git历史恢复）。
+
+## Open Questions
+
+1. **依赖解析准确性：** 是否需要维护一个更完整的Python标准库模块列表，以减少误判？
+   - 建议：基于Python 3.10+标准库文档维护列表
+
+2. **项目检测缓存：** 是否需要在同一工作目录内缓存项目检测结果，避免重复运行`uv sync --dry-run`？
+   - 建议：初期不实现，观察性能影响后再决定
+
+3. **隐式依赖处理：** 如何处理通过`__import__()`或动态加载的隐式依赖？
+   - 建议：暂不支持，在SKILL.md中说明限制
+
+4. **用户干预机制：** 是否提供机制让用户在脚本中显式声明额外依赖（如通过特殊注释）？
+   - 建议：初期不实现，通过错误提示引导用户
+
+5. **Windows路径长度限制：** Windows路径最大260字符限制如何处理？
+   - 建议：使用长路径前缀（\\?\）或尽量使用相对路径

openspec/changes/archive/2026-02-06-optimize-lyxy-runner-python-uv-syntax/proposal.md

@@ -0,0 +1,41 @@
+## Why
+
+当前lyxy-runner-python skill要求使用PEP 723规范在脚本顶部添加内联元数据块来声明依赖，这需要修改用户现有的Python脚本，降低了使用便利性。通过改用`uv run --with`语法并自动解析脚本内容中的依赖，可以在不改动用户脚本的情况下利用uv的隔离环境直接运行脚本，提升用户体验和灵活性。
+
+## What Changes
+
+- **BREAKING**: 移除对PEP 723规范的依赖，不再要求脚本顶部包含`# /// script`元数据块
+- **BREAKING**: 不再保持对包含PEP 723元数据的旧脚本的兼容性
+- 新增依赖解析功能：通过分析脚本内容自动识别所需的Python包
+- 新增智能执行逻辑：
+  - 使用`uv sync --dry-run`检测当前目录是否为uv项目
+  - 如果是uv项目，直接使用`uv run script.py`执行
+  - 如果不是uv项目，使用`uv run --with package1 --with package2 script.py`执行
+- 新增路径处理逻辑：
+  - 当用户指定脚本存储路径时，将脚本写入指定目录
+  - 仅在用户未指定路径或由大模型自主生成脚本时，才使用临时脚本
+- 更新执行命令模式，统一使用`--with`语法传递依赖
+- 简化实现：直接使用大模型命令行工具执行项目检测，无需新增辅助脚本
+
+## Capabilities
+
+### New Capabilities
+- `uv-run-with-syntax`: 使用`uv run --with`语法执行Python脚本的能力，包括自动依赖解析和智能项目检测
+
+### Modified Capabilities
+- `uv-lyxy-runner-python`: 现有spec需要更新以反映新的执行流程，包括：移除PEP 723要求、新增依赖解析逻辑、新增智能路径和项目检测
+
+## Impact
+
+- **代码影响**：
+  - 修改`skills/lyxy-runner-python/SKILL.md`，更新执行工作流和示例
+  - 保留现有的`get_temp_path.py`辅助脚本
+  - 不新增辅助脚本，项目检测直接使用命令行工具
+- **行为影响**：
+  - 不再支持PEP 723元数据格式
+  - 新版工作流可以不经修改直接运行用户现有的Python脚本
+  - 改进了与现有uv项目的集成体验
+- **依赖影响**：无新增依赖，继续使用uv作为核心依赖
+- **兼容性**：
+  - 保持跨平台兼容性（Windows/macOS/Linux）
+  - 不保持对旧版PEP 723格式的兼容性（BREAKING CHANGE）

openspec/changes/archive/2026-02-06-optimize-lyxy-runner-python-uv-syntax/specs/uv-python-runner/spec.md

@@ -0,0 +1,113 @@
+# UV Python Runner Spec (Delta)
+
+## Purpose
+
+This is a delta spec documenting changes to the existing uv-lyxy-runner-python capability to support `uv run --with` syntax and smart project detection.
+
+## REMOVED Requirements
+
+### 需求：生成符合PEP 723规范的Python脚本
+
+**Reason**: 已迁移至使用`uv run --with`语法和自动依赖解析，不再需要PEP 723内联元数据。用户可以直接运行标准Python脚本，无需修改脚本内容。
+
+**Migration**: 现有包含PEP 723元数据的脚本仍可正常运行，但不再要求使用该格式。新的工作流使用自动依赖解析和`--with`语法。
+
+## MODIFIED Requirements
+
+### 需求：在隔离的uv环境中执行脚本
+
+Skill SHALL指导LLM使用`uv run`命令执行Python脚本，并根据脚本位置和项目类型选择执行策略。Skill SHALL支持临时文件和用户指定路径两种模式。Skill SHALL使用`--with`语法传递依赖或利用项目现有依赖配置。
+
+#### 场景：成功执行独立脚本（无uv项目）
+- **WHEN** LLM生成有效的Python脚本且当前目录不是uv项目
+- **THEN** skill SHALL解析脚本内容获取依赖列表
+- **THEN** skill SHALL在用户指定路径或临时目录创建/使用脚本文件
+- **THEN** skill SHALL使用`uv run --with package1 --with package2 <script_path>`执行脚本
+- **THEN** uv SHALL自动创建隔离的虚拟环境，安装依赖，并执行脚本
+- **THEN** skill SHALL捕获并返回stdout/stderr输出
+
+#### 场景：成功执行uv项目内的脚本
+- **WHEN** LLM执行位于uv项目内的脚本（存在pyproject.toml）
+- **THEN** skill SHALL识别为uv项目
+- **THEN** skill SHALL使用`uv run <script_path>`执行脚本（相对路径）
+- **THEN** uv SHALL使用项目的虚拟环境和依赖配置
+- **THEN** skill SHALL捕获并返回stdout/stderr输出
+
+#### 场景：脚本执行失败
+- **WHEN** 脚本执行失败（运行时错误、依赖解析失败等）
+- **THEN** skill SHALL保留脚本文件用于调试（临时或指定路径）
+- **THEN** skill SHALL显示包含traceback的完整错误消息
+- **THEN** skill SHALL显示脚本文件路径
+- **THEN** skill SHALL停止任务（严格错误处理模式）
+
+### 需求：跨平台路径支持
+
+Skill SHALL支持Windows、macOS、Linux三个平台的路径处理，包括临时文件和用户指定路径。Skill SHALL在需要时使用辅助脚本获取平台特定的临时目录。
+
+#### 场景：创建临时脚本文件
+- **WHEN** LLM需要创建临时Python脚本且用户未指定路径
+- **THEN** skill SHALL指导LLM调用辅助脚本获取临时目录
+- **THEN** skill SHALL在临时目录创建唯一的Python文件
+- **THEN** 辅助脚本SHALL使用`tempfile.gettempdir()`自动返回平台特定的路径
+
+#### 场景：使用用户指定路径
+- **WHEN** 用户明确指定脚本存储或执行路径
+- **THEN** skill SHALL使用用户指定的完整路径或相对路径
+- **THEN** skill SHALL不创建临时文件
+- **THEN** skill SHALL确保路径在不同平台（Windows/macOS/Linux）上的有效性
+
+#### 场景：Windows平台路径处理
+- **WHEN** 在Windows平台创建或执行脚本
+- **THEN** skill SHALL正确处理Windows路径分隔符（`\`）
+- **THEN** 辅助脚本SHALL返回Windows临时目录（例如：`C:\Users\<username>\AppData\Local\Temp`）
+- **THEN** skill SHALL确保大模型不需要硬编码Windows路径
+
+#### 场景：macOS/Linux平台路径处理
+- **WHEN** 在macOS或Linux平台创建或执行脚本
+- **THEN** skill SHALL正确处理Unix路径分隔符（`/`）
+- **THEN** 辅助脚本SHALL返回`/tmp`路径
+- **THEN** skill SHALL确保大模型不需要硬编码Unix路径
+
+## ADDED Requirements
+
+### 需求：自动依赖解析
+
+Skill SHALL自动分析Python脚本内容以识别所需的Python包，排除Python标准库模块。
+
+#### 场景：解析import语句提取依赖
+- **WHEN** Skill分析Python脚本的import语句
+- **THEN** Skill SHALL提取外部包名
+- **THEN** Skill SHALL排除Python标准库模块
+- **THEN** Skill SHALL生成用于`--with`参数的依赖列表
+
+### 需求：智能项目检测
+
+Skill SHALL检测当前工作目录是否为uv项目（存在pyproject.toml），并据此选择执行策略。
+
+#### 场景：检测到uv项目
+- **WHEN** 当前工作目录包含`pyproject.toml`文件
+- **THEN** Skill SHALL使用项目依赖配置执行脚本
+- **THEN** Skill SHALL不添加`--with`参数
+
+#### 场景：非uv项目环境
+- **WHEN** 当前工作目录不包含`pyproject.toml`文件
+- **THEN** Skill SHALL使用`--with`语法传递解析的依赖
+
+### 需求：灵活脚本路径处理
+
+Skill SHALL支持用户指定脚本路径、现有脚本文件和临时脚本三种模式。
+
+#### 场景：用户指定脚本存储路径
+- **WHEN** 用户明确指定脚本存储路径
+- **THEN** Skill SHALL将脚本写入用户指定的路径
+- **THEN** Skill SHALL不使用临时文件
+
+#### 场景：用户指定现有脚本路径
+- **WHEN** 用户指定要运行的现有Python脚本
+- **THEN** Skill SHALL直接在指定路径执行
+- **THEN** Skill SHALL不修改用户脚本内容
+
+#### 场景：自主生成脚本且未指定路径
+- **WHEN** 大模型自主生成脚本且用户未指定存储路径
+- **THEN** Skill SHALL使用临时文件路径
+- **THEN** Skill SHALL允许系统自动清理临时文件

openspec/changes/archive/2026-02-06-optimize-lyxy-runner-python-uv-syntax/specs/uv-run-with-syntax/spec.md

@@ -0,0 +1,111 @@
+# UV Run With Syntax Spec
+
+## Purpose
+
+Define requirements for using `uv run --with` syntax to execute Python scripts with automatic dependency parsing, smart project detection, and flexible path handling.
+
+## Requirements
+
+### 需求：自动解析脚本依赖
+
+Skill SHALL自动分析Python脚本内容以识别所需的Python包。Skill SHALL解析import语句并提取外部包名，排除Python标准库模块。
+
+#### 场景：解析包含外部依赖的脚本
+- **WHEN** Skill分析包含import语句的Python脚本（例如：`import pandas as pd`）
+- **THEN** Skill SHALL提取包名（pandas）
+- **THEN** Skill SHALL排除Python标准库模块（os、sys、json等）
+- **THEN** Skill SHALL生成依赖列表，用于`--with`参数
+
+#### 场景：解析多个import来源
+- **WHEN** 脚本包含多种import语句（`import pandas`, `from numpy import array`, `import requests as req`）
+- **THEN** Skill SHALL正确提取所有外部包名（pandas, numpy, requests）
+- **THEN** Skill SHALL处理`import ... as`和`from ... import`语法
+- **THEN** Skill SHALL去重依赖列表
+
+#### 场景：仅使用标准库的脚本
+- **WHEN** 脚本只使用Python标准库（os、sys、json、pathlib等）
+- **THEN** Skill SHALL生成空的依赖列表
+- **THEN** Skill SHALL不添加任何`--with`参数到执行命令中
+
+### 需求：智能项目检测
+
+Skill SHALL检测当前工作目录是否为uv项目，并据此选择执行策略。
+
+#### 场景：检测到uv项目
+- **WHEN** 当前工作目录包含`pyproject.toml`文件
+- **THEN** Skill SHALL识别为uv项目
+- **THEN** Skill SHALL对当前目录下的脚本使用`uv run script.py`直接执行
+- **THEN** Skill SHALL不添加`--with`参数（依赖由项目pyproject.toml管理）
+
+#### 场景：非uv项目环境
+- **WHEN** 当前工作目录不包含`pyproject.toml`文件
+- **THEN** Skill SHALL识别为非uv项目
+- **THEN** Skill SHALL对脚本使用`uv run --with package1 --with package2 script.py`执行
+- **THEN** Skill SHALL根据解析的依赖列表动态构建`--with`参数
+
+#### 场景：脚本位于工作目录外
+- **WHEN** 用户指定的脚本路径不在当前工作目录下
+- **THEN** Skill SHALL按独立脚本处理
+- **THEN** Skill SHALL使用`uv run --with package1 --with package2 <script_path>`执行
+- **THEN** Skill SHALL解析脚本内容以获取依赖列表
+
+### 需求：灵活路径处理
+
+Skill SHALL根据用户指定和上下文灵活处理脚本路径，支持用户指定路径、现有脚本文件和临时脚本。
+
+#### 场景：用户指定脚本存储路径
+- **WHEN** 用户明确指定脚本存储路径（例如："在scripts/data_processing.py中写入脚本"）
+- **THEN** Skill SHALL将脚本内容写入用户指定的路径
+- **THEN** Skill SHALL不使用临时文件
+- **THEN** Skill SHALL在指定路径执行脚本
+
+#### 场景：用户指定现有脚本路径
+- **WHEN** 用户指定要运行的现有Python脚本（例如："运行scripts/my_script.py"）
+- **THEN** Skill SHALL读取该脚本内容（如需解析依赖）
+- **THEN** Skill SHALL直接在指定路径执行脚本
+- **THEN** Skill SHALL不修改用户脚本内容
+
+#### 场景：大模型自主生成脚本且未指定路径
+- **WHEN** 大模型自主生成Python脚本且用户未指定存储路径
+- **THEN** Skill SHALL使用辅助脚本获取临时文件路径
+- **THEN** Skill SHALL将脚本内容写入临时文件
+- **THEN** Skill SHALL在临时路径执行脚本
+- **THEN** Skill SHALL允许系统自动清理临时文件
+
+### 需求：使用--with语法执行
+
+Skill SHALL使用`uv run --with`语法将依赖传递给uv，替代PEP 723内联元数据方式。
+
+#### 场景：有外部依赖的脚本执行
+- **WHEN** 脚本解析结果包含依赖列表[package1, package2]
+- **THEN** Skill SHALL构造命令：`uv run --with package1 --with package2 <script_path>`
+- **THEN** uv SHALL为每个`--with`指定的包创建隔离环境
+- **THEN** Skill SHALL捕获并返回脚本输出
+
+#### 场景：无外部依赖的脚本执行
+- **WHEN** 脚本解析结果为空依赖列表
+- **THEN** Skill SHALL构造命令：`uv run <script_path>`
+- **THEN** Skill SHALL不包含任何`--with`参数
+- **THEN** uv SHALL使用隔离的Python标准库环境执行
+
+#### 场景：uv项目内的脚本执行
+- **WHEN** 脚本位于检测到的uv项目内
+- **THEN** Skill SHALL构造命令：`uv run <script_path>`（相对路径）
+- **THEN** Skill SHALL不包含`--with`参数
+- **THEN** uv SHALL使用项目的虚拟环境和依赖配置
+
+### 需求：向后兼容性
+
+Skill SHALL保持对包含PEP 723元数据的旧脚本的兼容性，但不再要求使用该格式。
+
+#### 场景：执行包含PEP 723元数据的脚本
+- **WHEN** 用户提供的脚本顶部包含PEP 723元数据块
+- **THEN** Skill SHALL正常执行脚本（PEP 723元数据将被uv忽略）
+- **THEN** Skill SHALL仍使用`--with`语法传递解析出的依赖
+- **THEN** 脚本SHALL成功执行
+
+#### 场景：新工作流执行标准Python脚本
+- **WHEN** 用户提供的标准Python脚本无任何元数据
+- **THEN** Skill SHALL自动解析import语句
+- **THEN** Skill SHALL使用`--with`语法传递依赖
+- **THEN** 脚本SHALL在不修改的情况下成功执行

openspec/changes/archive/2026-02-06-optimize-lyxy-runner-python-uv-syntax/tasks.md

@@ -0,0 +1,93 @@
+## 1. 文档准备
+
+- [x] 1.1 备份现有 SKILL.md 文件为 SKILL.md.backup
+- [x] 1.2 阅读 lyxy-runner-python skill 文档结构，了解现有内容组织方式
+
+## 2. 移除PEP 723相关内容
+
+- [x] 2.1 移除"生成符合PEP 723规范的Python脚本"相关章节
+- [x] 2.2 移除所有PEP 723元数据块的示例代码
+- [x] 2.3 移除`# /// script`、`# dependencies = []`等PEP 723语法说明
+- [x] 2.4 更新Purpose部分，移除对PEP 723的提及
+
+## 3. 添加依赖解析指导
+
+- [x] 3.1 添加"自动解析脚本依赖"章节，说明如何从import语句提取依赖
+- [x] 3.2 添加常见Python标准库模块列表（os、sys、json、pathlib等）
+- [x] 3.3 添加依赖解析示例（pandas、numpy、requests等外部包）
+- [x] 3.4 说明去重逻辑和过滤标准库的规则
+
+## 4. 添加项目检测流程
+
+- [x] 4.1 添加"智能项目检测"章节，说明使用`uv sync --dry-run`检测uv项目
+- [x] 4.2 说明检测逻辑：exit code 0为uv项目，非零为非uv项目
+- [x] 4.3 添加项目检测失败的处理说明（回退到非uv项目模式）
+
+## 5. 更新路径处理说明
+
+- [x] 5.1 添加路径处理三层逻辑说明（用户指定 → 现有脚本 → 临时文件）
+- [x] 5.2 更新临时文件获取流程，保留`get_temp_path.py`辅助脚本的使用
+- [x] 5.3 添加用户指定路径的处理说明和示例
+- [x] 5.4 添加现有脚本直接执行的说明
+
+## 6. 更新执行命令示例
+
+- [x] 6.1 添加uv项目内执行命令示例：`uv run script.py`
+- [x] 6.2 添加非uv项目有依赖执行命令示例：`uv run --with pandas --with numpy script.py`
+- [x] 6.3 添加非uv项目无依赖执行命令示例：`uv run script.py`
+- [x] 6.4 移除所有使用PEP 723元数据的执行示例
+
+## 7. 更新工作流章节
+
+- [x] 7.1 重写工作流步骤，移除"步骤1：生成符合PEP 723的Python脚本"
+- [x] 7.2 新增"步骤1：解析脚本依赖"（读取或生成脚本后分析import语句）
+- [x] 7.3 新增"步骤2：检测是否为uv项目"（执行`uv sync --dry-run`）
+- [x] 7.4 更新"步骤3：根据用户需求确定脚本路径"
+- [x] 7.5 更新"步骤4：根据检测结果构造执行命令"
+- [x] 7.6 更新完整工作流示例，包含三种场景（uv项目、非uv项目有依赖、非uv项目无依赖）
+
+## 8. 更新错误处理章节
+
+- [x] 8.1 添加项目检测失败的场景和错误处理
+- [x] 8.2 添加依赖解析不准确导致执行失败的处理说明
+- [x] 8.3 更新现有错误处理场景，移除对PEP 723的引用
+- [x] 8.4 添加路径权限问题的错误处理
+
+## 9. 更新示例章节
+
+- [x] 9.1 重写"示例1：数据分析"，使用标准Python脚本（无PEP 723）
+- [x] 9.2 重写"示例2：API交互"，使用标准Python脚本（无PEP 723）
+- [x] 9.3 重写"示例3：文件操作"，使用标准Python脚本（无PEP 723）
+- [x] 9.4 新增"示例4：uv项目内执行"，展示在uv项目中的执行流程
+- [x] 9.5 新增"示例5：用户指定路径"，展示指定存储路径的执行流程
+
+## 10. 更新说明和最佳实践
+
+- [x] 10.1 更新"为什么使用uv？"表格，移除PEP 723相关说明
+- [x] 10.2 更新"最佳实践"部分，移除PEP 723相关内容
+- [x] 10.3 添加新的最佳实践：依赖解析的准确性注意事项
+- [x] 10.4 更新"限制"部分，移除PEP 723相关限制
+- [x] 10.5 添加新的限制说明：项目检测失败、动态导入等
+
+## 11. 更新Workflow Summary
+
+- [x] 11.1 重写完整工作流示例，反映新的执行流程
+- [x] 11.2 更新关键特点说明，移除PEP 723相关内容
+- [x] 11.3 添加项目检测和依赖解析的特点说明
+
+## 12. 验证和测试
+
+- [x] 12.1 在Windows平台测试uv项目检测
+- [x] 12.2 在macOS平台测试uv项目检测
+- [x] 12.3 在Linux平台测试uv项目检测
+- [x] 12.4 测试依赖解析准确性（包含标准库和外部包）
+- [x] 12.5 测试三种路径模式（用户指定、现有脚本、临时文件）
+- [x] 12.6 测试错误处理场景（uv未安装、语法错误、依赖失败等）
+- [x] 12.7 验证SKILL.md文档的完整性和一致性
+
+## 13. 清理和提交
+
+- [x] 13.1 删除备份文件 SKILL.md.backup（如果一切正常）
+- [x] 13.2 验证修改后的SKILL.md符合所有spec要求
+- [x] 13.3 确认辅助脚本 `get_temp_path.py` 仍然可用
+- [x] 13.4 确认无需新增辅助脚本（项目检测直接使用命令行工具）

openspec/changes/archive/2026-02-12-develop-lyxy-reader-docx-skill/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-12

openspec/changes/archive/2026-02-12-develop-lyxy-reader-docx-skill/design.md

@@ -0,0 +1,106 @@
+## Context
+
+当前项目是一个专门用于开发大模型工具 skill 的项目。`skills/lyxy-reader-docx` 目录已经存在，其中包含：
+- `scripts/docx_parser.py` - 完整的 DOCX 解析脚本，支持多策略解析（MarkItDown、python-docx、XML 原生）
+- `docx_parser.md` - 脚本使用文档
+
+需要将这些现有资源封装为一个标准的 skill，让大模型能够识别并优先使用该工具处理 .docx 文件。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 创建 `skills/lyxy-reader-docx/skill.md` skill 定义文件，符合项目规范
+- 封装 docx_parser.py 的核心功能为 skill 的能力描述
+- 确保大模型在遇到 .docx 文件时能够识别并优先使用该 skill
+- 执行时优先委托给 lyxy-runner-python skill，利用其依赖管理和环境隔离能力
+- 支持多种解析模式：全文提取、标题提取、章节内容提取、关键词搜索
+
+**Non-Goals:**
+- 修改现有的 docx_parser.py 脚本逻辑
+- 添加图片或格式提取功能
+- 实现 docx 文件的编辑或修改功能
+- 支持 .doc 或其他文档格式
+
+## Decisions
+
+### 1. Skill 定义结构
+**决策**: 采用标准的 skill.md 格式，包含 description、capabilities 等核心字段
+
+**理由**: 遵循项目现有 skill 的统一规范，便于大模型理解和调用。查看 `skills/` 目录下的其他 skill 示例（如 `lyxy-runner-python`、`lyxy-runner-js`）可知项目有一致的定义格式。
+
+### 2. 依赖声明
+**决策**: 在 skill.md 的 Compatibility 字段中声明 Python 运行时依赖
+
+**理由**: docx_parser.py 需要 Python 3.6+ 环境，并且需要至少安装 `markitdown` 或 `python-docx` 之一。明确这些依赖可以帮助大模型判断环境是否就绪。
+
+### 3. 能力映射
+**决策**: 将 docx_parser.py 的所有功能映射为 skill 的 capabilities
+
+**理由**: 脚本提供了丰富的功能（全文、字数、行数、标题、章节、搜索），全部暴露给大模型可以提供更灵活的使用方式。能力包括：
+- 全文转换为 Markdown
+- 获取文档元信息（字数、行数）
+- 标题列表提取
+- 指定章节内容提取
+- 正则表达式搜索
+
+### 4. 触发器设计
+**决策**: 设置明确的触发器（Trigger phrases），包括中文和英文
+
+**理由**: 用户可能使用中文或英文请求解析 docx 文档。触发器包括：
+- "读取 docx", "解析 docx", "打开 word 文档"（中文）
+- "read docx", "parse docx", "extract from word document"（英文）
+- 文件扩展名 `.docx` 出现时
+
+### 5. 执行委托策略
+**决策**: lyxy-reader-docx skill 执行时优先委托给 lyxy-runner-python skill
+
+**理由**: lyxy-runner-python skill 提供了统一的 Python 脚本执行环境，具有以下优势：
+- 使用 uv 管理依赖，自动安装 markitdown 或 python-docx
+- 环境隔离，不污染系统 Python
+- 跨平台兼容
+
+**执行策略**:
+此 skill 的执行决策由大模型在调用时判断，不在 skill 定义或脚本中实现检查逻辑。
+
+当大模型决定执行 docx_reader skill 时：
+- 如果环境中存在 lyxy-runner-python skill，优先使用 lyxy-runner-python 执行 docx_parser.py
+- 如果环境中不存在 lyxy-runner-python skill，直接使用 Python 执行 docx_parser.py
+
+**好处**:
+- 最大化复用现有 skill
+- 自动处理 Python 依赖管理（通过 lyxy-runner-python）
+- 提供更好的错误处理和用户体验
+
+## Risks / Trade-offs
+
+### 风险 1: lyxy-runner-python skill 不可用
+**风险**: 目标环境可能没有安装 lyxy-runner-python skill 或其依赖（uv 工具）
+
+**缓解措施**:
+- 大模型在执行时判断 lyxy-runner-python skill 是否存在
+- 如果 lyxy-runner-python 不可用，自动降级为直接使用 Python 执行脚本
+- 在 skill.md 中说明降级策略和直接执行的条件
+
+### 风险 2: 依赖库未安装（降级场景）
+**风险**: 当 lyxy-runner-python 不可用时，直接执行脚本可能遇到 `markitdown` 或 `python-docx` 未安装的情况
+
+**缓解措施**:
+- 在 skill.md 的 Compatibility 字段中明确列出可选依赖
+- 在降级场景中，脚本本身已实现多策略降级（MarkItDown → python-docx → XML 原生）
+- 提示用户安装 lyxy-runner-python 获得更好的体验
+
+### 风险 2: 大文件处理性能
+**风险**: 大型 .docx 文件解析可能耗时较长
+
+**缓解措施**:
+- 在能力描述中提示可以使用章节提取或关键词搜索来限制处理范围
+- docx_parser.py 已实现流式处理，内存占用相对较低
+
+### 权衡: 纯文本 vs 格式保留
+**权衡**: 选择只提取纯文本，不保留图片和复杂格式
+
+**理由**: 用户明确要求"只能将docx文档转换为文字"，且大模型主要关注文本内容。虽然脚本支持 Markdown 格式转换（表格、粗体、斜体等），但图片会被自动移除，符合需求。
+
+## Open Questions
+
+无重大未决问题。设计清晰明确，可以直接进入实现阶段。

openspec/changes/archive/2026-02-12-develop-lyxy-reader-docx-skill/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+大模型在处理 Word 文档时缺乏统一的解析工具，需要能够直接识别并解析 .docx 文件能力的 skill。现有的 docx_parser.py 脚本已经实现了完整的解析功能，将其封装为 skill 可以让大模型在遇到需要读取 docx 文档的场景时优先使用该工具。
+
+## What Changes
+
+- 新增 `lyxy-reader-docx` skill，封装现有的 `skills/lyxy-reader-docx/scripts/docx_parser.py` 脚本
+- 创建 skill 定义文件，支持将 .docx 文件转换为纯文本内容
+- skill 定位为 docx 文档解析的优先选择工具
+- 仅支持文本内容提取，不处理图片和格式信息
+
+## Capabilities
+
+### New Capabilities
+- `docx-text-extraction`: 将 DOCX 文档转换为 Markdown 格式文本的能力，支持全文提取、标题提取、章节内容提取和关键词搜索
+
+### Modified Capabilities
+- 无
+
+## Impact
+
+- 新增 `skills/lyxy-reader-docx/skill.md` - skill 定义文件
+- 依赖现有的 `skills/lyxy-reader-docx/scripts/docx_parser.py` 解析脚本
+- 新增 Python 依赖：`markitdown` 或 `python-docx`（至少需要安装其一）
+- 影响大模型的技能调用策略，在遇到 .docx 文件时会优先使用该 skill

openspec/changes/archive/2026-02-12-develop-lyxy-reader-docx-skill/specs/docx-text-extraction/spec.md

@@ -0,0 +1,132 @@
+## ADDED Requirements
+
+### Requirement: Delegate execution to lyxy-runner-python skill
+当大模型执行 lyxy-reader-docx skill 时，应优先使用 lyxy-runner-python skill 来运行 docx_parser.py 脚本。如果 lyxy-runner-python skill 不可用，则直接使用 Python 执行。
+
+#### Scenario: lyxy-runner-python available
+- **WHEN** 大模型环境中存在 lyxy-runner-python skill
+- **THEN** 大模型通过 lyxy-runner-python skill 执行 docx_parser.py
+- **AND** 利用 lyxy-runner-python 的自动依赖管理功能安装所需的 Python 包（markitdown 或 python-docx）
+
+#### Scenario: lyxy-runner-python unavailable
+- **WHEN** 大模型环境中不存在 lyxy-runner-python skill
+- **THEN** 大模型直接使用 Python 执行 docx_parser.py
+- **AND** 提示用户正在使用直接执行模式（未使用 lyxy-runner-python）
+- **AND** 依赖 docx_parser.py 内部的多策略解析降级机制
+
+### Requirement: Extract full text from DOCX file
+系统 SHALL 能够将 DOCX 文件完整解析为 Markdown 格式的文本内容，移除所有图片但保留文本格式（如标题、列表、粗体、斜体、表格）。
+
+#### Scenario: Successful full text extraction
+- **WHEN** 用户请求解析一个有效的 .docx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 所有文本内容被保留
+- **AND** 所有图片被移除
+- **AND** 表格、列表、粗体、斜体等格式被转换为 Markdown 语法
+- **AND** 连续的空行被合并为一个空行
+
+#### Scenario: Invalid DOCX file
+- **WHEN** 提供的文件不是有效的 DOCX 格式或已损坏
+- **THEN** 系统返回错误信息
+- **AND** 错误信息明确说明文件格式问题
+
+#### Scenario: Empty DOCX file
+- **WHEN** 提供的 DOCX 文件为空或无文本内容
+- **THEN** 系统返回空字符串或相应的提示信息
+
+### Requirement: Extract document metadata
+系统 SHALL 能够提供 DOCX 文档的元数据信息，包括字数和行数。
+
+#### Scenario: Get word count
+- **WHEN** 用户请求获取 DOCX 文档的字数
+- **THEN** 系统返回文档的总字数（数字）
+- **AND** 字数统计基于解析后的 Markdown 内容
+
+#### Scenario: Get line count
+- **WHEN** 用户请求获取 DOCX 文档的行数
+- **THEN** 系统返回文档的总行数（数字）
+- **AND** 行数统计基于解析后的 Markdown 内容
+
+### Requirement: Extract document titles
+系统 SHALL 能够提取 DOCX 文档中的所有标题（1-6级标题），并按原始层级关系返回。
+
+#### Scenario: Extract all titles
+- **WHEN** 用户请求提取 DOCX 文档的所有标题
+- **THEN** 系统返回所有 1-6 级标题
+- **AND** 每个标题以 Markdown 标题格式返回（如 `# 主标题`、`## 二级标题`）
+- **AND** 标题按文档中的原始顺序返回
+- **AND** 保留原始标题层级关系
+
+#### Scenario: Document with no titles
+- **WHEN** DOCX 文档中不包含任何标题
+- **THEN** 系统返回空列表或无标题提示
+
+### Requirement: Extract chapter content by title name
+系统 SHALL 能够根据标题名称提取指定章节的内容，包括完整的上级标题链和所有下级内容。
+
+#### Scenario: Extract single chapter content
+- **WHEN** 用户请求提取特定标题名称的章节内容
+- **THEN** 系统返回该章节的完整内容
+- **AND** 包含完整的上级标题链（如：主标题 -> 章标题 -> 小节）
+- **AND** 包含该标题下的所有下级内容
+- **AND** 返回内容使用 Markdown 格式
+
+#### Scenario: Extract multiple chapters with same name
+- **WHEN** 文档中存在多个同名标题且用户请求提取该标题内容
+- **THEN** 系统返回所有同名标题的章节内容
+- **AND** 每个章节都包含其完整的上级标题链
+- **AND** 各章节内容之间有明确的分隔
+
+#### Scenario: Title not found
+- **WHEN** 用户请求提取的标题名称在文档中不存在
+- **THEN** 系统返回未找到标题的错误信息
+
+### Requirement: Search document with regex
+系统 SHALL 能够使用正则表达式在 DOCX 文档中搜索关键词，并返回所有匹配结果及其上下文。
+
+#### Scenario: Basic keyword search
+- **WHEN** 用户使用关键词搜索 DOCX 文档
+- **THEN** 系统返回所有匹配的文本片段
+- **AND** 每个结果包含默认的上下文（前后各 2 行）
+- **AND** 各结果之间使用 `---` 分隔
+- **AND** 上下文行数不包含空行
+
+#### Scenario: Custom context lines
+- **WHEN** 用户指定上下文行数进行搜索
+- **THEN** 系统按指定行数返回上下文
+- **AND** 支持 0 行上下文（仅返回匹配行）
+- **AND** 上下文行数不包含空行
+
+#### Scenario: Regex pattern search
+- **WHEN** 用户使用正则表达式模式搜索
+- **THEN** 系统支持 Python 标准正则表达式语法
+- **AND** 正确处理特殊字符的转义
+- **AND** 返回所有匹配模式的文本片段
+
+#### Scenario: No matches found
+- **WHEN** 搜索关键词或模式在文档中无匹配
+- **THEN** 系统返回未找到匹配的提示信息
+
+#### Scenario: Invalid regex pattern
+- **WHEN** 用户提供的正则表达式格式无效
+- **THEN** 系统返回正则表达式无效的错误信息
+
+### Requirement: Multi-strategy parsing fallback
+系统 SHALL 按优先级尝试多种解析策略，确保最大的兼容性。
+
+#### Scenario: Prefer MarkItDown parser
+- **WHEN** 系统检测到 `markitdown` 库已安装
+- **THEN** 系统优先使用 MarkItDown 解析器解析 DOCX 文件
+
+#### Scenario: Fallback to python-docx
+- **WHEN** MarkItDown 解析失败或未安装，且 `python-docx` 库已安装
+- **THEN** 系统使用 python-docx 作为备选解析器
+
+#### Scenario: Fallback to XML parsing
+- **WHEN** MarkItDown 和 python-docx 均未安装或解析失败
+- **THEN** 系统使用 XML 原生解析作为最后备选方案
+
+#### Scenario: All parsers failed
+- **WHEN** 所有解析策略均失败
+- **THEN** 系统返回详细的失败信息
+- **AND** 列出每种解析策略的失败原因

openspec/changes/archive/2026-02-12-develop-lyxy-reader-docx-skill/tasks.md

@@ -0,0 +1,27 @@
+## 1. 准备工作
+
+- [x] 1.1 研究现有 skill 定义格式，查看 `skills/` 目录下的其他 skill 示例（如 `lyxy-runner-python`、`lyxy-runner-js`）了解标准结构
+- [x] 1.2 阅读 `skills/lyxy-reader-docx/docx_parser.md` 了解解析脚本的详细功能和使用方式
+
+## 2. 创建 skill 定义文件
+
+- [x] 2.1 创建 `skills/lyxy-reader-docx/skill.md` 文件
+- [x] 2.2 编写 skill 的 description 字段，描述该 skill 的用途和定位（优先解析 docx 文档）
+- [x] 2.3 编写 skill 的 capabilities 字段，列出所有支持的解析功能：
+  - 全文转换为 Markdown
+  - 获取文档元信息（字数、行数）
+  - 标题列表提取
+  - 指定章节内容提取
+  - 正则表达式搜索
+- [x] 2.4 编写 skill 的 Compatibility 字段，声明 Python 3.6+ 和依赖库要求（markitdown 或 python-docx 至少安装其一）
+- [x] 2.5 编写 skill 的 Triggers 字段，包含中文和英文触发短语：
+  - 中文："读取 docx", "解析 docx", "打开 word 文档"
+  - 英文："read docx", "parse docx", "extract from word document"
+  - 文件扩展名 ".docx"
+
+## 3. 验证和测试
+
+- [x] 3.1 验证 skill.md 文件格式是否符合项目规范
+- [x] 3.2 确认 skill.md 中的触发器能够正确识别 docx 解析需求
+- [x] 3.3 确认 skill.md 中的依赖说明清晰准确
+- [x] 3.4 确认 skill.md 的 capabilities 覆盖了 docx_parser.py 的所有功能

openspec/changes/archive/2026-02-17-create-lyxy-reader-office/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-17

openspec/changes/archive/2026-02-17-create-lyxy-reader-office/design.md

@@ -0,0 +1,76 @@
+## Context
+
+当前项目中存在 `lyxy-reader-docx` skill，仅支持 DOCX 格式的文档解析。`skills/lyxy-reader-office/scripts/` 目录下已完成全部解析脚本的开发（parser.py、common.py、docx_parser.py、pptx_parser.py、xlsx_parser.py、pdf_parser.py、README.md），支持 DOCX、PPTX、XLSX、PDF 四种格式。现在需要创建 `SKILL.md` 作为 skill 的入口文件，并清理被替代的旧 skill。
+
+已有资源：
+- `skills/lyxy-reader-docx/SKILL.md`：参考模板，已验证的 skill 结构
+- `skills/lyxy-runner-python/SKILL.md`：Python 执行 skill，与本 skill 协作
+- `skills/lyxy-reader-office/scripts/README.md`：完整的脚本使用文档
+- `document/specification.md`：skill 格式规范
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 创建 `skills/lyxy-reader-office/SKILL.md`，遵循 skill 格式规范
+- SKILL.md 的 description 能覆盖 .docx、.xlsx、.pptx、.pdf 四种文件扩展名关键词，确保大模型在发现阶段能正确匹配
+- 引导大模型优先使用该 skill 读取这四种格式的文件
+- 引导大模型阅读 `scripts/README.md` 获取详细的脚本使用说明
+- 引导大模型在 `lyxy-runner-python` skill 可用时必须使用该 skill 来运行 Python 脚本
+- 删除 `skills/lyxy-reader-docx` 目录
+
+**Non-Goals:**
+
+- 不修改已有的解析脚本代码
+- 不修改 `lyxy-runner-python` skill
+- 不新增任何解析功能
+- 不创建单独的文档说明文件（如旧 skill 的 `docx_parser.md`），详细用法通过引导阅读 README.md 解决
+
+## Decisions
+
+### 决策 1：SKILL.md 结构参考 lyxy-reader-docx 但大幅精简
+
+**选择**：SKILL.md 专注于发现（description）、激活引导（何时使用、触发条件）和执行入口（指向 README.md），不在 SKILL.md 中重复 README.md 的内容。
+
+**理由**：
+- 规范建议 SKILL.md 保持在 500 行以下
+- README.md 已包含完整的命令行用法、参数说明、安装指南、错误处理等
+- 重复内容会导致维护负担，且增加不必要的 token 消耗
+- 渐进式披露：SKILL.md 负责激活判断，README.md 负责执行细节
+
+**替代方案**：将 README.md 全部内容嵌入 SKILL.md — 拒绝，因为会超过 500 行限制且违反渐进式披露原则。
+
+### 决策 2：强制引导使用 lyxy-runner-python
+
+**选择**：在 SKILL.md 中明确要求大模型在 `lyxy-runner-python` skill 可用时**必须**使用该 skill 来运行 parser.py，不提供直接 Python 执行的选项。仅在 `lyxy-runner-python` 不可用时降级到直接 Python 执行。
+
+**理由**：
+- lyxy-runner-python 使用 uv 管理依赖，能自动安装解析器所需的第三方库
+- 环境隔离，不污染系统 Python
+- 与 lyxy-reader-docx 保持一致的执行策略
+
+**替代方案**：将 lyxy-runner-python 作为可选推荐 — 拒绝，因为用户明确要求"必须使用"。
+
+### 决策 3：通过引导阅读 README.md 提供详细用法
+
+**选择**：SKILL.md 中仅给出基本的执行命令格式和常见示例，详细的参数说明、依赖安装、解析器对比等内容通过引导大模型阅读 `scripts/README.md` 获取。
+
+**理由**：
+- 符合渐进式披露原则：SKILL.md 是指令层，README.md 是资源层
+- README.md 已有完整且结构化的文档，无需重复
+- 减少 SKILL.md 的体积，提高激活阶段的效率
+
+### 决策 4：删除 lyxy-reader-docx 而非保留兼容
+
+**选择**：直接删除整个 `skills/lyxy-reader-docx/` 目录。
+
+**理由**：
+- lyxy-reader-office 完全覆盖了 lyxy-reader-docx 的功能
+- 保留旧 skill 会导致两个 skill 争抢 .docx 文件的处理权，造成歧义
+- 用户明确要求删除
+
+## Risks / Trade-offs
+
+- **[旧 skill 引用残留]** → 检查项目中是否有其他地方引用了 `lyxy-reader-docx`（如 .claude/settings 中的 skill 配置），删除时需同步清理
+- **[description 覆盖度]** → description 需要包含 docx、xlsx、pptx、pdf 等关键词，确保大模型在发现阶段能匹配到四种文件类型。但 description 有 1024 字符限制，需要精简表达
+- **[SKILL.md 体积控制]** → 需在"提供足够的执行引导"和"保持 500 行以内"之间平衡。通过引导阅读 README.md 解决详细信息的需求

openspec/changes/archive/2026-02-17-create-lyxy-reader-office/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+当前项目中仅有 `lyxy-reader-docx` skill 用于解析 DOCX 文档，无法覆盖 XLSX、PPTX、PDF 等常见办公文档格式。用户在日常工作中经常需要大模型读取多种格式的文档，缺少统一的多格式文档解析能力会导致大模型无法有效处理这些文件。需要创建一个统一的办公文档解析 skill，覆盖四种主流格式，并替换功能已被覆盖的旧 skill。
+
+## What Changes
+
+- 新增 `lyxy-reader-office` skill，支持解析 DOCX、XLSX、PPTX、PDF 四种格式
+- 该 skill 使用 `scripts/parser.py` 作为统一入口，自动识别文件类型并分派到对应的格式解析器
+- 引导大模型在遇到这四种文件时优先激活并使用该 skill
+- 引导大模型通过阅读 `scripts/README.md` 了解脚本的详细使用方式
+- 引导大模型在环境中存在 `lyxy-runner-python` skill 时，必须使用该 skill 来运行 Python 脚本
+- **BREAKING**：删除 `skills/lyxy-reader-docx` 目录，因为其功能已完全被 `lyxy-reader-office` 覆盖
+
+## Capabilities
+
+### New Capabilities
+
+- `office-document-parsing`: 统一的办公文档解析能力，覆盖 DOCX、XLSX、PPTX、PDF 四种格式，支持全文提取、标题提取、章节提取、正则搜索、字数统计、行数统计等功能，PDF 额外支持 OCR 高精度模式
+
+### Modified Capabilities
+
+- `docx-text-extraction`: 该能力将被 `office-document-parsing` 完全替代，原 spec 不再适用
+
+## Impact
+
+- **新增文件**：`skills/lyxy-reader-office/SKILL.md`（skill 主文件）
+- **脚本文件**：`skills/lyxy-reader-office/scripts/` 下的所有解析脚本已就绪（parser.py、common.py、docx_parser.py、pptx_parser.py、xlsx_parser.py、pdf_parser.py、README.md）
+- **删除目录**：`skills/lyxy-reader-docx/`（整个目录，包含 SKILL.md、docx_parser.md、scripts/docx_parser.py）
+- **依赖关系**：运行时依赖 Python 3.6+，推荐通过 `lyxy-runner-python` skill 使用 `uv` 自动管理依赖
+- **Spec 变更**：`docx-text-extraction` spec 将被废弃，新增 `office-document-parsing` spec

openspec/changes/archive/2026-02-17-create-lyxy-reader-office/specs/docx-text-extraction/spec.md

@@ -0,0 +1,29 @@
+## REMOVED Requirements
+
+### Requirement: Delegate execution to lyxy-runner-python skill
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「必须通过 lyxy-runner-python 执行脚本」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 替代 lyxy-reader-docx skill
+
+### Requirement: Extract full text from DOCX file
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「支持多格式文档解析」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 parser.py 解析 DOCX 文件
+
+### Requirement: Extract document metadata
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-c` 和 `-l` 参数
+
+### Requirement: Extract document titles
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-t` 参数
+
+### Requirement: Extract chapter content by title name
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-tc` 参数
+
+### Requirement: Search document with regex
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-s` 参数
+
+### Requirement: Multi-strategy parsing fallback
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「多策略解析降级」需求完全替代，且新版本支持更多格式和更多解析策略
+**Migration**: 使用 lyxy-reader-office skill，支持 DOCX/PPTX/XLSX/PDF 四种格式的多策略降级

openspec/changes/archive/2026-02-17-create-lyxy-reader-office/specs/office-document-parsing/spec.md

@@ -0,0 +1,115 @@
+## ADDED Requirements
+
+### Requirement: 优先使用 lyxy-reader-office 解析办公文档
+大模型在遇到 .docx、.xlsx、.pptx、.pdf 文件时，SHALL 优先激活并使用 lyxy-reader-office skill 来读取文件内容。
+
+#### Scenario: 用户请求读取支持的文件格式
+- **WHEN** 用户请求读取或解析 .docx、.xlsx、.pptx 或 .pdf 文件
+- **THEN** 大模型 SHALL 激活 lyxy-reader-office skill
+- **AND** 使用 skill 目录下的 `scripts/parser.py` 执行解析
+
+#### Scenario: 文件扩展名自动识别
+- **WHEN** 用户提供的文件路径以 .docx、.xlsx、.pptx 或 .pdf 结尾
+- **THEN** 大模型 SHALL 自动识别为 lyxy-reader-office skill 的处理范围
+- **AND** 无需用户显式指定使用哪个 skill
+
+### Requirement: 必须通过 lyxy-runner-python 执行脚本
+当环境中存在 lyxy-runner-python skill 时，大模型 SHALL 必须使用该 skill 来运行 parser.py 脚本。
+
+#### Scenario: lyxy-runner-python 可用
+- **WHEN** 大模型环境中存在 lyxy-runner-python skill
+- **THEN** 大模型 SHALL 通过 lyxy-runner-python skill 执行 parser.py
+- **AND** 利用 lyxy-runner-python 的自动依赖管理功能（uv）安装所需的 Python 包
+
+#### Scenario: lyxy-runner-python 不可用
+- **WHEN** 大模型环境中不存在 lyxy-runner-python skill
+- **THEN** 大模型 SHALL 降级到直接使用 Python 执行 parser.py
+- **AND** 提示用户当前使用直接执行模式
+- **AND** 禁止自动执行 pip install 安装依赖
+
+### Requirement: 引导阅读 README 获取详细用法
+大模型在需要了解 parser.py 的详细使用方式时，SHALL 阅读 `scripts/README.md` 文件。
+
+#### Scenario: 首次使用 skill 执行解析
+- **WHEN** 大模型首次使用 lyxy-reader-office skill 或不确定具体参数用法
+- **THEN** 大模型 SHALL 阅读 `scripts/README.md` 获取命令行参数、依赖安装和使用示例等详细信息
+
+#### Scenario: 遇到特殊参数需求
+- **WHEN** 用户请求使用特殊功能（如 PDF OCR、章节提取、正则搜索等）
+- **THEN** 大模型 SHALL 参考 `scripts/README.md` 中的对应参数说明
+
+### Requirement: 支持多格式文档解析
+系统 SHALL 支持 DOCX、PPTX、XLSX、PDF 四种格式的文档解析，将文件转换为 Markdown 格式输出。
+
+#### Scenario: 解析 DOCX 文件
+- **WHEN** 用户请求解析 .docx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 保留标题、列表、表格、粗体、斜体等格式
+- **AND** 移除图片
+
+#### Scenario: 解析 PPTX 文件
+- **WHEN** 用户请求解析 .pptx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 每张幻灯片以 `## Slide N` 为标题
+- **AND** 幻灯片之间以 `---` 分隔
+
+#### Scenario: 解析 XLSX 文件
+- **WHEN** 用户请求解析 .xlsx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 以 `## SheetName` 区分工作表
+- **AND** 数据以 Markdown 表格呈现
+
+#### Scenario: 解析 PDF 文件
+- **WHEN** 用户请求解析 .pdf 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 默认使用普通文本提取模式
+
+#### Scenario: PDF OCR 高精度模式
+- **WHEN** 用户请求对 PDF 文件启用 OCR 或高精度解析
+- **THEN** 系统使用 `--high-res` 参数启用 OCR 版面分析
+- **AND** 通过 Docling OCR 或 unstructured hi_res 策略处理
+
+### Requirement: 统一的查询功能
+系统 SHALL 对所有支持的文件格式提供统一的查询接口，包括全文提取、元数据查询、标题提取、章节提取和正则搜索。
+
+#### Scenario: 获取文档字数
+- **WHEN** 用户请求获取文档的字数
+- **THEN** 系统使用 `-c` 参数返回文档的总字符数
+
+#### Scenario: 获取文档行数
+- **WHEN** 用户请求获取文档的行数
+- **THEN** 系统使用 `-l` 参数返回文档的总行数
+
+#### Scenario: 提取所有标题
+- **WHEN** 用户请求提取文档的标题结构
+- **THEN** 系统使用 `-t` 参数返回所有 1-6 级标题
+
+#### Scenario: 提取指定章节内容
+- **WHEN** 用户请求提取特定标题名称的章节内容
+- **THEN** 系统使用 `-tc` 参数返回该章节的完整内容
+- **AND** 包含完整的上级标题链和所有下级内容
+
+#### Scenario: 正则表达式搜索
+- **WHEN** 用户请求在文档中搜索关键词或模式
+- **THEN** 系统使用 `-s` 参数返回所有匹配结果及上下文
+- **AND** 默认包含前后各 2 行非空行上下文
+- **AND** 支持 `-n` 参数自定义上下文行数
+
+### Requirement: 多策略解析降级
+系统 SHALL 对每种文件格式按优先级尝试多种解析策略，确保最大的兼容性。
+
+#### Scenario: 解析器按优先级降级
+- **WHEN** 优先级最高的解析器不可用或解析失败
+- **THEN** 系统自动尝试下一优先级的解析器
+- **AND** 记录每个解析器的失败原因
+
+#### Scenario: 所有解析器失败
+- **WHEN** 某种格式的所有解析策略均失败
+- **THEN** 系统返回详细的失败信息
+- **AND** 列出每种解析策略的失败原因
+- **AND** 以退出码 1 退出
+
+#### Scenario: DOCX/PPTX/XLSX 无依赖运行
+- **WHEN** 未安装任何第三方解析库
+- **THEN** DOCX、PPTX、XLSX 文件 SHALL 仍可通过内置 XML 原生解析工作
+- **AND** PDF 至少需要 pypdf 才能解析

openspec/changes/archive/2026-02-17-create-lyxy-reader-office/tasks.md

@@ -0,0 +1,22 @@
+## 1. 创建 SKILL.md
+
+- [x] 1.1 创建 `skills/lyxy-reader-office/SKILL.md` 文件，包含符合规范的 YAML frontmatter（name、description、compatibility）
+- [x] 1.2 编写 SKILL.md 正文：Purpose 部分，说明 skill 用途及与 lyxy-runner-python 的协作关系（必须使用 lyxy-runner-python，不可用时降级到直接 Python 执行）
+- [x] 1.3 编写 SKILL.md 正文：When to Use 部分，列出典型场景、触发词和支持的文件扩展名（.docx、.xlsx、.pptx、.pdf）
+- [x] 1.4 编写 SKILL.md 正文：Capabilities 部分，概述四种格式的解析能力和统一查询功能（全文提取、元数据、标题、章节、搜索）
+- [x] 1.5 编写 SKILL.md 正文：Execution 部分，给出基本的执行命令格式，并引导大模型阅读 `scripts/README.md` 获取详细参数说明和依赖安装指南
+- [x] 1.6 编写 SKILL.md 正文：Examples 部分，给出各格式的基本使用示例
+- [x] 1.7 编写 SKILL.md 正文：Notes 部分，说明限制和注意事项
+- [x] 1.8 验证 SKILL.md 总行数不超过 500 行，符合渐进式披露原则
+
+## 2. 清理旧 Skill
+
+- [x] 2.1 删除 `skills/lyxy-reader-docx/` 整个目录（包含 SKILL.md、docx_parser.md、scripts/docx_parser.py）
+- [x] 2.2 检查项目中是否有其他位置引用了 `lyxy-reader-docx`（如 .claude/settings 配置），如有则清理引用
+
+## 3. 验证
+
+- [x] 3.1 确认 `skills/lyxy-reader-office/SKILL.md` 存在且 frontmatter 格式正确
+- [x] 3.2 确认 `skills/lyxy-reader-office/scripts/` 下所有脚本文件完整（parser.py、common.py、docx_parser.py、pptx_parser.py、xlsx_parser.py、pdf_parser.py、README.md）
+- [x] 3.3 确认 `skills/lyxy-reader-docx/` 目录已被删除
+- [x] 3.4 使用各格式的测试文件（temp/test.docx、temp/test.xlsx、temp/test.pptx、temp/test.pdf）验证 parser.py 可正常运行

openspec/changes/archive/2026-02-19-add-lyxy-kb/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-18

openspec/changes/archive/2026-02-19-add-lyxy-kb/design.md

@@ -0,0 +1,176 @@
+## Context
+
+当前项目已有 `lyxy-reader-office` skill（解析 docx/pdf/pptx/xlsx 为 markdown）和 `lyxy-runner-python` skill（uv 执行 Python 脚本）。需要在此基础上新增知识库管理能力，让用户能将项目文档组织为可被大模型高效检索和问答的知识库。
+
+核心约束：
+- Skill 和 Command 分离：skill 定义底层规范和能力，command 定义用户交互流程
+- 纯文件驱动：不依赖数据库或向量存储，所有数据以文件形式存在
+- 渐进式查询：优先读摘要索引，按需加载详细内容，节省 token
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 提供完整的文档入库流程：放入文件 → 解析 → 归档 → 生成摘要
+- 支持增量更新和全量重建两种 project.md 维护模式
+- 基于知识库进行多轮问答，回答时标注文件来源
+- 复用已有 lyxy-reader-office 解析 office 文档
+- 支持任意纯文本文件直接入库
+
+**Non-Goals:**
+
+- 不做向量化或语义搜索
+- 不做跨项目知识关联
+- 不做文档版本对比或 diff
+- 不做权限控制或多用户协作
+- 不做 Web UI 或可视化界面
+
+## Decisions
+
+### 1. 目录结构：CWD 即知识库根目录
+
+每个知识项目是 CWD 下的一个子目录，内含固定结构：
+
+```
+CWD/
+└── <project-name>/
+    ├── project.md          # 高度摘要 + 文件索引
+    ├── manifest.json       # 增量追踪
+    ├── parsed/             # 解析后的 markdown
+    ├── sources/            # 待处理区
+    └── archive/            # 原始文件备份
+```
+
+**为什么不加 `knowledge/` 外层目录**：CWD 本身就是用户选定的知识库工作目录，额外嵌套层没有意义。用户可以在任意位置 `mkdir my-kb && cd my-kb` 然后使用 commands。
+
+### 2. 文档生命周期：sources → parsed + archive
+
+文件流转：
+1. 用户将文档放入 `sources/`
+2. ingest 解析文件，生成 `parsed/<文件名>.md`
+3. 原始文件移入 `archive/<文件名_YYYYMMDDHHmm>.<ext>`（每个版本都带时间戳）
+4. 同名文件覆盖 parsed 中的旧版本，archive 中保留所有历史版本
+
+**为什么 archive 全部带时间戳**：统一规则，无需判断"是否已有同名文件"。每次入库都是一个带时间戳的快照。
+
+**同名不同扩展名冲突处理**：如 `技术方案.pdf` 和 `技术方案.docx` 同时存在于 sources/，因为 parsed 产物都会命名为 `技术方案.md`，产生冲突。此时拒绝处理并提示用户重命名。
+
+### 3. 增量追踪：manifest.json
+
+```json
+{
+  "project": "my-project",
+  "created_at": "2026-02-18T16:00",
+  "last_ingest": "2026-02-18T17:25",
+  "files": [
+    {
+      "name": "需求文档",
+      "ext": ".docx",
+      "parsed": "parsed/需求文档.md",
+      "versions": [
+        {
+          "archived": "archive/需求文档_202602181600.docx",
+          "hash": "sha256:abc123...",
+          "ingested_at": "2026-02-18T16:00"
+        }
+      ]
+    }
+  ]
+}
+```
+
+manifest 用于：
+- 检测 sources/ 中哪些文件是新文件
+- 检测同名不同扩展名冲突（对比 files 中已有的 name 和 ext）
+- 记录版本历史，关联 parsed 和 archive 文件
+
+### 4. project.md 格式与更新策略
+
+project.md 结构：
+
+```markdown
+# <项目名称>
+
+## 概述
+（高度总结的项目信息）
+
+## 关键信息
+（从所有文档中提炼的核心要点）
+
+## 文件索引
+
+| 文件名 | 解析文件 | 最新归档 | 摘要 |
+|--------|----------|----------|------|
+| 需求文档 | parsed/需求文档.md | archive/需求文档_202602181600.docx | 简要摘要... |
+
+## 更新记录
+- 2026-02-18 16:00: 解析 需求文档.docx
+```
+
+**默认增量追加**（`lyxy-kb-ingest`）：
+- 新文件：在文件索引表追加新行，在更新记录追加条目
+- 概述和关键信息部分**不**自动更新
+
+**全量重写**（`lyxy-kb-rebuild`）：
+- 读取所有 parsed/*.md，重新生成整个 project.md
+- 概述、关键信息、文件索引全部重新生成
+
+### 5. 解析后 markdown 的元信息标记
+
+每个 parsed 文件头部包含元信息注释：
+
+```markdown
+<!-- source: 技术方案.pdf -->
+<!-- archived: archive/技术方案_202602181725.pdf -->
+<!-- parsed_at: 2026-02-18 17:25 -->
+
+# 技术方案
+（文档正文内容...）
+```
+
+用于问答时标注来源。
+
+### 6. 文件类型解析策略
+
+| 文件类型 | 解析方式 |
+|----------|----------|
+| .docx, .pdf, .pptx, .xlsx | lyxy-reader-office（通过 lyxy-runner-python 执行） |
+| .md, .txt, .csv, .json, .xml, .yaml/.yml, .log, .html 等 | 直接读取文件内容 |
+
+判断逻辑：先检查是否为 office 文档扩展名，是则调用 lyxy-reader-office；否则视为纯文本直接读取。
+
+### 7. 渐进式查询策略（ask 模式）
+
+```
+① 读取 project.md → 获取整体概述和文件索引
+② 根据用户问题判断需要哪些 parsed 文件
+③ 读取相关 parsed 文件（可能只需部分章节）
+④ 回答问题，标注来源格式：「根据《文件名》(parsed/文件名.md)，...」
+⑤ 保持会话上下文，用户可继续追问
+```
+
+### 8. Skill 与 Command 的职责划分
+
+**Skill（`skills/lyxy-kb/SKILL.md`）**：
+- 定义知识库目录结构规范
+- 定义 project.md 格式规范
+- 定义 manifest.json 结构
+- 定义解析规则和文件类型映射
+- 定义渐进式查询策略
+- 定义来源引用格式
+
+**Commands（`commands/lyxy-kb/`）**：
+- `init.md`：创建项目目录和初始文件的交互流程
+- `ingest.md`：触发解析、展示进度、增量更新 project.md 的交互流程
+- `rebuild.md`：全量重写 project.md 的交互流程
+- `ask.md`：进入会话问答模式的交互流程
+
+## Risks / Trade-offs
+
+**[project.md 增量追加导致概述过时]** → 用户可通过 `lyxy-kb-rebuild` 全量重写来更新概述。增量模式优先保证 token 效率，trade-off 是概述不会自动融入新文件的信息。
+
+**[大量文件时 rebuild 的 token 消耗]** → 如果 parsed 文件总量很大，全量重写时需要读取所有文件。目前无特殊缓解措施，依赖大模型上下文窗口限制自然约束项目规模。
+
+**[parsed 文件名冲突]** → 同名不同扩展名直接拒绝，要求用户重命名。简单但可能偶尔不便。
+
+**[纯文本文件的摘要质量]** → CSV、JSON 等结构化数据直接读取后，摘要可能不如 office 文档自然。大模型需要自行判断如何提取关键信息。

openspec/changes/archive/2026-02-19-add-lyxy-kb/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+在使用大模型辅助工作时，经常需要基于一组项目相关文档（需求文档、技术方案、数据表等）进行问答和分析。目前缺乏一种轻量的、基于文件的方式来组织这些文档，让大模型能够高效地读取、总结和检索。需要一套 skill + command 来实现个人知识库的初始化、文档解析入库、渐进式问答。
+
+## What Changes
+
+- 新增 `lyxy-kb` skill，定义知识库的目录结构规范、文档生命周期、解析规则、渐进式查询策略等底层能力
+- 新增 `lyxy-kb-init` command，引导用户创建知识项目目录结构
+- 新增 `lyxy-kb-ingest` command，解析 sources/ 中的新文件，增量更新 project.md
+- 新增 `lyxy-kb-rebuild` command，全量重新生成 project.md
+- 新增 `lyxy-kb-ask` command，进入会话式问答模式，基于项目知识渐进式查询回答问题并标注来源
+- 复用已有的 `lyxy-reader-office` skill 解析 office 文档，纯文本类文件直接读取
+
+## Capabilities
+
+### New Capabilities
+
+- `kb-project-management`：知识项目的初始化与目录结构管理，包括 project.md、parsed/、sources/、archive/ 的创建和维护
+- `kb-document-ingestion`：文档解析入库流程，包括文件类型识别、调用解析器、生成 parsed markdown、归档原始文件（带时间戳）、增量追踪（manifest.json）、同名冲突检测
+- `kb-knowledge-query`：基于知识库的渐进式问答能力，包括读取 project.md 摘要索引、按需加载 parsed 文件、回答时标注文件来源
+- `kb-project-summary`：project.md 的生成与维护策略，包括增量追加（默认）和全量重写两种模式
+
+### Modified Capabilities
+
+无。
+
+## Impact
+
+- **新增文件**：`skills/lyxy-kb/SKILL.md`、`commands/lyxy-kb/` 下 4 个 command 文件（init.md、ingest.md、rebuild.md、ask.md）
+- **依赖**：运行时依赖 `lyxy-reader-office` skill 解析 office 文档，依赖 `lyxy-runner-python` skill 执行 Python 脚本
+- **用户侧影响**：用户在任意项目目录下即可使用 command 创建和管理知识库项目，CWD 即为知识库根目录

openspec/changes/archive/2026-02-19-add-lyxy-kb/specs/kb-document-ingestion/spec.md

@@ -0,0 +1,71 @@
+## ADDED Requirements
+
+### Requirement: 扫描并识别待处理文件
+系统 SHALL 扫描项目 `sources/` 目录下的所有文件，并根据扩展名判断解析方式：
+- Office 文档（.docx、.pdf、.pptx、.xlsx）：调用 lyxy-reader-office skill 解析
+- 其他文件（.md、.txt、.csv、.json、.xml、.yaml、.yml、.log、.html 等）：直接读取内容
+
+#### Scenario: sources 中有 office 文档
+- **WHEN** sources/ 中存在 `报告.docx`
+- **THEN** 系统 SHALL 使用 lyxy-reader-office skill（通过 lyxy-runner-python 执行）将其解析为 markdown
+
+#### Scenario: sources 中有纯文本文件
+- **WHEN** sources/ 中存在 `config.json`
+- **THEN** 系统 SHALL 直接读取文件内容作为 parsed 产物
+
+#### Scenario: sources 目录为空
+- **WHEN** sources/ 中没有任何文件
+- **THEN** 系统 SHALL 提示用户 sources/ 中无待处理文件
+
+### Requirement: 同名不同扩展名冲突检测
+系统 SHALL 在解析前检测 sources/ 中是否存在同名但不同扩展名的文件（如 `技术方案.pdf` 和 `技术方案.docx`），因为 parsed 产物都会命名为相同的 `.md` 文件。同时也需检测 sources/ 中的文件名是否与 manifest.json 中已有记录的不同扩展名文件冲突。
+
+#### Scenario: sources 中存在同名不同扩展名文件
+- **WHEN** sources/ 中同时存在 `技术方案.pdf` 和 `技术方案.docx`
+- **THEN** 系统 SHALL 拒绝处理这两个文件，并提示用户重命名其中一个以消除冲突
+
+#### Scenario: sources 中文件与已入库文件同名但不同扩展名
+- **WHEN** manifest.json 中已有 `技术方案`（ext: `.pdf`）的记录，且 sources/ 中出现 `技术方案.docx`
+- **THEN** 系统 SHALL 拒绝处理该文件，并提示用户重命名
+
+### Requirement: 生成 parsed markdown 文件
+系统 SHALL 将解析后的内容写入 `parsed/<文件名>.md`，文件头部 MUST 包含元信息注释：
+```
+<!-- source: <原始文件名含扩展名> -->
+<!-- archived: archive/<文件名_时间戳>.<扩展名> -->
+<!-- parsed_at: <解析时间 YYYY-MM-DD HH:mm> -->
+```
+若 parsed/ 中已存在同名文件（同一文档的更新版本），SHALL 覆盖旧文件。
+
+#### Scenario: 首次解析文件
+- **WHEN** 解析 `需求文档.docx`，parsed/ 中不存在 `需求文档.md`
+- **THEN** 系统创建 `parsed/需求文档.md`，头部包含 source、archived、parsed_at 元信息，正文为解析后的 markdown 内容
+
+#### Scenario: 更新已有文件
+- **WHEN** 解析 `技术方案.pdf`，parsed/ 中已存在 `技术方案.md`（上一版本）
+- **THEN** 系统覆盖 `parsed/技术方案.md`，元信息更新为最新版本的 archive 路径和时间
+
+### Requirement: 归档原始文件
+系统 SHALL 将已解析的原始文件从 `sources/` 移动到 `archive/`，文件名格式为 `<文件名_YYYYMMDDHHmm>.<扩展名>`。每个进入 archive 的文件都 MUST 带有时间戳后缀，即使该文件只有一个版本。
+
+#### Scenario: 归档文件
+- **WHEN** `需求文档.docx` 解析完成，当前时间为 2026-02-18 16:00
+- **THEN** 原始文件移动为 `archive/需求文档_202602181600.docx`
+
+#### Scenario: 同名文件多次入库
+- **WHEN** `技术方案.pdf` 第二次入库，archive 中已有 `技术方案_202602181600.pdf`
+- **THEN** 新版本归档为 `技术方案_202602181725.pdf`（以当前时间为时间戳），两个版本并存于 archive
+
+### Requirement: 更新 manifest.json
+系统 SHALL 在每个文件处理完成后更新 manifest.json：
+- 新文件：在 files 数组中追加新条目，包含 name、ext、parsed 路径，versions 数组包含首个版本的 archived 路径、hash 和 ingested_at
+- 已有文件更新：在对应条目的 versions 数组中追加新版本记录
+- last_ingest 时间戳 SHALL 更新为当前 ingest 的时间
+
+#### Scenario: 新文件入库更新 manifest
+- **WHEN** `需求文档.docx` 首次解析完成
+- **THEN** manifest.json 的 files 数组中追加 `{"name": "需求文档", "ext": ".docx", "parsed": "parsed/需求文档.md", "versions": [{"archived": "archive/需求文档_202602181600.docx", "hash": "sha256:...", "ingested_at": "2026-02-18T16:00"}]}`
+
+#### Scenario: 已有文件更新 manifest
+- **WHEN** `技术方案.pdf` 第二次入库
+- **THEN** manifest.json 中该文件条目的 versions 数组追加新版本记录，不删除旧版本记录

openspec/changes/archive/2026-02-19-add-lyxy-kb/specs/kb-knowledge-query/spec.md

@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: 渐进式查询策略
+系统 SHALL 采用渐进式查询策略回答用户问题，以节省 token 消耗：
+1. 首先读取 project.md 获取整体概述和文件索引
+2. 根据用户问题和文件索引判断需要查阅哪些 parsed 文件
+3. 按需读取相关 parsed 文件的全部或部分内容
+4. 基于获取的信息回答问题
+
+#### Scenario: 问题可通过摘要回答
+- **WHEN** 用户提问"这个项目主要做什么？"，且 project.md 的概述中已包含足够信息
+- **THEN** 系统仅基于 project.md 内容回答，不加载 parsed 文件
+
+#### Scenario: 问题需要查阅具体文件
+- **WHEN** 用户提问"系统的权限控制是怎么设计的？"，且 project.md 文件索引中 `需求文档` 的摘要提到了权限相关内容
+- **THEN** 系统读取 `parsed/需求文档.md` 获取详细信息后回答
+
+### Requirement: 来源标注
+系统在回答中引用具体信息时 SHALL 标注文件来源，格式为：「根据《文件名》(parsed/文件名.md)，...」。来源标注 MUST 指向 parsed 目录下的具体文件。
+
+#### Scenario: 回答中包含来源标注
+- **WHEN** 系统从 `parsed/技术方案.md` 中获取信息来回答问题
+- **THEN** 回答中 SHALL 包含类似「根据《技术方案》(parsed/技术方案.md)，系统采用微服务架构...」的来源标注
+
+#### Scenario: 回答综合多个文件
+- **WHEN** 回答需要综合 `parsed/需求文档.md` 和 `parsed/技术方案.md` 的信息
+- **THEN** 回答中 SHALL 分别标注各信息点的来源文件
+
+### Requirement: 会话问答模式
+系统 SHALL 在 ask 模式下保持会话上下文，用户可以连续提问而无需每次重新加载知识库。会话的退出由用户自然决定（开启新话题或新会话），系统不主动终止会话。
+
+#### Scenario: 多轮追问
+- **WHEN** 用户先问"系统用了什么技术栈？"，接着追问"数据库选型的理由是什么？"
+- **THEN** 系统在第二次回答时保持之前的上下文，可复用已加载的 parsed 文件内容
+
+#### Scenario: 知识库中无相关信息
+- **WHEN** 用户提出的问题在 project.md 和所有 parsed 文件中均无相关信息
+- **THEN** 系统 SHALL 明确告知用户当前知识库中未找到相关信息，而非编造答案

openspec/changes/archive/2026-02-19-add-lyxy-kb/specs/kb-project-management/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: 初始化知识项目目录结构
+系统 SHALL 在 CWD 下创建以指定名称命名的子目录，并在其中生成以下固定结构：
+- `project.md`：初始内容包含项目名称标题、空的概述/关键信息段落、空的文件索引表和空的更新记录
+- `manifest.json`：初始内容包含项目名称、创建时间、空的 files 数组
+- `parsed/` 目录
+- `sources/` 目录
+- `archive/` 目录
+
+#### Scenario: 成功初始化新项目
+- **WHEN** 用户执行 `/lyxy-kb-init my-project`，且 CWD 下不存在 `my-project` 目录
+- **THEN** 系统创建 `my-project/` 目录及完整子结构（project.md、manifest.json、parsed/、sources/、archive/），并提示用户将文档放入 sources/ 目录
+
+#### Scenario: 目标目录已存在
+- **WHEN** 用户执行 `/lyxy-kb-init my-project`，且 CWD 下已存在 `my-project` 目录
+- **THEN** 系统 SHALL 提示用户该目录已存在，不覆盖任何现有内容
+
+### Requirement: 项目目录结构规范
+知识项目 SHALL 遵循固定的目录结构：`project.md`、`manifest.json`、`parsed/`、`sources/`、`archive/`。所有 command 和 skill 操作 SHALL 基于此结构进行，不在结构外创建额外文件或目录。
+
+#### Scenario: 验证项目结构完整性
+- **WHEN** 任何 command（ingest/rebuild/ask）在指定项目目录上执行
+- **THEN** 系统 SHALL 先检查目录结构是否完整（包含 project.md、manifest.json、parsed/、sources/、archive/），若不完整则提示用户先执行 init

openspec/changes/archive/2026-02-19-add-lyxy-kb/specs/kb-project-summary/spec.md

@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: project.md 格式规范
+project.md SHALL 遵循以下固定结构：
+
+```markdown
+# <项目名称>
+
+## 概述
+（高度总结的项目信息）
+
+## 关键信息
+（从所有文档中提炼的核心要点）
+
+## 文件索引
+
+| 文件名 | 解析文件 | 最新归档 | 摘要 |
+|--------|----------|----------|------|
+
+## 更新记录
+```
+
+初始化时概述和关键信息为空，文件索引表为空表头，更新记录为空。
+
+#### Scenario: 初始化后的 project.md
+- **WHEN** 执行 `/lyxy-kb-init my-project`
+- **THEN** 生成的 project.md 包含 `# my-project` 标题、空的概述/关键信息段落、空的文件索引表（仅表头）和空的更新记录
+
+### Requirement: 增量追加模式
+执行 ingest 时，系统 SHALL 以增量方式更新 project.md：
+- 在文件索引表中追加新解析文件的行（文件名、parsed 路径、最新 archive 路径、该文件的简要摘要）
+- 在更新记录中追加本次 ingest 的条目（时间和处理的文件列表）
+- 已有文件更新时：覆盖文件索引表中对应行的最新归档路径和摘要
+- 概述和关键信息部分 SHALL NOT 在增量模式下自动更新
+
+#### Scenario: 首次 ingest 追加索引
+- **WHEN** 首次 ingest 解析了 `需求文档.docx`
+- **THEN** project.md 文件索引表中追加一行，更新记录中追加 `- 2026-02-18 16:00: 解析 需求文档.docx`
+
+#### Scenario: 已有文件更新时追加索引
+- **WHEN** `技术方案.pdf` 第二次入库
+- **THEN** project.md 文件索引表中该文件的最新归档路径和摘要被更新，更新记录追加新条目
+
+### Requirement: 全量重写模式
+执行 rebuild 时，系统 SHALL 读取所有 `parsed/*.md` 文件，重新生成整个 project.md：
+- 概述：基于所有 parsed 文件内容重新生成高度总结
+- 关键信息：重新提炼核心要点
+- 文件索引：基于 manifest.json 和 parsed 文件重新生成完整索引表
+- 更新记录：保留历史记录，追加本次 rebuild 条目
+
+#### Scenario: 全量重写
+- **WHEN** 用户执行 `/lyxy-kb-rebuild my-project`，项目中有 3 个 parsed 文件
+- **THEN** 系统读取所有 3 个 parsed 文件，重新生成 project.md 的概述、关键信息和文件索引，更新记录追加 rebuild 条目

openspec/changes/archive/2026-02-19-add-lyxy-kb/tasks.md

@@ -0,0 +1,26 @@
+## 1. Skill 基础
+
+- [x] 1.1 创建 `skills/lyxy-kb/` 目录
+- [x] 1.2 编写 `skills/lyxy-kb/SKILL.md`，定义知识库底层规范，包括：目录结构规范（project.md、manifest.json、parsed/、sources/、archive/）、project.md 格式规范（标题/概述/关键信息/文件索引表/更新记录）、manifest.json 结构定义、文件类型解析策略（office 文档用 lyxy-reader-office，其他纯文本直接读取）、parsed 文件元信息标记格式、渐进式查询策略、来源引用格式、同名不同扩展名冲突检测规则
+
+## 2. Command: lyxy-kb-init
+
+- [x] 2.1 创建 `commands/lyxy-kb/` 目录
+- [x] 2.2 编写 `commands/lyxy-kb/init.md`，实现初始化交互流程：接收项目名称参数，检查目标目录是否已存在（已存在则提示不覆盖），在 CWD 下创建项目子目录及完整结构（project.md、manifest.json、parsed/、sources/、archive/），project.md 按规范格式生成初始内容（空概述/关键信息/文件索引/更新记录），manifest.json 初始化为含项目名和创建时间的空结构
+
+## 3. Command: lyxy-kb-ingest
+
+- [x] 3.1 编写 `commands/lyxy-kb/ingest.md`，实现增量解析入库交互流程，包括以下步骤：
+  - 接收项目名称参数，验证项目目录结构完整性
+  - 读取 manifest.json，扫描 sources/ 下所有文件
+  - 执行同名不同扩展名冲突检测（sources/ 内部互相检测 + 与 manifest 已有记录检测）
+  - 对每个无冲突的文件：根据扩展名判断解析方式（office → lyxy-reader-office，其他 → 直接读取），生成 parsed markdown（含头部元信息注释），移动原始文件到 archive（带时间戳后缀），更新 manifest.json
+  - 增量更新 project.md：在文件索引表追加/更新行，在更新记录追加条目，不修改概述和关键信息
+
+## 4. Command: lyxy-kb-rebuild
+
+- [x] 4.1 编写 `commands/lyxy-kb/rebuild.md`，实现全量重写交互流程：接收项目名称参数，验证项目目录结构完整性，读取所有 parsed/*.md 文件，基于全部内容重新生成 project.md（概述、关键信息、文件索引表全部重写），保留历史更新记录并追加本次 rebuild 条目
+
+## 5. Command: lyxy-kb-ask
+
+- [x] 5.1 编写 `commands/lyxy-kb/ask.md`，实现会话问答交互流程：接收项目名称参数，验证项目目录结构完整性，指导大模型执行渐进式查询策略（先读 project.md 摘要索引 → 按需加载 parsed 文件 → 回答并标注来源），进入持续会话模式（用户可连续追问），知识库无相关信息时明确告知

openspec/changes/archive/2026-02-25-build-skillmgr-cli/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-25

openspec/changes/archive/2026-02-25-build-skillmgr-cli/design.md

@@ -0,0 +1,322 @@
+## Context
+
+当前手动管理 AI 编程平台的 skills/commands 面临以下挑战：
+
+- **平台差异**：Claude Code 使用目录结构，OpenCode 使用扁平化文件命名（如 `lyxy-kb-init.md`）
+- **手动操作**：需要手动理解每个平台的规范、复制文件、重命名
+- **追踪困难**：无法知道哪些 skills/commands 已安装、来自哪个源、何时安装
+- **更新风险**：手动更新容易遗漏文件或破坏已有配置
+
+目标用户是作者本人，工具需要简单直接，优先实现核心功能而非过度设计。
+
+**约束条件**：
+- 单用户场景，不考虑多用户协作
+- 仅支持最新版本，不处理多版本共存
+- 不解析依赖关系，用户手动管理依赖
+- 平台支持范围：Claude Code、OpenCode（未来可扩展）
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 自动化从 git 源仓库到目标平台的完整安装流程
+- 支持全局和项目级两种安装作用域
+- 内置 Claude Code 和 OpenCode 的平台适配规则
+- 记录所有安装操作，支持查询、更新、卸载、清理
+- 事务性安装机制，避免部分失败导致的不一致状态
+- 用户友好的交互体验（确认覆盖、清晰的错误提示）
+
+**Non-Goals:**
+
+- ❌ 多版本管理（语义化版本、版本锁定、版本冲突解决）
+- ❌ 依赖解析和自动安装依赖
+- ❌ 插件化的平台适配器系统
+- ❌ 复杂的仓库注册中心或包索引服务
+- ❌ 跨平台迁移或批量同步
+
+## Decisions
+
+### 1. 技术栈选择：Go + Cobra
+
+**决策**：使用 Go 语言开发，CLI 框架选择 Cobra。
+
+**理由**：
+- **Go**：编译为单一可执行文件，无运行时依赖，跨平台分发简单
+- **Cobra**：业界标准 CLI 框架（kubectl、docker 都用它），支持子命令、自动帮助生成、参数验证
+- **替代方案**：标准库 `flag` 包功能过于简单，不适合多子命令场景
+
+**影响**：开发者需要熟悉 Go 和 Cobra 的基本用法。
+
+---
+
+### 2. 配置文件格式：JSON
+
+**决策**：使用 JSON 格式存储配置（repository.json、install.json）。
+
+**理由**：
+- Go 标准库原生支持，无需第三方依赖
+- 结构清晰，易于程序读写和人工检查
+- **替代方案**：YAML（需要第三方库）、TOML（生态较小）
+
+**配置结构**：
+```
+~/.skillmgr/
+├── repository.json    # 源仓库列表
+├── install.json       # 安装记录
+└── cache/             # git 仓库缓存
+```
+
+---
+
+### 3. 事务性安装：Tmp Staging
+
+**决策**：采用三阶段事务性安装（Stage → Commit → Rollback）。
+
+**理由**：
+- 避免部分文件复制失败导致目标目录处于不一致状态
+- 先在系统临时目录（`os.TempDir()`）组装完整的目标文件树
+- 验证成功后一次性移动到最终位置
+- 失败时自动清理临时目录，不污染目标
+
+**流程**：
+```
+1. 创建 staging 目录（/tmp/skillmgr-xxxxx/）
+2. 复制所有文件到 staging（应用平台适配规则）
+3. 验证 staging 目录完整性
+4. 移动 staging 到目标位置（原子操作）
+5. 失败则删除 staging，不影响目标
+```
+
+**替代方案**：直接复制到目标（风险高）、使用 Git worktree（过于复杂）。
+
+---
+
+### 4. 平台适配器：内置而非插件化
+
+**决策**：将 Claude Code 和 OpenCode 的适配规则硬编码在程序内，不支持用户自定义适配器。
+
+**理由**：
+- 目标平台数量少且稳定（2 个），插件系统收益低
+- 硬编码保证规则的正确性和一致性
+- 简化实现和维护成本
+- **替代方案**：配置文件定义适配规则（增加复杂度）、插件系统（过度设计）
+
+**适配器接口**：
+```go
+type PlatformAdapter interface {
+    GetSkillInstallPath(scope, name) (string, error)
+    GetCommandInstallPath(scope, group) (string, error)
+    AdaptSkill(sourcePath, destPath) (map[string]string, error)
+    AdaptCommand(sourcePath, destPath, group) (map[string]string, error)
+}
+```
+
+**差异处理**：
+- **Skills**：两个平台都保持目录结构，直接复制
+- **Commands**：
+  - Claude Code 保持目录结构（`commands/lyxy-kb/init.md`）
+  - OpenCode 扁平化文件名（`command/lyxy-kb-init.md`）
+
+---
+
+### 5. 安装策略：复制而非符号链接
+
+**决策**：全局和项目级安装都使用文件复制，不使用符号链接。
+
+**理由**：
+- 避免符号链接在跨平台和跨文件系统时的兼容性问题（尤其是 Windows）
+- 项目可以独立于全局安装，避免意外修改影响其他项目
+- 磁盘空间在现代系统中不是瓶颈
+- **替代方案**：全局符号链接（复杂度高，跨平台问题）
+
+**影响**：
+- 更新全局安装不会自动影响项目级安装（需显式更新）
+- 多个项目可以独立更新各自的 skills/commands
+
+---
+
+### 6. 命令文件组织：命令组概念
+
+**决策**：将 commands 按目录组织，整个目录作为"命令组"一起安装。
+
+**理由**：
+- 源仓库中 commands 按功能分组（如 `commands/lyxy-kb/` 包含 init/ask/ingest/rebuild）
+- 命令组内的命令通常有关联，应一起安装
+- 简化用户操作，避免逐个命令安装
+
+**命令组到命令的映射**：
+- Claude Code：`/lyxy-kb-init` → `commands/lyxy-kb/init.md`
+- OpenCode：`/lyxy-kb:init` → `command/lyxy-kb-init.md`
+
+---
+
+### 7. 安装记录清理：Clean 命令
+
+**决策**：提供 `clean` 命令扫描并清理孤立记录（install.json 中存在但目标路径已删除）。
+
+**理由**：
+- 用户可能手动删除已安装的目录
+- 避免 install.json 与实际文件系统状态不一致
+- 不自动清理（避免误删），由用户显式触发
+
+**实现**：
+```bash
+skillmgr clean
+# 扫描 install.json 中所有记录
+# 检查 install_path 是否存在
+# 列出孤立记录并确认删除
+```
+
+---
+
+### 8. 目录冲突处理：用户决策
+
+**决策**：安装前检查目标目录是否存在，存在时由用户决定是否覆盖。
+
+**场景**：
+1. **install.json 有记录 + 目录存在**：已安装，询问是否覆盖
+2. **install.json 无记录 + 目录存在**：未被 skillmgr 管理的目录，询问是否覆盖
+3. **install.json 有记录 + 目录不存在**：孤立记录，清理记录后继续安装
+
+**用户交互**：
+```
+Skill 'lyxy-kb' is already installed. Overwrite? [y/N]:
+```
+
+---
+
+### 9. 项目结构：独立 Go 项目
+
+**决策**：在 `manager/` 目录下创建独立的 Go 项目，与现有 skills 仓库分离。
+
+**目录结构**：
+```
+manager/
+├── cmd/skillmgr/        # CLI 命令实现
+├── internal/            # 内部包（不对外暴露）
+│   ├── config/          # 配置文件读写
+│   ├── repo/            # Git 仓库管理
+│   ├── adapter/         # 平台适配器
+│   ├── installer/       # 安装逻辑
+│   └── prompt/          # 用户交互
+├── pkg/                 # 可对外暴露的包
+│   └── fileutil/        # 文件工具
+├── go.mod
+└── README.md
+```
+
+**理由**：
+- 不污染现有 skills 仓库结构
+- 工具本身可以独立开发、测试、发布
+- 清晰的模块边界
+
+---
+
+### 10. 测试隔离：环境变量注入
+
+**决策**：通过环境变量覆盖配置和目标路径，实现零污染测试。
+
+**理由**：
+- 测试不应影响用户的实际配置（`~/.skillmgr/`）和安装目录（`~/.claude/`）
+- 环境变量注入是轻量级且侵入性最小的方案
+- 支持并行测试（每个测试独立目录）
+
+**实现**：
+```go
+// 配置路径注入
+func GetConfigRoot() (string, error) {
+    if testRoot := os.Getenv("SKILLMGR_TEST_ROOT"); testRoot != "" {
+        return testRoot, nil
+    }
+    // 生产模式...
+}
+
+// 目标路径注入
+func getBasePath(scope Scope) (string, error) {
+    if testBase := os.Getenv("SKILLMGR_TEST_BASE"); testBase != "" {
+        return testBase, nil
+    }
+    // 生产模式...
+}
+```
+
+**测试使用**：
+```go
+func TestInstall(t *testing.T) {
+    testRoot := t.TempDir()
+    testBase := t.TempDir()
+    os.Setenv("SKILLMGR_TEST_ROOT", testRoot)
+    os.Setenv("SKILLMGR_TEST_BASE", testBase)
+    defer os.Unsetenv("SKILLMGR_TEST_ROOT")
+    defer os.Unsetenv("SKILLMGR_TEST_BASE")
+    // 测试代码...
+}
+```
+
+**替代方案**：
+- **依赖注入**（将路径作为参数传递）：侵入性强，需要重构所有函数签名
+- **Mock 文件系统**（如 afero）：复杂度高，且无法测试真实文件系统行为
+- **专用测试模式标志**：需要额外的全局状态管理
+
+## Risks / Trade-offs
+
+### 1. 无版本管理
+
+**风险**：用户无法回退到旧版本的 skill/command，更新可能引入破坏性变更。
+
+**缓解**：
+- 文档中建议用户在重要项目中使用 git 管理项目配置目录（如 `.claude/`）
+- 工具记录 `updated_at` 时间，方便追溯
+
+---
+
+### 2. 无依赖解析
+
+**风险**：安装 command 时，依赖的 skill 可能未安装（如 `lyxy-kb` 命令依赖 `lyxy-reader-office` skill）。
+
+**缓解**：
+- 在 skill 的 SKILL.md 中明确记录依赖关系（如 `compatibility` 字段）
+- 错误提示中建议用户检查依赖
+- 未来可选增强：扫描 SKILL.md 提示缺失依赖
+
+---
+
+### 3. Git 依赖
+
+**风险**：工具依赖系统中已安装 Git 客户端，无 Git 则无法拉取仓库。
+
+**缓解**：
+- 在 README 中明确前置条件
+- 首次运行时检测 Git 是否可用，提示安装
+- 错误消息中包含 Git 安装指引
+
+---
+
+### 4. 跨文件系统移动失败
+
+**风险**：`os.Rename()` 在跨文件系统时会失败（如 tmp 在 tmpfs，目标在 ext4）。
+
+**缓解**：
+- 捕获 Rename 错误，fallback 到递归复制 + 删除 staging
+- 在事务实现中明确处理两种路径
+
+---
+
+### 5. 平台适配规则变化
+
+**风险**：Claude Code 或 OpenCode 未来修改目录结构规范，导致工具失效。
+
+**缓解**：
+- 将适配规则集中在 `internal/adapter/` 包中，便于修改
+- 提供版本号，用户可锁定工具版本以保证稳定性
+- 文档中建议关注平台更新公告
+
+---
+
+### 6. 手动修改配置文件
+
+**风险**：用户手动编辑 repository.json 或 install.json 可能破坏格式，导致解析失败。
+
+**缓解**：
+- JSON 解析错误时提示备份并重建配置文件
+- 提供 `doctor` 命令（未来增强）诊断和修复配置

openspec/changes/archive/2026-02-25-build-skillmgr-cli/proposal.md

@@ -0,0 +1,37 @@
+## Why
+
+当前手动管理和分发 AI 编程平台的 skills/commands 存在诸多问题：需要手动理解不同平台（Claude Code、OpenCode）的目录结构差异、手动复制文件、手动处理命名转换（如 OpenCode 的扁平化命名），且难以追踪已安装的内容和版本。随着 skills 数量增长和多平台支持需求，这种手动流程变得不可维护。需要一个自动化的管理工具来简化从源仓库到目标平台的完整流程。
+
+## What Changes
+
+- **新增**：创建独立的 Go CLI 工具（skillmgr），提供命令行界面管理 skills/commands 的完整生命周期
+- **新增**：支持从 git 仓库拉取和缓存 skills/commands 源代码
+- **新增**：内置 Claude Code 和 OpenCode 两个平台的适配规则
+- **新增**：支持全局安装（~/.claude/、~/.opencode/）和项目级安装（./.claude/、./.opencode/）
+- **新增**：安装记录追踪系统，支持更新、卸载、清理孤立记录
+- **新增**：事务性安装机制，通过 tmp staging 避免部分失败导致的不一致状态
+- **新增**：用户交互确认（目录覆盖、冲突解决）
+
+## Capabilities
+
+### New Capabilities
+
+- `repository-management`：管理源仓库配置（添加、移除、同步 git 仓库）
+- `skill-installation`：安装 skills 到目标平台（支持全局/项目作用域）
+- `command-installation`：安装 commands 到目标平台（处理命令组和平台特定命名）
+- `platform-adaptation`：适配不同 AI 编程平台的目录结构和命名规则
+- `install-tracking`：跟踪和管理安装记录（查询、更新、清理）
+- `transactional-install`：事务性文件安装（staging → commit → rollback）
+- `test-infrastructure`：测试环境隔离和自动化（零污染测试、fixture 管理、CI 集成）
+
+### Modified Capabilities
+
+（无现有能力需要修改）
+
+## Impact
+
+- **新增项目**：在 `manager/` 目录下创建独立的 Go 项目（不影响现有 skills 仓库结构）
+- **用户配置**：在用户目录创建 `~/.skillmgr/` 配置目录（repository.json、install.json、cache/）
+- **目标平台**：修改目标平台的 `.claude/` 和 `.opencode/` 目录（根据用户操作）
+- **依赖**：需要 Git 客户端（用于 clone/pull 操作）
+- **兼容性**：工具设计为独立运行，不破坏现有手动管理的 skills/commands

openspec/changes/archive/2026-02-25-build-skillmgr-cli/specs/command-installation/spec.md

@@ -0,0 +1,95 @@
+## ADDED Requirements
+
+### Requirement: 用户可以安装命令组到全局目录
+
+工具必须支持将整个命令组（commands 目录下的子目录）安装到平台配置目录。
+
+#### Scenario: 全局安装命令组到 Claude Code
+
+- **WHEN** 用户执行 `skillmgr install command <group> --platform claude --global`
+- **THEN** 系统将 `commands/<group>/` 下所有 .md 文件复制到 `~/.claude/commands/<group>/`
+
+#### Scenario: 全局安装命令组到 OpenCode
+
+- **WHEN** 用户执行 `skillmgr install command <group> --platform opencode --global`
+- **THEN** 系统将 `commands/<group>/` 下所有 .md 文件重命名为 `<group>-<action>.md` 并复制到 `~/.opencode/command/`
+
+---
+
+### Requirement: 用户可以安装命令组到项目目录
+
+工具必须支持将命令组安装到当前项目的平台配置目录。
+
+#### Scenario: 项目级安装命令组到 Claude Code
+
+- **WHEN** 用户在项目目录执行 `skillmgr install command <group> --platform claude`
+- **THEN** 系统将命令组复制到 `./.claude/commands/<group>/`
+
+#### Scenario: 项目级安装命令组到 OpenCode
+
+- **WHEN** 用户在项目目录执行 `skillmgr install command <group> --platform opencode`
+- **THEN** 系统将命令组扁平化复制到 `./.opencode/command/`
+
+---
+
+### Requirement: 系统必须在所有源仓库中查找命令组
+
+工具必须在所有已配置源仓库的 `commands/` 目录中搜索指定命令组。
+
+#### Scenario: 找到命令组
+
+- **WHEN** 源仓库包含 `commands/<group>/` 目录且内有 .md 文件
+- **THEN** 系统使用该命令组进行安装
+
+#### Scenario: 命令组不存在
+
+- **WHEN** 所有源仓库都不包含指定命令组
+- **THEN** 系统报错"command '<group>' not found in any repository"
+
+#### Scenario: 命令组目录为空
+
+- **WHEN** 找到命令组目录但其中没有 .md 文件
+- **THEN** 系统报错"command group '<group>' contains no command files"
+
+---
+
+### Requirement: OpenCode 平台必须扁平化命令文件名
+
+工具必须在安装到 OpenCode 平台时，将命令文件重命名为 `<group>-<action>.md` 格式。
+
+#### Scenario: 转换命令文件名
+
+- **WHEN** 安装 `commands/lyxy-kb/init.md` 到 OpenCode
+- **THEN** 文件被重命名为 `lyxy-kb-init.md`
+
+#### Scenario: 保留 .md 扩展名
+
+- **WHEN** 转换文件名时
+- **THEN** 系统保留 `.md` 扩展名
+
+---
+
+### Requirement: 系统必须处理命令组目录冲突
+
+工具必须在安装前检查目标目录或文件是否已存在。
+
+#### Scenario: Claude Code 命令组目录冲突
+
+- **WHEN** `~/.claude/commands/<group>/` 目录已存在
+- **THEN** 系统询问用户是否覆盖
+
+#### Scenario: OpenCode 命令文件冲突
+
+- **WHEN** 目标 `~/.opencode/command/` 中已存在同名的 `<group>-*.md` 文件
+- **THEN** 系统询问用户是否覆盖所有冲突文件
+
+---
+
+### Requirement: 系统必须记录命令组安装
+
+工具必须在成功安装后将记录写入 install.json。
+
+#### Scenario: 记录命令组安装信息
+
+- **WHEN** 命令组安装成功
+- **THEN** 系统在 install.json 中添加 type 为 "command"、包含命令组名称和安装路径的记录

openspec/changes/archive/2026-02-25-build-skillmgr-cli/specs/install-tracking/spec.md

@@ -0,0 +1,124 @@
+## ADDED Requirements
+
+### Requirement: 系统必须持久化安装记录
+
+工具必须在每次成功安装后，将安装信息写入 `~/.skillmgr/install.json`。
+
+#### Scenario: 创建新记录
+
+- **WHEN** 首次安装某个 skill/command
+- **THEN** 系统在 install.json 的 installations 数组中添加新记录
+
+#### Scenario: 记录包含必要字段
+
+- **WHEN** 创建安装记录
+- **THEN** 记录必须包含 type、name、source_repo、platform、scope、install_path、installed_at、updated_at
+
+---
+
+### Requirement: 用户可以查询已安装项
+
+工具必须提供命令列出所有已安装的 skills 和 commands。
+
+#### Scenario: 列出所有已安装项
+
+- **WHEN** 用户执行 `skillmgr list` 命令
+- **THEN** 系统显示所有 install.json 中的记录
+
+#### Scenario: 按类型过滤
+
+- **WHEN** 用户执行 `skillmgr list --type skill` 或 `--type command`
+- **THEN** 系统仅显示对应类型的安装记录
+
+#### Scenario: 按平台过滤
+
+- **WHEN** 用户执行 `skillmgr list --platform claude` 或 `--platform opencode`
+- **THEN** 系统仅显示对应平台的安装记录
+
+#### Scenario: 按作用域过滤
+
+- **WHEN** 用户执行 `skillmgr list --global` 或省略该参数
+- **THEN** 系统仅显示对应作用域的安装记录
+
+#### Scenario: 无已安装项
+
+- **WHEN** install.json 为空或不存在
+- **THEN** 系统提示"无已安装的 skills/commands"
+
+---
+
+### Requirement: 用户可以卸载已安装项
+
+工具必须提供卸载功能，删除文件并移除安装记录。
+
+#### Scenario: 卸载 skill
+
+- **WHEN** 用户执行 `skillmgr uninstall skill <name> --platform <platform> --global`
+- **THEN** 系统从 install.json 查找记录，删除对应目录，移除记录
+
+#### Scenario: 卸载 command
+
+- **WHEN** 用户执行 `skillmgr uninstall command <group> --platform <platform> --global`
+- **THEN** 系统删除对应的命令文件或目录，移除记录
+
+#### Scenario: 卸载不存在的项
+
+- **WHEN** install.json 中无对应记录
+- **THEN** 系统提示"未找到安装记录"，不执行删除
+
+#### Scenario: 安装路径已被手动删除
+
+- **WHEN** install.json 有记录但文件已不存在
+- **THEN** 系统仅移除记录，不报错
+
+---
+
+### Requirement: 用户可以更新已安装项
+
+工具必须提供更新功能，重新从源仓库安装最新版本。
+
+#### Scenario: 更新单个 skill
+
+- **WHEN** 用户执行 `skillmgr update skill <name> --platform <platform> --global`
+- **THEN** 系统从源重新安装到原路径，更新 updated_at 字段
+
+#### Scenario: 更新单个 command
+
+- **WHEN** 用户执行 `skillmgr update command <group> --platform <platform> --global`
+- **THEN** 系统从源重新安装到原路径，更新 updated_at 字段
+
+#### Scenario: 更新所有已安装项
+
+- **WHEN** 用户执行 `skillmgr update --all`
+- **THEN** 系统遍历 install.json 中所有记录，逐个更新
+
+#### Scenario: 源仓库找不到原始项
+
+- **WHEN** 更新时源仓库中不再存在该 skill/command
+- **THEN** 系统报错，不修改已安装文件和记录
+
+---
+
+### Requirement: 用户可以清理孤立记录
+
+工具必须提供命令扫描并清理 install.json 中文件路径已不存在的记录。
+
+#### Scenario: 扫描孤立记录
+
+- **WHEN** 用户执行 `skillmgr clean` 命令
+- **THEN** 系统遍历 install.json 中所有记录，检查 install_path 是否存在
+
+#### Scenario: 清理孤立记录
+
+- **WHEN** 发现安装路径不存在的记录
+- **THEN** 系统列出这些记录并从 install.json 中删除
+
+#### Scenario: 无孤立记录
+
+- **WHEN** 所有记录的安装路径都存在
+- **THEN** 系统提示"无孤立记录"
+
+#### Scenario: 显示清理结果
+
+- **WHEN** 清理完成
+- **THEN** 系统显示清理的记录数量和详情（type、name、platform、scope、路径）

openspec/changes/archive/2026-02-25-build-skillmgr-cli/specs/platform-adaptation/spec.md

@@ -0,0 +1,104 @@
+## ADDED Requirements
+
+### Requirement: 系统必须支持 Claude Code 平台
+
+工具必须内置 Claude Code 平台的目录结构和命名规则。
+
+#### Scenario: Skill 安装路径
+
+- **WHEN** 安装 skill 到 Claude Code
+- **THEN** 目标路径为 `<base>/.claude/skills/<skill-name>/`
+
+#### Scenario: Command 安装路径
+
+- **WHEN** 安装 command 到 Claude Code
+- **THEN** 目标路径为 `<base>/.claude/commands/<command-group>/`
+
+#### Scenario: 保持源目录结构
+
+- **WHEN** 复制文件到 Claude Code
+- **THEN** 系统保持源仓库的目录结构不变
+
+---
+
+### Requirement: 系统必须支持 OpenCode 平台
+
+工具必须内置 OpenCode 平台的目录结构和命名规则。
+
+#### Scenario: Skill 全局安装路径
+
+- **WHEN** 全局安装 skill 到 OpenCode
+- **THEN** 目标路径为 `~/.config/opencode/skills/<skill-name>/`
+
+#### Scenario: Skill 项目级安装路径
+
+- **WHEN** 项目级安装 skill 到 OpenCode
+- **THEN** 目标路径为 `./.opencode/skills/<skill-name>/`
+
+#### Scenario: Command 全局安装路径
+
+- **WHEN** 全局安装 command 到 OpenCode
+- **THEN** 目标路径为 `~/.config/opencode/commands/`
+
+#### Scenario: Command 项目级安装路径
+
+- **WHEN** 项目级安装 command 到 OpenCode
+- **THEN** 目标路径为 `./.opencode/commands/`
+
+#### Scenario: Skill 保持结构
+
+- **WHEN** 复制 skill 到 OpenCode
+- **THEN** 系统保持源目录结构
+
+#### Scenario: Command 扁平化
+
+- **WHEN** 复制 command 到 OpenCode
+- **THEN** 系统将文件重命名为 `<group>-<action>.md` 并放置在 commands/ 目录下
+
+---
+
+### Requirement: 系统必须根据作用域确定基础路径
+
+工具必须根据全局/项目作用域计算正确的基础路径。
+
+#### Scenario: 全局作用域
+
+- **WHEN** 用户指定 `--global` 参数
+- **THEN** 基础路径为用户主目录（`~` 或 `$HOME`）
+
+#### Scenario: 项目作用域
+
+- **WHEN** 用户未指定 `--global` 参数
+- **THEN** 基础路径为当前工作目录
+
+---
+
+### Requirement: 系统必须生成文件映射表
+
+适配器必须生成源文件到目标文件的完整映射表，供事务性安装使用。
+
+#### Scenario: Skill 文件映射
+
+- **WHEN** 适配 skill 文件
+- **THEN** 系统返回源路径到目标路径的 map（包括所有子目录和文件）
+
+#### Scenario: Command 文件映射（Claude）
+
+- **WHEN** 适配 command 到 Claude Code
+- **THEN** 系统返回 `commands/<group>/<action>.md` → `<base>/.claude/commands/<group>/<action>.md` 的映射
+
+#### Scenario: Command 文件映射（OpenCode）
+
+- **WHEN** 适配 command 到 OpenCode
+- **THEN** 系统返回 `commands/<group>/<action>.md` → `<base>/commands/<group>-<action>.md` 的映射（全局时 base 为 `~/.config/opencode`，项目级时为 `./.opencode`）
+
+---
+
+### Requirement: 系统必须处理不支持的平台
+
+工具必须拒绝处理未实现的平台。
+
+#### Scenario: 不支持的平台参数
+
+- **WHEN** 用户指定未实现的平台（如 `--platform cursor`）
+- **THEN** 系统报错"unsupported platform: cursor"

openspec/changes/archive/2026-02-25-build-skillmgr-cli/specs/repository-management/spec.md

@@ -0,0 +1,78 @@
+## ADDED Requirements
+
+### Requirement: 用户可以添加源仓库
+
+工具必须允许用户添加 git 仓库作为 skills/commands 的源，并将配置持久化到 `~/.skillmgr/repository.json`。
+
+#### Scenario: 成功添加新仓库
+
+- **WHEN** 用户执行 `skillmgr add <git-url>` 命令
+- **THEN** 系统克隆仓库到 `~/.skillmgr/cache/` 并将配置写入 repository.json
+
+#### Scenario: 添加已存在的仓库
+
+- **WHEN** 用户添加已存在的仓库（同名）
+- **THEN** 系统提示"仓库名称已存在，请先使用 `skillmgr remove <name>` 移除"，拒绝添加
+
+#### Scenario: 指定仓库别名
+
+- **WHEN** 用户使用 `--name` 参数指定仓库别名
+- **THEN** 系统使用指定的别名作为仓库名称
+
+#### Scenario: 指定分支
+
+- **WHEN** 用户使用 `--branch` 参数指定分支
+- **THEN** 系统克隆指定分支而非默认分支
+
+---
+
+### Requirement: 用户可以移除源仓库
+
+工具必须允许用户从配置中移除已添加的源仓库。
+
+#### Scenario: 成功移除仓库
+
+- **WHEN** 用户执行 `skillmgr remove <name>` 命令
+- **THEN** 系统从 repository.json 中删除对应配置
+
+#### Scenario: 移除不存在的仓库
+
+- **WHEN** 用户尝试移除不存在的仓库名称
+- **THEN** 系统提示仓库不存在，不报错
+
+---
+
+### Requirement: 用户可以列出已配置的源仓库
+
+工具必须提供命令列出所有已添加的源仓库及其信息。
+
+#### Scenario: 列出所有仓库
+
+- **WHEN** 用户执行 `skillmgr list-repos` 命令
+- **THEN** 系统显示所有仓库的名称、URL、分支和添加时间
+
+#### Scenario: 无已配置仓库
+
+- **WHEN** 用户执行列表命令但 repository.json 为空
+- **THEN** 系统提示"无已配置的源仓库"
+
+---
+
+### Requirement: 用户可以同步源仓库
+
+工具必须提供命令从远程拉取最新代码，更新本地缓存。
+
+#### Scenario: 同步单个仓库
+
+- **WHEN** 用户执行 `skillmgr sync <name>` 命令
+- **THEN** 系统对指定仓库执行 `git pull`
+
+#### Scenario: 同步所有仓库
+
+- **WHEN** 用户执行 `skillmgr sync` 不带参数
+- **THEN** 系统对所有已配置仓库执行 `git pull`
+
+#### Scenario: Git 操作失败
+
+- **WHEN** git pull 失败（网络错误、冲突等）
+- **THEN** 系统显示 git 错误信息并继续处理其他仓库

openspec/changes/archive/2026-02-25-build-skillmgr-cli/specs/skill-installation/spec.md

@@ -0,0 +1,95 @@
+## ADDED Requirements
+
+### Requirement: 用户可以安装 skill 到全局目录
+
+工具必须支持将 skill 安装到用户主目录下的平台配置目录（如 `~/.claude/skills/`）。
+
+#### Scenario: 全局安装到 Claude Code
+
+- **WHEN** 用户执行 `skillmgr install skill <name> --platform claude --global`
+- **THEN** 系统将 skill 复制到 `~/.claude/skills/<name>/`
+
+#### Scenario: 全局安装到 OpenCode
+
+- **WHEN** 用户执行 `skillmgr install skill <name> --platform opencode --global`
+- **THEN** 系统将 skill 复制到 `~/.config/opencode/skills/<name>/`
+
+---
+
+### Requirement: 用户可以安装 skill 到项目目录
+
+工具必须支持将 skill 安装到当前项目目录下的平台配置目录。
+
+#### Scenario: 项目级安装到 Claude Code
+
+- **WHEN** 用户在项目目录执行 `skillmgr install skill <name> --platform claude`
+- **THEN** 系统将 skill 复制到 `./claude/skills/<name>/`
+
+#### Scenario: 项目级安装到 OpenCode
+
+- **WHEN** 用户在项目目录执行 `skillmgr install skill <name> --platform opencode`
+- **THEN** 系统将 skill 复制到 `./.opencode/skills/<name>/`
+
+---
+
+### Requirement: 系统必须在所有源仓库中查找 skill
+
+工具必须在所有已配置的源仓库缓存中搜索指定的 skill。
+
+#### Scenario: 在第一个仓库找到
+
+- **WHEN** 第一个仓库包含目标 skill
+- **THEN** 系统使用该仓库的 skill 进行安装
+
+#### Scenario: 在后续仓库找到
+
+- **WHEN** 前面的仓库不包含目标 skill，但后续仓库包含
+- **THEN** 系统使用找到的第一个匹配仓库
+
+#### Scenario: 所有仓库都不包含
+
+- **WHEN** 所有源仓库都不包含目标 skill
+- **THEN** 系统报错"skill '<name>' not found in any repository"
+
+---
+
+### Requirement: 用户可以临时指定源仓库
+
+工具必须支持通过 `--from` 参数临时指定源仓库 URL，不保存到配置文件。
+
+#### Scenario: 使用临时仓库安装
+
+- **WHEN** 用户执行 `skillmgr install skill <name> --platform claude --global --from <git-url>`
+- **THEN** 系统从指定 URL 拉取仓库并安装，不修改 repository.json
+
+---
+
+### Requirement: 系统必须处理目录已存在的情况
+
+工具必须在安装前检查目标目录是否已存在，并根据情况处理。
+
+#### Scenario: install.json 有记录且目录存在
+
+- **WHEN** 目标 skill 已通过 skillmgr 安装
+- **THEN** 系统询问用户是否覆盖，默认为否
+
+#### Scenario: install.json 无记录但目录存在
+
+- **WHEN** 目标目录存在但不在 install.json 中
+- **THEN** 系统询问用户是否覆盖该目录，默认为否
+
+#### Scenario: 用户拒绝覆盖
+
+- **WHEN** 用户选择不覆盖
+- **THEN** 系统取消安装，不修改任何文件
+
+---
+
+### Requirement: 系统必须记录安装操作
+
+工具必须在成功安装后将记录写入 `~/.skillmgr/install.json`。
+
+#### Scenario: 记录包含完整信息
+
+- **WHEN** 安装成功完成
+- **THEN** 系统在 install.json 中添加包含 type、name、platform、scope、install_path、installed_at、updated_at 的记录

openspec/changes/archive/2026-02-25-build-skillmgr-cli/specs/test-infrastructure/spec.md

@@ -0,0 +1,153 @@
+## ADDED Requirements
+
+### Requirement: 测试必须不污染用户环境
+
+工具的所有测试必须通过环境变量隔离配置和安装目录，不影响用户的实际数据和系统配置。
+
+#### Scenario: 配置目录隔离
+
+- **WHEN** 测试运行时设置 `SKILLMGR_TEST_ROOT` 环境变量
+- **THEN** 系统使用该环境变量指定的目录作为配置根目录，而非 `~/.skillmgr/`
+
+#### Scenario: 安装目标目录隔离
+
+- **WHEN** 测试运行时设置 `SKILLMGR_TEST_BASE` 环境变量
+- **THEN** 系统使用该环境变量指定的目录作为全局/项目基础路径，而非用户主目录或当前工作目录
+
+#### Scenario: 生产模式不受影响
+
+- **WHEN** 环境变量未设置（生产模式）
+- **THEN** 系统使用默认路径（`~/.skillmgr/`、`~/.claude/` 等）
+
+---
+
+### Requirement: 测试必须自动清理临时资源
+
+所有测试创建的临时目录、文件和 git 仓库必须在测试结束后自动清理，不留垃圾文件。
+
+#### Scenario: 使用 Go 测试框架自动清理
+
+- **WHEN** 测试使用 `t.TempDir()` 创建临时目录
+- **THEN** Go 测试框架在测试结束时自动删除该目录及其所有内容
+
+#### Scenario: 测试失败时也清理
+
+- **WHEN** 测试失败或 panic
+- **THEN** 临时资源仍然被自动清理
+
+---
+
+### Requirement: 测试必须支持并行执行
+
+测试设计必须允许多个测试并行运行，互不干扰，充分利用多核性能。
+
+#### Scenario: 独立测试环境
+
+- **WHEN** 使用 `go test -parallel N` 并行运行多个测试
+- **THEN** 每个测试使用独立的临时目录，不产生竞态条件
+
+#### Scenario: 配置隔离
+
+- **WHEN** 多个测试同时设置环境变量
+- **THEN** 每个测试的环境变量设置独立生效（通过 t.Setenv 或 defer os.Unsetenv）
+
+---
+
+### Requirement: 用户交互必须可 mock
+
+所有涉及用户输入的功能必须支持测试时注入 mock 输入，不依赖真实的标准输入。
+
+#### Scenario: Mock 用户确认输入
+
+- **WHEN** 测试需要模拟用户输入 "y" 或 "n"
+- **THEN** `prompt.ConfirmWithReader` 函数接受 `io.Reader` 参数，测试时传入 `strings.NewReader("y\n")`
+
+#### Scenario: 生产模式使用真实输入
+
+- **WHEN** 生产代码调用 `prompt.Confirm`
+- **THEN** 内部调用 `ConfirmWithReader(message, os.Stdin)` 读取真实用户输入
+
+---
+
+### Requirement: 测试必须使用真实文件系统
+
+测试应使用真实的文件系统操作和 git 命令，而非 mock，以确保行为与生产一致。
+
+#### Scenario: 真实文件复制测试
+
+- **WHEN** 测试文件复制功能
+- **THEN** 在临时目录中创建真实文件，执行复制，验证结果
+
+#### Scenario: 真实 git 操作测试
+
+- **WHEN** 测试 git clone/pull 功能
+- **THEN** 在临时目录中初始化真实的 git 仓库，执行 git 命令
+
+---
+
+### Requirement: 测试数据必须可复用
+
+测试应提供标准的 fixture 数据和辅助函数，避免每个测试重复构建测试环境。
+
+#### Scenario: Fixture 仓库
+
+- **WHEN** 测试需要一个标准的 skills/commands 仓库
+- **THEN** 从 `testdata/fixtures/test-repo/` 复制 fixture 并初始化为 git 仓库
+
+#### Scenario: 测试辅助函数
+
+- **WHEN** 测试需要设置隔离环境
+- **THEN** 调用 `setupTestEnv(t)` 函数自动设置环境变量和临时目录
+
+---
+
+### Requirement: 测试覆盖必须全面
+
+测试必须覆盖所有核心模块、关键路径和边界条件。
+
+#### Scenario: 单元测试覆盖
+
+- **WHEN** 实现任何核心函数（config、adapter、repo、installer）
+- **THEN** 必须编写对应的单元测试，覆盖正常和异常情况
+
+#### Scenario: 集成测试覆盖
+
+- **WHEN** 实现跨模块功能（完整安装流程）
+- **THEN** 必须编写集成测试，验证端到端行为
+
+#### Scenario: 平台兼容性测试
+
+- **WHEN** 支持多个平台（Claude Code、OpenCode）
+- **THEN** 每个平台都必须有独立的兼容性测试
+
+---
+
+### Requirement: 测试脚本必须简化运行
+
+必须提供自动化脚本，简化测试环境设置和测试执行。
+
+#### Scenario: 自动化测试脚本
+
+- **WHEN** 开发者运行 `./scripts/test.sh`
+- **THEN** 脚本自动设置测试环境变量、运行所有测试、清理临时资源
+
+#### Scenario: 沙盒测试环境
+
+- **WHEN** 开发者运行 `./scripts/sandbox.sh`
+- **THEN** 脚本创建隔离的沙盒环境，允许手动测试而不影响系统
+
+---
+
+### Requirement: CI/CD 集成必须无缝
+
+测试必须能在 CI/CD 环境中稳定运行，不依赖本地环境配置。
+
+#### Scenario: GitHub Actions 集成
+
+- **WHEN** 在 CI 中运行测试
+- **THEN** 通过环境变量设置测试路径，所有测试通过且自动清理
+
+#### Scenario: 测试失败报告
+
+- **WHEN** 测试失败
+- **THEN** CI 系统捕获失败信息、日志和覆盖率报告

openspec/changes/archive/2026-02-25-build-skillmgr-cli/specs/transactional-install/spec.md

@@ -0,0 +1,126 @@
+## ADDED Requirements
+
+### Requirement: 系统必须使用临时目录进行 staging
+
+工具必须在系统临时目录中创建 staging 区域，组装完整的目标文件树后再移动到最终位置。
+
+#### Scenario: 创建 staging 目录
+
+- **WHEN** 开始安装事务
+- **THEN** 系统在 `/tmp/` 或 `os.TempDir()` 创建唯一的临时目录（如 `skillmgr-xxxxx/`）
+
+#### Scenario: Staging 目录结构与目标一致
+
+- **WHEN** 在 staging 中组装文件
+- **THEN** staging 目录结构必须与最终目标目录结构完全一致
+
+---
+
+### Requirement: 系统必须先完整复制到 staging
+
+工具必须将所有源文件完整复制到 staging 目录，应用平台适配规则。
+
+#### Scenario: 复制所有文件到 staging
+
+- **WHEN** 执行 Stage 阶段
+- **THEN** 系统根据平台适配器返回的文件映射，将所有文件复制到 staging
+
+#### Scenario: 复制失败回滚
+
+- **WHEN** 复制过程中任何文件失败
+- **THEN** 系统删除 staging 目录，报错终止，不影响目标目录
+
+---
+
+### Requirement: 系统必须验证 staging 完整性
+
+工具必须在提交前验证 staging 目录中的文件完整性。
+
+#### Scenario: 验证文件数量
+
+- **WHEN** 所有文件复制到 staging
+- **THEN** 系统验证 staging 中文件数量与预期映射表一致
+
+---
+
+### Requirement: 系统必须原子性提交 staging
+
+工具必须在 staging 验证通过后，将整个 staging 目录移动到目标位置。
+
+#### Scenario: 同文件系统移动
+
+- **WHEN** staging 和目标在同一文件系统
+- **THEN** 系统使用 `os.Rename()` 原子性移动
+
+#### Scenario: 跨文件系统复制
+
+- **WHEN** `os.Rename()` 失败（跨文件系统）
+- **THEN** 系统 fallback 到递归复制 + 删除 staging
+
+#### Scenario: 覆盖已存在目录
+
+- **WHEN** 目标目录已存在（用户已确认覆盖）
+- **THEN** 系统先删除目标目录，再移动 staging
+
+---
+
+### Requirement: 系统必须在失败时自动回滚
+
+工具必须在任何阶段失败时，自动清理 staging 目录，不留垃圾文件。
+
+#### Scenario: Stage 阶段失败
+
+- **WHEN** 文件复制到 staging 失败
+- **THEN** 系统删除 staging 目录，不修改目标
+
+#### Scenario: Commit 阶段失败
+
+- **WHEN** 移动 staging 到目标失败
+- **THEN** 系统删除 staging 目录，目标目录保持原状（或已删除的状态）
+
+#### Scenario: defer 确保清理
+
+- **WHEN** 事务对象被销毁
+- **THEN** 系统使用 defer 确保 staging 目录被清理
+
+---
+
+### Requirement: 系统必须提供事务接口
+
+工具必须提供清晰的事务接口，包含 Stage、Commit、Rollback 方法。
+
+#### Scenario: 创建事务对象
+
+- **WHEN** 开始安装流程
+- **THEN** 系统创建 Transaction 对象，包含 stagingDir、targetDir、fileMap 字段
+
+#### Scenario: 调用 Stage 方法
+
+- **WHEN** 调用 `transaction.Stage()`
+- **THEN** 系统执行文件复制到 staging
+
+#### Scenario: 调用 Commit 方法
+
+- **WHEN** 调用 `transaction.Commit()`
+- **THEN** 系统将 staging 移动到目标
+
+#### Scenario: 调用 Rollback 方法
+
+- **WHEN** 调用 `transaction.Rollback()`
+- **THEN** 系统删除 staging 目录
+
+---
+
+### Requirement: 系统必须确保目标目录的父目录存在
+
+工具必须在提交前确保目标目录的父目录已创建。
+
+#### Scenario: 创建父目录
+
+- **WHEN** 提交 staging 到目标
+- **THEN** 系统先创建目标目录的父目录（如 `~/.claude/skills/`）
+
+#### Scenario: 父目录创建失败
+
+- **WHEN** 父目录创建失败（权限不足等）
+- **THEN** 系统报错，回滚 staging

openspec/changes/archive/2026-02-25-build-skillmgr-cli/tasks.md

@@ -0,0 +1,191 @@
+## 1. 项目初始化
+
+- [x] 1.1 在 `manager/` 目录创建 Go 项目，初始化 go.mod（module: skillmgr）
+- [x] 1.2 创建项目目录结构（cmd/、internal/、pkg/、testdata/）
+- [x] 1.3 添加 Cobra 依赖（github.com/spf13/cobra）
+- [x] 1.4 创建 .gitignore 文件
+- [x] 1.5 创建测试脚本目录（scripts/）
+
+## 2. 核心类型定义
+
+- [x] 2.1 创建 `internal/types/types.go`，定义 Platform、ItemType、Scope 枚举类型
+- [x] 2.2 定义 Repository 结构体（name、url、branch、added_at）
+- [x] 2.3 定义 RepositoryConfig 结构体（repositories 数组）
+- [x] 2.4 定义 InstallRecord 结构体（type、name、source_repo、platform、scope、install_path、installed_at、updated_at）
+- [x] 2.5 定义 InstallConfig 结构体（installations 数组）
+- [x] 2.6 定义 SkillMetadata 和 CommandGroup 结构体
+
+## 3. 配置管理模块
+
+- [x] 3.1 创建 `internal/config/paths.go`，实现配置目录路径函数（GetConfigRoot、GetRepositoryConfigPath、GetInstallConfigPath、GetCachePath）
+- [x] 3.2 在 GetConfigRoot 中添加环境变量 SKILLMGR_TEST_ROOT 支持（测试隔离）
+- [x] 3.3 实现 EnsureConfigDirs 函数，确保配置目录存在
+- [x] 3.4 创建 `internal/config/repository.go`，实现 LoadRepositoryConfig 和 SaveRepositoryConfig
+- [x] 3.5 实现 AddRepository 函数（检查同名仓库，存在则拒绝并提示先移除）
+- [x] 3.6 实现 RemoveRepository 和 FindRepository 函数
+- [x] 3.7 创建 `internal/config/install.go`，实现 LoadInstallConfig 和 SaveInstallConfig
+- [x] 3.8 实现 AddInstallRecord、RemoveInstallRecord、FindInstallRecord、UpdateInstallRecord 函数
+- [x] 3.9 实现 CleanOrphanRecords 函数（扫描并清理安装路径不存在的记录）
+
+## 4. 文件工具模块
+
+- [x] 4.1 创建 `pkg/fileutil/fileutil.go`
+- [x] 4.2 实现 CopyFile 函数（复制单个文件并保留权限）
+- [x] 4.3 实现 CopyDir 函数（递归复制目录）
+
+## 5. Git 仓库管理模块
+
+- [x] 5.1 创建 `internal/repo/git.go`
+- [x] 5.2 实现 URLToPathName 函数（将 git URL 转换为缓存目录名）
+- [x] 5.3 实现 CloneOrPull 函数（检查仓库是否存在，不存在则 clone，存在则 pull）
+- [x] 5.4 实现 cloneRepo 函数（执行 git clone --depth 1）
+- [x] 5.5 实现 pullRepo 函数（执行 git pull）
+- [x] 5.6 创建 `internal/repo/scanner.go`
+- [x] 5.7 实现 ScanSkills 函数（扫描 skills/ 目录，返回 skill 列表）
+- [x] 5.8 实现 ScanCommands 函数（扫描 commands/ 目录，返回命令组列表）
+- [x] 5.9 实现 FindSkill 函数（在所有仓库缓存中查找指定 skill）
+- [x] 5.10 实现 FindCommand 函数（在所有仓库缓存中查找指定命令组）
+
+## 6. 平台适配器模块
+
+- [x] 6.1 创建 `internal/adapter/adapter.go`，定义 PlatformAdapter 接口
+- [x] 6.2 实现 GetAdapter 函数（根据 Platform 返回对应适配器，不支持则报错）
+- [x] 6.3 实现 getBasePath 辅助函数（根据 Scope 返回基础路径，支持 SKILLMGR_TEST_BASE 环境变量）
+- [x] 6.4 创建 `internal/adapter/claude.go`，实现 ClaudeAdapter 结构体
+- [x] 6.5 实现 Claude 的 GetSkillInstallPath 和 GetCommandInstallPath 方法
+- [x] 6.6 实现 Claude 的 AdaptSkill 方法（遍历源目录，生成文件映射）
+- [x] 6.7 实现 Claude 的 AdaptCommand 方法（保持目录结构）
+- [x] 6.8 创建 `internal/adapter/opencode.go`，实现 OpenCodeAdapter 结构体
+- [x] 6.9 实现 OpenCode 的 GetSkillInstallPath（注意 command 是单数）和 GetCommandInstallPath 方法
+- [x] 6.10 实现 OpenCode 的 AdaptSkill 方法（与 Claude 相同）
+- [x] 6.11 实现 OpenCode 的 AdaptCommand 方法（扁平化文件名：<group>-<action>.md）
+
+## 7. 事务性安装模块
+
+- [x] 7.1 创建 `internal/installer/transaction.go`
+- [x] 7.2 定义 Transaction 结构体（stagingDir、targetDir、fileMap）
+- [x] 7.3 实现 NewTransaction 函数（在系统临时目录创建 staging）
+- [x] 7.4 实现 Stage 方法（复制所有文件到 staging，创建必要的子目录）
+- [x] 7.5 实现 Commit 方法（确保父目录存在，删除已存在的目标，移动 staging 到目标）
+- [x] 7.6 处理 Commit 中的跨文件系统情况（Rename 失败则 fallback 到 CopyDir）
+- [x] 7.7 实现 Rollback 方法（删除 staging 目录）
+- [x] 7.8 在 NewTransaction 中使用 defer 确保清理
+
+## 8. 用户交互模块
+
+- [x] 8.1 创建 `internal/prompt/prompt.go`
+- [x] 8.2 实现 ConfirmWithReader 函数（接受 io.Reader，支持测试 mock）
+- [x] 8.3 实现 Confirm 函数（调用 ConfirmWithReader，使用 os.Stdin）
+
+## 9. 安装器模块
+
+- [x] 9.1 创建 `internal/installer/installer.go`
+- [x] 9.2 实现 checkExistingInstallation 函数（检查 install.json 记录和目录存在性，询问用户是否覆盖）
+- [x] 9.3 实现 InstallSkill 函数（查找 skill、获取适配器、确定路径、检查冲突、适配、事务安装、记录）
+- [x] 9.4 实现 InstallCommand 函数（查找 command、获取适配器、确定路径、检查冲突、适配、事务安装、记录）
+- [x] 9.5 创建 `internal/installer/uninstaller.go`
+- [x] 9.6 实现 UninstallSkill 函数（查找记录、删除目录、移除记录）
+- [x] 9.7 实现 UninstallCommand 函数（查找记录、删除目录或文件、移除记录）
+
+## 10. CLI 根命令
+
+- [x] 10.1 创建 `cmd/skillmgr/root.go`
+- [x] 10.2 定义 rootCmd，设置 Use、Short、Long
+- [x] 10.3 实现 Execute 函数
+- [x] 10.4 在 init 中调用 config.EnsureConfigDirs 初始化配置目录
+- [x] 10.5 创建 `cmd/skillmgr/main.go`，调用 Execute
+
+## 11. 仓库管理命令
+
+- [x] 11.1 创建 `cmd/skillmgr/add.go`，实现 addCmd
+- [x] 11.2 添加 --name 和 --branch 参数
+- [x] 11.3 实现 RunE：解析参数、调用 repo.CloneOrPull、调用 config.AddRepository、显示成功信息
+- [x] 11.4 创建 `cmd/skillmgr/remove.go`，实现 removeCmd
+- [x] 11.5 实现 RunE：调用 config.RemoveRepository
+- [x] 11.6 创建 `cmd/skillmgr/list_repos.go`，实现 listReposCmd
+- [x] 11.7 实现 RunE：调用 config.LoadRepositoryConfig、格式化输出
+- [x] 11.8 创建 `cmd/skillmgr/sync.go`，实现 syncCmd
+- [x] 11.9 实现 RunE：支持指定仓库名或同步所有，调用 repo.CloneOrPull
+
+## 12. 安装命令
+
+- [x] 12.1 创建 `cmd/skillmgr/install.go`，实现 installCmd
+- [x] 12.2 添加 --platform（必需）、--global、--from 参数
+- [x] 12.3 实现 Args 验证（必须有 2 个参数：type 和 name）
+- [x] 12.4 实现 RunE：解析 type（skill/command）、调用对应安装函数
+- [x] 12.5 处理 --from 参数（TODO：临时仓库，暂时跳过实现）
+
+## 13. 追踪管理命令
+
+- [x] 13.1 创建 `cmd/skillmgr/list.go`，实现 listCmd
+- [x] 13.2 添加 --type、--platform、--global 参数
+- [x] 13.3 实现 RunE：加载 install.json、根据参数过滤、格式化输出
+- [x] 13.4 创建 `cmd/skillmgr/uninstall.go`，实现 uninstallCmd
+- [x] 13.5 添加 --platform（必需）、--global 参数
+- [x] 13.6 实现 Args 验证和 RunE：调用对应卸载函数
+- [x] 13.7 创建 `cmd/skillmgr/update.go`，实现 updateCmd
+- [x] 13.8 添加 --platform、--global、--all 参数
+- [x] 13.9 实现 RunE：支持更新单个或全部已安装项
+- [x] 13.10 创建 `cmd/skillmgr/clean.go`，实现 cleanCmd
+- [x] 13.11 实现 RunE：调用 config.CleanOrphanRecords、显示清理结果
+
+## 14. 搜索命令（可选）
+
+- [x] 14.1 创建 `cmd/skillmgr/search.go`，实现 searchCmd
+- [x] 14.2 实现 RunE：遍历所有仓库缓存、扫描 skills 和 commands、匹配关键词、输出结果
+
+## 15. 错误处理和用户体验优化
+
+- [x] 15.1 确保所有 Git 操作失败时显示清晰错误信息
+- [x] 15.2 安装/卸载成功时显示 ✓ 符号和路径信息
+- [x] 15.3 配置文件解析错误时提示用户检查 JSON 格式
+- [x] 15.4 未找到 skill/command 时列出可用项
+
+## 16. 测试基础设施
+
+- [x] 16.1 创建 `testdata/fixtures/` 目录
+- [x] 16.2 创建测试用 fixture 仓库（test-repo，包含 2 个 skills 和 1 个 command 组）
+- [x] 16.3 编写测试辅助函数 setupTestRepo（初始化临时 git 仓库）
+- [x] 16.4 编写测试辅助函数 copyFixtureRepo（复制 fixture 并初始化 git）
+- [x] 16.5 创建 `scripts/test.sh`（设置测试环境变量并运行测试）
+- [x] 16.6 创建 `scripts/sandbox.sh`（手动测试沙盒环境）
+
+## 17. 单元测试
+
+- [x] 17.1 创建 `internal/config/paths_test.go`，测试环境变量覆盖
+- [x] 17.2 创建 `internal/config/repository_test.go`，测试仓库配置增删改查
+- [x] 17.3 测试 AddRepository 拒绝同名仓库场景
+- [x] 17.4 创建 `internal/config/install_test.go`，测试安装记录管理
+- [x] 17.5 测试 CleanOrphanRecords 功能
+- [x] 17.6 创建 `internal/adapter/claude_test.go`，测试路径计算和文件映射
+- [x] 17.7 创建 `internal/adapter/opencode_test.go`，测试扁平化命名转换
+- [x] 17.8 创建 `internal/repo/git_test.go`，测试 URL 转换
+- [x] 17.9 创建 `internal/installer/transaction_test.go`，测试 Stage/Commit/Rollback
+- [x] 17.10 创建 `internal/prompt/prompt_test.go`，测试用户输入 mock
+- [x] 17.11 创建 `pkg/fileutil/fileutil_test.go`，测试文件复制
+
+## 18. 集成测试
+
+- [x] 18.1 创建 `internal/installer/installer_test.go`
+- [x] 18.2 测试完整安装流程（add repo → install skill → 验证文件和记录）
+- [x] 18.3 测试冲突覆盖场景（已安装 → 再次安装 → 用户确认）
+- [x] 18.4 测试事务回滚（Stage 失败 → 验证 staging 清理）
+- [x] 18.5 测试卸载流程（install → uninstall → 验证删除）
+- [x] 18.6 测试更新流程（install → update → 验证更新）
+- [x] 18.7 测试清理孤立记录（install → 手动删除 → clean）
+- [x] 18.8 测试 Claude Code 平台安装（skill 和 command）
+- [x] 18.9 测试 OpenCode 平台安装（skill 和 command 扁平化）
+
+## 19. 构建和手动验证
+
+- [x] 19.1 编写 Makefile 或构建脚本，支持 `go build -o skillmgr`
+- [x] 19.2 在沙盒环境手动测试基本流程
+- [x] 19.3 验证全局和项目级安装
+- [x] 19.4 验证两个平台的适配正确性
+
+## 20. 文档
+
+- [x] 20.1 编写 README.md，包含安装说明、使用示例、命令参考
+- [x] 20.2 记录配置文件格式和路径
+- [x] 20.3 添加常见问题和故障排除指南
+- [x] 20.4 添加测试说明（如何运行测试、测试环境变量）

openspec/changes/archive/2026-02-25-optimize-skills-structure/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-25

openspec/changes/archive/2026-02-25-optimize-skills-structure/design.md

@@ -0,0 +1,76 @@
+## Context
+
+当前项目包含 4 个 skills（lyxy-runner-python、lyxy-runner-js、lyxy-reader-office、lyxy-kb），每个 SKILL.md 文件内容在 200-300 行之间。根据 `document/the-complete-guide-to-building-skill.md` 中的渐进式披露原则，SKILL.md 应保持精简（建议 5000 字以内），详细文档应放在 `references/` 目录中。
+
+**当前状态**：
+- SKILL.md 包含完整的工作流程、示例、错误处理、最佳实践等所有内容
+- 无 references/ 目录结构
+- 每次 Claude 加载 skill 时需要处理全部内容
+
+## Goals / Non-Goals
+
+**Goals:**
+- 遵循三层渐进式披露结构：YAML 前置元数据 → SKILL.md 核心指令 → references/ 详细文档
+- 减少 skill 加载时的 token 消耗
+- 保持 lyxy-runner-python 和 lyxy-runner-js 的 description 宽泛性
+- 为 4 个现有 skills 创建 references/ 目录并迁移内容
+
+**Non-Goals:**
+- 不修改 skill 的功能逻辑
+- 不修改 scripts/ 目录中的可执行代码
+- 不新增 skill 或删除现有 skill
+
+## Decisions
+
+### 决策 1：三层结构内容划分
+
+| 层级 | 位置 | 内容 | 加载时机 |
+|-----|------|------|---------|
+| 第一层 | YAML 前置元数据 | name、description、compatibility | 始终加载到系统提示 |
+| 第二层 | SKILL.md 正文 | 核心工作流、关键命令、快速参考 | Claude 判断相关时加载 |
+| 第三层 | references/*.md | 详细示例、错误处理、最佳实践、API 参考 | 按需导航和发现 |
+
+**理由**：遵循官方指南的渐进式披露原则，最小化 token 消耗的同时保持完整能力。
+
+### 决策 2：SKILL.md 保留内容
+
+每个 SKILL.md 正文保留以下核心部分：
+1. **Purpose**：简要说明用途和关键依赖
+2. **When to Use**：适用/不适用场景（简化版）
+3. **Quick Reference**：核心命令表格或流程图
+4. **Workflow**：简化的执行步骤
+5. **References 链接**：指向 references/ 中详细文档的链接
+
+**理由**：保留足够信息让 Claude 完成任务，详细内容按需加载。
+
+### 决策 3：references/ 目录结构
+
+```
+references/
+├── examples.md          # 详细示例
+├── error-handling.md    # 错误处理和故障排除
+├── best-practices.md    # 最佳实践和注意事项
+└── api-reference.md     # API/命令参数详细说明（可选）
+```
+
+**理由**：按主题分类，便于 Claude 按需定位和加载。
+
+### 决策 4：Description 格式
+
+采用统一格式：`[做什么] + [何时使用] + [关键能力]`
+
+- lyxy-runner-python：保持 "Any task that requires Python processing should use this skill."（宽泛）
+- lyxy-runner-js：保持 "Any task that requires Javascript/Typescript processing should use this skill."（宽泛）
+- lyxy-reader-office：保持当前描述，已包含具体文件类型和操作
+- lyxy-kb：可优化添加用户触发短语
+
+**理由**：runner skills 需要宽泛以匹配所有相关任务，reader/kb skills 可以更具体以精准触发。
+
+## Risks / Trade-offs
+
+| 风险 | 缓解措施 |
+|-----|---------|
+| references/ 文件未被 Claude 发现 | 在 SKILL.md 中明确列出 references/ 文件并说明用途 |
+| 拆分后信息不完整 | 核心工作流程保留在 SKILL.md，确保基本任务可完成 |
+| 迁移过程中遗漏内容 | 逐个 skill 处理，对比前后内容确保完整性 |
+| 文件数量增加 | references/ 文件按需加载，不影响初始 token 消耗 |