Claude Code Instructions — SkillTree

You are the lead engineer building SkillTree, a real, installable VS Code extension to discover, organize, install, and track Claude Code skills.

Read README.md completely before implementing anything. It is the product specification and includes phased acceptance criteria. Read DESIGN_SYSTEM.md for the selected Quiet Workbench aesthetic; implement it as the default UI direction, not as a separate optional theme.

Immediate task

Start implementing Phase 1 now. Do not stop after producing a plan or a design mockup. Create the actual files, run the build/tests, fix issues, and leave a runnable extension. Only proceed to the later phases when the earlier phase works.

Prioritize a clean, attractive, functional product. Do not build a web app as the product; React is allowed only inside a locally bundled VS Code webview. Do not begin with a marketing landing page.

Technical approach

• Target desktop VS Code using TypeScript and the official Extension API.
• Contribute a SkillTree Activity Bar icon and sidebar. Use native Tree View for compact hierarchical items where useful, and a webview editor panel for a visually rich, interactive skill graph.
• Bundle the React UI with Vite. For graph interactions, try @xyflow/react. Use VS Code theme CSS variables and respect accessibility/reduced motion.
• Extension host does privileged operations (filesystem, network, install). The React webview must not receive filesystem access or execute arbitrary external scripts; communicate with typed message contracts.
• Start with filesystem-backed project and personal skills. Parse real SKILL.md metadata. Avoid duplicate entries and distinguish scopes.
• Store organization metadata separately. Never silently rewrite a skill's Markdown instructions.
• Local skill discovery must work without network access and without Claude Code running.
• Marketplace: use a versioned static catalog generated by a scheduled GitHub indexer. Don't require a production backend for the MVP. A sample catalog is acceptable temporarily if labeled.
• Skill installer: explicit confirmation, project/global scope, pinned commit, file preview, path checks, collision handling, cancellation, rollback, no code execution.
• Usage tracking: opt-in only. Confirm actual current Claude hooks semantics against https://code.claude.com/docs/en/hooks, including PreToolUse for the Skill tool and UserPromptExpansion for directly typed slash commands. Don't guess about hidden Claude activity.

Implementation order

1. Scaffold a runnable extension and verify the F5 Extension Development Host cycle.
2. Implement local skill scanner, frontmatter parser, and workspace/global scope types.
3. Add the Activity Bar/sidebar and full Skill Tree graph with real data.
4. Add skill details, search/filter, open-on-disk, and persisted categories/graph positions.
5. Add tests and fix all errors in Phase 1.
6. Add marketplace UI backed by sample validated JSON.
7. Implement GitHub catalog indexer, scheduled workflow, JSON hosting/caching, and safe install flow.
8. Add opt-in activity instrumentation and timeline.
9. Add .vsix packaging; only afterwards discuss website/publishing.

UI quality bar

Visual mandate: Follow DESIGN_SYSTEM.md. Use the selected Quiet Workbench direction. This must look like an honest, compact, precise VS Code tool (similar density and conventions to native editor panels), not an RPG, constellation, sci-fi dashboard or AI-generated marketing concept. Default to theme variables, 1px gray dividers/graph edges, small category indicators, rectangular nodes and 4–6px radii. Avoid glowing/pulsing nodes, purple outlines, liquid glass, fake session stats, dramatic shadows, excess padding and unnecessary gradients. Keep dark, light and high-contrast themes usable. No imaginary data in the UI.

Required graph semantics: organization edges are solid; activity/co-usage edges (only when captured) are dashed; suggested relationships, if implemented, are dotted. Label these states and show a legend. A displayed relationship is not necessarily proof of causal impact.

The app should resemble a well-crafted professional developer extension: compact sidebar, legible node graph, readable details panel, tiny muted category markers, thin edges, smooth pan/zoom, good empty/loading/error states, theme support, accessible focus, and no fake "usage" counts or placeholder GitHub rankings.

Keep the sidebar lightweight. The Skill Tree and Marketplace should be full editor panels for enough room to inspect and interact.

Safety and correctness

• Public repository content is untrusted. Never execute a GitHub skill while indexing, previewing, or installing.
• Validate file path containment and enforce per-file/total-size limits. Reject traversal and unsafe symlinks. Avoid extracting arbitrary tarballs without inspection.
• Never overwrite or delete existing skill files without explicit confirmation. Respect managed/synced/bundled skills as read-only.
• Use a restrictive webview Content Security Policy and safe rendering for Markdown.
• Don't log or upload code/prompts. Keep activity metadata local; tracking requires opt-in and reversible setup.
• Don't imply that skills were used based on their mere presence. Keep direct recorded events distinct from inferred Git/files correlations.
• Read workspace trust status and avoid modifying untrusted workspaces.
• Don't invent marketplace source URLs, ratings, download counts, or licenses.
• Prefer a working thin slice to extensive speculative architecture.

Tests and developer experience

Include tests for:

• Parsing valid/invalid SKILL.md files and missing frontmatter.
• Scanning project/global skills and handling duplicate names.
• Filtering/searching graph data.
• Catalog schema validation and offline cache behavior.
• Safe installer path validation and existing-file collision behavior.
• Hook event parsing (in phase 3).

Add scripts for npm run build, npm test, and npm run package (VSIX) once supported. Run them; document actual results. Do not claim a test passed if you did not run it.

How to communicate progress

Work in small, reviewable increments. After each phase, give a concise summary of what changed, how to launch it, what was verified, and what remains. Ask only for truly necessary credentials or publishing permissions. Do not ask for basic UI/product choices when reasonable defaults are specified in README.

Definition of first success: F5 opens an extension development window, SkillTree appears in the Activity Bar, scanning a real local SKILL.md creates a node, and clicking that node opens its actual file.