refactor: address all code review issues

.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -83,9 +83,7 @@ A zero-dependency Python script that converts your skills directory into a Hiera
 ### Step 1: Run the Setup Script
 Download and run `setup.py`. It automatically categorizes your skills into expert domains (e.g., `ai-ml`, `security`, `frontend`, `automation`) using a keyword heuristic engine.
 
-By default, the script targets OpenCode. You can specify Claude Code using the `--agent` flag:
-
-**For OpenCode:**
+**For OpenCode (default):**
 ```bash
 python setup.py
 # Targets: ~/.config/opencode/skills
@@ -98,6 +96,28 @@ python setup.py --agent claude
 # Targets: ~/.claude/skills
 # Vault: ~/.skillpointer-vault
 ```
+
+**Custom Directories:**
+```bash
+python setup.py --skill-dir ~/.agents/skills --vault-dir ~/.skillpointer-vault
+```
+
+**Preview Changes (Dry Run):**
+```bash
+python setup.py --dry-run
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--agent {opencode,claude}` | Target AI agent (default: opencode) |
+| `--skill-dir PATH` | Custom skills directory (overrides --agent) |
+| `--vault-dir PATH` | Custom vault directory (overrides --agent) |
+| `--dry-run` | Preview changes without making them |
+| `--version` | Show version number |
+| `--help` | Show help message |
+
 *(Note for Claude Code: The `.skillpointer-vault` directory is intentionally prefixed with a dot so Claude's aggressive file scanner natively skips it during Level 1 context hydration).*
 
 ### Step 2: Test It!
@@ -173,6 +193,31 @@ No custom tools, no plugins, no API calls. Just smart organization of native ski
 
 ---
 
+## 🧪 Development & Testing
+
+Run the test suite:
+
+```bash
+# Create virtual environment
+uv venv .venv && source .venv/bin/activate
+
+# Install dev dependencies
+uv pip install pytest
+
+# Run tests
+python -m pytest tests/ -v
+```
+
+Run linting and type checking:
+
+```bash
+uv pip install ruff mypy
+ruff check setup.py
+mypy setup.py
+```
+
+---
+
 <details>
 <summary><b>View Star History</b></summary>
 <br>

pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "skillpointer"
+version = "1.1.0"
+description = "Infinite AI Context. Zero Token Tax."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "SkillPointer Contributors"}
+]
+keywords = ["ai", "skills", "context", "opencode", "claude"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.scripts]
+skillpointer = "setup:main"
+
+[project.urls]
+Homepage = "https://github.com/blacksiders/SkillPointer"
+Repository = "https://github.com/blacksiders/SkillPointer"
+Issues = "https://github.com/blacksiders/SkillPointer/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+
+[tool.ruff.per-file-ignores]
+"tests/*" = ["B011"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = ["pytest"]
+ignore_missing_imports = true