test: fix test pollution in home directory

README.md

@@ -25,7 +25,7 @@ Claude Agent Skills are great - but they only work in Claude. What about Cursor,
 | 50+ skills, "which one was for PR reviews?" | Search by keyword - finds it in milliseconds | [Scale →](#scale-progressive-disclosure) |
 | Long debugging session, context running low | Skills load on-demand - not all upfront | [Scale →](#scale-progressive-disclosure) |
 | Found an awesome skill on GitHub | `skillport add <url>` - ready to use in seconds | [CLI →](#manage-cli) |
-| Don't want to set up MCP | CLI works standalone - `init`, `add`, `sync` to AGENTS.md | [CLI Mode →](#cli-mode) |
+| Don't want to set up MCP | CLI works standalone - `init`, `add`, `doc` to AGENTS.md | [CLI Mode →](#cli-mode) |
 
 <br>
 
@@ -77,7 +77,7 @@ uv tool install skillport
 # or: pip install skillport
 ```
 
-Enables `add`, `remove`, `lint`, `search`, `show`, and `sync` (export to AGENTS.md for non-MCP agents).
+Enables `add`, `remove`, `lint`, `search`, `show`, and `doc` (generate AGENTS.md for non-MCP agents).
 
 ### 2. Add Skills
 
@@ -183,7 +183,7 @@ The agent will:
 
 **For:** Coding agents with shell commands (Cursor, Windsurf, Cline, Copilot, Codex, etc.)
 
-Skills sync to AGENTS.md and load via `skillport show`. No MCP configuration needed.
+Skills are documented in AGENTS.md and load via `skillport show`. No MCP configuration needed.
 
 ```bash
 # 1. Install
@@ -192,7 +192,7 @@ uv tool install skillport
 # 2. Initialize your project (in your project directory)
 skillport init
 # → Select skills directory and instruction files interactively
-# → Creates .skillportrc, syncs skills to AGENTS.md
+# → Creates .skillportrc, generates skills to AGENTS.md
 
 # 3. Add skills (uses skills_dir from .skillportrc)
 skillport add hello-world
@@ -227,8 +227,8 @@ Tools for progressive skill loading:
 
 ```bash
 skillport init              # Initialize project (.skillportrc, AGENTS.md)
-skillport sync              # Update AGENTS.md when skills change
-skillport sync --all        # Update all instruction files in .skillportrc
+skillport doc               # Update AGENTS.md when skills change
+skillport doc --all         # Update all instruction files in .skillportrc
 ```
 
 **Skill Management:**

guide/cli.md

@@ -14,7 +14,7 @@ SkillPort provides a command-line interface for managing [Agent Skills](https://
   - [remove](#skillport-remove) - Remove skills
   - [lint](#skillport-lint) - Validate skills
   - [serve](#skillport-serve) - Start MCP server
-  - [sync](#skillport-sync) - Sync to AGENTS.md
+  - [doc](#skillport-doc) - Generate AGENTS.md
 - [Exit Codes](#exit-codes)
 - [Configuration](#configuration)
 
@@ -44,7 +44,7 @@ Precedence: CLI flag > environment variable (`SKILLPORT_SKILLS_DIR` / `SKILLPORT
 
 ### skillport init
 
-Initialize SkillPort for a project. Creates configuration and syncs skills to instruction files.
+Initialize SkillPort for a project. Creates configuration and generates skills to instruction files.
 
 ```bash
 skillport init [options]
@@ -122,7 +122,7 @@ instructions:
   - GEMINI.md
 ```
 
-The `instructions` list is used by `skillport sync --all` to update all files at once.
+The `instructions` list is used by `skillport doc --all` to update all files at once.
 
 ---
 
@@ -525,12 +525,12 @@ skillport serve
 
 ---
 
-### skillport sync
+### skillport doc
 
-Sync installed skills to instruction files (AGENTS.md, etc.).
+Generate skill documentation for instruction files (AGENTS.md, etc.).
 
 ```bash
-skillport sync [options]
+skillport doc [options]
 ```
 
 #### Options
@@ -558,32 +558,32 @@ skillport sync [options]
 #### Examples
 
 ```bash
-# Sync all skills to ./AGENTS.md
-skillport sync
+# Generate skill docs to ./AGENTS.md
+skillport doc
 
 # Update all instruction files from .skillportrc
-skillport sync --all
+skillport doc --all
 
-# Sync to specific file
-skillport sync -o .claude/AGENTS.md
+# Generate to specific file
+skillport doc -o .claude/AGENTS.md
 
 # Force overwrite without confirmation
-skillport sync -f
+skillport doc -f
 
 # Filter by category
-skillport sync --category development,testing
+skillport doc --category development,testing
 
 # Filter by skill IDs
-skillport sync --skills pdf,code-review
+skillport doc --skills pdf,code-review
 
 # Use markdown format (no XML tags)
-skillport sync --format markdown
+skillport doc --format markdown
 
 # Generate for MCP-enabled agents
-skillport sync --mode mcp
+skillport doc --mode mcp
 
 # Replace entire file instead of appending
-skillport sync --replace
+skillport doc --replace
 ```
 
 #### Output Format

src/skillport/interfaces/cli/app.py

@@ -8,7 +8,7 @@
 - remove: Uninstall skills
 - lint: Validate skill definitions
 - serve: Start MCP server
-- sync: Sync skills to AGENTS.md for non-MCP agents
+- doc: Generate skill documentation for AGENTS.md
 """
 
 from pathlib import Path
@@ -26,7 +26,7 @@
 from .commands.list import list_cmd
 from .commands.lint import lint
 from .commands.serve import serve
-from .commands.sync import sync
+from .commands.doc import doc
 from .commands.init import init
 from .theme import VERSION, console
 from .auto_index import should_auto_reindex
@@ -182,14 +182,14 @@ def main(
 )(serve)
 
 app.command(
-    "sync",
-    help="Sync skills to AGENTS.md for non-MCP agents.\n\n"
+    "doc",
+    help="Generate skill documentation for AGENTS.md.\n\n"
          "[bold]Examples:[/bold]\n\n"
-         "  skillport sync\n\n"
-         "  skillport sync --all\n\n"
-         "  skillport sync -o .claude/AGENTS.md\n\n"
-         "  skillport sync --category development,testing",
-)(sync)
+         "  skillport doc\n\n"
+         "  skillport doc --all\n\n"
+         "  skillport doc -o .claude/AGENTS.md\n\n"
+         "  skillport doc --category development,testing",
+)(doc)
 
 
 def run():

src/skillport/interfaces/cli/commands/sync.py → src/skillport/interfaces/cli/commands/doc.py

@@ -1,6 +1,6 @@
-"""Sync installed skills to AGENTS.md for non-MCP agents.
+"""Generate skill documentation for AGENTS.md.
 
-Implements SPEC2-CLI Section 3.2: sync コマンド.
+Implements SPEC2-CLI Section 3.2: doc コマンド.
 Generates a skills block that can be embedded in AGENTS.md files.
 """
 
@@ -37,7 +37,7 @@ def _truncate_description(desc: str, max_len: int = 50) -> str:
 
 ### Workflow
 
-1. **Find a skill** - Check the table below for a skill matching your task
+1. **Find a skill** - Check the list below for a skill matching your task
 2. **Get instructions** - Run `skillport show <skill-id>` to load full instructions
 3. **Follow the instructions** - Execute the steps using your available tools
 
@@ -91,31 +91,22 @@ def generate_skills_block(
     """
     lines = [MARKER_START]
 
-    if format == "xml":
-        lines.append("<available_skills>")
-        lines.append("")
-
     # Instructions first (most important for agents)
     instructions = MCP_INSTRUCTIONS if mode == "mcp" else CLI_INSTRUCTIONS
     lines.append(instructions)
     lines.append("")
 
-    # Skills table
-    lines.append("### Available Skills")
-    lines.append("")
-    lines.append("| ID | Description | Category |")
-    lines.append("|----|-------------|----------|")
+    # Skills list wrapped in <available_skills> tag (xml format only)
+    if format == "xml":
+        lines.append("<available_skills>")
 
     for skill in skills:
         skill_id = skill.id
-        # Clean description (normalize whitespace, escape pipes)
+        # Clean description (normalize whitespace)
         desc = " ".join(skill.description.split())
-        desc = desc.replace("|", "\\|")
-        cat = skill.category or "-"
-        lines.append(f"| {skill_id} | {desc} | {cat} |")
+        lines.append(f"- `{skill_id}`: {desc}")
 
     if format == "xml":
-        lines.append("")
         lines.append("</available_skills>")
 
     lines.append(MARKER_END)
@@ -162,15 +153,15 @@ def update_agents_md(
         return True
 
 
-def sync(
+def doc(
     ctx: typer.Context,
     output: Path = typer.Option(
         Path("./AGENTS.md"),
         "--output",
         "-o",
         help="Output file path",
     ),
-    sync_all: bool = typer.Option(
+    doc_all: bool = typer.Option(
         False,
         "--all",
         "-a",
@@ -209,7 +200,7 @@ def sync(
         help="Overwrite without confirmation",
     ),
 ):
-    """Sync skills to AGENTS.md for non-MCP agents."""
+    """Generate skill documentation for AGENTS.md."""
     # Validate format
     if format not in ("xml", "markdown"):
         console.print(f"[error]Invalid format: {format}. Use 'xml' or 'markdown'.[/error]")
@@ -254,7 +245,7 @@ def sync(
     block = generate_skills_block(skills, format=format, mode=mode)
 
     # Determine output files
-    if sync_all:
+    if doc_all:
         # Use instruction files from project config
         if not project_config.instructions:
             console.print(
@@ -282,4 +273,4 @@ def sync(
 
         # Update file
         update_agents_md(out_path, block, append=append)
-        console.print(f"[success]Synced {len(skills)} skill(s) to {out_path}[/success]")
+        console.print(f"[success]Generated {len(skills)} skill(s) to {out_path}[/success]")

src/skillport/interfaces/cli/commands/init.py

@@ -12,7 +12,7 @@
 from skillport.modules.indexing import build_index
 from skillport.modules.skills import list_skills
 from ..context import get_config
-from .sync import generate_skills_block, update_agents_md
+from .doc import generate_skills_block, update_agents_md
 from ..theme import console, print_banner
 
 # Default choices for interactive mode

tests/conftest.py

@@ -0,0 +1,19 @@
+"""Shared pytest fixtures for SkillPort tests."""
+
+from pathlib import Path
+
+import pytest
+
+from skillport.shared.config import Config
+
+
+@pytest.fixture
+def test_config(tmp_path: Path) -> Config:
+    """Create a Config that uses temporary directories.
+
+    This ensures tests don't pollute ~/.skillport/ with indexes or metadata.
+    """
+    return Config(
+        skills_dir=tmp_path / "skills",
+        db_path=tmp_path / "index" / "skills.lancedb",
+    )