Compare commits

..
Author SHA1 Message Date
Rohit Ghumare 2b63b37ee6 fix: address CodeRabbit and Devin review findings for skills.sh integration
- Fix path traversal vulnerability in SkillsShProvider.clone (validate subpath containment)
- Fix federated search skipped for interactive queries (use searchTerm instead of this.query)
- Guard showSkillsShStats to skip network call for local providers
- Replace deprecated npm --production with --omit=dev
- Fix loose includes() match in getSkillStats to use strict endsWith()
- Fix FederatedSearch resilience: don't re-throw RateLimitError, return partial results
- Forward timeoutMs through FederatedSearch to registries
- Extract shared formatCount utility to helpers.ts (deduplicate find.ts/install.ts)
- Fix install hint to use skill.source instead of fragile skill.description
- Fix timer leak in fetchLeaderboard using finally block
- Deduplicate URL parsing via shared parseSkillsShParts helper
- Validate --agent flag values against known agent types
2026-02-22 21:38:39 +05:30
Rohit Ghumare 57b29014ec feat: integrate skills.sh as first-class registry
Add SkillsShRegistry and SkillsShProvider so users can install skills
directly from skills.sh (e.g. `skillkit install skills.sh/owner/repo/skill`).
The find command now searches skills.sh by default alongside the local
marketplace. Post-install shows skills.sh popularity stats and pro tips
highlighting skillkit's unique features (translate, recommend, evaluate).
2026-02-22 21:38:39 +05:30
Rohit Ghumare 39b94534ec chore: release v1.19.2 2026-02-20 00:16:28 +05:30
Rohit Ghumare aeb2b05f15 fix: update composioHQ repo name from awesome-claude-code-skills to awesome-claude-skills (#73)
Closes #72
2026-02-17 19:28:39 +00:00
Rohit Ghumare 5991fead9b fix: compact Features grid — 3 cols mobile, 4 cols desktop 2026-02-14 16:08:19 +05:30
Rohit Ghumare 1d3a779c2e fix: show Docs link on mobile nav (#71)
* chore: migrate domain from agenstskills.com to skillkit.sh

Update all OG/Twitter meta tags, API endpoints, docs links, badge
URLs, privacy policy, extension store listing, and README references
to use skillkit.sh. Both skillkit.sh and agenstskills.com are treated
as equal domains — privacy policy, store listing, and docs reference
both.

* perf: skip Vercel builds when docs unchanged

Add ignoreCommand to both docs/skillkit and docs/fumadocs vercel.json.
Vercel will skip rebuilds when the respective docs folder has no
changes, saving ~1h+ of build minutes per billing cycle.
2026-02-14 10:31:26 +00:00
Rohit Ghumare 2fe4702bd6 chore: migrate domain to skillkit.sh (#70)
* chore: migrate domain from agenstskills.com to skillkit.sh

Update all OG/Twitter meta tags, API endpoints, docs links, badge
URLs, privacy policy, extension store listing, and README references
to use skillkit.sh. Both skillkit.sh and agenstskills.com are treated
as equal domains — privacy policy, store listing, and docs reference
both.

* perf: skip Vercel builds when docs unchanged

Add ignoreCommand to both docs/skillkit and docs/fumadocs vercel.json.
Vercel will skip rebuilds when the respective docs folder has no
changes, saving ~1h+ of build minutes per billing cycle.
2026-02-14 10:24:08 +00:00
Rohit Ghumare 28ed83deb0 chore: release v1.19.1 2026-02-14 14:24:41 +05:30
Rohit Ghumare 7c4ee9cfef refactor: simplify homepage by removing 5 sections and adding docs CTA (#69)
Remove WhySkillKit, StackBuilder, BadgeGenerator, Commands, and
TeamEnterprise sections to streamline the landing page from 14 to 9
sections. Replace Extension nav link with Docs, remove duplicate Docs
link, and add a lightweight docs CTA between AdvancedFeatures and
UseCases.
2026-02-14 07:50:00 +00:00
Rohit Ghumare 64cafc76a1 feat: add TUI screens for session intelligence (timeline, lineage, handoff) (#68)
Wire up 3 new screens from PR #65's session intelligence commands into the TUI with
keyboard navigation (l=timeline, v=lineage, f=handoff) and a new Session sidebar section.
2026-02-14 07:33:01 +00:00
Rohit Ghumare 7e3b31b43b feat: add session intelligence — timeline, handoff, and lineage (#65)
* feat: add session intelligence — timeline, handoff, and lineage commands

Three new skill-centric session intelligence features:
- `skillkit timeline` — unified chronological event stream merging skill executions, git commits, observations, decisions, and snapshots
- `skillkit session handoff` — generates structured markdown for agent-to-agent context transfer with accomplished/pending tasks, key files, observations, and recommendations
- `skillkit lineage` — tracks skill impact graph connecting skills to files, commits, and observations with aggregate stats

Includes 44 tests, updated docs/website to reflect 44 agents, and CodeRabbit review fixes (defensive access, type validation, double-count prevention).

* fix: address CodeRabbit review round 2

- Fix primer.mdx example: "29 more agents" → "41 more agents"
- Validate invalid since date in timeline (return empty instead of silent filter-all)
- Guard hist.durationMs with Number.isFinite before formatting
- Fix misleading "commits" label → "changes" for activity log entries
2026-02-14 07:11:44 +00:00
Rohit Ghumare ff089429ae feat: redesign website with aggregator positioning (#67)
* feat: redesign website with aggregator positioning and competitor landscape

- Add WhySkillKit section with competitor comparison table (Vercel skills, PRPM, Askill, Skild, Paks)
- Show SkillKit as meta-package manager aggregating 31+ sources, not competing with them
- Add source grid showing all curated repositories (Anthropic, Vercel, Expo, Supabase, Stripe, etc.)
- Update Hero tagline: "One CLI. Every Source. Every Agent. Zero Telemetry."
- Fix agent count from 32 to 44 in Features stats
- Reframe comparison table: "Simple Installers" vs "SkillKit" instead of vague "Without"
- Update CompatibilityMatrix with all 44 agents (was 16)
- Add zero-telemetry, Apache 2.0, no-account trust signals
- Update nav to include "Why SkillKit" link

* feat: update terminal demo to showcase aggregator workflow

Show install from multiple sources (Anthropic, Vercel), auto-translation
to 44 formats, security scanning, and cross-source recommendations.

* feat: update promo video with aggregator positioning

Updated Remotion video to reflect SkillKit's meta-package manager identity:
- Version bumped from v1.7.5 to v1.19.0 across all scenes
- Install scene shows multi-source aggregation + security scan
- Find scene searches 31+ sources (15K+ skills)
- Translate scene shows cross-source bulk translation
- Workflow scene replaced with security scanner (46 rules)
- Recommend scene shows cross-source recommendations with source labels
- TUI scene updated with source attribution and 44 agents
- Manifest scene shows multi-source team sync
- Logo scene: "One CLI. Every Source. Every Agent." + "Zero Telemetry"
- Agent count updated from "17 agents" to "44 agents | 31+ sources | 15K+ skills"
2026-02-14 07:10:35 +00:00
Rohit Ghumare 6c3cecec4d chore: add v1.19.0 extension zip and remove old one 2026-02-14 11:48:52 +05:30
Rohit Ghumare 8ed4ada674 chore: release v1.19.0 2026-02-14 11:33:57 +05:30
Rohit Ghumare 514de86727 feat: server-side save-skill API for Chrome extension (#66)
* feat: move extension save-skill to server-side API

Chrome Web Store rejected the content script approach since it doesn't
inject on pre-existing tabs. Move webpage-to-skill conversion from
client-side to a server-side API route that uses Turndown + weighted
tag detection, eliminating the need for content scripts entirely.

- Add POST /api/save-skill route with SSRF protection and rate limiting
- Rewrite extension to call API with tab URL instead of injecting scripts
- Remove content script, scripting permission, and turndown dependency
- Add name field validation and YAML-escape source URLs
- Bump extension manifest to v1.18.0

* fix: update privacy policy and store listing for server-side save

Privacy policy previously stated "no external requests" which is now
inaccurate. Updated to clearly disclose that the page URL is sent to
agenstskills.com for processing, what data is NOT sent, and that
nothing is stored server-side.

Store listing updated to match: removed "no server" claims, added
data flow explanation, permissions justifications, and data usage
disclosure section for the Chrome Web Store Privacy tab.

* fix: address Devin and CodeRabbit review findings

- Fix SSRF IPv6 checks blocking legit domains (ffmpeg.org, fdroid.org)
  by requiring colon in fc00:/ff prefixes (Devin)
- Add 5MB response body size limit to prevent OOM on large pages,
  applied to both extractFromUrl and fetchGitHubContent (CodeRabbit)
- Guard response.json() in callSaveApi against non-JSON error pages
  from proxies returning HTML 502/504 (CodeRabbit)
- YAML-escape source URL in buildSelectionSkill to match server-side
  handling of URLs with #, :, or query strings (CodeRabbit)
2026-02-14 06:00:28 +00:00
Rohit Ghumare bf5903bf7f chore: release v1.18.0 2026-02-11 20:50:49 +00:00
Rohit Ghumare aafa086314 feat: add skillkit doctor command and enhance skillkit status (#64)
* feat: add `skillkit doctor` command and enhance `skillkit status`

- New `skillkit doctor` command with 10 health checks across 3 categories
  (environment, configuration, skills) with --json and --fix flags
- Enhanced `skillkit status` shows project overview dashboard when no
  active session exists instead of bare "No active session found" message
- Overview includes agent, config, version, skills count, recent history

* feat: add skill activity log, session snapshots, and session explain

Three new session intelligence features:

- Activity Log: tracks which skills were active per git commit
  (`skillkit activity` with --skill, --limit, --json flags)
- Session Snapshots: save/restore named snapshots of session state
  (`skillkit session snapshot save|restore|list|delete`)
- Session Explain: structured summary of current session
  (`skillkit session explain` with --json, --no-git flags)

Includes path traversal protection on snapshot names, YAML validation
on parsed activity data, and robust error handling on snapshot restore.

983 tests passing (942 core + 41 CLI including 14 E2E tests).

* feat: add issue planner - generate plans from GitHub Issues

New `skillkit issue plan` and `skillkit issue list` commands that
fetch GitHub Issues via `gh` CLI and generate StructuredPlans.
Parses checkboxes, file mentions, and labels from issue body.
29 new tests, all passing.

* fix: address CodeRabbit review suggestions for PR #64

- doctor.ts: use execFileSync, typed AgentType, remove as-any casts
- activity.ts: validate parseInt with radix and NaN guard
- issue.ts: wrap JSON.parse in try/catch for gh CLI output
- issue-planner.ts: guard JSON.parse, fix includeTests no-op ternary,
  remove duplicate IssuePlanMetadata (import from types.ts)
- status.ts: typed StatusOverview interface, remove as-any casts
- snapshot-manager.ts: align observations param with SessionSnapshot type
- session.ts: proper type mapping for observations (no double cast)
- activity-log.ts: min-length guard for SHA prefix match
- e2e tests: use top-level imports instead of inline require()
- commands.test.ts: add assertions for DoctorCommand, IssuePlanCommand,
  IssueListCommand

* fix: address review feedback from CodeRabbit and Devin

- Include test step in no-checklist fallback when includeTests is true
- Restore observations from snapshot in SessionSnapshotRestoreCommand

* fix: address remaining CodeRabbit and Devin review feedback

- doctor.ts: Use getAdapter() per AgentType instead of getAllAdapters()
  spread (which destroys prototype methods like isDetected)
- doctor.ts: Use getGlobalSkillsDir() from AGENT_CONFIG instead of
  hardcoded path formula
- session-explainer.ts: Defensively default state.history and
  state.decisions to empty arrays
- session-explainer.ts: Use loadConfig().agent with skillSource fallback
  instead of always using skillSource as agent name
- observation-store.ts: Add static readAll() that reads observations
  without sessionId mismatch clearing
- session.ts: Use ObservationStore.readAll() for snapshot save to avoid
  empty observations due to sessionId mismatch
2026-02-11 20:26:51 +00:00
Rohit Ghumare 344f081664 feat: add privacy policy page for Chrome Web Store compliance 2026-02-11 17:56:38 +00:00
Rohit Ghumare 86c1e5d8f9 chore: release v1.17.0 2026-02-10 11:21:57 +00:00
Rohit Ghumare 9930096242 fix: MCP server fails to start via npx (#58) (#63)
* fix: MCP server fails to start via npx — symlink + skills.json issues

1. isMain guard: process.argv[1] (symlink path) never matched
   import.meta.url (real path). Fixed with realpathSync comparison.

2. skills.json not in npm package: prebuild copies marketplace/skills.json
   to data/ dir, included in package files.

3. Version string bumped from 1.12.0 to 1.16.0.

Closes #58

* fix: guard realpathSync against undefined argv and resolve both paths

- Wrap in try/catch so library imports don't crash
- Check process.argv[1] exists before calling realpathSync
- Also resolve import.meta.url with realpathSync for pnpm/hoisted setups
2026-02-10 11:13:05 +00:00
Rohit Ghumare 24ff833265 feat: Chrome extension — Save any webpage as a Skill (#62)
* fix: remove redundant GitHub Star button from Hero section

Star count is already visible in navbar and stats bar on all screen sizes.

* fix: keep GitHub Star button on mobile, hide on desktop

Star button uses sm:hidden so it only appears on mobile where
the navbar star badge is less prominent. On desktop (sm+), the
navbar star badge is sufficient.
2026-02-10 10:13:47 +00:00
Rohit Ghumare 12ac7356f8 docs: add Chrome extension to website, fumadocs, and README (#61)
- Website Hero: "Add to Chrome" button (white, high contrast) between
  install command and GitHub star button
- Website navbar: "Extension" link in desktop nav
- Fumadocs: new chrome-extension.mdx page with install, usage,
  architecture, permissions, and build docs
- README: Chrome extension section + link in header nav
- Extension README: setup and usage guide
2026-02-10 09:57:51 +00:00
Rohit Ghumare 53b3f4f839 feat: add Chrome extension to save webpages as skills (#60)
Fully browser-based — no local server required. Content script extracts
page content as markdown (Turndown), background generates SKILL.md with
frontmatter and auto-tags, and downloads via chrome.downloads API.

- Manifest V3 with contextMenus, activeTab, downloads permissions
- Content script: HTML-to-markdown via Turndown, extracts article/main
- Background: SKILL.md generation (slugify, YAML frontmatter, tag detection)
- Downloads to skillkit-skills/{name}/SKILL.md in browser Downloads folder
- Monochromatic popup UI matching website design system
- Context menu: "Save page as Skill" / "Save selection as Skill"
- POST /save API endpoint still available for CLI users
2026-02-10 09:49:52 +00:00
Rohit Ghumare 896eff184c feat: standards reference implementation — URL-to-Skill, AGENTS.md, spec validation (#59)
* feat: implement standards reference — URL-to-Skill, AGENTS.md, spec validation

Phase 1-4 of positioning SkillKit as THE runtime implementing all three
AI agent skill standards (Agent Skills, AGENTS.md, well-known discovery).

New modules:
- save/ — ContentExtractor, SkillGenerator, AutoTagger for URL-to-Skill
- agents-md/ — AGENTS.md generator with managed section markers
- validation/ — SpecValidator with strict mode for agentskills.io compliance

New CLI commands:
- `skillkit save <url>` — save any URL/text/file as a reusable SKILL.md
- `skillkit agents init|sync|show` — generate and manage AGENTS.md

Updated:
- Well-known provider: Mintlify convention paths, discoverFromUrl()
- Install command: smart URL fallback (well-known → offer save)
- Remove command: auto-updates AGENTS.md on skill removal
- Validate command: --strict flag for spec compliance checks
- Quality module: name-directory match + token budget warnings
- Schema: agents enum updated from 7 → 44 agents

* fix: address Devin review — register AgentsMd commands, fix temp dir leak, wrap AGENTS.md update

- Register AgentsMdCommand/Init/Sync/Show in CLI entry point (were exported but never registered)
- Clean up tempDir in wellknown clone() when no skills found via index or mintlify
- Wrap AGENTS.md auto-update in install.ts with try-catch to prevent masking successful installs

* fix: address CodeRabbit review findings

- wellknown.ts: drop multiline flag from frontmatter regex, extract skill name
  from URL path segments instead of basename on full URL
- agents-md.ts: wrap init/sync in try-catch for user-friendly error messages
- publish.ts: add path-traversal guard to mintlify branch
- validate.ts: remove duplicate error/warning output in spec report
- extractor.ts: add 30s AbortSignal timeout to all fetch calls
- skill-generator.ts: fix .filter(Boolean) stripping blank line after frontmatter
2026-02-10 09:05:49 +00:00
Rohit Ghumare 407e8215f2 fix: stack ASCII and PH badge vertically on mobile, hide ASCII below sm 2026-02-09 23:16:18 +00:00
Rohit Ghumare dd4ec56a1a fix: show ASCII logo on mobile, use B&W Product Hunt badge 2026-02-09 21:58:30 +00:00
Rohit Ghumare e9bb9fbd0d fix: add separate mobile PH badge, fix visibility on small screens 2026-02-09 21:53:01 +00:00
Rohit Ghumare ee54bf1545 fix: show Product Hunt badge on mobile, remove duplicate from nav 2026-02-09 21:43:57 +00:00
Rohit Ghumare f097ec7ad7 style: add Product Hunt badge next to ASCII logo on website hero 2026-02-09 21:38:32 +00:00
152 changed files with 14309 additions and 624 deletions
+1 -1
View File
@@ -35,7 +35,7 @@ assignees: rohitg00
- [ ] Repository is public
- [ ] Repository contains valid SKILL.md files
- [ ] Repository has a clear license
- [ ] Skills follow the [Agent Skills specification](https://agenstskills.com)
- [ ] Skills follow the [Agent Skills specification](https://skillkit.sh)
## Additional Context
+1 -1
View File
@@ -83,7 +83,7 @@ body:
options:
- label: Repository is public
required: true
- label: SKILL.md follows the agenstskills.com standard format
- label: SKILL.md follows the skillkit.sh standard format
required: true
- label: Skill has been tested with at least one AI agent
required: false
+1
View File
@@ -65,3 +65,4 @@ skillkit.yaml
CLAUDE.md
prd.md
.vercel
packages/extension/store-assets/skillkit-extension.zip
+1 -1
View File
@@ -206,7 +206,7 @@ To add support for a new AI coding agent:
If you want to contribute skills to the ecosystem:
1. Follow the [Agent Skills specification](https://agenstskills.com)
1. Follow the [Agent Skills specification](https://skillkit.sh)
2. Include a `SKILL.md` with proper frontmatter
3. Test with multiple agents using `skillkit translate`
4. Submit to the appropriate skill repository
+35 -5
View File
@@ -17,7 +17,7 @@
**SkillKit** is the open source package manager for AI agent skills. Write a skill once, deploy it to **44 agents** — Claude, Cursor, Copilot, Windsurf, Devin, Codex, and 38 more. No rewrites. 15,000+ skills in the marketplace.
[Website](https://agenstskills.com) &middot; [Docs](https://agenstskills.com/docs) &middot; [API Explorer](https://agenstskills.com/api) &middot; [npm](https://www.npmjs.com/package/skillkit)
[Website](https://skillkit.sh) &middot; [Docs](https://skillkit.sh/docs) &middot; [API Explorer](https://skillkit.sh/api) &middot; [Chrome Extension](https://github.com/rohitg00/skillkit/tree/main/packages/extension#readme) &middot; [npm](https://www.npmjs.com/package/skillkit)
</div>
@@ -125,7 +125,7 @@ async with SkillKitClient() as client:
results = await client.search("react performance", limit=5)
```
[REST API docs](https://agenstskills.com/docs/rest-api) &middot; [MCP Server docs](https://agenstskills.com/docs/mcp-server) &middot; [Python Client docs](https://agenstskills.com/docs/python-client) &middot; [Interactive API explorer](https://agenstskills.com/api)
[REST API docs](https://skillkit.sh/docs/rest-api) &middot; [MCP Server docs](https://skillkit.sh/docs/mcp-server) &middot; [Python Client docs](https://skillkit.sh/docs/python-client) &middot; [Interactive API explorer](https://skillkit.sh/api)
### Auto-generate agent instructions
@@ -181,6 +181,18 @@ git commit -m "add team skills"
Team members run `skillkit manifest install` and they're in sync.
### Chrome Extension
Save any webpage as a skill directly from your browser.
1. Build: `pnpm --filter @skillkit/extension build`
2. Chrome → `chrome://extensions` → Load unpacked → `packages/extension/dist/`
3. Click the extension icon or right-click → "Save page as Skill"
The extension sends the page URL to the SkillKit API for server-side extraction with Turndown, 5-source weighted tag detection, and GitHub URL support. The resulting SKILL.md downloads automatically. Then run `skillkit install ~/Downloads/skillkit-skills/my-skill` to deploy to all agents.
[Extension docs](https://skillkit.sh/docs/chrome-extension)
### Interactive TUI
```bash
@@ -209,7 +221,7 @@ skillkit ui
Plus 33 more: Amp, Antigravity, Augment Code, Bolt, Clawdbot, Cline, CodeBuddy, CodeGPT, CommandCode, Continue, Crush, Droid, Factory, Goose, Kilo Code, Kiro CLI, Lovable, MCPJam, Mux, Neovate, OpenHands, Pi, PlayCode, Qoder, Qwen, Replit Agent, Roo Code, Tabby, Tabnine, Trae, Vercel, Zencoder, Universal
[Full agent details](https://agenstskills.com/docs/agents)
[Full agent details](https://skillkit.sh/docs/agents)
## Commands
@@ -234,6 +246,24 @@ skillkit find <query> # Quick search
skillkit scan <path> # Security scan for skills
```
### Issue Planner
```bash
skillkit issue plan "#42" # Plan from GitHub Issue
skillkit issue plan owner/repo#42 # Cross-repo plan
skillkit issue list # List open issues
```
### Session Intelligence
```bash
skillkit timeline # Unified event stream
skillkit session handoff # Agent-to-agent context
skillkit lineage # Skill impact graph
skillkit session explain # Human-readable summary
skillkit activity # Skill activity log
```
### Advanced
```bash
@@ -246,7 +276,7 @@ skillkit test # Test skills
skillkit cicd init # CI/CD templates
```
[Full command reference](https://agenstskills.com/docs/commands)
[Full command reference](https://skillkit.sh/docs/commands)
## Creating Skills
@@ -337,4 +367,4 @@ Apache License 2.0 — see [LICENSE](LICENSE).
## Links
[Documentation](https://agenstskills.com/docs) &middot; [Website](https://agenstskills.com) &middot; [API Explorer](https://agenstskills.com/api) &middot; [npm](https://www.npmjs.com/package/skillkit) &middot; [GitHub](https://github.com/rohitg00/skillkit)
[Documentation](https://skillkit.sh/docs) &middot; [Website](https://skillkit.sh) &middot; [API Explorer](https://skillkit.sh/api) &middot; [npm](https://www.npmjs.com/package/skillkit) &middot; [GitHub](https://github.com/rohitg00/skillkit)
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit",
"version": "1.16.0",
"version": "1.19.2",
"description": "Supercharge AI coding agents with portable skills. Install, translate, and share skills across Claude Code, Cursor, Codex, Copilot & 13 more",
"type": "module",
"bin": {
+36
View File
@@ -86,6 +86,12 @@ import {
SessionNoteCommand,
SessionCompleteCommand,
SessionInProgressCommand,
SessionSnapshotSaveCommand,
SessionSnapshotRestoreCommand,
SessionSnapshotListCommand,
SessionSnapshotDeleteCommand,
SessionExplainCommand,
ActivityCommand,
ProfileCommand,
ProfileListCommand,
ProfileCreateCommand,
@@ -104,6 +110,17 @@ import {
SkillMdCheckCommand,
ServeCommand,
ScanCommand,
DoctorCommand,
SaveCommand,
AgentsMdCommand,
AgentsMdInitCommand,
AgentsMdSyncCommand,
AgentsMdShowCommand,
IssuePlanCommand,
IssueListCommand,
TimelineCommand,
SessionHandoffCommand,
LineageCommand,
} from '@skillkit/cli';
const __filename = fileURLToPath(import.meta.url);
@@ -210,6 +227,12 @@ cli.register(SessionListCommand);
cli.register(SessionNoteCommand);
cli.register(SessionCompleteCommand);
cli.register(SessionInProgressCommand);
cli.register(SessionSnapshotSaveCommand);
cli.register(SessionSnapshotRestoreCommand);
cli.register(SessionSnapshotListCommand);
cli.register(SessionSnapshotDeleteCommand);
cli.register(SessionExplainCommand);
cli.register(ActivityCommand);
cli.register(ProfileCommand);
cli.register(ProfileListCommand);
@@ -233,5 +256,18 @@ cli.register(SkillMdCheckCommand);
cli.register(ServeCommand);
cli.register(ScanCommand);
cli.register(DoctorCommand);
cli.register(SaveCommand);
cli.register(AgentsMdCommand);
cli.register(AgentsMdInitCommand);
cli.register(AgentsMdSyncCommand);
cli.register(AgentsMdShowCommand);
cli.register(IssuePlanCommand);
cli.register(IssueListCommand);
cli.register(TimelineCommand);
cli.register(SessionHandoffCommand);
cli.register(LineageCommand);
cli.runExit(process.argv.slice(2));
+1 -1
View File
@@ -38,5 +38,5 @@ dev = [
[project.urls]
Homepage = "https://github.com/rohitg00/skillkit"
Documentation = "https://agenstskills.com"
Documentation = "https://skillkit.sh"
Repository = "https://github.com/rohitg00/skillkit"
@@ -0,0 +1,121 @@
---
title: Chrome Extension
description: Save any webpage as an AI agent skill from your browser
---
# Chrome Extension
Save any webpage as a SKILL.md directly from your browser.
## Install
1. Download the extension from the [releases page](https://github.com/rohitg00/skillkit/releases)
2. Open `chrome://extensions` in Chrome
3. Enable "Developer mode" (top right)
4. Click "Load unpacked" and select the `packages/extension/dist/` folder
Or build from source:
```bash
git clone https://github.com/rohitg00/skillkit.git
cd skillkit
pnpm install && pnpm --filter @skillkit/extension build
```
Then load `packages/extension/dist/` as an unpacked extension.
## Usage
### Popup
1. Navigate to any webpage
2. Click the SkillKit extension icon
3. Optionally enter a custom skill name
4. Click **Save as Skill**
The extension sends the page URL to the SkillKit API, which extracts the content as markdown, generates tags using weighted 5-source analysis, and returns a complete SKILL.md. The file downloads to your `Downloads/skillkit-skills/` folder.
### Context Menu
Right-click on any page:
- **Save page as Skill** — sends the URL to the API, downloads the result
- **Save selection as Skill** — builds the skill locally from selected text (no network request)
### Making Skills Available to Agents
After downloading, install the skill so all agents can use it:
```bash
skillkit install ~/Downloads/skillkit-skills/my-skill
```
Or copy directly:
```bash
cp -r ~/Downloads/skillkit-skills/my-skill ~/.skillkit/skills/
skillkit sync
```
## How It Works
```
Extension → POST /api/save-skill { url } → Server pipeline → Download
```
1. **Popup** reads the current tab's URL and title via `activeTab` permission. No content script injection needed.
2. **Background service worker** sends the URL to `skillkit.sh/api/save-skill` (or `agenstskills.com/api/save-skill`):
- Server fetches the page and converts HTML to markdown via Turndown
- GitHub URLs are auto-converted to raw content
- Tags are detected from 5 weighted sources (URL segments, headings, code blocks, keywords, language)
- Returns a complete SKILL.md with YAML frontmatter
3. **Download** — the service worker creates a blob and saves via `chrome.downloads` API.
4. **Selection saves** work entirely offline — Chrome natively provides `selectionText` via the context menu API, so the skill is built locally with no server round-trip.
## Permissions
| Permission | Why |
|-----------|-----|
| `contextMenus` | Right-click "Save as Skill" menu items |
| `activeTab` | Access current page URL and title on click |
| `downloads` | Save SKILL.md files to disk |
No `host_permissions` or `scripting` permissions needed. Only the page URL is sent to the server — no page content, browsing history, or personal data.
## Generated SKILL.md Format
```yaml
---
name: react-performance-tips
description: Optimizing React rendering with memo and useMemo
tags:
- react
- javascript
- testing
metadata:
source: https://example.com/react-performance
savedAt: 2026-02-14T09:00:00.000Z
---
# React Performance Tips
The extracted markdown content of the page...
```
## Building from Source
The extension uses tsup to bundle TypeScript into IIFE format for browser compatibility:
```bash
pnpm --filter @skillkit/extension build
```
Output goes to `packages/extension/dist/` with:
- `background.global.js` — Service worker (~4KB)
- `popup.global.js` — Popup UI logic (~2KB)
- `popup.html` + `popup.css` — Monochromatic UI
- `manifest.json` — Chrome Manifest V3
- `icons/` — 16/48/128px PNG icons
+95
View File
@@ -343,6 +343,101 @@ skillkit serve --cache-ttl 3600000
| GET | `/health` | Server health |
| GET | `/cache/stats` | Cache statistics |
## Issue Planner
Generate structured plans from GitHub Issues. Requires the `gh` CLI.
```bash
skillkit issue plan "#42" # Plan from current repo
skillkit issue plan rohitg00/skillkit#42 # Cross-repo
skillkit issue plan "#42" --agent cursor # Target specific agent
skillkit issue plan "#42" --no-tests # Skip test steps
skillkit issue plan "#42" --json # JSON output
skillkit issue plan "#42" --tech-stack react,ts # Override tech stack
```
### Issue Plan Options
| Option | Short | Default | Purpose |
|--------|-------|---------|---------|
| `--agent` | `-a` | `claude-code` | Target agent |
| `--output` | `-o` | `.skillkit/plans/issue-<n>.md` | Output file path |
| `--no-tests` | — | `false` | Skip test steps |
| `--json` | — | `false` | Output as JSON |
| `--tech-stack` | — | — | Comma-separated tech stack |
### Issue List
```bash
skillkit issue list # List open issues
skillkit issue list --repo owner/repo # Specific repo
skillkit issue list --label bug # Filter by label
skillkit issue list --limit 20 # More results
skillkit issue list --json # JSON output
```
The planner extracts task lists (checkboxes) from the issue body, infers file mentions from backtick-quoted paths, and maps labels to tags (e.g., `bug` → `fix`, `enhancement` → `feature`). Generated plans work with `skillkit plan validate` and `skillkit plan execute`.
## Session Intelligence
Track skill executions, generate handoff documents, and analyze skill impact.
### Timeline
View a unified chronological event stream of all session activity.
```bash
skillkit timeline # Last 50 events
skillkit timeline --type git_commit # Filter by event type
skillkit timeline --skill code-simplifier # Filter by skill
skillkit timeline --since 2026-02-10 # Date filter
skillkit timeline --limit 20 --json # JSON output
```
| Option | Short | Purpose |
|--------|-------|---------|
| `--type` | `-t` | Filter: skill_start, skill_complete, task_progress, git_commit, observation, decision, snapshot |
| `--skill` | `-s` | Filter events by skill name |
| `--since` | — | Show events since date (YYYY-MM-DD) |
| `--limit` | `-l` | Max events (default: 50) |
| `--json` | `-j` | JSON output |
### Session Handoff
Generate a structured context document for agent switching.
```bash
skillkit session handoff # Print markdown to stdout
skillkit session handoff --to cursor # Target agent recommendations
skillkit session handoff --out handoff.md # Save to file
skillkit session handoff --json # JSON output
```
| Option | Short | Purpose |
|--------|-------|---------|
| `--to` | — | Target agent for recommendations |
| `--out` | `-o` | Save to file path |
| `--json` | `-j` | JSON output |
### Lineage
Show which skills produced which code changes with aggregate impact stats.
```bash
skillkit lineage # Full overview
skillkit lineage --skill code-simplifier # Single skill
skillkit lineage --file src/index.ts # Single file
skillkit lineage --since 2026-02-01 --json # Date filter + JSON
```
| Option | Short | Purpose |
|--------|-------|---------|
| `--skill` | `-s` | Filter by skill name |
| `--file` | `-f` | Filter by file path |
| `--since` | — | Show lineage since date |
| `--limit` | `-l` | Max entries |
| `--json` | `-j` | JSON output |
## Utility Commands
```bash
+1 -1
View File
@@ -29,7 +29,7 @@ skillkit/
│ ├── core/ # Business logic
│ ├── cli/ # CLI
│ ├── tui/ # Terminal UI
│ └── agents/ # 32 adapters
│ └── agents/ # 44 adapters
├── marketplace/ # Skills data
│ ├── skills.json
│ └── sources.json
+11 -1
View File
@@ -124,6 +124,16 @@ skillkit memory search "auth patterns"
skillkit memory export auth-patterns
```
### Session Intelligence
Track skill executions, generate handoff documents for agent switching, and view skill impact lineage:
```bash
skillkit timeline # Unified event stream
skillkit session handoff # Agent-to-agent context
skillkit lineage # Skill impact graph
```
### Primer
Auto-generate CLAUDE.md, .cursorrules, and agent instructions by analyzing your codebase:
@@ -163,4 +173,4 @@ Team members run `skillkit manifest install` and they're in sync.
- [MCP Server](/docs/mcp-server) — Agent-native discovery
- [Python Client](/docs/python-client) — Python SDK
**Current version:** v1.12.0 | [npm](https://www.npmjs.com/package/skillkit) | [GitHub](https://github.com/rohitg00/skillkit) | Apache-2.0
**Current version:** v1.18.0 | [npm](https://www.npmjs.com/package/skillkit) | [GitHub](https://github.com/rohitg00/skillkit) | Apache-2.0
+1
View File
@@ -3,6 +3,7 @@
"pages": [
"index",
"installation",
"chrome-extension",
"quickstart",
"tui",
"skills",
+3 -3
View File
@@ -5,7 +5,7 @@ description: Auto-generate AI agent instructions from your codebase
# Primer
Primer analyzes your codebase and automatically generates optimized instructions for all 32 AI agents. No more manual configuration—let SkillKit detect your tech stack, coding patterns, and project structure.
Primer analyzes your codebase and automatically generates optimized instructions for all 44 AI agents. No more manual configuration—let SkillKit detect your tech stack, coding patterns, and project structure.
## Quick Start
@@ -65,7 +65,7 @@ Primer creates agent-specific instructions for:
└── copilot-instructions.md
```
### All 32 Agents
### All 44 Agents
Each agent gets optimized instructions in their native format.
## Example Output
@@ -86,7 +86,7 @@ Detected:
- Claude Code (.claude/CLAUDE.md)
- Cursor (.cursor/.cursorrules)
- Codex (.codex/instructions.md)
+ 29 more agents
+ 41 more agents
💡 Tip: Run `skillkit sync` to apply changes
```
+1 -1
View File
@@ -188,7 +188,7 @@ const { app, cache } = createApp({
The server includes built-in Swagger UI at `/docs` and an OpenAPI 3.1 spec at `/openapi.json`. Open `http://localhost:3737/docs` in your browser to try endpoints interactively.
The hosted version is available at [agenstskills.com/api](https://agenstskills.com/api).
The hosted version is available at [skillkit.sh/api](https://skillkit.sh/api) and [agenstskills.com/api](https://agenstskills.com/api).
## All endpoints
+1 -1
View File
@@ -5,7 +5,7 @@ description: Convert skills between AI agent formats
# Translation
SkillKit automatically converts between all 32 agent formats using an adapter pattern.
SkillKit automatically converts between all 44 agent formats using an adapter pattern.
## Basic Translation
+4 -2
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit-docs",
"version": "1.16.0",
"version": "1.19.2",
"private": true,
"scripts": {
"build": "next build",
@@ -21,7 +21,8 @@
"next-themes": "^0.4.6",
"react": "^19.2.3",
"react-dom": "^19.2.3",
"tailwind-merge": "^3.4.0"
"tailwind-merge": "^3.4.0",
"turndown": "^7.2.2"
},
"devDependencies": {
"@tailwindcss/postcss": "^4.1.18",
@@ -29,6 +30,7 @@
"@types/node": "^24.10.2",
"@types/react": "^19.2.7",
"@types/react-dom": "^19.2.3",
"@types/turndown": "^5.0.6",
"postcss": "^8.5.6",
"tailwindcss": "^4.1.18",
"typescript": "^5.9.3"
+3 -3
View File
@@ -18,7 +18,7 @@ export default function HomePage() {
<p className="text-lg text-zinc-400 mb-8 max-w-2xl mx-auto font-mono">
One CLI to install, sync, and manage skills across Claude Code, Cursor,
Windsurf, Copilot, and 28 more agents. 15,000+ skills ready to use.
Windsurf, Copilot, and 40 more agents. 15,000+ skills ready to use.
</p>
<div className="flex flex-wrap justify-center gap-4 mb-12">
@@ -39,8 +39,8 @@ export default function HomePage() {
{/* Features Grid */}
<div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-16">
<div className="border border-zinc-800 bg-zinc-900/30 p-6">
<h3 className="text-lg font-bold text-white mb-2 font-mono">32 Agents</h3>
<p className="text-zinc-500 text-sm">Claude, Cursor, Codex, Windsurf, Copilot, and 27 more supported out of the box.</p>
<h3 className="text-lg font-bold text-white mb-2 font-mono">44 Agents</h3>
<p className="text-zinc-500 text-sm">Claude, Cursor, Codex, Windsurf, Copilot, and 39 more supported out of the box.</p>
</div>
<div className="border border-zinc-800 bg-zinc-900/30 p-6">
<h3 className="text-lg font-bold text-white mb-2 font-mono">15,000+ Skills</h3>
@@ -0,0 +1,291 @@
import { NextRequest, NextResponse } from 'next/server';
import TurndownService from 'turndown';
const rateLimitMap = new Map<string, { count: number; resetTime: number }>();
const RATE_LIMIT_WINDOW_MS = 60 * 1000;
const RATE_LIMIT_MAX_REQUESTS = 10;
function checkRateLimit(key: string): { allowed: boolean; remaining: number } {
const now = Date.now();
const entry = rateLimitMap.get(key);
if (!entry || now > entry.resetTime) {
rateLimitMap.set(key, { count: 1, resetTime: now + RATE_LIMIT_WINDOW_MS });
return { allowed: true, remaining: RATE_LIMIT_MAX_REQUESTS - 1 };
}
if (entry.count >= RATE_LIMIT_MAX_REQUESTS) {
return { allowed: false, remaining: 0 };
}
entry.count++;
return { allowed: true, remaining: RATE_LIMIT_MAX_REQUESTS - entry.count };
}
const BLOCKED_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1', '0.0.0.0']);
function isAllowedUrl(url: string): boolean {
try {
const parsed = new URL(url);
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
const hostname = parsed.hostname.toLowerCase();
const bare = hostname.replace(/^\[|\]$/g, '');
if (BLOCKED_HOSTS.has(hostname) || BLOCKED_HOSTS.has(bare)) return false;
if (bare.startsWith('::ffff:')) return isAllowedUrl(`http://${bare.slice(7)}`);
if (/^127\./.test(bare) || /^0\./.test(bare)) return false;
if (bare.startsWith('10.') || bare.startsWith('192.168.')) return false;
if (/^172\.(1[6-9]|2\d|3[01])\./.test(bare)) return false;
if (bare.startsWith('169.254.')) return false;
if (bare.startsWith('fe80:') || bare.startsWith('fc00:') || bare.startsWith('fd')) return false;
if (/^(22[4-9]|23\d|24\d|25[0-5])\./.test(bare)) return false;
if (/^ff[0-9a-f]{2}:/.test(bare)) return false;
return true;
} catch {
return false;
}
}
const GITHUB_URL_PATTERN = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/;
const GITHUB_RAW_PATTERN = /^https?:\/\/raw\.githubusercontent\.com\//;
const FETCH_TIMEOUT = 30_000;
const TECH_KEYWORDS = new Set([
'react', 'vue', 'angular', 'svelte', 'nextjs', 'nuxt', 'remix',
'typescript', 'javascript', 'python', 'rust', 'go', 'java', 'ruby',
'node', 'deno', 'bun', 'docker', 'kubernetes', 'terraform',
'aws', 'gcp', 'azure', 'vercel', 'netlify', 'cloudflare',
'graphql', 'rest', 'grpc', 'websocket', 'redis', 'postgres',
'mongodb', 'sqlite', 'mysql', 'prisma', 'drizzle',
'tailwind', 'css', 'html', 'sass', 'webpack', 'vite', 'esbuild',
'git', 'ci', 'cd', 'testing', 'security', 'authentication',
'api', 'cli', 'sdk', 'mcp', 'llm', 'ai', 'ml', 'openai', 'anthropic',
]);
const TAG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
const turndown = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
interface ExtractedContent {
title: string;
content: string;
sourceUrl: string;
contentType: string;
language?: string;
}
async function extractFromUrl(url: string): Promise<ExtractedContent> {
if (GITHUB_URL_PATTERN.test(url) || GITHUB_RAW_PATTERN.test(url)) {
return fetchGitHubContent(url);
}
const MAX_BODY_SIZE = 5 * 1024 * 1024;
const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
if (!response.ok) {
throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
}
const contentLength = Number(response.headers.get('content-length') || '0');
if (contentLength > MAX_BODY_SIZE) {
throw new Error('Response too large');
}
const contentType = response.headers.get('content-type') ?? '';
const body = await response.text();
if (body.length > MAX_BODY_SIZE) {
throw new Error('Response too large');
}
if (contentType.includes('text/html')) {
const titleMatch = body.match(/<title[^>]*>([^<]+)<\/title>/i);
const title = titleMatch?.[1]?.trim() ?? new URL(url).hostname;
const bodyMatch = body.match(/<body[^>]*>([\s\S]*)<\/body>/i);
const content = turndown.turndown(bodyMatch?.[1] ?? body);
return { title, content, sourceUrl: url, contentType: 'webpage' };
}
const title = new URL(url).pathname.split('/').pop() ?? 'Untitled';
return { title, content: body, sourceUrl: url, contentType: 'text' };
}
const LANG_MAP: Record<string, string> = {
'.ts': 'typescript', '.tsx': 'typescript', '.js': 'javascript', '.jsx': 'javascript',
'.py': 'python', '.rb': 'ruby', '.go': 'go', '.rs': 'rust', '.java': 'java',
'.kt': 'kotlin', '.swift': 'swift', '.sh': 'shell', '.yml': 'yaml', '.yaml': 'yaml',
'.json': 'json', '.md': 'markdown', '.html': 'html', '.css': 'css', '.sql': 'sql',
};
async function fetchGitHubContent(url: string): Promise<ExtractedContent> {
let rawUrl = url;
const match = url.match(GITHUB_URL_PATTERN);
if (match) {
const [, owner, repo, branch, path] = match;
rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
}
const MAX_BODY_SIZE = 5 * 1024 * 1024;
const response = await fetch(rawUrl, { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
if (!response.ok) {
throw new Error(`Failed to fetch GitHub content: ${response.status} ${response.statusText}`);
}
const contentLength = Number(response.headers.get('content-length') || '0');
if (contentLength > MAX_BODY_SIZE) {
throw new Error('Response too large');
}
const body = await response.text();
if (body.length > MAX_BODY_SIZE) {
throw new Error('Response too large');
}
const filename = rawUrl.split('/').pop() ?? 'file';
const ext = filename.includes('.') ? '.' + filename.split('.').pop()!.toLowerCase() : '';
const language = LANG_MAP[ext];
const isCode = language !== undefined && language !== 'markdown';
const content = isCode ? `\`\`\`${language}\n${body}\n\`\`\`` : body;
return { title: filename, content, sourceUrl: url, contentType: 'github', language };
}
function addTag(counts: Map<string, number>, tag: string, weight: number): void {
if (TAG_PATTERN.test(tag)) {
counts.set(tag, (counts.get(tag) ?? 0) + weight);
}
}
function detectTags(extracted: ExtractedContent): string[] {
const counts = new Map<string, number>();
try {
const segments = new URL(extracted.sourceUrl).pathname
.split('/').filter(Boolean)
.map((s) => s.toLowerCase().replace(/[^a-z0-9-]/g, ''));
for (const seg of segments) {
if (seg.length >= 2 && seg.length <= 30) {
addTag(counts, seg, 2);
}
}
} catch { /* skip */ }
const headingRe = /^#{1,2}\s+(.+)$/gm;
let m: RegExpExecArray | null;
while ((m = headingRe.exec(extracted.content)) !== null) {
for (const word of m[1].toLowerCase().split(/\s+/)) {
const cleaned = word.replace(/[^a-z0-9-]/g, '');
if (cleaned.length >= 2) {
addTag(counts, cleaned, 2);
}
}
}
const codeBlockRe = /^```(\w+)/gm;
while ((m = codeBlockRe.exec(extracted.content)) !== null) {
const lang = m[1].toLowerCase();
if (lang.length >= 2) {
addTag(counts, lang, 3);
}
}
const lower = extracted.content.toLowerCase();
for (const keyword of TECH_KEYWORDS) {
if (new RegExp(`\\b${keyword}\\b`, 'i').test(lower)) {
addTag(counts, keyword, 1);
}
}
if (extracted.language) {
addTag(counts, extracted.language.toLowerCase(), 3);
}
return Array.from(counts.entries())
.sort((a, b) => b[1] - a[1])
.slice(0, 10)
.map(([tag]) => tag);
}
function slugify(input: string): string {
const slug = input
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '')
.replace(/-{2,}/g, '-');
return slug.slice(0, 64).replace(/-+$/, '') || 'untitled-skill';
}
function yamlEscape(value: string): string {
const singleLine = value.replace(/\r?\n/g, ' ').trim();
if (/[:#{}[\],&*?|>!%@`]/.test(singleLine) || singleLine.startsWith("'") || singleLine.startsWith('"')) {
return `"${singleLine.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
}
return singleLine;
}
export async function POST(request: NextRequest) {
const ip = request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown';
const { allowed, remaining } = checkRateLimit(ip);
if (!allowed) {
return NextResponse.json(
{ error: 'Too many requests. Try again in a minute.' },
{ status: 429, headers: { 'X-RateLimit-Remaining': '0', 'Retry-After': '60' } },
);
}
let body: { url?: string; name?: string };
try {
body = await request.json();
} catch {
return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
}
const { url, name } = body;
if (!url || typeof url !== 'string') {
return NextResponse.json({ error: 'Missing required field: url' }, { status: 400 });
}
if (name !== undefined && typeof name !== 'string') {
return NextResponse.json({ error: 'Field "name" must be a string' }, { status: 400 });
}
if (!isAllowedUrl(url)) {
return NextResponse.json({ error: 'URL not allowed' }, { status: 403 });
}
try {
const extracted = await extractFromUrl(url);
const tags = detectTags(extracted);
const skillName = slugify(name || extracted.title || 'untitled');
const description = extracted.content
.split('\n')
.find((l) => l.trim().length > 0)
?.replace(/^#+\s*/, '')
.trim()
.slice(0, 200) || 'Saved skill';
const savedAt = new Date().toISOString();
const yamlTags = tags.length > 0
? `tags:\n${tags.map((t) => ` - ${t}`).join('\n')}\n`
: '';
const skillMd =
`---\n` +
`name: ${skillName}\n` +
`description: ${yamlEscape(description)}\n` +
yamlTags +
`metadata:\n` +
` source: ${yamlEscape(url)}\n` +
` savedAt: ${savedAt}\n` +
`---\n\n` +
extracted.content + '\n';
return NextResponse.json(
{ name: skillName, skillMd, tags, description },
{ headers: { 'X-RateLimit-Remaining': String(remaining) } },
);
} catch (err) {
const message = err instanceof Error ? err.message : 'Failed to extract content';
return NextResponse.json({ error: message }, { status: 502 });
}
}
+1 -1
View File
@@ -24,7 +24,7 @@ export const metadata: Metadata = {
openGraph: {
title: 'SkillKit - Universal Skills for AI Coding Agents',
description: 'One CLI to install, sync, and manage skills across Claude Code, Cursor, Windsurf, Copilot, and 28 more agents.',
url: 'https://agenstskills.com',
url: 'https://skillkit.sh',
siteName: 'SkillKit',
images: [{ url: '/og-image.png', width: 1200, height: 630 }],
type: 'website',
+16 -4
View File
@@ -44,12 +44,12 @@ const sections: DocSection[] = [
content: (
<div className="space-y-4">
<p className="text-zinc-300">
SkillKit is a universal command-line interface (CLI) and programmatic toolkit for managing AI agent skills across 32 AI coding platforms. It solves the fragmentation problem where each AI agent uses different skill formats and directory structures.
SkillKit is a universal command-line interface (CLI) and programmatic toolkit for managing AI agent skills across 44 AI coding platforms. It solves the fragmentation problem where each AI agent uses different skill formats and directory structures.
</p>
<h3 className="text-lg font-semibold text-white mt-6">Core Capabilities</h3>
<ul className="list-disc list-inside space-y-2 text-zinc-400">
<li><span className="text-white">Skill Discovery</span> - Browse 15,000+ skills from marketplace with AI-powered recommendations</li>
<li><span className="text-white">Cross-Agent Translation</span> - Automatically convert skills between 32 agent-specific formats</li>
<li><span className="text-white">Cross-Agent Translation</span> - Automatically convert skills between 44 agent-specific formats</li>
<li><span className="text-white">Team Collaboration</span> - Share skills via .skills manifest files and publish to marketplace</li>
</ul>
</div>
@@ -102,7 +102,7 @@ skillkit install anthropics/skills`}</CodeBlock>
<ul className="list-disc list-inside space-y-2 text-zinc-400">
<li><span className="text-white">UI Tier</span> - CLI commands, Terminal UI (OpenTUI-based), and documentation website</li>
<li><span className="text-white">Core Logic Tier</span> - @skillkit/core for business logic; @skillkit/agents for adapter implementations</li>
<li><span className="text-white">Integration Tier</span> - File systems, Git repositories, marketplace APIs, and 32 AI agents</li>
<li><span className="text-white">Integration Tier</span> - File systems, Git repositories, marketplace APIs, and 44 AI agents</li>
</ul>
<h3 className="text-lg font-semibold text-white mt-6">Monorepo Structure</h3>
@@ -130,7 +130,7 @@ skillkit install anthropics/skills`}</CodeBlock>
content: (
<div className="space-y-4">
<p className="text-zinc-300">
SkillKit supports 32 AI coding agents with automatic format translation:
SkillKit supports 44 AI coding agents with automatic format translation:
</p>
<Table
@@ -167,6 +167,18 @@ skillkit install anthropics/skills`}</CodeBlock>
['Trae', '.trae/skills/', 'SKILL.md'],
['Vercel', '.vercel/skills/', 'SKILL.md'],
['Zencoder', '.zencoder/skills/', 'SKILL.md'],
['Devin', '.devin/skills/', 'SKILL.md'],
['Aider', '.aider/skills/', 'SKILL.md'],
['Sourcegraph Cody', '.cody/skills/', 'SKILL.md'],
['Amazon Q', '.amazonq/skills/', 'SKILL.md'],
['Augment Code', '.augment/skills/', 'SKILL.md'],
['Replit Agent', '.replit/skills/', 'SKILL.md'],
['Bolt', '.bolt/skills/', 'SKILL.md'],
['Lovable', '.lovable/skills/', 'SKILL.md'],
['Tabby', '.tabby/skills/', 'SKILL.md'],
['Tabnine', '.tabnine/skills/', 'SKILL.md'],
['CodeGPT', '.codegpt/skills/', 'SKILL.md'],
['PlayCode Agent', '.playcode/skills/', 'SKILL.md'],
['Universal', 'skills/', 'SKILL.md'],
]}
/>
+3 -3
View File
@@ -9,7 +9,7 @@ interface Feature {
const FEATURES: Feature[] = [
{
title: 'Multi-Agent',
description: 'Deploy to 32 AI coding agents with one command.',
description: 'Deploy to 44 AI coding agents with one command.',
icon: (
<svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
@@ -64,7 +64,7 @@ const FEATURES: Feature[] = [
];
const COMPARISONS = [
['Agents', '1', '32'],
['Agents', '1', '44'],
['Translation', 'Manual', 'Auto'],
['Sharing', 'Copy/paste', '.skills manifest'],
['Discovery', 'Forums', 'CLI + AI'],
@@ -83,7 +83,7 @@ export function Features(): React.ReactElement {
</p>
<div className="flex gap-6 sm:gap-8">
<div>
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">32</div>
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">44</div>
<div className="text-zinc-600 text-[10px] sm:text-xs font-mono">Agents</div>
</div>
<div>
+1 -1
View File
@@ -18,7 +18,7 @@ export function Footer(): React.ReactElement {
</p>
<span className="hidden sm:inline text-zinc-700">•</span>
<a
href="https://agenstskills.com"
href="https://skillkit.sh"
target="_blank"
rel="noopener noreferrer"
className="text-zinc-600 hover:text-zinc-400 text-xs font-mono transition-colors"
+1
View File
@@ -1,5 +1,6 @@
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"ignoreCommand": "git diff --quiet HEAD^ HEAD -- .",
"buildCommand": "next build",
"installCommand": "npm install",
"outputDirectory": ".next",
+1 -1
View File
@@ -29,7 +29,7 @@
<g transform="translate(890, 58)">
<rect width="250" height="40" fill="url(#ph-badge)" stroke="#444" stroke-width="1" rx="20"/>
<circle cx="28" cy="20" r="14" fill="#da552f"/>
<circle cx="28" cy="20" r="14" fill="none" stroke="#666" stroke-width="1.5"/>
<text x="28" y="25" font-family="system-ui, sans-serif" font-size="16" font-weight="700" fill="white" text-anchor="middle">P</text>
<text x="54" y="16" font-family="system-ui, sans-serif" font-size="9" font-weight="600" fill="#888" letter-spacing="1">PRODUCT HUNT</text>
<text x="54" y="30" font-family="system-ui, sans-serif" font-size="13" font-weight="700" fill="white">#3 Product of the Day</text>

Before

Width:  |  Height:  |  Size: 3.9 KiB

After

Width:  |  Height:  |  Size: 3.9 KiB

+44 -77
View File
@@ -5,14 +5,10 @@ import { Agents } from './components/Agents';
import { Footer } from './components/Footer';
import { SkillGenerator } from './components/SkillGenerator';
import { SkillSubmitForm } from './components/SkillSubmitForm';
import { Commands } from './components/Commands';
import { StackBuilder } from './components/StackBuilder';
import { TrendingSkills } from './components/TrendingSkills';
import { Attribution } from './components/Attribution';
import { AdvancedFeatures } from './components/AdvancedFeatures';
import { UseCases } from './components/UseCases';
import { TeamEnterprise } from './components/TeamEnterprise';
import { BadgeGenerator } from './components/BadgeGenerator';
import { CompatibilityMatrix } from './components/CompatibilityMatrix';
import { useStats } from './hooks/useStats';
@@ -56,13 +52,6 @@ export default function App(): React.ReactElement {
>
Trending
</a>
<a
href="#stack"
onClick={(e) => scrollToSection(e, 'stack')}
className="text-zinc-500 hover:text-white transition-colors"
>
Stack
</a>
<a
href="#matrix"
onClick={(e) => scrollToSection(e, 'matrix')}
@@ -70,13 +59,6 @@ export default function App(): React.ReactElement {
>
Matrix
</a>
<a
href="#badge"
onClick={(e) => scrollToSection(e, 'badge')}
className="text-zinc-500 hover:text-white transition-colors"
>
Badge
</a>
<a
href="#advanced"
onClick={(e) => scrollToSection(e, 'advanced')}
@@ -100,18 +82,18 @@ export default function App(): React.ReactElement {
</a>
</div>
<div className="flex items-center gap-3 sm:gap-4">
<a
href="/docs"
className="text-zinc-400 hover:text-white transition-colors text-xs sm:text-sm font-mono"
>
Docs
</a>
<a
href="/api"
className="text-zinc-400 hover:text-white transition-colors text-xs sm:text-sm font-mono"
>
API
</a>
<a
href="https://agenstskills.com/docs"
className="text-zinc-400 hover:text-white transition-colors text-xs sm:text-sm font-mono"
>
Docs
</a>
<a
href="https://github.com/rohitg00/skillkit"
target="_blank"
@@ -169,21 +151,6 @@ export default function App(): React.ReactElement {
</svg>
<span className="text-white font-medium">{stats.stars || '—'}</span>
</a>
<span className="text-zinc-800 hidden sm:inline">·</span>
<a
href="https://www.producthunt.com/products/skillkit-2?embed=true&utm_source=badge-top-post-badge&utm_medium=badge&utm_campaign=badge-skillkit-2"
target="_blank"
rel="noopener noreferrer"
className="hidden sm:inline-flex items-center hover:opacity-80 transition-opacity"
>
<img
src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1071813&theme=dark&period=daily"
alt="Skillkit - The package manager for AI agent skills | Product Hunt"
width="250"
height="54"
style={{ height: '28px', width: 'auto' }}
/>
</a>
</div>
</div>
</div>
@@ -194,44 +161,6 @@ export default function App(): React.ReactElement {
{/* Core Features & Comparison - Value prop at a glance */}
<Features />
{/* Trending Skills - Social proof, what's popular */}
<section id="trending" style={{ scrollMarginTop: '4rem' }}>
<TrendingSkills />
</section>
{/* Stack Builder - Interactive, engaging */}
<section id="stack" style={{ scrollMarginTop: '4rem' }}>
<StackBuilder />
</section>
{/* Compatibility Matrix */}
<section id="matrix" style={{ scrollMarginTop: '4rem' }}>
<CompatibilityMatrix />
</section>
{/* Badge Generator */}
<section id="badge" style={{ scrollMarginTop: '4rem' }}>
<BadgeGenerator />
</section>
{/* Advanced Capabilities: Memory, Primer, Mesh, Messaging */}
<section id="advanced" style={{ scrollMarginTop: '4rem' }}>
<AdvancedFeatures />
</section>
{/* Commands Reference */}
<Commands />
{/* Real-World Use Cases */}
<section id="use-cases" style={{ scrollMarginTop: '4rem' }}>
<UseCases />
</section>
{/* Team & Enterprise */}
<section id="team" style={{ scrollMarginTop: '4rem' }}>
<TeamEnterprise />
</section>
{/* Skill Generator */}
<section id="skills" className="py-12 border-b border-zinc-800" style={{ scrollMarginTop: '4rem' }}>
<SkillGenerator />
@@ -250,6 +179,44 @@ export default function App(): React.ReactElement {
</div>
</section>
{/* Trending Skills - Social proof, what's popular */}
<section id="trending" style={{ scrollMarginTop: '4rem' }}>
<TrendingSkills />
</section>
{/* Compatibility Matrix */}
<section id="matrix" style={{ scrollMarginTop: '4rem' }}>
<CompatibilityMatrix />
</section>
{/* Advanced Capabilities: Memory, Primer, Mesh, Messaging */}
<section id="advanced" style={{ scrollMarginTop: '4rem' }}>
<AdvancedFeatures />
</section>
{/* Docs CTA */}
<section className="py-8 border-b border-zinc-800">
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8 text-center">
<p className="text-sm font-mono text-zinc-400">
Explore all 50+ commands, team workflows, and integrations in the{' '}
<a
href="/docs"
target="_blank"
rel="noopener noreferrer"
className="text-white underline underline-offset-4 hover:text-zinc-300 transition-colors"
>
documentation
</a>
.
</p>
</div>
</section>
{/* Real-World Use Cases */}
<section id="use-cases" style={{ scrollMarginTop: '4rem' }}>
<UseCases />
</section>
{/* Attribution & Sources */}
<section id="sources" style={{ scrollMarginTop: '4rem' }}>
<Attribution />
@@ -47,6 +47,24 @@ const ADVANCED_FEATURES: AdvancedFeature[] = [
{ cmd: 'memory --global', desc: 'Share across all projects' },
],
},
{
id: 'session',
title: 'Session Intelligence',
subtitle: 'Skill Lineage & Agent Handoffs',
description: 'Track which skills produced which code changes. Generate handoff documents when switching agents. View unified timelines of all session events — skill executions, git commits, observations, and decisions in one stream.',
highlight: 'Timeline, handoff, and lineage in one place',
icon: (
<svg className="w-8 h-8" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
</svg>
),
commands: [
{ cmd: 'timeline', desc: 'Unified event stream' },
{ cmd: 'session handoff', desc: 'Agent-to-agent context' },
{ cmd: 'lineage', desc: 'Skill impact graph' },
{ cmd: 'lineage --skill code-simplifier', desc: 'Per-skill impact' },
],
},
{
id: 'primer',
title: 'Primer',
+2 -2
View File
@@ -35,8 +35,8 @@ export function BadgeGenerator(): React.ReactElement {
const badgeUrl = useMemo(() => buildBadgeUrl(skills), [skills]);
const markdown = `[![SkillKit Stack](${badgeUrl})](https://agenstskills.com)`;
const html = `<a href="https://agenstskills.com"><img src="${badgeUrl}" alt="SkillKit Stack" /></a>`;
const markdown = `[![SkillKit Stack](${badgeUrl})](https://skillkit.sh)`;
const html = `<a href="https://skillkit.sh"><img src="${badgeUrl}" alt="SkillKit Stack" /></a>`;
function addSkill(skill: string): void {
const trimmed = skill.trim().toLowerCase();
+22
View File
@@ -93,6 +93,28 @@ const COMMAND_GROUPS: CommandGroup[] = [
{ cmd: 'validate', desc: 'Validate format' },
],
},
{
name: 'Issues',
commands: [
{ cmd: 'issue plan "#42"', desc: 'Plan from issue' },
{ cmd: 'issue plan owner/repo#42', desc: 'Cross-repo plan' },
{ cmd: 'issue plan "#42" --agent cursor', desc: 'Target agent' },
{ cmd: 'issue plan "#42" --json', desc: 'JSON output' },
{ cmd: 'issue list', desc: 'List open issues' },
{ cmd: 'issue list --label bug', desc: 'Filter by label' },
],
},
{
name: 'Session',
commands: [
{ cmd: 'timeline', desc: 'Unified event stream' },
{ cmd: 'session handoff', desc: 'Agent handoff doc' },
{ cmd: 'lineage', desc: 'Skill impact graph' },
{ cmd: 'session explain', desc: 'Session summary' },
{ cmd: 'activity', desc: 'Skill activity log' },
{ cmd: 'session snapshot save', desc: 'Save state' },
],
},
{
name: 'Advanced',
commands: [
@@ -24,14 +24,42 @@ const AGENTS: AgentDef[] = [
{ id: 'windsurf', name: 'Windsurf', icon: '\u25C7', group: 'Tier 1' },
{ id: 'github-copilot', name: 'Copilot', icon: '\u2318', group: 'Tier 1' },
{ id: 'cline', name: 'Cline', icon: '\u25CF', group: 'Tier 1' },
{ id: 'devin', name: 'Devin', icon: '\u25C9', group: 'Tier 1' },
{ id: 'roo', name: 'Roo', icon: '\u25C6', group: 'Tier 2' },
{ id: 'kilo', name: 'Kilo', icon: '\u25B3', group: 'Tier 2' },
{ id: 'kiro-cli', name: 'Kiro CLI', icon: '\u25BD', group: 'Tier 2' },
{ id: 'goose', name: 'Goose', icon: '\u25CA', group: 'Tier 2' },
{ id: 'trae', name: 'Trae', icon: '\u25A0', group: 'Tier 2' },
{ id: 'amp', name: 'AMP', icon: '\u26A1', group: 'Tier 2' },
{ id: 'aider', name: 'Aider', icon: '\u25E6', group: 'Tier 2' },
{ id: 'cody', name: 'Cody', icon: '\u25D0', group: 'Tier 2' },
{ id: 'amazon-q', name: 'Amazon Q', icon: '\u25A3', group: 'Tier 2' },
{ id: 'antigravity', name: 'Antigrav', icon: '\u2191', group: 'Tier 3' },
{ id: 'continue', name: 'Continue', icon: '\u25B6', group: 'Tier 3' },
{ id: 'augment', name: 'Augment', icon: '\u25C8', group: 'Tier 3' },
{ id: 'replit', name: 'Replit', icon: '\u25B7', group: 'Tier 3' },
{ id: 'bolt', name: 'Bolt', icon: '\u2605', group: 'Tier 3' },
{ id: 'lovable', name: 'Lovable', icon: '\u2665', group: 'Tier 3' },
{ id: 'tabby', name: 'Tabby', icon: '\u25AB', group: 'Tier 3' },
{ id: 'tabnine', name: 'Tabnine', icon: '\u25AA', group: 'Tier 3' },
{ id: 'codegpt', name: 'CodeGPT', icon: '\u25E7', group: 'Tier 3' },
{ id: 'playcode', name: 'PlayCode', icon: '\u25B9', group: 'Tier 3' },
{ id: 'clawdbot', name: 'Clawdbot', icon: '\u25D1', group: 'Tier 3' },
{ id: 'droid', name: 'Droid', icon: '\u25D2', group: 'Tier 3' },
{ id: 'codebuddy', name: 'CodeBuddy', icon: '\u25D3', group: 'Tier 3' },
{ id: 'commandcode', name: 'CmdCode', icon: '\u25D4', group: 'Tier 3' },
{ id: 'crush', name: 'Crush', icon: '\u25D5', group: 'Tier 3' },
{ id: 'factory', name: 'Factory', icon: '\u25D6', group: 'Tier 3' },
{ id: 'mcpjam', name: 'MCPJam', icon: '\u25D7', group: 'Tier 3' },
{ id: 'mux', name: 'Mux', icon: '\u25E0', group: 'Tier 3' },
{ id: 'neovate', name: 'Neovate', icon: '\u25E1', group: 'Tier 3' },
{ id: 'openhands', name: 'OpenHands', icon: '\u25E2', group: 'Tier 3' },
{ id: 'pi', name: 'Pi', icon: '\u25E3', group: 'Tier 3' },
{ id: 'qoder', name: 'Qoder', icon: '\u25E4', group: 'Tier 3' },
{ id: 'qwen', name: 'Qwen', icon: '\u25E5', group: 'Tier 3' },
{ id: 'vercel', name: 'Vercel', icon: '\u25B2', group: 'Tier 3' },
{ id: 'zencoder', name: 'Zencoder', icon: '\u25E8', group: 'Tier 3' },
{ id: 'universal', name: 'Universal', icon: '\u25CB', group: 'Tier 3' },
];
const CATEGORIES: CategoryDef[] = [
@@ -56,66 +84,87 @@ const CATEGORIES: CategoryDef[] = [
// - windsurf: 32K context, no MCP/tools, workflow YAML format
// - kilo, kiro-cli: XML block format, multi-mode support, no MCP
// - goose, amp, antigravity, trae, continue: varies, mostly universal adapter
const T3_FULL: Record<string, Support> = {
'augment': 'full', 'replit': 'full', 'bolt': 'full', 'lovable': 'full',
'tabby': 'full', 'tabnine': 'full', 'codegpt': 'full', 'playcode': 'full',
'clawdbot': 'full', 'droid': 'full', 'codebuddy': 'full', 'commandcode': 'full',
'crush': 'full', 'factory': 'full', 'mcpjam': 'full', 'mux': 'full',
'neovate': 'full', 'openhands': 'full', 'pi': 'full', 'qoder': 'full',
'qwen': 'full', 'vercel': 'full', 'zencoder': 'full', 'universal': 'full',
};
const T3_PARTIAL: Record<string, Support> = Object.fromEntries(Object.keys(T3_FULL).map(k => [k, 'partial']));
const T3_NONE: Record<string, Support> = Object.fromEntries(Object.keys(T3_FULL).map(k => [k, 'none']));
const MATRIX: Record<string, Record<string, Support>> = {
'translation': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'cline': 'full',
'roo': 'full', 'kilo': 'full', 'kiro-cli': 'partial', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'antigravity': 'full', 'continue': 'full',
'devin': 'full', 'roo': 'full', 'kilo': 'full', 'kiro-cli': 'partial', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'aider': 'full', 'cody': 'full', 'amazon-q': 'full',
'antigravity': 'full', 'continue': 'full', ...T3_FULL,
},
'hooks': {
'claude-code': 'full', 'cursor': 'partial', 'codex': 'partial', 'gemini-cli': 'partial',
'opencode': 'partial', 'windsurf': 'none', 'github-copilot': 'none', 'cline': 'full',
'roo': 'full', 'kilo': 'partial', 'kiro-cli': 'partial', 'goose': 'partial',
'trae': 'partial', 'amp': 'partial', 'antigravity': 'none', 'continue': 'none',
'devin': 'partial', 'roo': 'full', 'kilo': 'partial', 'kiro-cli': 'partial', 'goose': 'partial',
'trae': 'partial', 'amp': 'partial', 'aider': 'none', 'cody': 'none', 'amazon-q': 'none',
'antigravity': 'none', 'continue': 'none', ...T3_NONE,
},
'mcp-tools': {
'claude-code': 'full', 'cursor': 'none', 'codex': 'none', 'gemini-cli': 'none',
'opencode': 'none', 'windsurf': 'none', 'github-copilot': 'none', 'cline': 'full',
'roo': 'full', 'kilo': 'none', 'kiro-cli': 'none', 'goose': 'none',
'trae': 'none', 'amp': 'none', 'antigravity': 'none', 'continue': 'none',
'devin': 'partial', 'roo': 'full', 'kilo': 'none', 'kiro-cli': 'none', 'goose': 'none',
'trae': 'none', 'amp': 'none', 'aider': 'none', 'cody': 'none', 'amazon-q': 'none',
'antigravity': 'none', 'continue': 'none', ...T3_NONE,
},
'context': {
'claude-code': 'full', 'cursor': 'partial', 'codex': 'partial', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'partial', 'cline': 'full',
'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'partial', 'amp': 'full', 'antigravity': 'partial', 'continue': 'partial',
'devin': 'full', 'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'partial', 'amp': 'full', 'aider': 'full', 'cody': 'full', 'amazon-q': 'partial',
'antigravity': 'partial', 'continue': 'partial', ...T3_PARTIAL,
},
'security': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'partial', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'partial', 'cline': 'full',
'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'antigravity': 'partial', 'continue': 'partial',
'devin': 'full', 'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'aider': 'full', 'cody': 'full', 'amazon-q': 'full',
'antigravity': 'partial', 'continue': 'partial', ...T3_PARTIAL,
},
'testing': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'partial', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'partial', 'cline': 'full',
'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'antigravity': 'partial', 'continue': 'partial',
'devin': 'full', 'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'aider': 'full', 'cody': 'full', 'amazon-q': 'partial',
'antigravity': 'partial', 'continue': 'partial', ...T3_PARTIAL,
},
'frontend': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'partial', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'partial', 'cline': 'full',
'roo': 'full', 'kilo': 'partial', 'kiro-cli': 'partial', 'goose': 'partial',
'trae': 'full', 'amp': 'full', 'antigravity': 'partial', 'continue': 'partial',
'devin': 'full', 'roo': 'full', 'kilo': 'partial', 'kiro-cli': 'partial', 'goose': 'partial',
'trae': 'full', 'amp': 'full', 'aider': 'partial', 'cody': 'partial', 'amazon-q': 'partial',
'antigravity': 'partial', 'continue': 'partial', ...T3_PARTIAL,
},
'backend': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'partial', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'partial', 'cline': 'full',
'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'antigravity': 'partial', 'continue': 'partial',
'devin': 'full', 'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'aider': 'full', 'cody': 'full', 'amazon-q': 'partial',
'antigravity': 'partial', 'continue': 'partial', ...T3_PARTIAL,
},
'devops': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'partial', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'partial', 'cline': 'full',
'roo': 'full', 'kilo': 'partial', 'kiro-cli': 'partial', 'goose': 'partial',
'trae': 'partial', 'amp': 'partial', 'antigravity': 'partial', 'continue': 'partial',
'devin': 'full', 'roo': 'full', 'kilo': 'partial', 'kiro-cli': 'partial', 'goose': 'partial',
'trae': 'partial', 'amp': 'partial', 'aider': 'partial', 'cody': 'partial', 'amazon-q': 'partial',
'antigravity': 'partial', 'continue': 'partial', ...T3_PARTIAL,
},
'docs': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'partial', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'cline': 'full',
'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'antigravity': 'full', 'continue': 'full',
'devin': 'full', 'roo': 'full', 'kilo': 'full', 'kiro-cli': 'full', 'goose': 'full',
'trae': 'full', 'amp': 'full', 'aider': 'full', 'cody': 'full', 'amazon-q': 'full',
'antigravity': 'full', 'continue': 'full', ...T3_FULL,
},
};
@@ -197,7 +246,7 @@ export function CompatibilityMatrix(): React.ReactElement {
<div>
<h2 className="text-lg sm:text-xl font-bold text-white mb-1 font-mono">Compatibility Matrix</h2>
<p className="text-zinc-500 font-mono text-[10px] sm:text-xs">
Skill support across {AGENTS.length} agents and {CATEGORIES.length} categories.
Skill support across all 44 agents and {CATEGORIES.length} categories.
</p>
</div>
<div className="flex items-center gap-2">
@@ -213,6 +213,13 @@ skillkit primer --dry-run # Preview without writing files
skillkit primer --json # Output analysis as JSON
skillkit primer --output ./dir # Custom output directory`}</CodeBlock>
<h3 className="text-lg font-semibold text-white mt-6">Session Intelligence</h3>
<CodeBlock>{`skillkit timeline # Unified event stream
skillkit session handoff # Agent-to-agent context
skillkit lineage # Skill impact graph
skillkit session explain # Session summary
skillkit activity # Skill activity log`}</CodeBlock>
<h3 className="text-lg font-semibold text-white mt-6">Advanced</h3>
<CodeBlock>{`skillkit ui # Launch Terminal UI
skillkit workflow # Manage workflows
+21 -21
View File
@@ -109,34 +109,34 @@ const FEATURES: Feature[] = [
];
const COMPARISONS = [
['Agent Support', '1 agent', '44 agents'],
['Setup', 'Write rules manually', 'Auto-generate (Primer)'],
['Learning', 'Lost each session', 'Persistent memory'],
['Translation', 'Rewrite for each', 'One-click conversion'],
['Team Sharing', 'Copy/paste files', '.skills manifest'],
['Discovery', 'Search forums', 'AI recommendations'],
['Security', 'Manual review', 'Auto-scan on install'],
['Agent Support', '1-17 agents', '44 agents'],
['Sources', 'Single registry', '31+ aggregated'],
['Translation', 'None or limited', 'All 44 formats'],
['Memory', 'None', 'Persistent learning'],
['Security', 'None', '46-rule scanner'],
['Team Sync', 'None', '.skills manifest'],
['Telemetry', 'Varies', 'Zero. Ever.'],
['API Access', 'None', 'REST + MCP + Python'],
] as const;
export function Features(): React.ReactElement {
return (
<section id="features" className="py-12 border-b border-zinc-800 bg-surface">
<section id="features" className="py-8 border-b border-zinc-800 bg-surface">
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
<div className="grid grid-cols-1 lg:grid-cols-5 gap-6 lg:gap-8 mb-10">
<div className="grid grid-cols-1 lg:grid-cols-5 gap-6 lg:gap-8 mb-6">
<div className="lg:col-span-2">
<h2 className="text-xl font-bold text-white mb-2 font-mono">Why SkillKit?</h2>
<h2 className="text-xl font-bold text-white mb-2 font-mono">At a Glance</h2>
<p className="text-zinc-500 font-mono text-sm mb-6">
Universal bridge for AI coding agents.
What you get vs. a simple installer.
</p>
<div className="flex gap-6 sm:gap-8">
<div>
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">32</div>
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">44</div>
<div className="text-zinc-600 text-[10px] sm:text-xs font-mono">Agents</div>
</div>
<div>
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">50+</div>
<div className="text-zinc-600 text-[10px] sm:text-xs font-mono">Commands</div>
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">31+</div>
<div className="text-zinc-600 text-[10px] sm:text-xs font-mono">Sources</div>
</div>
<div>
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">15K+</div>
@@ -147,8 +147,8 @@ export function Features(): React.ReactElement {
<div className="lg:col-span-3 border border-zinc-800 bg-black/50 p-4 font-mono text-xs backdrop-blur-sm">
<div className="grid grid-cols-3 gap-2 border-b border-zinc-800 pb-2 mb-3 text-zinc-500 uppercase tracking-wider text-[10px]">
<div>Feature</div>
<div className="text-center">Without</div>
<div>Capability</div>
<div className="text-center">Simple Installers</div>
<div className="text-right">SkillKit</div>
</div>
<div className="space-y-1">
@@ -167,20 +167,20 @@ export function Features(): React.ReactElement {
</div>
</div>
<div className="grid grid-cols-2 sm:grid-cols-3 gap-3">
<div className="grid grid-cols-3 sm:grid-cols-4 gap-2">
{FEATURES.map((feature, index) => (
<div
key={feature.title}
className="group relative p-4 border border-zinc-800 bg-zinc-900/30 hover:bg-zinc-900/80 hover:border-zinc-700 transition-all duration-300 cursor-default"
className="group relative p-2.5 border border-zinc-800 bg-zinc-900/30 hover:bg-zinc-900/80 hover:border-zinc-700 transition-all duration-300 cursor-default"
style={{ animationDelay: `${index * 50}ms` }}
>
<div className="absolute inset-0 bg-gradient-to-b from-zinc-800/0 to-zinc-800/20 opacity-0 group-hover:opacity-100 transition-opacity"></div>
<div className="relative">
<div className="text-zinc-500 group-hover:text-white transition-colors mb-2">
<div className="text-zinc-500 group-hover:text-white transition-colors mb-1">
{feature.icon}
</div>
<h4 className="text-xs font-bold text-white mb-1 font-mono">{feature.title}</h4>
<p className="text-zinc-600 text-[10px] leading-relaxed font-mono group-hover:text-zinc-400 transition-colors">
<h4 className="text-[11px] font-bold text-white mb-0.5 font-mono">{feature.title}</h4>
<p className="text-zinc-600 text-[10px] leading-snug font-mono group-hover:text-zinc-400 transition-colors">
{feature.description}
</p>
</div>
+1 -1
View File
@@ -18,7 +18,7 @@ export function Footer(): React.ReactElement {
</p>
<span className="hidden sm:inline text-zinc-700">•</span>
<a
href="https://agenstskills.com"
href="https://skillkit.sh"
target="_blank"
rel="noopener noreferrer"
className="text-zinc-600 hover:text-zinc-400 text-xs font-mono transition-colors"
+49 -24
View File
@@ -20,16 +20,18 @@ interface TerminalLine {
}
const TERMINAL_LINES: TerminalLine[] = [
{ type: 'cmd', text: 'skillkit install anthropics/skills --agent all' },
{ type: 'out', text: '→ Installed to 44 agents' },
{ type: 'cmd', text: 'skillkit install anthropics/skills' },
{ type: 'out', text: '→ Fetched from github.com/anthropics/skills' },
{ type: 'out', text: '→ Translated to 44 agent formats' },
{ type: 'out', text: '→ Scanned: 0 issues found' },
{ type: 'cmd', text: 'skillkit install vercel-labs/agent-skills' },
{ type: 'out', text: '→ Installed 12 skills from Vercel' },
{ type: 'cmd', text: 'skillkit translate --all --to cursor' },
{ type: 'out', text: '→ 26 skills → .cursor/skills/' },
{ type: 'cmd', text: 'skillkit recommend' },
{ type: 'out', text: ' 92% vercel-react-best-practices' },
{ type: 'out', text: ' 87% typescript-strict-mode' },
{ type: 'cmd', text: 'skillkit serve' },
{ type: 'out', text: '→ API server on http://0.0.0.0:3737' },
{ type: 'out', text: ' GET /search · /trending · /categories' },
{ type: 'cmd', text: 'curl localhost:3737/search?q=react' },
{ type: 'out', text: ' {"skills":[...],"total":42}' },
{ type: 'out', text: ' 92% react-best-practices (vercel)' },
{ type: 'out', text: ' 87% strict-typescript (anthropic)' },
{ type: 'out', text: ' 85% supabase-auth (supabase)' },
];
const FADE_ANIMATION_STYLES = `
@@ -107,10 +109,6 @@ export function Hero({ version, stars }: HeroProps): React.ReactElement {
}
}
function openGitHub(): void {
window.open('https://github.com/rohitg00/skillkit', '_blank', 'noopener,noreferrer');
}
const isTyping = visibleLines < TERMINAL_LINES.length && TERMINAL_LINES[visibleLines].type === 'cmd';
const isComplete = visibleLines >= TERMINAL_LINES.length;
@@ -119,10 +117,22 @@ export function Hero({ version, stars }: HeroProps): React.ReactElement {
<div className="absolute inset-0 bg-gradient-to-b from-zinc-900/50 to-transparent pointer-events-none"></div>
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8 pt-8 pb-10 relative">
<div className="hidden lg:block mb-6 overflow-hidden">
<pre className="text-zinc-600 text-[10px] leading-none font-mono select-none whitespace-pre" style={{ fontFamily: 'JetBrains Mono, Consolas, monospace' }}>
<div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-3 mb-4 lg:mb-6">
<pre className="hidden sm:block text-zinc-600 text-[6px] sm:text-[8px] lg:text-[10px] leading-none font-mono select-none whitespace-pre overflow-x-auto" style={{ fontFamily: 'JetBrains Mono, Consolas, monospace' }}>
{ASCII_LOGO}
</pre>
<a
href="https://www.producthunt.com/products/skillkit-2?embed=true&utm_source=badge-top-post-badge&utm_medium=badge&utm_campaign=badge-skillkit-2"
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-2 sm:gap-3 bg-zinc-900/80 border border-zinc-800 hover:border-zinc-600 transition-colors rounded-full px-3 sm:px-4 py-1.5 sm:py-2 group shrink-0 self-start"
>
<span className="flex items-center justify-center w-6 h-6 sm:w-8 sm:h-8 rounded-full border border-zinc-600 bg-transparent text-white font-bold text-xs sm:text-sm">P</span>
<span className="flex flex-col">
<span className="text-[8px] sm:text-[10px] font-semibold text-zinc-500 tracking-wider uppercase leading-tight">Product Hunt</span>
<span className="text-[11px] sm:text-sm font-bold text-white group-hover:text-zinc-300 transition-colors leading-tight">#3 Product of the Day</span>
</span>
</a>
</div>
<div className="grid grid-cols-1 md:grid-cols-2 gap-6 lg:gap-8 items-start">
@@ -133,14 +143,14 @@ export function Hero({ version, stars }: HeroProps): React.ReactElement {
</div>
<h1 className="text-2xl sm:text-3xl lg:text-4xl font-bold tracking-tight text-white mb-3 font-mono">
One Skill.<br />
<span className="text-zinc-500">44 Agents. Zero Rewrites.</span>
One CLI. Every Source.<br />
<span className="text-zinc-500">Every Agent. Zero Telemetry.</span>
</h1>
<p className="text-sm text-zinc-400 mb-5 max-w-lg font-mono leading-relaxed">
The open source package manager for AI agent skills. Install from 15,000+ skills,
auto-translate between formats, persist learnings with Memory.
Works with Claude, Cursor, Windsurf, Copilot, Devin, Codex, and 38 more.
The open source package manager that aggregates 31+ skill sources,
auto-translates to 44 agent formats, and adds memory, security scanning,
and team workflows. No account required. Everything runs locally.
</p>
<div className="flex flex-wrap items-center gap-2 mb-4">
@@ -161,9 +171,24 @@ export function Hero({ version, stars }: HeroProps): React.ReactElement {
)}
</span>
</button>
<button
onClick={openGitHub}
className="inline-flex items-center gap-2 border border-zinc-700 px-3 py-2 hover:border-zinc-500 transition-colors group"
<a
href="https://github.com/rohitg00/skillkit/tree/main/packages/extension#readme"
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-2 bg-white text-black border border-zinc-300 px-3 py-2 hover:bg-zinc-200 transition-colors font-mono text-sm font-semibold"
>
<svg className="w-4 h-4" viewBox="0 0 24 24" fill="none">
<circle cx="12" cy="12" r="10" fill="#09090b"/>
<circle cx="12" cy="12" r="4.5" fill="white"/>
<path d="M12 2v5.5M12 16.5V22M2 12h5.5M16.5 12H22" stroke="white" strokeWidth="1.5"/>
</svg>
Add to Chrome
</a>
<a
href="https://github.com/rohitg00/skillkit"
target="_blank"
rel="noopener noreferrer"
className="sm:hidden inline-flex items-center gap-2 border border-zinc-700 px-3 py-2 hover:border-zinc-500 transition-colors group"
>
<svg className="w-4 h-4 text-zinc-400 group-hover:text-white transition-colors" fill="currentColor" viewBox="0 0 24 24">
<path fillRule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clipRule="evenodd" />
@@ -178,7 +203,7 @@ export function Hero({ version, stars }: HeroProps): React.ReactElement {
<span className="font-mono text-sm text-white font-medium">{stars}</span>
</>
)}
</button>
</a>
</div>
</div>
+2 -2
View File
@@ -92,7 +92,7 @@ export function TeamEnterprise(): React.ReactElement {
</p>
</div>
<a
href="https://agenstskills.com/docs/api-reference"
href="https://skillkit.sh/docs/api-reference"
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-2 px-3 sm:px-4 py-2 bg-zinc-800 text-white font-mono text-xs sm:text-sm hover:bg-zinc-700 transition-colors border border-zinc-700 whitespace-nowrap"
@@ -108,7 +108,7 @@ export function TeamEnterprise(): React.ReactElement {
{/* Bottom CTA */}
<div className="mt-6 sm:mt-8 text-center">
<a
href="https://agenstskills.com/docs"
href="https://skillkit.sh/docs"
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-2 px-4 sm:px-6 py-2.5 sm:py-3 bg-white text-black font-mono text-xs sm:text-sm hover:bg-zinc-200 transition-colors cursor-pointer"
+159
View File
@@ -0,0 +1,159 @@
import React from 'react';
interface Competitor {
name: string;
type: string;
agents: string;
translate: boolean;
memory: boolean;
security: boolean;
team: boolean;
tui: boolean;
api: boolean;
}
const COMPETITORS: Competitor[] = [
{ name: 'Vercel skills', type: 'Installer', agents: '~17', translate: false, memory: false, security: false, team: false, tui: false, api: false },
{ name: 'PRPM', type: 'Registry', agents: '~6', translate: true, memory: false, security: false, team: false, tui: false, api: false },
{ name: 'Askill', type: 'Installer', agents: '~40', translate: false, memory: false, security: true, team: false, tui: false, api: false },
{ name: 'Skild', type: 'Installer', agents: '~7', translate: false, memory: false, security: false, team: false, tui: false, api: false },
{ name: 'Paks', type: 'Installer', agents: '~6', translate: false, memory: false, security: false, team: false, tui: false, api: false },
{ name: 'SkillKit', type: 'Platform', agents: '44', translate: true, memory: true, security: true, team: true, tui: true, api: true },
];
const SOURCES = [
{ name: 'Anthropic', repo: 'anthropics/skills', official: true },
{ name: 'Vercel', repo: 'vercel-labs/agent-skills', official: true },
{ name: 'Expo', repo: 'expo/skills', official: true },
{ name: 'Supabase', repo: 'supabase/agent-skills', official: true },
{ name: 'Stripe', repo: 'stripe/ai', official: true },
{ name: 'Remotion', repo: 'remotion-dev/skills', official: true },
{ name: 'Trail of Bits', repo: 'trailofbits/skills', official: false },
{ name: 'Better Auth', repo: 'better-auth/skills', official: false },
{ name: 'ElysiaJS', repo: 'elysiajs/skills', official: false },
{ name: 'Nuxt', repo: 'onmax/nuxt-skills', official: false },
{ name: 'NestJS', repo: 'kadajett/agent-nestjs-skills', official: false },
{ name: 'Three.js', repo: 'cloudai-x/threejs-skills', official: false },
];
function Check(): React.ReactElement {
return <span className="text-green-400 text-xs font-bold">&#10003;</span>;
}
function Cross(): React.ReactElement {
return <span className="text-zinc-700 text-xs">&#8212;</span>;
}
export function WhySkillKit(): React.ReactElement {
return (
<section id="why" className="py-12 sm:py-16 border-b border-zinc-800" style={{ scrollMarginTop: '4rem' }}>
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
<div className="text-center mb-8 sm:mb-12">
<div className="inline-flex items-center gap-2 border border-zinc-700 bg-zinc-900/80 px-2 sm:px-3 py-1 mb-4 backdrop-blur-sm">
<span className="w-1.5 h-1.5 bg-white rounded-full"></span>
<span className="text-[10px] sm:text-xs font-mono text-zinc-300 uppercase tracking-wider">Not Another Installer</span>
</div>
<h2 className="text-2xl sm:text-3xl lg:text-4xl font-bold text-white mb-3 font-mono tracking-tight">
Others Install. SkillKit Orchestrates.
</h2>
<p className="text-zinc-400 font-mono text-xs sm:text-sm max-w-2xl mx-auto">
Most skill tools are simple installers with 3-5 commands.
SkillKit is a full platform that aggregates every source, translates to every format,
and adds memory, security, and team workflows on top.
</p>
</div>
<div className="overflow-x-auto -mx-4 px-4 sm:mx-0 sm:px-0 mb-12">
<div className="min-w-[640px]">
<table className="w-full border-collapse font-mono text-[10px] sm:text-xs">
<thead>
<tr className="border-b border-zinc-800">
<th className="text-left text-zinc-500 uppercase tracking-wider py-2 pr-3">Tool</th>
<th className="px-2 py-2 text-center text-zinc-500 uppercase tracking-wider">Agents</th>
<th className="px-2 py-2 text-center text-zinc-500 uppercase tracking-wider">Translate</th>
<th className="px-2 py-2 text-center text-zinc-500 uppercase tracking-wider">Memory</th>
<th className="px-2 py-2 text-center text-zinc-500 uppercase tracking-wider">Security</th>
<th className="px-2 py-2 text-center text-zinc-500 uppercase tracking-wider">Team</th>
<th className="px-2 py-2 text-center text-zinc-500 uppercase tracking-wider">TUI</th>
<th className="px-2 py-2 text-center text-zinc-500 uppercase tracking-wider">API</th>
</tr>
</thead>
<tbody>
{COMPETITORS.map((c) => {
const isSkillKit = c.name === 'SkillKit';
const rowClass = isSkillKit
? 'bg-white/[0.03] border-b border-zinc-700'
: 'border-b border-zinc-800/50 hover:bg-zinc-900/50';
const nameClass = isSkillKit ? 'text-white font-bold' : 'text-zinc-400';
return (
<tr key={c.name} className={rowClass}>
<td className="py-2.5 pr-3">
<div className="flex items-center gap-2">
<span className={nameClass}>{c.name}</span>
<span className="text-zinc-700 text-[9px]">{c.type}</span>
</div>
</td>
<td className={`px-2 py-2.5 text-center ${isSkillKit ? 'text-white font-bold' : 'text-zinc-500'}`}>{c.agents}</td>
<td className="px-2 py-2.5 text-center">{c.translate ? <Check /> : <Cross />}</td>
<td className="px-2 py-2.5 text-center">{c.memory ? <Check /> : <Cross />}</td>
<td className="px-2 py-2.5 text-center">{c.security ? <Check /> : <Cross />}</td>
<td className="px-2 py-2.5 text-center">{c.team ? <Check /> : <Cross />}</td>
<td className="px-2 py-2.5 text-center">{c.tui ? <Check /> : <Cross />}</td>
<td className="px-2 py-2.5 text-center">{c.api ? <Check /> : <Cross />}</td>
</tr>
);
})}
</tbody>
</table>
</div>
</div>
<div className="mb-8">
<h3 className="text-lg font-bold text-white mb-2 font-mono">
One CLI. Every Source. Zero Telemetry.
</h3>
<p className="text-zinc-400 font-mono text-xs sm:text-sm mb-6">
SkillKit doesn't compete with skill sources &mdash; it aggregates them.
Install from 31+ curated repositories, any GitHub/GitLab repo, or local paths.
Everything runs locally. No accounts, no tracking, no lock-in.
</p>
<div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-2">
{SOURCES.map((s) => (
<a
key={s.repo}
href={`https://github.com/${s.repo}`}
target="_blank"
rel="noopener noreferrer"
className="group flex items-center gap-2 px-3 py-2 border border-zinc-800 bg-zinc-900/30 hover:border-zinc-600 hover:bg-zinc-900/80 transition-all"
>
<span className="text-zinc-400 group-hover:text-white text-xs font-mono transition-colors">{s.name}</span>
{s.official && (
<span className="text-[8px] text-zinc-600 border border-zinc-800 px-1 py-0.5 uppercase tracking-wider">official</span>
)}
</a>
))}
<div className="flex items-center gap-2 px-3 py-2 border border-dashed border-zinc-800 text-zinc-600 text-xs font-mono">
+ 19 more community sources
</div>
</div>
</div>
<div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
<div className="p-4 border border-zinc-800 bg-zinc-900/30">
<div className="text-2xl font-bold text-white font-mono mb-1">0 bytes</div>
<div className="text-zinc-500 text-xs font-mono">telemetry collected</div>
</div>
<div className="p-4 border border-zinc-800 bg-zinc-900/30">
<div className="text-2xl font-bold text-white font-mono mb-1">Apache 2.0</div>
<div className="text-zinc-500 text-xs font-mono">fully open source</div>
</div>
<div className="p-4 border border-zinc-800 bg-zinc-900/30">
<div className="text-2xl font-bold text-white font-mono mb-1">No account</div>
<div className="text-zinc-500 text-xs font-mono">required to use</div>
</div>
</div>
</div>
</section>
);
}
+4 -4
View File
@@ -8,20 +8,20 @@
<!-- Open Graph -->
<meta property="og:type" content="website">
<meta property="og:url" content="https://agenstskills.com/">
<meta property="og:url" content="https://skillkit.sh/">
<meta property="og:title" content="SkillKit - Universal Skills for AI Coding Agents">
<meta property="og:description" content="Write once, deploy to 44 AI coding agents. Skills for Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and more.">
<meta property="og:image" content="https://agenstskills.com/og-image.png">
<meta property="og:image" content="https://skillkit.sh/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:site_name" content="SkillKit">
<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:url" content="https://agenstskills.com/">
<meta name="twitter:url" content="https://skillkit.sh/">
<meta name="twitter:title" content="SkillKit - Universal Skills for AI Coding Agents">
<meta name="twitter:description" content="Write once, deploy to 44 AI coding agents. Skills for Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and more.">
<meta name="twitter:image" content="https://agenstskills.com/og-image.png">
<meta name="twitter:image" content="https://skillkit.sh/og-image.png">
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32.png" />
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "skillkit",
"private": true,
"version": "1.16.0",
"version": "1.19.2",
"type": "module",
"scripts": {
"dev": "vite",
+76
View File
@@ -0,0 +1,76 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Privacy Policy — SkillKit</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { background: #09090b; color: #d4d4d8; font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif; line-height: 1.7; }
.container { max-width: 640px; margin: 0 auto; padding: 48px 24px; }
h1 { color: #fafafa; font-size: 28px; font-weight: 700; margin-bottom: 8px; font-family: 'JetBrains Mono', monospace; }
.updated { color: #71717a; font-size: 13px; margin-bottom: 32px; }
h2 { color: #fafafa; font-size: 18px; font-weight: 600; margin-top: 32px; margin-bottom: 12px; }
p { margin-bottom: 16px; font-size: 15px; }
ul { margin-bottom: 16px; padding-left: 24px; }
li { margin-bottom: 8px; font-size: 15px; }
a { color: #fafafa; text-decoration: underline; text-underline-offset: 2px; }
a:hover { color: #a1a1aa; }
.back { display: inline-block; margin-bottom: 24px; color: #71717a; font-size: 13px; text-decoration: none; font-family: 'JetBrains Mono', monospace; }
.back:hover { color: #fafafa; }
</style>
</head>
<body>
<div class="container">
<a href="/" class="back">&larr; Back to SkillKit</a>
<h1>Privacy Policy</h1>
<p class="updated">Last updated: February 14, 2026</p>
<h2>Overview</h2>
<p>SkillKit ("we", "our", "us") is an open-source CLI tool and Chrome extension for managing AI agent skills. We are committed to protecting your privacy. This policy explains what data we collect (or don't) across all SkillKit products.</p>
<h2>Chrome Extension — "SkillKit - Save as Skill"</h2>
<p>The Chrome extension helps you save webpages as AI agent skill files.</p>
<ul>
<li><strong>What data is sent:</strong> When you click "Save as Skill", the extension sends the URL of the current page to our server at <code>https://skillkit.sh/api/save-skill</code>. This is required to fetch and convert the webpage content into a skill file.</li>
<li><strong>What data is NOT sent:</strong> We do not send page content, browsing history, personal information, cookies, authentication tokens, or any data beyond the single URL you choose to save.</li>
<li><strong>No data stored on server:</strong> The URL is processed in real time to extract content, generate tags, and build the skill file. No URLs, page content, or user data are stored, logged, or retained on the server after the response is returned.</li>
<li><strong>Selection saves are local:</strong> When you save selected text via the right-click menu, the skill file is built entirely in the browser with no network requests.</li>
<li><strong>No analytics or tracking:</strong> We do not use any analytics, telemetry, or tracking services.</li>
<li><strong>No user accounts:</strong> No login, API key, or account is required.</li>
<li><strong>Downloads:</strong> Generated skill files are saved to your local filesystem via the Chrome Downloads API. No files are uploaded anywhere.</li>
</ul>
<h2>Permissions Used</h2>
<ul>
<li><strong>activeTab:</strong> Read the URL and title of the tab you are viewing when you click the extension. Only accessed when you actively use the extension.</li>
<li><strong>contextMenus:</strong> Add "Save page as Skill" and "Save selection as Skill" to the right-click menu.</li>
<li><strong>downloads:</strong> Save the generated SKILL.md file to your Downloads folder.</li>
</ul>
<h2>CLI Tool</h2>
<p>The SkillKit CLI runs entirely on your local machine. It does not phone home, collect telemetry, or transmit any data to external servers unless you explicitly use network features (e.g., <code>skillkit install</code> fetches public GitHub repositories).</p>
<h2>MCP Server</h2>
<p>The SkillKit MCP server runs locally and provides skill discovery over the Model Context Protocol. It loads skill data from a bundled JSON file and does not make external network requests or collect user data.</p>
<h2>Website</h2>
<p>The SkillKit website is available at <a href="https://skillkit.sh">skillkit.sh</a> and <a href="https://agenstskills.com">agenstskills.com</a>. It is a static site hosted on Vercel. We do not use cookies, analytics trackers, or collect personal information. Vercel may collect standard web server logs (IP address, user agent) as described in their <a href="https://vercel.com/legal/privacy-policy">privacy policy</a>.</p>
<h2>Third-Party Services</h2>
<p>The Chrome extension communicates with <code>skillkit.sh</code> and <code>agenstskills.com</code> (both our own servers, hosted on Vercel) to process webpage URLs. No third-party data processors, advertising networks, or analytics services are used.</p>
<h2>Data Retention</h2>
<p>We do not retain any user data. URLs sent to the API are processed in memory and discarded immediately after the response.</p>
<h2>Changes to This Policy</h2>
<p>We may update this privacy policy from time to time. Changes will be posted on this page with an updated revision date.</p>
<h2>Contact</h2>
<p>If you have questions about this privacy policy, contact us at <a href="mailto:ghumare64@gmail.com">ghumare64@gmail.com</a>.</p>
<h2>Open Source</h2>
<p>SkillKit is open source under the Apache 2.0 license. You can review all source code at <a href="https://github.com/rohitg00/skillkit">github.com/rohitg00/skillkit</a>.</p>
</div>
</body>
</html>
Binary file not shown.
+1
View File
@@ -1,4 +1,5 @@
{
"ignoreCommand": "git diff --quiet HEAD^ HEAD -- .",
"buildCommand": "npm run build",
"outputDirectory": "dist",
"installCommand": "npm install",
+6 -6
View File
@@ -536,28 +536,28 @@
]
},
{
"id": "composioHQ/awesome-claude-code-skills/python-best-practices",
"id": "composioHQ/awesome-claude-skills/python-best-practices",
"name": "Python Best Practices",
"description": "Python coding standards and patterns",
"source": "composioHQ/awesome-claude-code-skills",
"source": "composioHQ/awesome-claude-skills",
"tags": [
"python"
]
},
{
"id": "composioHQ/awesome-claude-code-skills/rust-patterns",
"id": "composioHQ/awesome-claude-skills/rust-patterns",
"name": "Rust Patterns",
"description": "Rust memory safety and performance patterns",
"source": "composioHQ/awesome-claude-code-skills",
"source": "composioHQ/awesome-claude-skills",
"tags": [
"rust"
]
},
{
"id": "composioHQ/awesome-claude-code-skills/go-patterns",
"id": "composioHQ/awesome-claude-skills/go-patterns",
"name": "Go Patterns",
"description": "Go concurrency and idiomatic patterns",
"source": "composioHQ/awesome-claude-code-skills",
"source": "composioHQ/awesome-claude-skills",
"tags": [
"golang",
"go"
+2 -1
View File
@@ -34,6 +34,7 @@
{ "source": "jimliu/baoyu-skills", "name": "Baoyu Tools" },
{ "source": "giuseppe-trisciuoglio/developer-kit", "name": "Shadcn / Radix" },
{ "source": "openrouterteam/agent-skills", "name": "OpenRouter SDK" },
{ "source": "intellectronica/agent-skills", "name": "Context7" }
{ "source": "intellectronica/agent-skills", "name": "Context7" },
{ "source": "skills.sh", "name": "Skills.sh Leaderboard", "official": true, "registry": "skills-sh" }
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit-monorepo",
"version": "1.16.0",
"version": "1.19.2",
"private": true,
"description": "The package manager for AI agent skills — install, translate, share across 32 coding agents",
"type": "module",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/agents",
"version": "1.16.0",
"version": "1.19.2",
"description": "Agent adapters for SkillKit - supports 32 AI coding agents",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/api",
"version": "1.16.0",
"version": "1.19.2",
"description": "REST API server for SkillKit skill discovery",
"type": "module",
"main": "./dist/index.js",
+95
View File
@@ -0,0 +1,95 @@
import { Hono } from 'hono';
import { ContentExtractor, SkillGenerator, AutoTagger } from '@skillkit/core';
interface SaveRequest {
url?: string;
text?: string;
name?: string;
global?: boolean;
}
const MAX_TEXT_LENGTH = 500_000;
const BLOCKED_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1', '0.0.0.0']);
function isAllowedUrl(url: string): boolean {
try {
const parsed = new URL(url);
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
const hostname = parsed.hostname.toLowerCase();
const bare = hostname.replace(/^\[|\]$/g, '');
if (BLOCKED_HOSTS.has(hostname) || BLOCKED_HOSTS.has(bare)) return false;
if (bare.startsWith('::ffff:')) return isAllowedUrl(`http://${bare.slice(7)}`);
if (/^127\./.test(bare) || /^0\./.test(bare)) return false;
if (bare.startsWith('10.') || bare.startsWith('192.168.')) return false;
if (/^172\.(1[6-9]|2\d|3[01])\./.test(bare)) return false;
if (bare.startsWith('169.254.')) return false;
if (bare.startsWith('fe80:') || bare.startsWith('fc') || bare.startsWith('fd')) return false;
if (/^(22[4-9]|23\d|24\d|25[0-5])\./.test(bare)) return false;
if (bare.startsWith('ff')) return false;
return true;
} catch {
return false;
}
}
export function saveRoutes() {
const app = new Hono();
const extractor = new ContentExtractor();
const generator = new SkillGenerator();
const tagger = new AutoTagger();
app.post('/save', async (c) => {
let body: SaveRequest;
try {
body = await c.req.json();
} catch {
return c.json({ error: 'Invalid JSON body' }, 400);
}
if (!body.url && !body.text) {
return c.json({ error: 'Either "url" or "text" is required' }, 400);
}
if (body.url && !isAllowedUrl(body.url)) {
return c.json({ error: 'URL must be a public HTTP(S) address' }, 400);
}
if (body.text && body.text.length > MAX_TEXT_LENGTH) {
return c.json({ error: `Text exceeds maximum length of ${MAX_TEXT_LENGTH} characters` }, 400);
}
try {
const content = body.url
? await extractor.extractFromUrl(body.url)
: extractor.extractFromText(body.text!);
const result = generator.generate(content, {
name: body.name,
global: body.global ?? true,
});
return c.json({
name: result.name,
skillPath: result.skillPath,
skillMd: result.skillMd,
tags: tagger.detectTags(content),
});
} catch (err) {
const message = err instanceof Error ? err.message : 'Unknown error';
const isTimeout =
(err instanceof DOMException && err.name === 'TimeoutError') ||
(err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError'));
if (isTimeout) {
return c.json({ error: `Fetch timeout: ${message}` }, 504);
}
return c.json({ error: `Extraction failed: ${message}` }, 422);
}
});
return app;
}
+2
View File
@@ -8,6 +8,7 @@ import { skillRoutes } from './routes/skills.js';
import { trendingRoutes } from './routes/trending.js';
import { categoryRoutes } from './routes/categories.js';
import { docsRoutes } from './routes/docs.js';
import { saveRoutes } from './routes/save.js';
import type { ApiSkill, SearchResponse } from './types.js';
export interface ServerOptions {
@@ -37,6 +38,7 @@ export function createApp(options: ServerOptions = {}) {
app.route('/', trendingRoutes(skills));
app.route('/', categoryRoutes(skills));
app.route('/', docsRoutes());
app.route('/', saveRoutes());
return { app, cache };
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/cli",
"version": "1.16.0",
"version": "1.19.2",
"description": "CLI commands for SkillKit",
"type": "module",
"main": "./dist/index.js",
@@ -20,6 +20,16 @@ describe('CLI Commands', () => {
expect(commands.TranslateCommand).toBeDefined();
expect(commands.ContextCommand).toBeDefined();
expect(commands.RecommendCommand).toBeDefined();
expect(commands.ActivityCommand).toBeDefined();
expect(commands.DoctorCommand).toBeDefined();
expect(commands.IssuePlanCommand).toBeDefined();
expect(commands.IssueListCommand).toBeDefined();
expect(commands.SessionSnapshotSaveCommand).toBeDefined();
expect(commands.SessionSnapshotRestoreCommand).toBeDefined();
expect(commands.SessionSnapshotListCommand).toBeDefined();
expect(commands.SessionSnapshotDeleteCommand).toBeDefined();
expect(commands.SessionExplainCommand).toBeDefined();
});
});
});
@@ -0,0 +1,232 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { execSync } from 'node:child_process';
import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { stringify } from 'yaml';
const CLI = join(__dirname, '../../../../apps/skillkit/dist/cli.js');
function run(args: string, cwd: string): string {
try {
return execSync(`node ${CLI} ${args}`, {
cwd,
encoding: 'utf-8',
timeout: 15000,
env: { ...process.env, NO_COLOR: '1' },
});
} catch (err: any) {
return err.stdout || err.stderr || err.message;
}
}
describe('E2E: Session Features', () => {
let testDir: string;
beforeEach(() => {
testDir = join(tmpdir(), `skillkit-e2e-${Date.now()}`);
mkdirSync(testDir, { recursive: true });
});
afterEach(() => {
rmSync(testDir, { recursive: true, force: true });
});
describe('skillkit activity', () => {
it('should show empty state message', () => {
const output = run('activity', testDir);
expect(output).toContain('No activity recorded');
});
it('should return empty JSON array', () => {
const output = run('activity --json', testDir);
const parsed = JSON.parse(output.trim());
expect(parsed).toEqual([]);
});
it('should accept --skill filter without error', () => {
const output = run('activity --skill code-simplifier', testDir);
expect(output).toContain('No activity recorded');
});
it('should accept --limit flag without error', () => {
const output = run('activity --limit 5', testDir);
expect(output).toContain('No activity recorded');
});
});
describe('skillkit session snapshot', () => {
it('should list no snapshots initially', () => {
const output = run('session snapshot list', testDir);
expect(output).toContain('No snapshots found');
});
it('should return empty JSON for snapshot list', () => {
const output = run('session snapshot list --json', testDir);
const parsed = JSON.parse(output.trim());
expect(parsed).toEqual([]);
});
it('should fail to save without active session', () => {
const output = run('session snapshot save test-snap', testDir);
expect(output).toContain('No active session');
});
it('should fail to restore nonexistent snapshot', () => {
const output = run('session snapshot restore nonexistent', testDir);
expect(output).toContain('not found');
});
it('should fail to delete nonexistent snapshot', () => {
const output = run('session snapshot delete nonexistent', testDir);
expect(output).toContain('not found');
});
it('should save and restore snapshot with active session', () => {
const skillkitDir = join(testDir, '.skillkit');
mkdirSync(skillkitDir, { recursive: true });
const sessionState = {
version: 1,
lastActivity: new Date().toISOString(),
projectPath: testDir,
currentExecution: {
skillName: 'code-simplifier',
skillSource: 'local',
currentStep: 1,
totalSteps: 2,
status: 'running',
startedAt: new Date().toISOString(),
tasks: [
{
id: 'task-1',
name: 'Test task',
type: 'auto',
status: 'completed',
},
],
},
history: [],
decisions: [{ key: 'test-key', value: 'test-value', madeAt: new Date().toISOString() }],
};
writeFileSync(
join(skillkitDir, 'session.yaml'),
stringify(sessionState)
);
const saveOutput = run('session snapshot save my-test-snap --desc "E2E test"', testDir);
expect(saveOutput).toContain('Snapshot saved: my-test-snap');
const snapshotFile = join(skillkitDir, 'snapshots', 'my-test-snap.yaml');
expect(existsSync(snapshotFile)).toBe(true);
const listOutput = run('session snapshot list', testDir);
expect(listOutput).toContain('my-test-snap');
expect(listOutput).toContain('E2E test');
const restoreOutput = run('session snapshot restore my-test-snap', testDir);
expect(restoreOutput).toContain('Snapshot restored: my-test-snap');
const deleteOutput = run('session snapshot delete my-test-snap', testDir);
expect(deleteOutput).toContain('Snapshot deleted: my-test-snap');
expect(existsSync(snapshotFile)).toBe(false);
});
});
describe('skillkit session explain', () => {
it('should show empty session summary', () => {
const output = run('session explain --no-git', testDir);
expect(output).toContain('Session Summary');
expect(output).toContain('Agent:');
expect(output).toContain('Files Modified: 0 files');
});
it('should return valid JSON', () => {
const output = run('session explain --json --no-git', testDir);
const parsed = JSON.parse(output.trim());
expect(parsed.date).toBeDefined();
expect(parsed.agent).toBe('unknown');
expect(parsed.skillsUsed).toEqual([]);
expect(parsed.observationCounts).toBeDefined();
expect(typeof parsed.observationCounts.errors).toBe('number');
expect(typeof parsed.observationCounts.solutions).toBe('number');
expect(typeof parsed.observationCounts.patterns).toBe('number');
});
it('should explain session with active execution', () => {
const skillkitDir = join(testDir, '.skillkit');
mkdirSync(skillkitDir, { recursive: true });
const sessionState = {
version: 1,
lastActivity: new Date().toISOString(),
projectPath: testDir,
currentExecution: {
skillName: 'remotion-best-practices',
skillSource: 'claude-code',
currentStep: 2,
totalSteps: 3,
status: 'running',
startedAt: new Date(Date.now() - 3600000).toISOString(),
tasks: [
{
id: 't1',
name: 'Setup video',
type: 'auto',
status: 'completed',
startedAt: new Date(Date.now() - 3600000).toISOString(),
completedAt: new Date(Date.now() - 1800000).toISOString(),
filesModified: ['src/video.tsx'],
},
{
id: 't2',
name: 'Add effects',
type: 'auto',
status: 'in_progress',
startedAt: new Date(Date.now() - 1800000).toISOString(),
},
],
},
history: [],
decisions: [
{ key: 'codec', value: 'h264', madeAt: new Date().toISOString() },
],
};
writeFileSync(
join(skillkitDir, 'session.yaml'),
stringify(sessionState)
);
const output = run('session explain --no-git', testDir);
expect(output).toContain('Session Summary');
expect(output).toContain('Duration:');
expect(output).toContain('claude-code');
expect(output).toContain('remotion-best-practices');
expect(output).toContain('Setup video');
expect(output).toContain('Add effects');
expect(output).toContain('codec');
const jsonOutput = run('session explain --json --no-git', testDir);
const parsed = JSON.parse(jsonOutput.trim());
expect(parsed.skillsUsed).toHaveLength(1);
expect(parsed.skillsUsed[0].name).toBe('remotion-best-practices');
expect(parsed.tasks).toHaveLength(2);
expect(parsed.decisions).toHaveLength(1);
expect(parsed.filesModified).toContain('src/video.tsx');
});
});
describe('skillkit session (help)', () => {
it('should list all subcommands including new ones', () => {
const output = run('session', testDir);
expect(output).toContain('session explain');
expect(output).toContain('session snapshot save');
expect(output).toContain('session snapshot restore');
expect(output).toContain('session snapshot list');
expect(output).toContain('session snapshot delete');
});
});
});
+4 -4
View File
@@ -16,8 +16,8 @@ export function generateBadge(skills: string[]): {
const url = `https://img.shields.io/badge/SkillKit-No%20Skills-555555?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
return {
url,
markdown: `[![SkillKit Stack](${url})](https://agenstskills.com)`,
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
markdown: `[![SkillKit Stack](${url})](https://skillkit.sh)`,
html: `<a href="https://skillkit.sh"><img src="${url}" alt="SkillKit Stack" /></a>`,
};
}
@@ -33,7 +33,7 @@ export function generateBadge(skills: string[]): {
return {
url,
markdown: `[![SkillKit Stack](${url})](https://agenstskills.com)`,
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
markdown: `[![SkillKit Stack](${url})](https://skillkit.sh)`,
html: `<a href="https://skillkit.sh"><img src="${url}" alt="SkillKit Stack" /></a>`,
};
}
+94
View File
@@ -0,0 +1,94 @@
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import { ActivityLog } from '@skillkit/core';
export class ActivityCommand extends Command {
static override paths = [['activity']];
static override usage = Command.Usage({
description: 'Show skill activity log for git commits',
examples: [
['Show recent activity', '$0 activity'],
['Filter by skill', '$0 activity --skill code-simplifier'],
['JSON output', '$0 activity --json'],
],
});
skill = Option.String('--skill,-s', {
description: 'Filter by skill name',
});
limit = Option.String('--limit,-l', {
description: 'Number of entries to show (default: 10)',
});
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const log = new ActivityLog(projectPath);
const parsed = this.limit ? parseInt(this.limit, 10) : 10;
const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 10;
const activities = this.skill
? log.getBySkill(this.skill)
: log.getRecent(limit);
if (this.json) {
console.log(JSON.stringify(activities.slice(0, limit), null, 2));
return 0;
}
if (activities.length === 0) {
console.log(chalk.yellow('No activity recorded'));
console.log(
chalk.dim(
'Activity is recorded when skills are active during git commits.'
)
);
return 0;
}
console.log(chalk.cyan(' Recent Skill Activity\n'));
const displayed = activities.slice(0, limit);
for (const activity of displayed) {
const shortSha = activity.commitSha.slice(0, 7);
const skills = activity.activeSkills.join(', ');
const files = activity.filesChanged.join(', ');
const ago = formatTimeAgo(activity.committedAt);
console.log(` ${chalk.bold(shortSha)} ${activity.message}`);
console.log(` Skills: ${chalk.green(skills)}`);
console.log(
` Files: ${files} ${chalk.dim(`(${ago})`)}`
);
console.log();
}
const topSkills = log.getMostUsedSkills().slice(0, 5);
if (topSkills.length > 0) {
const formatted = topSkills
.map((s) => `${s.skill} (${s.count})`)
.join(', ');
console.log(` Top Skills: ${formatted}`);
}
return 0;
}
}
function formatTimeAgo(isoDate: string): string {
const diff = Date.now() - new Date(isoDate).getTime();
const minutes = Math.floor(diff / 60000);
const hours = Math.floor(minutes / 60);
const days = Math.floor(hours / 24);
if (days > 0) return `${days}d ago`;
if (hours > 0) return `${hours}h ago`;
if (minutes > 0) return `${minutes}m ago`;
return 'just now';
}
+123
View File
@@ -0,0 +1,123 @@
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import chalk from 'chalk';
import { Command } from 'clipanion';
import { AgentsMdGenerator, AgentsMdParser } from '@skillkit/core';
export class AgentsMdCommand extends Command {
static override paths = [['agents']];
static override usage = Command.Usage({
description: 'Manage AGENTS.md for project-specific agent context',
details: `
Sub-commands:
agents init - Generate initial AGENTS.md
agents sync - Update managed sections in existing AGENTS.md
agents show - Display current AGENTS.md content
`,
examples: [
['Generate AGENTS.md', '$0 agents init'],
['Update skills section', '$0 agents sync'],
['Show AGENTS.md', '$0 agents show'],
],
});
async execute(): Promise<number> {
this.context.stdout.write(this.cli.usage(AgentsMdCommand, { detailed: true }));
return 0;
}
}
export class AgentsMdInitCommand extends Command {
static override paths = [['agents', 'init']];
static override usage = Command.Usage({
description: 'Generate initial AGENTS.md in current directory',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const agentsPath = join(projectPath, 'AGENTS.md');
if (existsSync(agentsPath)) {
console.log(chalk.yellow('AGENTS.md already exists. Use `skillkit agents sync` to update.'));
return 1;
}
try {
const generator = new AgentsMdGenerator({ projectPath });
const result = generator.generate();
console.log(chalk.dim('Preview:'));
console.log('');
console.log(result.content);
writeFileSync(agentsPath, result.content, 'utf-8');
console.log(chalk.green(`Created ${agentsPath}`));
return 0;
} catch (err) {
console.log(chalk.red(`Failed to generate AGENTS.md: ${err instanceof Error ? err.message : String(err)}`));
return 1;
}
}
}
export class AgentsMdSyncCommand extends Command {
static override paths = [['agents', 'sync']];
static override usage = Command.Usage({
description: 'Update managed sections in existing AGENTS.md',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const agentsPath = join(projectPath, 'AGENTS.md');
if (!existsSync(agentsPath)) {
console.log(chalk.yellow('No AGENTS.md found. Run `skillkit agents init` first.'));
return 1;
}
try {
const existing = readFileSync(agentsPath, 'utf-8');
const parser = new AgentsMdParser();
if (!parser.hasManagedSections(existing)) {
console.log(chalk.yellow('No managed sections found in AGENTS.md. Nothing to update.'));
return 0;
}
const generator = new AgentsMdGenerator({ projectPath });
const result = generator.generate();
const managedSections = result.sections.filter(s => s.managed);
const updated = parser.updateManagedSections(existing, managedSections);
writeFileSync(agentsPath, updated, 'utf-8');
console.log(chalk.green(`Updated ${managedSections.length} managed section(s) in AGENTS.md`));
return 0;
} catch (err) {
console.log(chalk.red(`Failed to sync AGENTS.md: ${err instanceof Error ? err.message : String(err)}`));
return 1;
}
}
}
export class AgentsMdShowCommand extends Command {
static override paths = [['agents', 'show']];
static override usage = Command.Usage({
description: 'Display current AGENTS.md content',
});
async execute(): Promise<number> {
const agentsPath = join(process.cwd(), 'AGENTS.md');
if (!existsSync(agentsPath)) {
console.log(chalk.yellow('No AGENTS.md found. Run `skillkit agents init` to create one.'));
return 1;
}
console.log(readFileSync(agentsPath, 'utf-8'));
return 0;
}
}
+297
View File
@@ -0,0 +1,297 @@
import { Command, Option } from 'clipanion';
import { execFileSync } from 'node:child_process';
import { existsSync, lstatSync, readlinkSync, readdirSync, mkdirSync, unlinkSync } from 'node:fs';
import { resolve, join } from 'node:path';
import { homedir } from 'node:os';
import { detectAgent, getAdapter } from '@skillkit/agents';
import { AgentType, findAllSkills, validateSkill, loadConfig, getProjectConfigPath, getGlobalSkillsDir } from '@skillkit/core';
import type { AgentType as AgentTypeT } from '@skillkit/core';
import { getSearchDirs } from '../helpers.js';
import { colors, symbols } from '../onboarding/index.js';
interface CheckResult {
name: string;
status: 'pass' | 'warn' | 'fail';
message: string;
fix?: string;
}
export class DoctorCommand extends Command {
static override paths = [['doctor']];
static override usage = Command.Usage({
description: 'Diagnose setup issues and check environment health',
details: `
Runs a series of checks to verify your SkillKit setup is correct,
including environment, agent detection, skills health, and configuration.
`,
examples: [
['Run health checks', '$0 doctor'],
['JSON output', '$0 doctor --json'],
['Auto-fix issues', '$0 doctor --fix'],
],
});
json = Option.Boolean('--json,-j', false, {
description: 'Output in JSON format',
});
fix = Option.Boolean('--fix', false, {
description: 'Auto-fix issues where possible',
});
async execute(): Promise<number> {
const results: CheckResult[] = [];
// --- Environment ---
const nodeVersion = process.version;
const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0], 10);
if (nodeMajor >= 18) {
results.push({ name: 'Node.js version', status: 'pass', message: `Node.js ${nodeVersion}` });
} else {
results.push({ name: 'Node.js version', status: 'fail', message: `Node.js ${nodeVersion} — upgrade to >=18 required` });
}
const npmVersion = this.whichVersion('npm');
if (npmVersion) {
results.push({ name: 'npm available', status: 'pass', message: `npm v${npmVersion}` });
} else {
results.push({ name: 'npm available', status: 'warn', message: 'npm not found' });
}
const pnpmVersion = this.whichVersion('pnpm');
if (pnpmVersion) {
results.push({ name: 'pnpm available', status: 'pass', message: `pnpm v${pnpmVersion}` });
}
const skillkitVersion = this.cli.binaryVersion ?? 'unknown';
results.push({ name: 'SkillKit version', status: 'pass', message: `skillkit v${skillkitVersion}` });
// --- Configuration ---
const configPath = getProjectConfigPath();
const hasConfig = existsSync(configPath);
if (hasConfig) {
try {
const agent = loadConfig().agent;
results.push({ name: 'Config file', status: 'pass', message: `skillkit.yaml (agent: ${agent})` });
} catch {
results.push({ name: 'Config file', status: 'warn', message: 'skillkit.yaml found but has parse errors' });
}
} else {
results.push({ name: 'Config file', status: 'warn', message: 'No config file (using defaults)' });
}
// --- Agent Detection ---
let detectedAgent: AgentTypeT = 'universal';
try {
detectedAgent = await detectAgent();
results.push({ name: 'Detected agent', status: 'pass', message: `Detected: ${detectedAgent}` });
} catch {
results.push({ name: 'Detected agent', status: 'warn', message: 'No agent detected (using universal)' });
}
const otherDetected: string[] = [];
try {
for (const agentType of AgentType.options) {
if (agentType === detectedAgent || agentType === 'universal') continue;
try {
const agentAdapter = getAdapter(agentType);
if (await agentAdapter.isDetected()) {
otherDetected.push(agentType);
}
} catch {
// skip
}
}
if (otherDetected.length > 0) {
results.push({ name: 'Other agents', status: 'warn', message: `Also detected: ${otherDetected.join(', ')}` });
}
} catch {
// skip
}
// --- Skills ---
const adapter = getAdapter(detectedAgent);
const skillsDir = resolve(adapter.skillsDir);
const skillsDirExists = existsSync(skillsDir);
if (skillsDirExists) {
const entries = readdirSync(skillsDir).filter(e => !e.startsWith('.'));
results.push({ name: 'Project skills dir', status: 'pass', message: `${adapter.skillsDir} (${entries.length} entries)` });
} else {
if (this.fix) {
mkdirSync(skillsDir, { recursive: true });
results.push({ name: 'Project skills dir', status: 'pass', message: `${adapter.skillsDir} (created)` });
} else {
results.push({
name: 'Project skills dir',
status: 'warn',
message: `${adapter.skillsDir} missing`,
fix: 'Run with --fix to create it',
});
}
}
const globalSkillsDirRaw = getGlobalSkillsDir(detectedAgent);
const globalSkillsDir = globalSkillsDirRaw ? globalSkillsDirRaw.replace(/^~/, homedir()) : null;
if (globalSkillsDir && existsSync(globalSkillsDir)) {
const entries = readdirSync(globalSkillsDir).filter(e => !e.startsWith('.'));
results.push({ name: 'Global skills dir', status: 'pass', message: `${globalSkillsDir} (${entries.length} entries)` });
} else {
results.push({ name: 'Global skills dir', status: 'pass', message: 'No global skills directory' });
}
// Skill validation
let searchDirs: string[] = [];
try {
searchDirs = getSearchDirs(detectedAgent);
} catch {
searchDirs = skillsDirExists ? [skillsDir] : [];
}
const allSkills = findAllSkills(searchDirs);
const invalidSkills: string[] = [];
for (const skill of allSkills) {
const validation = validateSkill(skill.path);
if (!validation.valid) {
invalidSkills.push(`${skill.name}: ${validation.errors.join(', ')}`);
}
}
if (allSkills.length === 0) {
results.push({ name: 'Installed skills', status: 'pass', message: 'No skills installed' });
} else if (invalidSkills.length === 0) {
results.push({ name: 'Installed skills', status: 'pass', message: `${allSkills.length} skills, all valid` });
} else {
results.push({
name: 'Installed skills',
status: 'fail',
message: `${invalidSkills.length} of ${allSkills.length} skills have errors`,
fix: invalidSkills.join('; '),
});
}
// Broken symlinks
const brokenSymlinks: string[] = [];
for (const dir of searchDirs) {
if (!existsSync(dir)) continue;
try {
const entries = readdirSync(dir);
for (const entry of entries) {
const fullPath = join(dir, entry);
try {
const stat = lstatSync(fullPath);
if (stat.isSymbolicLink()) {
const target = readlinkSync(fullPath);
const resolvedTarget = resolve(dir, target);
if (!existsSync(resolvedTarget)) {
brokenSymlinks.push(fullPath);
}
}
} catch {
// skip
}
}
} catch {
// skip
}
}
if (brokenSymlinks.length > 0) {
if (this.fix) {
let removed = 0;
const failed: string[] = [];
for (const link of brokenSymlinks) {
try {
unlinkSync(link);
removed++;
} catch {
failed.push(link);
}
}
if (failed.length > 0) {
results.push({ name: 'Broken symlinks', status: 'warn', message: `Removed ${removed}, failed to remove ${failed.length}` });
} else {
results.push({ name: 'Broken symlinks', status: 'pass', message: `Removed ${brokenSymlinks.length} broken symlink(s)` });
}
} else {
results.push({
name: 'Broken symlinks',
status: 'fail',
message: `${brokenSymlinks.length} broken symlink(s) found`,
fix: brokenSymlinks.map(l => ` ${l}`).join('\n'),
});
}
} else {
results.push({ name: 'Broken symlinks', status: 'pass', message: 'No broken symlinks' });
}
// --- Output ---
if (this.json) {
const summary = {
checks: results,
passed: results.filter(r => r.status === 'pass').length,
warnings: results.filter(r => r.status === 'warn').length,
errors: results.filter(r => r.status === 'fail').length,
};
console.log(JSON.stringify(summary, null, 2));
return summary.errors > 0 ? 1 : 0;
}
console.log('');
console.log(colors.primary('skillkit doctor'));
console.log('');
const sections: Record<string, string[]> = {
Environment: ['Node.js version', 'npm available', 'pnpm available', 'SkillKit version'],
Configuration: ['Config file', 'Detected agent', 'Other agents'],
Skills: ['Project skills dir', 'Global skills dir', 'Installed skills', 'Broken symlinks'],
};
for (const [section, checkNames] of Object.entries(sections)) {
const sectionResults = results.filter(r => checkNames.includes(r.name));
if (sectionResults.length === 0) continue;
console.log(` ${colors.primary(section)}`);
for (const result of sectionResults) {
const icon = this.statusIcon(result.status);
console.log(` ${icon} ${result.message}`);
if (result.fix && result.status !== 'pass') {
console.log(` ${colors.muted(result.fix)}`);
}
}
console.log('');
}
const passed = results.filter(r => r.status === 'pass').length;
const warnings = results.filter(r => r.status === 'warn').length;
const errors = results.filter(r => r.status === 'fail').length;
const parts = [`${passed} passed`];
if (warnings > 0) parts.push(`${warnings} warning(s)`);
if (errors > 0) parts.push(`${errors} error(s)`);
console.log(` ${colors.muted('Summary:')} ${parts.join(', ')}`);
console.log('');
return errors > 0 ? 1 : 0;
}
private statusIcon(status: CheckResult['status']): string {
switch (status) {
case 'pass': return colors.success(symbols.success);
case 'warn': return colors.warning(symbols.warning);
case 'fail': return colors.error(symbols.error);
}
}
private whichVersion(cmd: string): string | null {
try {
return execFileSync(cmd, ['--version'], { encoding: 'utf-8', timeout: 5000 })
.trim()
.replace(/^v/, '');
} catch {
return null;
}
}
}
+175 -92
View File
@@ -1,4 +1,4 @@
import { Command, Option } from 'clipanion';
import { Command, Option } from "clipanion";
import {
colors,
symbols,
@@ -7,8 +7,13 @@ import {
isCancel,
select,
header,
} from '../onboarding/index.js';
import { FederatedSearch, GitHubSkillRegistry, RateLimitError } from '@skillkit/core';
} from "../onboarding/index.js";
import {
FederatedSearch,
GitHubSkillRegistry,
SkillsShRegistry,
} from "@skillkit/core";
import { formatCount } from "../helpers.js";
interface SkillResult {
name: string;
@@ -17,46 +22,46 @@ interface SkillResult {
repoName: string;
}
import skillsData from '../../../../marketplace/skills.json' with { type: 'json' };
import sourcesData from '../../../../marketplace/sources.json' with { type: 'json' };
import skillsData from "../../../../marketplace/skills.json" with { type: "json" };
import sourcesData from "../../../../marketplace/sources.json" with { type: "json" };
export class FindCommand extends Command {
static override paths = [['find'], ['search']];
static override paths = [["find"], ["search"]];
static override usage = Command.Usage({
description: 'Search for skills in the marketplace',
description: "Search for skills in the marketplace",
details: `
Quickly find and install skills from the marketplace.
Interactive mode lets you browse and install in one step.
`,
examples: [
['Interactive search', '$0 find'],
['Search for specific skill', '$0 find pdf'],
['Search with keyword', '$0 find "nextjs"'],
['List top skills', '$0 find --top'],
["Interactive search", "$0 find"],
["Search for specific skill", "$0 find pdf"],
["Search with keyword", '$0 find "nextjs"'],
["List top skills", "$0 find --top"],
],
});
query = Option.String({ required: false });
top = Option.Boolean('--top,-t', false, {
description: 'Show top/featured skills',
top = Option.Boolean("--top,-t", false, {
description: "Show top/featured skills",
});
limit = Option.String('--limit,-l', '10', {
description: 'Maximum results to show',
limit = Option.String("--limit,-l", "10", {
description: "Maximum results to show",
});
install = Option.Boolean('--install,-i', false, {
description: 'Prompt to install after finding',
install = Option.Boolean("--install,-i", false, {
description: "Prompt to install after finding",
});
quiet = Option.Boolean('--quiet,-q', false, {
description: 'Minimal output (just list skills)',
quiet = Option.Boolean("--quiet,-q", false, {
description: "Minimal output (just list skills)",
});
federated = Option.Boolean('--federated,-f', false, {
description: 'Search external registries (GitHub SKILL.md files)',
federated = Option.Boolean("--federated,-f", false, {
description: "Search external registries (GitHub SKILL.md files)",
});
async execute(): Promise<number> {
@@ -64,17 +69,25 @@ export class FindCommand extends Command {
const limit = parseInt(this.limit, 10) || 10;
if (!this.quiet) {
header('Find Skills');
header("Find Skills");
}
const allSkills: SkillResult[] = (skillsData.skills || []).map((skill: { name: string; description?: string; source?: string; repo?: string }) => ({
name: skill.name,
description: skill.description,
source: skill.source || '',
repoName: skill.repo || skill.source?.split('/').pop() || '',
}));
const allSkills: SkillResult[] = (skillsData.skills || []).map(
(skill: {
name: string;
description?: string;
source?: string;
repo?: string;
}) => ({
name: skill.name,
description: skill.description,
source: skill.source || "",
repoName: skill.repo || skill.source?.split("/").pop() || "",
}),
);
let results: SkillResult[];
let searchTerm: string | undefined;
if (this.top) {
const featured = sourcesData.sources
@@ -82,35 +95,43 @@ export class FindCommand extends Command {
.slice(0, 5);
results = allSkills
.filter(skill => featured.some((f: { source: string }) => skill.source.includes(f.source)))
.filter((skill) =>
featured.some((f: { source: string }) =>
skill.source.includes(f.source),
),
)
.slice(0, limit);
if (!this.quiet) {
step('Showing featured skills');
step("Showing featured skills");
}
} else if (this.query) {
const query = this.query.toLowerCase();
searchTerm = this.query;
s.start('Searching...');
s.start("Searching...");
results = allSkills.filter(skill =>
skill.name.toLowerCase().includes(query) ||
skill.description?.toLowerCase().includes(query) ||
skill.source.toLowerCase().includes(query) ||
skill.repoName.toLowerCase().includes(query)
).slice(0, limit);
results = allSkills
.filter(
(skill) =>
skill.name.toLowerCase().includes(query) ||
skill.description?.toLowerCase().includes(query) ||
skill.source.toLowerCase().includes(query) ||
skill.repoName.toLowerCase().includes(query),
)
.slice(0, limit);
s.stop(`Found ${results.length} skill(s)`);
} else {
if (!this.quiet) {
step('Enter a search term or browse featured skills');
step("Enter a search term or browse featured skills");
}
const { text } = await import('../onboarding/prompts.js');
const { text } = await import("../onboarding/prompts.js");
const searchResult = await text({
message: 'Search skills',
placeholder: 'e.g., pdf, nextjs, testing',
message: "Search skills",
placeholder: "e.g., pdf, nextjs, testing",
});
if (isCancel(searchResult)) {
@@ -118,101 +139,163 @@ export class FindCommand extends Command {
}
const query = (searchResult as string).toLowerCase();
searchTerm = searchResult as string;
if (query) {
s.start('Searching...');
results = allSkills.filter(skill =>
skill.name.toLowerCase().includes(query) ||
skill.description?.toLowerCase().includes(query) ||
skill.source.toLowerCase().includes(query) ||
skill.repoName.toLowerCase().includes(query)
).slice(0, limit);
s.start("Searching...");
results = allSkills
.filter(
(skill) =>
skill.name.toLowerCase().includes(query) ||
skill.description?.toLowerCase().includes(query) ||
skill.source.toLowerCase().includes(query) ||
skill.repoName.toLowerCase().includes(query),
)
.slice(0, limit);
s.stop(`Found ${results.length} skill(s)`);
} else {
results = allSkills.slice(0, limit);
}
}
if (this.federated && this.query) {
s.start('Searching external registries...');
if (searchTerm) {
s.start("Searching skills.sh + external registries...");
const fedSearch = new FederatedSearch();
fedSearch.addRegistry(new GitHubSkillRegistry());
fedSearch.addRegistry(new SkillsShRegistry());
if (this.federated) {
fedSearch.addRegistry(new GitHubSkillRegistry());
}
try {
const fedResult = await fedSearch.search(this.query, { limit: parseInt(this.limit, 10) || 10 });
s.stop(`Found ${fedResult.total} external skill(s) from ${fedResult.registries.join(', ') || 'none'}`);
const fedResult = await fedSearch.search(searchTerm, {
limit: parseInt(this.limit, 10) || 10,
});
const sourceLabel = fedResult.registries.join(", ") || "none";
s.stop(`Found ${fedResult.total} skill(s) from ${sourceLabel}`);
if (fedResult.skills.length > 0) {
console.log('');
console.log(colors.bold('External Skills (SKILL.md):'));
for (const skill of fedResult.skills) {
const stars = typeof skill.stars === 'number' ? colors.muted(` ★${skill.stars}`) : '';
const desc = skill.description
? colors.muted(` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? '...' : ''}`)
: '';
console.log(` ${colors.cyan(symbols.bullet)} ${colors.primary(skill.name)}${stars}${desc}`);
if (!this.quiet) {
console.log(` ${colors.muted(skill.source)}`);
const skillsShResults = fedResult.skills.filter(
(sk) => sk.registry === "skills.sh",
);
const githubResults = fedResult.skills.filter(
(sk) => sk.registry !== "skills.sh",
);
if (skillsShResults.length > 0) {
console.log("");
console.log(colors.bold("Skills.sh Registry:"));
for (const skill of skillsShResults) {
const installs =
typeof skill.stars === "number" && skill.stars > 0
? colors.muted(` ${formatCount(skill.stars)} installs`)
: "";
const desc = skill.description
? colors.muted(
` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? "..." : ""}`,
)
: "";
console.log(
` ${colors.cyan(symbols.bullet)} ${colors.primary(skill.name)}${installs}${desc}`,
);
if (!this.quiet) {
const installSource = skill.source.replace(
"https://github.com/",
"",
);
console.log(
` ${colors.muted(`skillkit install skills.sh/${installSource}/${skill.name}`)}`,
);
}
}
}
console.log('');
}
} catch (err) {
if (err instanceof RateLimitError) {
s.stop(colors.warning('Rate limited by GitHub API'));
console.log(colors.muted('Set GITHUB_TOKEN env var or wait before retrying.'));
} else {
s.stop(colors.warning('Federated search failed'));
if (githubResults.length > 0) {
console.log("");
console.log(colors.bold("GitHub (SKILL.md):"));
for (const skill of githubResults) {
const stars =
typeof skill.stars === "number"
? colors.muted(` ★${skill.stars}`)
: "";
const desc = skill.description
? colors.muted(
` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? "..." : ""}`,
)
: "";
console.log(
` ${colors.cyan(symbols.bullet)} ${colors.primary(skill.name)}${stars}${desc}`,
);
if (!this.quiet) {
console.log(` ${colors.muted(skill.source)}`);
}
}
}
console.log("");
}
} catch {
s.stop(colors.warning("External search unavailable"));
}
}
if (results.length === 0) {
console.log(colors.muted('No skills found matching your search'));
console.log('');
console.log(colors.muted('Try:'));
console.log(colors.muted(' skillkit find --top # Show featured skills'));
console.log(colors.muted(' skillkit find -f <query> # Search external registries'));
console.log(colors.muted(' skillkit ui # Browse in TUI'));
console.log(colors.muted("No skills found matching your search"));
console.log("");
console.log(colors.muted("Try:"));
console.log(
colors.muted(" skillkit find --top # Show featured skills"),
);
console.log(
colors.muted(
" skillkit find -f <query> # Also search GitHub SKILL.md files",
),
);
console.log(colors.muted(" skillkit ui # Browse in TUI"));
return 0;
}
console.log('');
console.log("");
for (const skill of results) {
const desc = skill.description
? colors.muted(` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? '...' : ''}`)
: '';
console.log(` ${colors.success(symbols.bullet)} ${colors.primary(skill.name)}${desc}`);
? colors.muted(
` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? "..." : ""}`,
)
: "";
console.log(
` ${colors.success(symbols.bullet)} ${colors.primary(skill.name)}${desc}`,
);
if (!this.quiet && skill.source) {
console.log(` ${colors.muted(skill.source)}`);
}
}
console.log('');
console.log(colors.muted(`Showing ${results.length} of ${allSkills.length} skills`));
console.log('');
console.log("");
console.log(
colors.muted(`Showing ${results.length} of ${allSkills.length} skills`),
);
console.log("");
if (this.install || (!this.query && !this.top && process.stdin.isTTY)) {
const installResult = await select({
message: 'Install a skill?',
message: "Install a skill?",
options: [
{ value: 'none', label: 'No, just browsing' },
...results.slice(0, 5).map(skill => ({
{ value: "none", label: "No, just browsing" },
...results.slice(0, 5).map((skill) => ({
value: skill.source,
label: skill.name,
hint: skill.repoName,
})),
],
initialValue: 'none',
initialValue: "none",
});
if (!isCancel(installResult) && installResult !== 'none') {
console.log('');
console.log(colors.cyan('To install, run:'));
if (!isCancel(installResult) && installResult !== "none") {
console.log("");
console.log(colors.cyan("To install, run:"));
console.log(` ${colors.bold(`skillkit install ${installResult}`)}`);
}
} else {
console.log(colors.muted('To install: skillkit install <source>'));
console.log(colors.muted("To install: skillkit install <source>"));
}
return 0;
+55
View File
@@ -0,0 +1,55 @@
import { Command, Option } from 'clipanion';
import { writeFileSync } from 'node:fs';
import chalk from 'chalk';
import { SessionHandoff } from '@skillkit/core';
export class SessionHandoffCommand extends Command {
static override paths = [['session', 'handoff']];
static override usage = Command.Usage({
description: 'Generate agent-to-agent session handoff document',
examples: [
['Print handoff to stdout', '$0 session handoff'],
['Target agent recommendations', '$0 session handoff --to cursor'],
['Save to file', '$0 session handoff --out handoff.md'],
['JSON output', '$0 session handoff --json'],
],
});
to = Option.String('--to', {
description: 'Target agent for recommendations',
});
out = Option.String('--out,-o', {
description: 'Save handoff to file',
});
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const handoff = new SessionHandoff(projectPath);
const doc = handoff.generate({
targetAgent: this.to,
});
const output = this.json ? handoff.toJson(doc) : handoff.toMarkdown(doc);
if (this.out) {
try {
writeFileSync(this.out, output, 'utf-8');
console.log(chalk.green(`Handoff saved to ${this.out}`));
} catch (error) {
console.error(chalk.red(`Failed to write file: ${(error as Error).message}`));
return 1;
}
} else {
console.log(output);
}
return 0;
}
}
+18
View File
@@ -90,7 +90,13 @@ export {
SessionNoteCommand,
SessionCompleteCommand,
SessionInProgressCommand,
SessionSnapshotSaveCommand,
SessionSnapshotRestoreCommand,
SessionSnapshotListCommand,
SessionSnapshotDeleteCommand,
SessionExplainCommand,
} from './session.js';
export { ActivityCommand } from './activity.js';
export {
ProfileCommand,
ProfileListCommand,
@@ -119,3 +125,15 @@ export { SkillMdValidateCommand, SkillMdInitCommand, SkillMdCheckCommand } from
// API server
export { ServeCommand } from './serve.js';
export { ScanCommand } from './scan.js';
export { IssuePlanCommand, IssueListCommand } from './issue.js';
export { DoctorCommand } from './doctor.js';
export { TimelineCommand } from './timeline.js';
export { SessionHandoffCommand } from './handoff.js';
export { LineageCommand } from './lineage.js';
export { SaveCommand } from './save.js';
export {
AgentsMdCommand,
AgentsMdInitCommand,
AgentsMdSyncCommand,
AgentsMdShowCommand,
} from './agents-md.js';
+372 -130
View File
@@ -1,15 +1,36 @@
import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync } from 'node:fs';
import { join } from 'node:path';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import {
existsSync,
mkdirSync,
cpSync,
rmSync,
symlinkSync,
readFileSync,
writeFileSync,
} from "node:fs";
import { join } from "node:path";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const execFileAsync = promisify(execFile);
import { Command, Option } from 'clipanion';
import { detectProvider, isLocalPath, getProvider, evaluateSkillDirectory, SkillScanner, formatSummary, Severity } from '@skillkit/core';
import type { SkillMetadata, GitProvider, AgentType } from '@skillkit/core';
import { isPathInside } from '@skillkit/core';
import { getAdapter, detectAgent, getAllAdapters } from '@skillkit/agents';
import { getInstallDir, saveSkillMetadata } from '../helpers.js';
import { Command, Option } from "clipanion";
import {
detectProvider,
isLocalPath,
getProvider,
evaluateSkillDirectory,
SkillScanner,
formatSummary,
Severity,
WellKnownProvider,
AgentsMdParser,
AgentsMdGenerator,
SkillsShRegistry,
} from "@skillkit/core";
import type { SkillsShStats } from "@skillkit/core";
import type { SkillMetadata, GitProvider, AgentType } from "@skillkit/core";
import { isPathInside } from "@skillkit/core";
import { getAdapter, detectAgent, getAllAdapters } from "@skillkit/agents";
import { getInstallDir, saveSkillMetadata, formatCount } from "../helpers.js";
import {
welcome,
colors,
@@ -35,71 +56,80 @@ import {
formatQualityBadge,
getQualityGradeFromScore,
type InstallResult,
} from '../onboarding/index.js';
} from "../onboarding/index.js";
export class InstallCommand extends Command {
static override paths = [['install'], ['i'], ['add']];
static override paths = [["install"], ["i"], ["add"]];
static override usage = Command.Usage({
description: 'Install skills from GitHub, GitLab, Bitbucket, or local path',
description:
"Install skills from GitHub, GitLab, Bitbucket, skills.sh, or local path",
examples: [
['Install from GitHub', '$0 install owner/repo'],
['Install from GitLab', '$0 install gitlab:owner/repo'],
['Install from Bitbucket', '$0 install bitbucket:owner/repo'],
['Install specific skill', '$0 install owner/repo --skill=pdf'],
['Install multiple skills (CI/CD)', '$0 install owner/repo --skills=pdf,xlsx'],
['Install all skills non-interactively', '$0 install owner/repo --all'],
['Install from local path', '$0 install ./my-skills'],
['Install globally', '$0 install owner/repo --global'],
['List available skills', '$0 install owner/repo --list'],
['Install to specific agents', '$0 install owner/repo --agent claude-code --agent cursor'],
["Install from GitHub", "$0 install owner/repo"],
["Install from skills.sh", "$0 install skills.sh/owner/repo/skill-name"],
["Install from GitLab", "$0 install gitlab:owner/repo"],
["Install from Bitbucket", "$0 install bitbucket:owner/repo"],
["Install specific skill", "$0 install owner/repo --skill=pdf"],
[
"Install multiple skills (CI/CD)",
"$0 install owner/repo --skills=pdf,xlsx",
],
["Install all skills non-interactively", "$0 install owner/repo --all"],
["Install from local path", "$0 install ./my-skills"],
["Install globally", "$0 install owner/repo --global"],
["List available skills", "$0 install owner/repo --list"],
[
"Install to specific agents",
"$0 install owner/repo --agent claude-code --agent cursor",
],
],
});
source = Option.String({ required: true });
skills = Option.String('--skills,--skill,-s', {
description: 'Comma-separated list of skills to install (non-interactive)',
skills = Option.String("--skills,--skill,-s", {
description: "Comma-separated list of skills to install (non-interactive)",
});
all = Option.Boolean('--all,-a', false, {
description: 'Install all discovered skills (non-interactive)',
all = Option.Boolean("--all,-a", false, {
description: "Install all discovered skills (non-interactive)",
});
yes = Option.Boolean('--yes,-y', false, {
description: 'Skip confirmation prompts',
yes = Option.Boolean("--yes,-y", false, {
description: "Skip confirmation prompts",
});
global = Option.Boolean('--global,-g', false, {
description: 'Install to global skills directory',
global = Option.Boolean("--global,-g", false, {
description: "Install to global skills directory",
});
force = Option.Boolean('--force,-f', false, {
description: 'Overwrite existing skills',
force = Option.Boolean("--force,-f", false, {
description: "Overwrite existing skills",
});
provider = Option.String('--provider,-p', {
description: 'Force specific provider (github, gitlab, bitbucket)',
provider = Option.String("--provider,-p", {
description: "Force specific provider (github, gitlab, bitbucket)",
});
list = Option.Boolean('--list,-l', false, {
description: 'List available skills without installing',
list = Option.Boolean("--list,-l", false, {
description: "List available skills without installing",
});
agent = Option.Array('--agent', {
description: 'Target specific agents (can specify multiple)',
agent = Option.Array("--agent", {
description: "Target specific agents (can specify multiple)",
});
quiet = Option.Boolean('--quiet,-q', false, {
description: 'Minimal output (no logo)',
quiet = Option.Boolean("--quiet,-q", false, {
description: "Minimal output (no logo)",
});
scan = Option.Boolean('--scan', true, {
description: 'Run security scan before installing (default: true)',
scan = Option.Boolean("--scan", true, {
description: "Run security scan before installing (default: true)",
});
async execute(): Promise<number> {
const isInteractive = process.stdin.isTTY && !this.skills && !this.all && !this.yes;
const isInteractive =
process.stdin.isTTY && !this.skills && !this.all && !this.yes;
const s = spinner();
try {
@@ -109,6 +139,41 @@ export class InstallCommand extends Command {
}
let providerAdapter = detectProvider(this.source);
let result: {
success: boolean;
path?: string;
tempRoot?: string;
error?: string;
skills?: string[];
discoveredSkills?: Array<{
name: string;
dirName: string;
path: string;
}>;
} | null = null;
const isUrl =
this.source.startsWith("http://") || this.source.startsWith("https://");
if (isUrl && !this.provider && !providerAdapter) {
s.start("Checking for well-known skills...");
const wellKnown = new WellKnownProvider();
const discovery = await wellKnown.discoverFromUrl(this.source);
if (discovery.success) {
s.stop(
`Found ${discovery.skills?.length || 0} skill(s) via well-known discovery`,
);
providerAdapter = wellKnown;
result = discovery;
} else {
s.stop("No well-known skills found");
warn(`No well-known skills found at ${this.source}`);
console.log(
colors.muted("You can save this URL as a skill instead:"),
);
console.log(colors.muted(` skillkit save ${this.source}`));
return 1;
}
}
if (this.provider) {
providerAdapter = getProvider(this.provider as GitProvider);
@@ -116,47 +181,72 @@ export class InstallCommand extends Command {
if (!providerAdapter) {
error(`Could not detect provider for: ${this.source}`);
console.log(colors.muted('Use --provider flag or specify source as:'));
console.log(colors.muted(' GitHub: owner/repo or https://github.com/owner/repo'));
console.log(colors.muted(' GitLab: gitlab:owner/repo or https://gitlab.com/owner/repo'));
console.log(colors.muted(' Bitbucket: bitbucket:owner/repo'));
console.log(colors.muted(' Local: ./path or ~/path'));
console.log(colors.muted("Use --provider flag or specify source as:"));
console.log(
colors.muted(
" GitHub: owner/repo or https://github.com/owner/repo",
),
);
console.log(
colors.muted(" Skills.sh: skills.sh/owner/repo/skill-name"),
);
console.log(
colors.muted(
" GitLab: gitlab:owner/repo or https://gitlab.com/owner/repo",
),
);
console.log(colors.muted(" Bitbucket: bitbucket:owner/repo"));
console.log(colors.muted(" Local: ./path or ~/path"));
return 1;
}
s.start(`Fetching from ${providerAdapter.name}...`);
if (!result) {
s.start(`Fetching from ${providerAdapter.name}...`);
result = await providerAdapter.clone(this.source, "", { depth: 1 });
const result = await providerAdapter.clone(this.source, '', { depth: 1 });
if (!result.success || !result.path) {
s.stop(colors.error(result.error || "Failed to fetch source"));
return 1;
}
if (!result.success || !result.path) {
s.stop(colors.error(result.error || 'Failed to fetch source'));
return 1;
s.stop(`Found ${result.skills?.length || 0} skill(s)`);
}
s.stop(`Found ${result.skills?.length || 0} skill(s)`);
const discoveredSkills = result.discoveredSkills || [];
const cloneResult = result!;
const discoveredSkills = cloneResult.discoveredSkills || [];
// List mode - just show skills and exit
if (this.list) {
if (discoveredSkills.length === 0) {
warn('No skills found in this repository');
warn("No skills found in this repository");
} else {
console.log('');
console.log(colors.bold('Available skills:'));
console.log('');
console.log("");
console.log(colors.bold("Available skills:"));
console.log("");
for (const skill of discoveredSkills) {
const quality = evaluateSkillDirectory(skill.path);
const qualityBadge = quality ? ` ${formatQualityBadge(quality.overall)}` : '';
console.log(` ${colors.success(symbols.stepActive)} ${colors.primary(skill.name)}${qualityBadge}`);
const qualityBadge = quality
? ` ${formatQualityBadge(quality.overall)}`
: "";
console.log(
` ${colors.success(symbols.stepActive)} ${colors.primary(skill.name)}${qualityBadge}`,
);
}
console.log('');
console.log(colors.muted(`Total: ${discoveredSkills.length} skill(s)`));
console.log(colors.muted('To install: skillkit install <source> --skill=name'));
console.log("");
console.log(
colors.muted(`Total: ${discoveredSkills.length} skill(s)`),
);
console.log(
colors.muted("To install: skillkit install <source> --skill=name"),
);
}
const cleanupPath = result.tempRoot || result.path;
if (!isLocalPath(this.source) && cleanupPath && existsSync(cleanupPath)) {
const cleanupPath = cloneResult.tempRoot || cloneResult.path;
if (
!isLocalPath(this.source) &&
cleanupPath &&
existsSync(cleanupPath)
) {
rmSync(cleanupPath, { recursive: true, force: true });
}
@@ -167,17 +257,19 @@ export class InstallCommand extends Command {
// Non-interactive: use --skills filter
if (this.skills) {
const requestedSkills = this.skills.split(',').map(s => s.trim());
const available = discoveredSkills.map(s => s.name);
const notFound = requestedSkills.filter(s => !available.includes(s));
const requestedSkills = this.skills.split(",").map((s) => s.trim());
const available = discoveredSkills.map((s) => s.name);
const notFound = requestedSkills.filter((s) => !available.includes(s));
if (notFound.length > 0) {
error(`Skills not found: ${notFound.join(', ')}`);
console.log(colors.muted(`Available: ${available.join(', ')}`));
error(`Skills not found: ${notFound.join(", ")}`);
console.log(colors.muted(`Available: ${available.join(", ")}`));
return 1;
}
skillsToInstall = discoveredSkills.filter(s => requestedSkills.includes(s.name));
skillsToInstall = discoveredSkills.filter((s) =>
requestedSkills.includes(s.name),
);
} else if (this.all || this.yes) {
skillsToInstall = discoveredSkills;
} else if (isInteractive && discoveredSkills.length > 1) {
@@ -185,21 +277,23 @@ export class InstallCommand extends Command {
step(`Source: ${colors.cyan(this.source)}`);
const skillResult = await skillMultiselect({
message: 'Select skills to install',
skills: discoveredSkills.map(s => ({ name: s.name })),
initialValues: discoveredSkills.map(s => s.name),
message: "Select skills to install",
skills: discoveredSkills.map((s) => ({ name: s.name })),
initialValues: discoveredSkills.map((s) => s.name),
});
if (isCancel(skillResult)) {
cancel('Installation cancelled');
cancel("Installation cancelled");
return 0;
}
skillsToInstall = discoveredSkills.filter(s => (skillResult as string[]).includes(s.name));
skillsToInstall = discoveredSkills.filter((s) =>
(skillResult as string[]).includes(s.name),
);
}
if (skillsToInstall.length === 0) {
warn('No skills to install');
warn("No skills to install");
return 0;
}
@@ -207,26 +301,35 @@ export class InstallCommand extends Command {
let targetAgents: AgentType[];
if (this.agent && this.agent.length > 0) {
// Explicitly specified agents
const allValid = getAllAdapters().map((a) => a.type);
const invalid = this.agent.filter(
(a) => !allValid.includes(a as AgentType),
);
if (invalid.length > 0) {
error(`Unknown agent(s): ${invalid.join(", ")}`);
console.log(colors.muted(`Available: ${allValid.join(", ")}`));
return 1;
}
targetAgents = this.agent as AgentType[];
} else if (isInteractive) {
const allAgentTypes = getAllAdapters().map(a => a.type);
const allAgentTypes = getAllAdapters().map((a) => a.type);
const lastAgents = getLastAgents();
step(`Detected ${allAgentTypes.length} agents`);
const agentResult = await quickAgentSelect({
message: 'Install to',
message: "Install to",
agents: allAgentTypes,
lastSelected: lastAgents,
});
if (isCancel(agentResult)) {
cancel('Installation cancelled');
cancel("Installation cancelled");
return 0;
}
targetAgents = (agentResult as { agents: string[] }).agents as AgentType[];
targetAgents = (agentResult as { agents: string[] })
.agents as AgentType[];
// Save selection for next time
saveLastAgents(targetAgents);
@@ -237,21 +340,25 @@ export class InstallCommand extends Command {
}
// Interactive: select installation method
let installMethod: 'symlink' | 'copy' = 'copy';
let installMethod: "symlink" | "copy" = "copy";
if (isInteractive && targetAgents.length > 1) {
const methodResult = await selectInstallMethod({});
if (isCancel(methodResult)) {
cancel('Installation cancelled');
cancel("Installation cancelled");
return 0;
}
installMethod = methodResult as 'symlink' | 'copy';
installMethod = methodResult as "symlink" | "copy";
}
// Check for low-quality skills and warn
const lowQualitySkills: Array<{ name: string; score: number; warnings: string[] }> = [];
const lowQualitySkills: Array<{
name: string;
score: number;
warnings: string[];
}> = [];
for (const skill of skillsToInstall) {
const quality = evaluateSkillDirectory(skill.path);
if (quality && quality.overall < 60) {
@@ -268,42 +375,60 @@ export class InstallCommand extends Command {
for (const skill of skillsToInstall) {
const scanResult = await scanner.scan(skill.path);
if (scanResult.verdict === 'fail' && !this.force) {
if (scanResult.verdict === "fail" && !this.force) {
error(`Security scan FAILED for "${skill.name}"`);
console.log(formatSummary(scanResult));
console.log(colors.muted('Use --force to install anyway, or --no-scan to skip scanning'));
console.log(
colors.muted(
"Use --force to install anyway, or --no-scan to skip scanning",
),
);
const cleanupPath = result.tempRoot || result.path;
if (!isLocalPath(this.source) && cleanupPath && existsSync(cleanupPath)) {
const cleanupPath = cloneResult.tempRoot || cloneResult.path;
if (
!isLocalPath(this.source) &&
cleanupPath &&
existsSync(cleanupPath)
) {
rmSync(cleanupPath, { recursive: true, force: true });
}
return 1;
}
if (scanResult.verdict === 'warn' && !this.quiet) {
warn(`Security warnings for "${skill.name}" (${scanResult.stats.medium} medium, ${scanResult.stats.low} low)`);
if (scanResult.verdict === "warn" && !this.quiet) {
warn(
`Security warnings for "${skill.name}" (${scanResult.stats.medium} medium, ${scanResult.stats.low} low)`,
);
}
}
}
// Confirm installation
if (isInteractive && !this.yes) {
console.log('');
console.log("");
// Show low-quality warning if any
if (lowQualitySkills.length > 0) {
console.log(colors.warning(`${symbols.warning} Warning: ${lowQualitySkills.length} skill(s) have low quality scores (< 60)`));
console.log(
colors.warning(
`${symbols.warning} Warning: ${lowQualitySkills.length} skill(s) have low quality scores (< 60)`,
),
);
for (const lq of lowQualitySkills) {
const grade = getQualityGradeFromScore(lq.score);
const warningText = lq.warnings.length > 0 ? ` - ${lq.warnings.join(', ')}` : '';
console.log(colors.muted(` - ${lq.name} [${grade}]${warningText}`));
const warningText =
lq.warnings.length > 0 ? ` - ${lq.warnings.join(", ")}` : "";
console.log(
colors.muted(` - ${lq.name} [${grade}]${warningText}`),
);
}
console.log('');
console.log("");
}
const agentDisplay = targetAgents.length <= 3
? targetAgents.map(formatAgent).join(', ')
: `${targetAgents.slice(0, 2).map(formatAgent).join(', ')} +${targetAgents.length - 2} more`;
const agentDisplay =
targetAgents.length <= 3
? targetAgents.map(formatAgent).join(", ")
: `${targetAgents.slice(0, 2).map(formatAgent).join(", ")} +${targetAgents.length - 2} more`;
const confirmResult = await confirm({
message: `Install ${skillsToInstall.length} skill(s) to ${agentDisplay}?`,
@@ -311,7 +436,7 @@ export class InstallCommand extends Command {
});
if (isCancel(confirmResult) || !confirmResult) {
cancel('Installation cancelled');
cancel("Installation cancelled");
return 0;
}
}
@@ -338,21 +463,26 @@ export class InstallCommand extends Command {
if (existsSync(targetPath) && !this.force) {
if (!this.quiet) {
warn(`Skipping ${skillName} for ${adapter.name} (already exists, use --force)`);
warn(
`Skipping ${skillName} for ${adapter.name} (already exists, use --force)`,
);
}
continue;
}
const securityRoot = result.tempRoot || result.path;
if (!isPathInside(sourcePath, securityRoot)) {
const securityRoot = cloneResult.tempRoot || cloneResult.path || "";
if (!securityRoot || !isPathInside(sourcePath, securityRoot)) {
error(`Skipping ${skillName} (path traversal detected)`);
continue;
}
const isSymlinkMode = installMethod === 'symlink' && targetAgents.length > 1;
const isSymlinkMode =
installMethod === "symlink" && targetAgents.length > 1;
const useSymlink = isSymlinkMode && primaryPath !== null;
s.start(`Installing ${skillName} to ${adapter.name}${useSymlink ? ' (symlink)' : ''}...`);
s.start(
`Installing ${skillName} to ${adapter.name}${useSymlink ? " (symlink)" : ""}...`,
);
try {
if (existsSync(targetPath)) {
@@ -360,24 +490,33 @@ export class InstallCommand extends Command {
}
if (useSymlink && primaryPath) {
symlinkSync(primaryPath, targetPath, 'dir');
symlinkSync(primaryPath, targetPath, "dir");
} else {
cpSync(sourcePath, targetPath, { recursive: true, dereference: true });
cpSync(sourcePath, targetPath, {
recursive: true,
dereference: true,
});
if (isSymlinkMode && primaryPath === null) {
primaryPath = targetPath;
}
// Auto-install npm dependencies if package.json exists
const packageJsonPath = join(targetPath, 'package.json');
const packageJsonPath = join(targetPath, "package.json");
if (existsSync(packageJsonPath)) {
s.stop(`Installed ${skillName} to ${adapter.name}`);
s.start(`Installing npm dependencies for ${skillName}...`);
try {
await execFileAsync('npm', ['install', '--production'], { cwd: targetPath });
await execFileAsync("npm", ["install", "--omit=dev"], {
cwd: targetPath,
});
s.stop(`Installed dependencies for ${skillName}`);
} catch (npmErr) {
s.stop(colors.warning(`Dependencies failed for ${skillName}`));
console.log(colors.muted('Run manually: npm install in ' + targetPath));
s.stop(
colors.warning(`Dependencies failed for ${skillName}`),
);
console.log(
colors.muted("Run manually: npm install in " + targetPath),
);
}
s.start(`Finishing ${skillName} installation...`);
}
@@ -385,7 +524,7 @@ export class InstallCommand extends Command {
const metadata: SkillMetadata = {
name: skillName,
description: '',
description: "",
source: this.source,
sourceType: providerAdapter.type,
subpath: skillName,
@@ -395,10 +534,16 @@ export class InstallCommand extends Command {
saveSkillMetadata(targetPath, metadata);
installedAgents.push(agentType);
s.stop(`Installed ${skillName} to ${adapter.name}${useSymlink ? ' (symlink)' : ''}`);
s.stop(
`Installed ${skillName} to ${adapter.name}${useSymlink ? " (symlink)" : ""}`,
);
} catch (err) {
s.stop(colors.error(`Failed to install ${skillName} to ${adapter.name}`));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
s.stop(
colors.error(`Failed to install ${skillName} to ${adapter.name}`),
);
console.log(
colors.muted(err instanceof Error ? err.message : String(err)),
);
}
}
@@ -408,17 +553,41 @@ export class InstallCommand extends Command {
skillName,
method: installMethod,
agents: installedAgents,
path: join(getInstallDir(this.global, installedAgents[0] as AgentType), skillName),
path: join(
getInstallDir(this.global, installedAgents[0] as AgentType),
skillName,
),
});
}
}
// Cleanup temp directory
const cleanupPath = result.tempRoot || result.path;
const cleanupPath = cloneResult.tempRoot || cloneResult.path;
if (!isLocalPath(this.source) && cleanupPath && existsSync(cleanupPath)) {
rmSync(cleanupPath, { recursive: true, force: true });
}
if (totalInstalled > 0) {
try {
const agentsMdPath = join(process.cwd(), "AGENTS.md");
if (existsSync(agentsMdPath)) {
const parser = new AgentsMdParser();
const existing = readFileSync(agentsMdPath, "utf-8");
if (parser.hasManagedSections(existing)) {
const gen = new AgentsMdGenerator({ projectPath: process.cwd() });
const genResult = gen.generate();
const updated = parser.updateManagedSections(
existing,
genResult.sections.filter((s) => s.managed),
);
writeFileSync(agentsMdPath, updated, "utf-8");
}
}
} catch {
warn("Failed to update AGENTS.md");
}
}
// Show summary
if (totalInstalled > 0) {
if (isInteractive) {
@@ -429,32 +598,105 @@ export class InstallCommand extends Command {
source: this.source,
});
outro('Installation complete!');
await this.showSkillsShStats(
installResults.map((r) => r.skillName),
providerAdapter,
);
outro("Installation complete!");
if (!this.yes) {
showNextSteps({
skillNames: installResults.map(r => r.skillName),
skillNames: installResults.map((r) => r.skillName),
agentTypes: targetAgents,
syncNeeded: true,
});
this.showProTips(installResults.map((r) => r.skillName));
}
} else {
success(`Installed ${totalInstalled} skill(s) to ${targetAgents.length} agent(s)`);
success(
`Installed ${totalInstalled} skill(s) to ${targetAgents.length} agent(s)`,
);
for (const r of installResults) {
console.log(colors.muted(` ${symbols.success} ${r.skillName} ${symbols.arrowRight} ${r.agents.map(getAgentIcon).join(' ')}`));
console.log(
colors.muted(
` ${symbols.success} ${r.skillName} ${symbols.arrowRight} ${r.agents.map(getAgentIcon).join(" ")}`,
),
);
}
console.log('');
console.log(colors.muted('Run `skillkit sync` to update agent configs'));
console.log("");
console.log(
colors.muted("Run `skillkit sync` to update agent configs"),
);
}
} else {
warn('No skills were installed');
warn("No skills were installed");
}
return 0;
} catch (err) {
s.stop(colors.error('Installation failed'));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
s.stop(colors.error("Installation failed"));
console.log(
colors.muted(err instanceof Error ? err.message : String(err)),
);
return 1;
}
}
private async showSkillsShStats(
skillNames: string[],
provider: {
type: string;
parseSource: (s: string) => { owner: string; repo: string } | null;
},
): Promise<void> {
try {
if (provider.type === "local") return;
const parsed = provider.parseSource(this.source);
if (!parsed) return;
const registry = new SkillsShRegistry();
const statsResults: SkillsShStats[] = [];
for (const name of skillNames) {
const stats = await registry.getSkillStats(
parsed.owner,
parsed.repo,
name,
);
if (stats) statsResults.push(stats);
}
if (statsResults.length > 0) {
console.log("");
console.log(colors.bold("Skills.sh Popularity:"));
for (const s of statsResults) {
const rank =
s.rank <= 10
? colors.success(`#${s.rank}`)
: colors.muted(`#${s.rank}`);
const installs = s.installs > 0 ? formatCount(s.installs) : "n/a";
console.log(
` ${rank} ${colors.primary(s.skillName)} ${colors.muted(`(${installs} installs)`)}`,
);
}
}
} catch {
// Non-critical, silently skip
}
}
private showProTips(skillNames: string[]): void {
const tips = [
`Translate to any agent format: ${colors.bold(`skillkit translate ${skillNames[0] || "skill-name"} --to cursor`)}`,
`Get AI recommendations: ${colors.bold("skillkit recommend")}`,
`Score quality: ${colors.bold(`skillkit evaluate ${skillNames[0] || "skill-name"}`)}`,
`Browse all skills: ${colors.bold("skillkit find --top")}`,
];
const tip = tips[Math.floor(Math.random() * tips.length)];
console.log("");
console.log(colors.muted(`Pro tip: ${tip}`));
}
}
+284
View File
@@ -0,0 +1,284 @@
import { Command, Option } from 'clipanion';
import { execFileSync } from 'node:child_process';
import { writeFile, mkdir } from 'node:fs/promises';
import { resolve, dirname } from 'node:path';
import {
createIssuePlanner,
createPlanGenerator,
createPlanValidator,
} from '@skillkit/core';
export class IssuePlanCommand extends Command {
static paths = [['issue', 'plan']];
static usage = Command.Usage({
category: 'Development',
description: 'Generate a structured plan from a GitHub Issue',
details: `
Fetches a GitHub Issue and generates a StructuredPlan that can be
validated and executed with existing plan commands.
Requires the \`gh\` CLI to be installed and authenticated.
Examples:
$ skillkit issue plan "#42"
$ skillkit issue plan rohitg00/skillkit#42
$ skillkit issue plan "#42" --agent cursor --no-tests
$ skillkit issue plan "#42" --json
`,
examples: [
['Plan from current repo issue', '$0 issue plan "#42"'],
['Plan from specific repo', '$0 issue plan rohitg00/skillkit#42'],
['Plan with JSON output', '$0 issue plan "#42" --json'],
],
});
ref = Option.String({ required: true });
agent = Option.String('--agent,-a', 'claude-code', {
description: 'Target agent',
});
output = Option.String('--output,-o', {
description: 'Output file path (default: .skillkit/plans/issue-<n>.md)',
});
noTests = Option.Boolean('--no-tests', false, {
description: 'Skip adding test steps',
});
json = Option.Boolean('--json', false, {
description: 'Output as JSON',
});
techStack = Option.String('--tech-stack', {
description: 'Comma-separated tech stack',
});
async execute(): Promise<number> {
try {
execFileSync('gh', ['--version'], { encoding: 'utf-8', timeout: 5_000 });
} catch {
this.context.stderr.write(
'Error: GitHub CLI (gh) is not installed or not in PATH.\n' +
'Install it from https://cli.github.com/\n'
);
return 1;
}
const planner = createIssuePlanner();
let issue;
try {
issue = planner.fetchIssue(this.ref);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
this.context.stderr.write(`Error fetching issue: ${message}\n`);
return 1;
}
const techStackArr = this.techStack
? this.techStack.split(',').map((s) => s.trim())
: undefined;
const plan = planner.generatePlan(issue, {
agent: this.agent,
techStack: techStackArr,
includeTests: !this.noTests,
});
const validator = createPlanValidator();
const validation = validator.validate(plan);
const generator = createPlanGenerator();
const markdown = generator.toMarkdown(plan);
const outputPath =
this.output || resolve(`.skillkit/plans/issue-${issue.number}.md`);
await mkdir(dirname(outputPath), { recursive: true });
await writeFile(outputPath, markdown, 'utf-8');
if (this.json) {
this.context.stdout.write(
JSON.stringify(
{
issue: {
number: issue.number,
title: issue.title,
url: issue.url,
state: issue.state,
labels: issue.labels,
},
plan: {
name: plan.name,
goal: plan.goal,
tasks: plan.tasks.map((t) => ({
id: t.id,
name: t.name,
files: t.files,
steps: t.steps.length,
status: t.status,
})),
metadata: plan.metadata,
},
validation: {
valid: validation.valid,
issues: validation.issues.length,
stats: validation.stats,
},
outputPath,
},
null,
2
) + '\n'
);
} else {
this.context.stdout.write(`\n Issue #${issue.number}: ${issue.title}\n\n`);
this.context.stdout.write(` Generated Plan: ${outputPath}\n\n`);
this.context.stdout.write(` Tasks (${plan.tasks.length})\n`);
for (const task of plan.tasks) {
const fileList: string[] = [];
if (task.files.create) {
fileList.push(...task.files.create.map((f) => `${f} (create)`));
}
if (task.files.modify) {
fileList.push(...task.files.modify.map((f) => `${f} (modify)`));
}
this.context.stdout.write(` ${task.id}. ${task.name}\n`);
if (fileList.length > 0) {
this.context.stdout.write(
` Files: ${fileList.join(', ')}\n`
);
}
}
if (plan.tags && plan.tags.length > 0) {
this.context.stdout.write(
`\n Labels: ${issue.labels.join(', ')} -> ${plan.tags.join(', ')}\n`
);
}
this.context.stdout.write(` Agent: ${this.agent}\n\n`);
if (!validation.valid) {
this.context.stdout.write(
` Warnings: ${validation.issues.length}\n`
);
}
this.context.stdout.write(
` Next: skillkit plan validate -f ${outputPath}\n` +
` skillkit plan execute -f ${outputPath} --dry-run\n\n`
);
}
return 0;
}
}
export class IssueListCommand extends Command {
static paths = [['issue', 'list']];
static usage = Command.Usage({
category: 'Development',
description: 'List open GitHub Issues',
details: `
Lists open issues from a GitHub repository. Useful for picking
which issue to plan.
Examples:
$ skillkit issue list
$ skillkit issue list --repo rohitg00/skillkit --label bug
$ skillkit issue list --limit 20 --json
`,
examples: [
['List issues in current repo', '$0 issue list'],
['Filter by label', '$0 issue list --label enhancement'],
],
});
repo = Option.String('--repo,-r', {
description: 'Repository (owner/repo)',
});
label = Option.String('--label,-l', {
description: 'Filter by label',
});
limit = Option.String('--limit', '10', {
description: 'Maximum issues to list',
});
json = Option.Boolean('--json', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
try {
execFileSync('gh', ['--version'], { encoding: 'utf-8', timeout: 5_000 });
} catch {
this.context.stderr.write(
'Error: GitHub CLI (gh) is not installed or not in PATH.\n'
);
return 1;
}
const args = [
'issue',
'list',
'--limit',
this.limit,
'--json',
'number,title,labels,assignees',
'--state',
'open',
];
if (this.repo) {
args.push('--repo', this.repo);
}
if (this.label) {
args.push('--label', this.label);
}
let result: string;
try {
result = execFileSync('gh', args, {
encoding: 'utf-8',
timeout: 15_000,
});
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
this.context.stderr.write(`Error listing issues: ${message}\n`);
return 1;
}
let issues: Array<{
number: number;
title: string;
labels: Array<{ name: string }>;
assignees: Array<{ login: string }>;
}>;
try {
issues = JSON.parse(result);
} catch {
this.context.stderr.write('Error: Failed to parse GitHub CLI response.\n');
return 1;
}
if (this.json) {
this.context.stdout.write(JSON.stringify(issues, null, 2) + '\n');
} else {
if (issues.length === 0) {
this.context.stdout.write(' No open issues found.\n');
return 0;
}
this.context.stdout.write('\n Open Issues\n\n');
for (const issue of issues) {
const labels = issue.labels.map((l) => l.name).join(', ');
const labelStr = labels ? ` [${labels}]` : '';
this.context.stdout.write(
` #${issue.number} ${issue.title}${labelStr}\n`
);
}
this.context.stdout.write(
`\n Use: skillkit issue plan "#<number>" to generate a plan\n\n`
);
}
return 0;
}
}
+66
View File
@@ -0,0 +1,66 @@
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import { SkillLineage } from '@skillkit/core';
export class LineageCommand extends Command {
static override paths = [['lineage']];
static override usage = Command.Usage({
description: 'Show skill impact lineage — which skills produced which changes',
examples: [
['Full overview', '$0 lineage'],
['Single skill', '$0 lineage --skill code-simplifier'],
['Single file', '$0 lineage --file src/index.ts'],
['Date filter + JSON', '$0 lineage --since 2026-02-01 --json'],
],
});
skill = Option.String('--skill,-s', {
description: 'Filter by skill name',
});
file = Option.String('--file,-f', {
description: 'Filter by file path',
});
since = Option.String('--since', {
description: 'Show lineage since date (YYYY-MM-DD)',
});
limit = Option.String('--limit,-l', {
description: 'Max entries to show',
});
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const lineage = new SkillLineage(projectPath);
const parsed = this.limit ? parseInt(this.limit, 10) : undefined;
const limit = parsed && Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
const data = lineage.build({
skill: this.skill,
file: this.file,
since: this.since,
limit,
});
if (this.json) {
console.log(lineage.formatJson(data));
return 0;
}
if (data.skills.length === 0) {
console.log(chalk.yellow('No skill lineage found.'));
console.log(chalk.dim('Lineage is built from skill execution history and activity logs.'));
return 0;
}
console.log(lineage.formatText(data));
return 0;
}
}
+1 -1
View File
@@ -23,7 +23,7 @@ export class MarketplaceCommand extends Command {
from curated repositories.
Skills are aggregated from multiple sources including:
- composioHQ/awesome-claude-code-skills
- composioHQ/awesome-claude-skills
- anthropics/courses
- User-added custom sources
`,
+42
View File
@@ -55,6 +55,10 @@ export class PublishCommand extends Command {
description: 'Show what would be generated without writing files',
});
format = Option.String('--format', {
description: 'Output format: "standard" (default) or "mintlify" (.well-known/skills/default/skill.md)',
});
async execute(): Promise<number> {
const basePath = this.skillPath || process.cwd();
const outputDir = this.output || basePath;
@@ -115,6 +119,44 @@ export class PublishCommand extends Command {
console.log('');
if (this.format === 'mintlify') {
if (this.dryRun) {
console.log(chalk.yellow('Dry run - not writing files\n'));
console.log(chalk.white('Would generate (Mintlify format):'));
for (const skill of validSkills) {
console.log(chalk.dim(` ${outputDir}/.well-known/skills/${skill.safeName}/skill.md`));
}
return 0;
}
const resolvedOutput = resolve(outputDir);
for (const skill of validSkills) {
const mintlifyDir = join(outputDir, '.well-known', 'skills', skill.safeName);
const resolvedDir = resolve(mintlifyDir);
if (!resolvedDir.startsWith(resolvedOutput)) {
console.log(chalk.red(`Skipping ${skill.safeName} (path traversal detected)`));
continue;
}
mkdirSync(mintlifyDir, { recursive: true });
const skillMdPath = join(skill.path, 'SKILL.md');
if (existsSync(skillMdPath)) {
const content = readFileSync(skillMdPath, 'utf-8');
writeFileSync(join(mintlifyDir, 'skill.md'), content);
}
}
console.log(chalk.green('Generated Mintlify well-known structure:\n'));
for (const skill of validSkills) {
console.log(chalk.dim(` ${outputDir}/.well-known/skills/${skill.safeName}/skill.md`));
}
console.log('');
console.log(chalk.cyan('Next steps:'));
console.log(chalk.dim(' 1. Deploy the .well-known directory to your web server'));
console.log(chalk.dim(' 2. Users can install via: skillkit install https://your-domain.com'));
console.log(chalk.dim(' 3. Skills auto-discovered from /.well-known/skills/{name}/skill.md'));
return 0;
}
if (this.dryRun) {
console.log(chalk.yellow('Dry run - not writing files\n'));
console.log(chalk.white('Would generate:'));
+1 -1
View File
@@ -351,7 +351,7 @@ export class QuickCommand extends Command {
console.log('');
const badgeUrl = `https://img.shields.io/badge/SkillKit-${encodeURIComponent(matchedSkill.name)}-black?style=flat-square`;
console.log(colors.dim('Add to your README:'));
console.log(colors.muted(` [![SkillKit](${badgeUrl})](https://agenstskills.com)`));
console.log(colors.muted(` [![SkillKit](${badgeUrl})](https://skillkit.sh)`));
outro('Quick setup complete!');
+19 -2
View File
@@ -1,7 +1,8 @@
import { existsSync, rmSync } from 'node:fs';
import { existsSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import chalk from 'chalk';
import { Command, Option } from 'clipanion';
import { findSkill } from '@skillkit/core';
import { findSkill, AgentsMdParser, AgentsMdGenerator } from '@skillkit/core';
import { getSearchDirs } from '../helpers.js';
export class RemoveCommand extends Command {
@@ -52,6 +53,22 @@ export class RemoveCommand extends Command {
}
if (removed > 0) {
try {
const agentsMdPath = join(process.cwd(), 'AGENTS.md');
if (existsSync(agentsMdPath)) {
const parser = new AgentsMdParser();
const existing = readFileSync(agentsMdPath, 'utf-8');
if (parser.hasManagedSections(existing)) {
const gen = new AgentsMdGenerator({ projectPath: process.cwd() });
const genResult = gen.generate();
const updated = parser.updateManagedSections(existing, genResult.sections.filter(s => s.managed));
writeFileSync(agentsMdPath, updated, 'utf-8');
}
}
} catch (error) {
console.log(chalk.yellow('Warning: Failed to update AGENTS.md'));
console.error(chalk.dim(error instanceof Error ? error.message : String(error)));
}
console.log(chalk.dim('\nRun `skillkit sync` to update your agent config'));
}
+120
View File
@@ -0,0 +1,120 @@
import { cpSync, mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
import chalk from 'chalk';
import { Command, Option } from 'clipanion';
import { ContentExtractor, SkillGenerator, AutoTagger } from '@skillkit/core';
import type { AgentType } from '@skillkit/core';
import { getAdapter } from '@skillkit/agents';
import { spinner } from '../onboarding/index.js';
export class SaveCommand extends Command {
static override paths = [['save']];
static override usage = Command.Usage({
description: 'Save content from a URL, text, or file as a reusable skill',
examples: [
['Save a webpage as a skill', '$0 save https://example.com/guide'],
['Save with a custom name', '$0 save https://example.com/guide --name my-guide'],
['Save raw text', '$0 save --text "Always use TypeScript strict mode"'],
['Save a local file', '$0 save --file ./notes.md'],
['Save globally', '$0 save https://example.com/guide --global'],
['Save and install to agents', '$0 save https://example.com/guide --agent claude-code,cursor'],
],
});
url = Option.String({ required: false });
name = Option.String('--name,-n', {
description: 'Custom skill name',
});
agent = Option.String('--agent,-a', {
description: 'Comma-separated list of agents to install the skill to',
});
global = Option.Boolean('--global,-g', false, {
description: 'Save to global skills directory',
});
text = Option.String('--text,-t', {
description: 'Raw text to save as a skill',
});
file = Option.String('--file,-f', {
description: 'Local file path to save as a skill',
});
async execute(): Promise<number> {
const sources = [this.url, this.text, this.file].filter(Boolean);
if (sources.length === 0) {
console.log(chalk.red('Provide a URL, --text, or --file'));
return 1;
}
if (sources.length > 1) {
console.log(chalk.red('Provide only one of: URL, --text, or --file'));
return 1;
}
const extractor = new ContentExtractor();
const generator = new SkillGenerator();
const tagger = new AutoTagger();
const s = spinner();
try {
s.start('Extracting content');
let content;
if (this.url) {
content = await extractor.extractFromUrl(this.url);
} else if (this.text) {
content = extractor.extractFromText(this.text);
} else {
content = extractor.extractFromFile(this.file!);
}
const tags = tagger.detectTags(content);
content.tags = tags;
s.message('Generating skill');
const result = generator.generate(content, {
name: this.name,
global: this.global,
});
s.stop(chalk.green('Skill saved'));
console.log('');
console.log(chalk.bold(' Name: ') + chalk.cyan(result.name));
console.log(chalk.bold(' Path: ') + chalk.dim(result.skillPath));
if (tags.length > 0) {
console.log(chalk.bold(' Tags: ') + tags.map(t => chalk.yellow(t)).join(', '));
}
if (this.agent) {
const agents = this.agent.split(',').map(a => a.trim()).filter(Boolean);
const skillDir = dirname(result.skillPath);
for (const agentName of agents) {
try {
const adapter = getAdapter(agentName as AgentType);
const targetDir = join(adapter.skillsDir, result.name);
mkdirSync(targetDir, { recursive: true });
cpSync(skillDir, targetDir, { recursive: true });
console.log(chalk.green(` Installed to ${agentName}: `) + chalk.dim(targetDir));
} catch (err) {
console.log(chalk.yellow(` Skipped ${agentName}: ${err instanceof Error ? err.message : String(err)}`));
}
}
}
console.log('');
return 0;
} catch (err) {
s.stop(chalk.red('Failed'));
console.log(chalk.red(err instanceof Error ? err.message : String(err)));
return 1;
}
}
}
+223 -6
View File
@@ -7,7 +7,12 @@ import {
updateSessionFile,
listSessions,
getMostRecentSession,
SnapshotManager,
SessionManager,
SessionExplainer,
ObservationStore,
type SessionFile,
type SessionSnapshot,
} from '@skillkit/core';
export class SessionCommand extends Command {
@@ -28,12 +33,17 @@ export class SessionCommand extends Command {
async execute(): Promise<number> {
console.log(chalk.cyan('Session commands:\n'));
console.log(' session status Show current session state');
console.log(' session start Start a new session');
console.log(' session load Load session from specific date');
console.log(' session list List recent sessions');
console.log(' session note Add note to current session');
console.log(' session complete Mark task as completed');
console.log(' session status Show current session state');
console.log(' session start Start a new session');
console.log(' session load Load session from specific date');
console.log(' session list List recent sessions');
console.log(' session note Add note to current session');
console.log(' session complete Mark task as completed');
console.log(' session explain Explain current session');
console.log(' session snapshot save Save session snapshot');
console.log(' session snapshot restore Restore session snapshot');
console.log(' session snapshot list List snapshots');
console.log(' session snapshot delete Delete snapshot');
console.log();
return 0;
}
@@ -319,3 +329,210 @@ export class SessionInProgressCommand extends Command {
return 0;
}
}
export class SessionSnapshotSaveCommand extends Command {
static override paths = [['session', 'snapshot', 'save']];
static override usage = Command.Usage({
description: 'Save current session state as a named snapshot',
examples: [
['Save snapshot', '$0 session snapshot save my-feature'],
['With description', '$0 session snapshot save my-feature --desc "Before refactor"'],
],
});
name = Option.String({ required: true });
desc = Option.String('--desc,-d', {
description: 'Snapshot description',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const manager = new SnapshotManager(projectPath);
const sessionMgr = new SessionManager(projectPath);
const state = sessionMgr.get();
if (!state) {
console.log(chalk.yellow('No active session to snapshot'));
return 1;
}
let observations: SessionSnapshot['observations'] = [];
try {
const raw = ObservationStore.readAll(projectPath);
observations = raw.map((o) => ({
id: o.id,
timestamp: o.timestamp,
sessionId: o.sessionId,
agent: o.agent as string,
type: o.type as string,
content: { ...o.content } as Record<string, unknown>,
relevance: o.relevance,
}));
} catch {
// No observations available
}
manager.save(this.name, state, observations, this.desc);
console.log(chalk.green(`\u2713 Snapshot saved: ${this.name}`));
if (this.desc) {
console.log(chalk.dim(` ${this.desc}`));
}
return 0;
}
}
export class SessionSnapshotRestoreCommand extends Command {
static override paths = [['session', 'snapshot', 'restore']];
static override usage = Command.Usage({
description: 'Restore session state from a snapshot',
examples: [['Restore snapshot', '$0 session snapshot restore my-feature']],
});
name = Option.String({ required: true });
async execute(): Promise<number> {
const projectPath = process.cwd();
const manager = new SnapshotManager(projectPath);
if (!manager.exists(this.name)) {
console.log(chalk.red(`Snapshot "${this.name}" not found`));
return 1;
}
const { sessionState, observations } = manager.restore(this.name);
const sessionMgr = new SessionManager(projectPath);
const currentState = sessionMgr.getOrCreate();
Object.assign(currentState, {
currentExecution: sessionState.currentExecution,
history: sessionState.history,
decisions: sessionState.decisions,
});
sessionMgr.save();
try {
if (observations && observations.length > 0) {
const store = new ObservationStore(projectPath);
for (const obs of observations) {
store.add(
obs.type as Parameters<ObservationStore['add']>[0],
obs.content as unknown as Parameters<ObservationStore['add']>[1],
obs.agent as Parameters<ObservationStore['add']>[2],
obs.relevance,
);
}
}
} catch {
// Non-critical: session state restored even if observations fail
}
console.log(chalk.green(`\u2713 Snapshot restored: ${this.name}`));
return 0;
}
}
export class SessionSnapshotListCommand extends Command {
static override paths = [['session', 'snapshot', 'list'], ['session', 'snapshot', 'ls']];
static override usage = Command.Usage({
description: 'List all session snapshots',
examples: [['List snapshots', '$0 session snapshot list']],
});
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const manager = new SnapshotManager(projectPath);
const snapshots = manager.list();
if (this.json) {
console.log(JSON.stringify(snapshots, null, 2));
return 0;
}
if (snapshots.length === 0) {
console.log(chalk.yellow('No snapshots found'));
console.log(chalk.dim('Save one with: skillkit session snapshot save <name>'));
return 0;
}
console.log(chalk.cyan(`Snapshots (${snapshots.length}):\n`));
for (const snap of snapshots) {
console.log(` ${chalk.bold(snap.name)}`);
console.log(` Created: ${snap.createdAt}`);
if (snap.description) {
console.log(` ${chalk.dim(snap.description)}`);
}
console.log(` Skills in history: ${snap.skillCount}`);
console.log();
}
return 0;
}
}
export class SessionSnapshotDeleteCommand extends Command {
static override paths = [['session', 'snapshot', 'delete']];
static override usage = Command.Usage({
description: 'Delete a session snapshot',
examples: [['Delete snapshot', '$0 session snapshot delete my-feature']],
});
name = Option.String({ required: true });
async execute(): Promise<number> {
const projectPath = process.cwd();
const manager = new SnapshotManager(projectPath);
if (!manager.delete(this.name)) {
console.log(chalk.red(`Snapshot "${this.name}" not found`));
return 1;
}
console.log(chalk.green(`\u2713 Snapshot deleted: ${this.name}`));
return 0;
}
}
export class SessionExplainCommand extends Command {
static override paths = [['session', 'explain']];
static override usage = Command.Usage({
description: 'Explain what happened in the current session',
examples: [
['Explain session', '$0 session explain'],
['JSON output', '$0 session explain --json'],
['Skip git', '$0 session explain --no-git'],
],
});
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
noGit = Option.Boolean('--no-git', false, {
description: 'Skip git analysis',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const explainer = new SessionExplainer(projectPath);
const explanation = explainer.explain({ includeGit: !this.noGit });
if (this.json) {
console.log(explainer.formatJson(explanation));
return 0;
}
console.log(explainer.formatText(explanation));
return 0;
}
}
+101 -10
View File
@@ -1,7 +1,23 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import { existsSync } from 'node:fs';
import chalk from 'chalk';
import { SessionManager } from '@skillkit/core';
import type { AgentType } from '@skillkit/core';
import { SessionManager, findAllSkills, loadConfig, getProjectConfigPath } from '@skillkit/core';
import { detectAgent, getAdapter } from '@skillkit/agents';
import { getSearchDirs } from '../helpers.js';
interface StatusOverview {
agent: string;
config: string | null;
configAgent: string;
version: string;
totalSkills: number;
projectSkills: number;
globalSkills: number;
skillsDir: string;
recentHistory: Array<{ status: string; skillName: string; completedAt: string }>;
}
/**
* Status command - show current session state
@@ -22,22 +38,18 @@ export class StatusCommand extends Command {
],
});
// Show history
history = Option.Boolean('--history,-h', false, {
description: 'Show execution history',
});
// History limit
limit = Option.String('--limit,-l', {
description: 'Limit history entries (default: 10)',
});
// JSON output
json = Option.Boolean('--json,-j', false, {
description: 'Output in JSON format',
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
@@ -47,14 +59,18 @@ export class StatusCommand extends Command {
const manager = new SessionManager(targetPath);
const state = manager.get();
if (this.json) {
console.log(JSON.stringify(state || { message: 'No session found' }, null, 2));
if (!state) {
const overview = await this.buildOverview(manager);
if (this.json) {
console.log(JSON.stringify({ session: null, overview }, null, 2));
return 0;
}
this.showOverview(overview);
return 0;
}
if (!state) {
console.log(chalk.dim('No active session found.'));
console.log(chalk.dim('Run a skill with "skillkit run <skill>" to start a session.'));
if (this.json) {
console.log(JSON.stringify(state, null, 2));
return 0;
}
@@ -134,6 +150,81 @@ export class StatusCommand extends Command {
return 0;
}
private async buildOverview(manager: SessionManager): Promise<StatusOverview> {
let agent: AgentType = 'universal';
try {
agent = await detectAgent();
} catch {
// fallback
}
const configPath = getProjectConfigPath();
const hasConfig = existsSync(configPath);
let configAgent = 'universal';
if (hasConfig) {
try {
configAgent = loadConfig().agent;
} catch {
// ignore
}
}
const version = this.cli.binaryVersion ?? 'unknown';
let searchDirs: string[] = [];
try {
searchDirs = getSearchDirs(agent);
} catch {
// fallback
}
const allSkills = findAllSkills(searchDirs);
const projectSkills = allSkills.filter(s => s.location === 'project');
const globalSkills = allSkills.filter(s => s.location === 'global');
const adapter = getAdapter(agent);
const recentHistory = manager.getHistory(3);
return {
agent,
config: hasConfig ? configPath : null,
configAgent,
version,
totalSkills: allSkills.length,
projectSkills: projectSkills.length,
globalSkills: globalSkills.length,
skillsDir: adapter.skillsDir,
recentHistory,
};
}
private showOverview(overview: StatusOverview): void {
console.log('');
console.log(chalk.cyan(' Project Overview'));
console.log(` Agent: ${chalk.bold(overview.agent)}`);
console.log(` Config: ${overview.config ? chalk.green('skillkit.yaml') : chalk.dim('none (defaults)')}`);
console.log(` Version: ${chalk.bold(overview.version)}`);
console.log('');
console.log(chalk.cyan(` Skills (${overview.totalSkills} installed)`));
console.log(` Project: ${overview.projectSkills} skills in ${overview.skillsDir}`);
console.log(` Global: ${overview.globalSkills} skills`);
console.log('');
console.log(chalk.cyan(' Recent Activity'));
if (overview.recentHistory.length === 0) {
console.log(chalk.dim(' No recent executions.'));
} else {
for (const entry of overview.recentHistory) {
const statusColor = entry.status === 'completed' ? chalk.green : chalk.red;
console.log(` ${statusColor('\u25cf')} ${entry.skillName} - ${new Date(entry.completedAt).toLocaleDateString()}`);
}
}
console.log('');
console.log(chalk.dim(' Tip: Run "skillkit doctor" for a full health check.'));
console.log('');
}
private getStatusIcon(status: string): string {
switch (status) {
case 'completed':
+83
View File
@@ -0,0 +1,83 @@
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import { SessionTimeline } from '@skillkit/core';
import type { TimelineEventType } from '@skillkit/core';
export class TimelineCommand extends Command {
static override paths = [['timeline']];
static override usage = Command.Usage({
description: 'Show unified session event timeline',
examples: [
['Show last 50 events', '$0 timeline'],
['Filter by type', '$0 timeline --type git_commit'],
['Filter by skill', '$0 timeline --skill code-simplifier'],
['Date filter', '$0 timeline --since 2026-02-10'],
['JSON output with limit', '$0 timeline --limit 20 --json'],
],
});
type = Option.String('--type,-t', {
description: 'Filter by event type (skill_start, skill_complete, task_progress, git_commit, observation, decision, snapshot)',
});
skill = Option.String('--skill,-s', {
description: 'Filter by skill name',
});
since = Option.String('--since', {
description: 'Show events since date (YYYY-MM-DD)',
});
limit = Option.String('--limit,-l', {
description: 'Max events to show (default: 50)',
});
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const projectPath = process.cwd();
const timeline = new SessionTimeline(projectPath);
const parsed = this.limit ? parseInt(this.limit, 10) : 50;
const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 50;
const validTypes: TimelineEventType[] = [
'skill_start', 'skill_complete', 'task_progress',
'git_commit', 'observation', 'decision', 'snapshot',
];
let types: TimelineEventType[] | undefined;
if (this.type) {
if (!validTypes.includes(this.type as TimelineEventType)) {
console.log(chalk.red(`Invalid event type: ${this.type}`));
console.log(chalk.dim(`Valid types: ${validTypes.join(', ')}`));
return 1;
}
types = [this.type as TimelineEventType];
}
const data = timeline.build({
since: this.since,
types,
limit,
skillFilter: this.skill,
});
if (this.json) {
console.log(timeline.formatJson(data));
return 0;
}
if (data.events.length === 0) {
console.log(chalk.yellow('No timeline events found.'));
console.log(chalk.dim('Events are recorded during skill execution, git commits, and observations.'));
return 0;
}
console.log(timeline.formatText(data));
return 0;
}
}
+29 -1
View File
@@ -9,8 +9,10 @@ import {
isHighQuality,
findAllSkills,
benchmarkSkill,
SpecValidator,
type QualityScore,
type BenchmarkResult,
type SpecValidationResult,
} from '@skillkit/core';
import { getSearchDirs } from '../helpers.js';
import {
@@ -142,6 +144,22 @@ function printBenchmarkReport(benchmark: BenchmarkResult): void {
}
}
function printSpecReport(specResult: SpecValidationResult): void {
console.log('');
console.log(colors.bold('Spec Validation'));
console.log(` ${colors.muted('Spec Version:')} ${specResult.specVersion}`);
console.log(` ${colors.muted('Valid:')} ${specResult.valid ? colors.success('yes') : colors.error('no')}`);
if (specResult.checks.length > 0) {
console.log('');
for (const check of specResult.checks) {
const icon = check.passed ? colors.success(symbols.success) : (check.severity === 'error' ? colors.error(symbols.error) : colors.warning(symbols.warning));
console.log(` ${icon} ${check.message}`);
}
}
}
function getOrdinal(n: number): string {
const s = ['th', 'st', 'nd', 'rd'];
const v = n % 100;
@@ -198,6 +216,10 @@ export class ValidateCommand extends Command {
description: 'Compare skill against category leaders',
});
strict = Option.Boolean('--strict,-s', false, {
description: 'Run strict spec validation checks',
});
fix = Option.Boolean('--fix', false, {
description: 'Automatically fix common quality issues (runs fix command)',
});
@@ -378,7 +400,7 @@ export class ValidateCommand extends Command {
filteredResults.sort((a, b) => (b.quality?.overall ?? 0) - (a.quality?.overall ?? 0));
for (const { name, quality, formatValid, formatErrors } of filteredResults) {
for (const { name, quality, formatValid, formatErrors, path: skillPath } of filteredResults) {
if (!formatValid) {
console.log(`\n${colors.error(symbols.error)} ${colors.primary(name)}`);
console.log(` ${colors.error('Format validation failed:')}`);
@@ -395,6 +417,12 @@ export class ValidateCommand extends Command {
printBenchmarkReport(benchmark);
}
}
if (this.strict && skillPath) {
const specValidator = new SpecValidator();
const specResult = specValidator.validate(skillPath, { strict: true });
printSpecReport(specResult);
}
}
console.log('');
+9 -3
View File
@@ -7,9 +7,9 @@ import {
initProject as coreInitProject,
loadSkillMetadata as coreLoadSkillMetadata,
saveSkillMetadata as coreSaveSkillMetadata,
} from '@skillkit/core';
import { getAdapter, detectAgent } from '@skillkit/agents';
import type { AgentType, AgentAdapterInfo } from '@skillkit/core';
} from "@skillkit/core";
import { getAdapter, detectAgent } from "@skillkit/agents";
import type { AgentType, AgentAdapterInfo } from "@skillkit/core";
// Re-export metadata functions directly (they don't need adapter bridging)
export const loadSkillMetadata = coreLoadSkillMetadata;
@@ -62,3 +62,9 @@ export async function initProject(agentType?: AgentType): Promise<void> {
};
return coreInitProject(type, adapterInfo);
}
export function formatCount(count: number): string {
if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
if (count >= 1_000) return `${(count / 1_000).toFixed(1)}K`;
return String(count);
}
+7 -4
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/core",
"version": "1.16.0",
"version": "1.19.2",
"description": "Core functionality for SkillKit - skill discovery, parsing, and translation",
"type": "module",
"main": "./dist/index.js",
@@ -53,22 +53,25 @@
"test": "vitest run"
},
"dependencies": {
"@mozilla/readability": "^0.6.0",
"minimatch": "^10.1.1",
"turndown": "^7.2.2",
"yaml": "^2.6.1",
"zod": "^3.24.1"
},
"optionalDependencies": {
"@anthropic-ai/sdk": "^0.39.0",
"openai": "^4.0.0",
"@google/genai": "^1.0.0",
"ollama": "^0.5.0",
"node-llama-cpp": "^3.15.0",
"better-sqlite3": "^12.0.0",
"node-llama-cpp": "^3.15.0",
"ollama": "^0.5.0",
"openai": "^4.0.0",
"sqlite-vec": "^0.1.6"
},
"devDependencies": {
"@types/better-sqlite3": "^7.6.11",
"@types/node": "^22.10.5",
"@types/turndown": "^5.0.6",
"tsup": "^8.3.5",
"typescript": "^5.7.2",
"vitest": "^2.1.8"
+206
View File
@@ -0,0 +1,206 @@
import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { ProjectDetector } from '../context/detector.js';
import { findAllSkills } from '../skills.js';
import type { Skill } from '../types.js';
import type { AgentsMdConfig, AgentsMdResult, AgentsMdSection } from './types.js';
function escapeTableCell(text: string): string {
return text.replace(/\|/g, '\\|').replace(/\n/g, ' ');
}
const MANAGED_START = '<!-- skillkit:managed:start -->';
const MANAGED_END = '<!-- skillkit:managed:end -->';
export class AgentsMdGenerator {
private config: AgentsMdConfig;
private detector: ProjectDetector;
constructor(config: AgentsMdConfig) {
this.config = config;
this.detector = new ProjectDetector(config.projectPath);
}
generate(): AgentsMdResult {
this.detector.analyze();
const sections: AgentsMdSection[] = [];
sections.push({
id: 'project-overview',
title: 'Project Overview',
content: this.generateProjectSection(),
managed: true,
});
sections.push({
id: 'technology-stack',
title: 'Technology Stack',
content: this.generateStackSection(),
managed: true,
});
if (this.config.includeSkills !== false) {
const skillsContent = this.generateSkillsSection(findAllSkills([join(this.config.projectPath, 'skills')]));
if (skillsContent) {
sections.push({
id: 'installed-skills',
title: 'Installed Skills',
content: skillsContent,
managed: true,
});
}
}
if (this.config.includeBuildCommands !== false) {
const buildContent = this.generateBuildSection();
if (buildContent) {
sections.push({
id: 'build-test',
title: 'Build & Test',
content: buildContent,
managed: true,
});
}
}
if (this.config.includeCodeStyle !== false) {
const styleContent = this.generateCodeStyleSection();
if (styleContent) {
sections.push({
id: 'code-style',
title: 'Code Style',
content: styleContent,
managed: true,
});
}
}
const lines: string[] = ['# AGENTS.md', '', MANAGED_START];
for (const section of sections) {
lines.push(`## ${section.title}`);
lines.push(section.content);
lines.push('');
}
lines.push(MANAGED_END, '');
const content = lines.join('\n');
return {
content,
sections,
path: join(this.config.projectPath, 'AGENTS.md'),
};
}
generateSkillsSection(skills: Skill[]): string {
if (skills.length === 0) {
return '';
}
const lines: string[] = [
'| Skill | Description | Tags |',
'|-------|-------------|------|',
];
for (const skill of skills) {
const name = escapeTableCell(skill.name);
const desc = escapeTableCell(skill.description);
lines.push(`| ${name} | ${desc} | |`);
}
return lines.join('\n');
}
generateProjectSection(): string {
const name = this.detector.getProjectName();
const description = this.detector.getProjectDescription();
const projectType = this.detector.detectProjectType();
const lines: string[] = [];
lines.push(`- **Name**: ${name}`);
if (description) {
lines.push(`- **Description**: ${description}`);
}
lines.push(`- **Type**: ${projectType}`);
return lines.join('\n');
}
generateBuildSection(): string {
const packageJsonPath = join(this.config.projectPath, 'package.json');
if (!existsSync(packageJsonPath)) {
return '';
}
try {
const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
const scripts = pkg.scripts as Record<string, string> | undefined;
if (!scripts || Object.keys(scripts).length === 0) {
return '';
}
const relevantScripts = ['build', 'dev', 'start', 'test', 'lint', 'format', 'typecheck', 'check'];
const lines: string[] = ['```bash'];
for (const key of relevantScripts) {
if (scripts[key]) {
lines.push(`# ${key}`);
lines.push(scripts[key]);
lines.push('');
}
}
if (lines.length === 1) {
return '';
}
lines.push('```');
return lines.join('\n');
} catch {
return '';
}
}
generateCodeStyleSection(): string {
const patterns = this.detector.detectPatterns();
const lines: string[] = [];
if (patterns.linting) {
lines.push(`- **Linting**: ${patterns.linting}`);
}
if (patterns.formatting) {
lines.push(`- **Formatting**: ${patterns.formatting}`);
}
if (patterns.testing) {
lines.push(`- **Testing**: ${patterns.testing}`);
}
if (patterns.styling) {
lines.push(`- **Styling**: ${patterns.styling}`);
}
return lines.length > 0 ? lines.join('\n') : '';
}
private generateStackSection(): string {
const stack = this.detector.analyze();
const lines: string[] = [];
if (stack.languages.length > 0) {
lines.push(`- **Languages**: ${stack.languages.map(l => l.version ? `${l.name} ${l.version}` : l.name).join(', ')}`);
}
if (stack.frameworks.length > 0) {
lines.push(`- **Frameworks**: ${stack.frameworks.map(f => f.version ? `${f.name} ${f.version}` : f.name).join(', ')}`);
}
if (stack.libraries.length > 0) {
lines.push(`- **Libraries**: ${stack.libraries.map(l => l.name).join(', ')}`);
}
if (stack.databases.length > 0) {
lines.push(`- **Databases**: ${stack.databases.map(d => d.name).join(', ')}`);
}
if (stack.runtime.length > 0) {
lines.push(`- **Runtime**: ${stack.runtime.map(r => r.version ? `${r.name} ${r.version}` : r.name).join(', ')}`);
}
return lines.length > 0 ? lines.join('\n') : 'No technology stack detected.';
}
}
+3
View File
@@ -0,0 +1,3 @@
export { AgentsMdGenerator } from './generator.js';
export { AgentsMdParser } from './parser.js';
export type { AgentsMdConfig, AgentsMdSection, AgentsMdResult } from './types.js';
+103
View File
@@ -0,0 +1,103 @@
import type { AgentsMdSection } from './types.js';
const MANAGED_START = '<!-- skillkit:managed:start -->';
const MANAGED_END = '<!-- skillkit:managed:end -->';
export class AgentsMdParser {
parse(content: string): AgentsMdSection[] {
const sections: AgentsMdSection[] = [];
const lines = content.split('\n');
let inManaged = false;
let currentSection: { id: string; title: string; lines: string[]; managed: boolean } | null = null;
for (const line of lines) {
if (line.trim() === MANAGED_START) {
inManaged = true;
continue;
}
if (line.trim() === MANAGED_END) {
if (currentSection) {
sections.push({
id: currentSection.id,
title: currentSection.title,
content: currentSection.lines.join('\n').trim(),
managed: currentSection.managed,
});
currentSection = null;
}
inManaged = false;
continue;
}
const headingMatch = line.match(/^##\s+(.+)$/);
if (headingMatch) {
if (currentSection) {
sections.push({
id: currentSection.id,
title: currentSection.title,
content: currentSection.lines.join('\n').trim(),
managed: currentSection.managed,
});
}
const title = headingMatch[1];
currentSection = {
id: title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''),
title,
lines: [],
managed: inManaged,
};
continue;
}
if (currentSection) {
currentSection.lines.push(line);
}
}
if (currentSection) {
sections.push({
id: currentSection.id,
title: currentSection.title,
content: currentSection.lines.join('\n').trim(),
managed: currentSection.managed,
});
}
return sections;
}
hasManagedSections(content: string): boolean {
return content.includes(MANAGED_START) && content.includes(MANAGED_END);
}
updateManagedSections(existing: string, newManaged: AgentsMdSection[]): string {
if (!this.hasManagedSections(existing)) {
return existing;
}
const startIdx = existing.indexOf(MANAGED_START);
const endIdx = existing.indexOf(MANAGED_END);
if (startIdx >= endIdx) {
return existing;
}
const managedBlock = this.buildManagedBlock(newManaged);
const before = existing.substring(0, startIdx);
const after = existing.substring(endIdx + MANAGED_END.length);
return `${before}${managedBlock}${after}`;
}
private buildManagedBlock(sections: AgentsMdSection[]): string {
const lines: string[] = [MANAGED_START];
for (const section of sections) {
lines.push(`## ${section.title}`);
lines.push(section.content);
lines.push('');
}
lines.push(MANAGED_END);
return lines.join('\n');
}
}
+19
View File
@@ -0,0 +1,19 @@
export interface AgentsMdConfig {
projectPath: string;
includeSkills?: boolean;
includeBuildCommands?: boolean;
includeCodeStyle?: boolean;
}
export interface AgentsMdSection {
id: string;
title: string;
content: string;
managed: boolean;
}
export interface AgentsMdResult {
content: string;
sections: AgentsMdSection[];
path: string;
}
+9
View File
@@ -123,3 +123,12 @@ export * from './runtime/index.js';
// Security Scanner
export * from './scanner/index.js';
// Spec Validation
export * from './validation/index.js';
// AGENTS.md generator
export * from './agents-md/index.js';
// Save (Content Extraction & Skill Generation)
export * from './save/index.js';
@@ -181,6 +181,18 @@ export class ObservationStore {
return this.load().observations;
}
static readAll(projectPath: string): Observation[] {
const filePath = join(projectPath, '.skillkit', 'memory', 'observations.yaml');
if (!existsSync(filePath)) return [];
try {
const content = readFileSync(filePath, 'utf-8');
const data = parseYaml(content) as ObservationStoreData;
return data?.observations ?? [];
} catch {
return [];
}
}
getByType(type: ObservationType): Observation[] {
return this.load().observations.filter((o) => o.type === type);
}
@@ -0,0 +1,307 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { IssuePlanner, createIssuePlanner } from '../issue-planner.js';
import type { GitHubIssue } from '../issue-planner.js';
vi.mock('node:child_process', () => ({
execFileSync: vi.fn(),
}));
import { execFileSync } from 'node:child_process';
const mockExecFileSync = vi.mocked(execFileSync);
describe('IssuePlanner', () => {
let planner: IssuePlanner;
beforeEach(() => {
planner = new IssuePlanner();
vi.clearAllMocks();
});
afterEach(() => {
vi.restoreAllMocks();
});
describe('parseIssueRef', () => {
it('should parse short ref #123', () => {
const result = planner.parseIssueRef('#123');
expect(result).toEqual({ number: 123 });
});
it('should parse bare number 123', () => {
const result = planner.parseIssueRef('123');
expect(result).toEqual({ number: 123 });
});
it('should parse owner/repo#123', () => {
const result = planner.parseIssueRef('rohitg00/skillkit#42');
expect(result).toEqual({
owner: 'rohitg00',
repo: 'skillkit',
number: 42,
});
});
it('should parse full GitHub URL', () => {
const result = planner.parseIssueRef(
'https://github.com/rohitg00/skillkit/issues/42'
);
expect(result).toEqual({
owner: 'rohitg00',
repo: 'skillkit',
number: 42,
});
});
it('should throw on invalid ref', () => {
expect(() => planner.parseIssueRef('invalid')).toThrow(
'Invalid issue reference'
);
});
});
describe('extractTasksFromBody', () => {
it('should extract unchecked tasks', () => {
const body = '- [ ] Add auth\n- [ ] Add tests\n';
const tasks = planner.extractTasksFromBody(body);
expect(tasks).toEqual([
{ name: 'Add auth', checked: false },
{ name: 'Add tests', checked: false },
]);
});
it('should extract checked tasks', () => {
const body = '- [x] Setup project\n- [X] Add config\n';
const tasks = planner.extractTasksFromBody(body);
expect(tasks).toEqual([
{ name: 'Setup project', checked: true },
{ name: 'Add config', checked: true },
]);
});
it('should handle mixed tasks', () => {
const body = '- [x] Done task\n- [ ] Pending task\n';
const tasks = planner.extractTasksFromBody(body);
expect(tasks).toHaveLength(2);
expect(tasks[0].checked).toBe(true);
expect(tasks[1].checked).toBe(false);
});
it('should handle empty body', () => {
expect(planner.extractTasksFromBody('')).toEqual([]);
});
it('should ignore non-checkbox lines', () => {
const body = '- Regular list item\n- [ ] Checkbox item\n';
const tasks = planner.extractTasksFromBody(body);
expect(tasks).toHaveLength(1);
expect(tasks[0].name).toBe('Checkbox item');
});
it('should handle indented checkboxes', () => {
const body = ' - [ ] Indented task\n';
const tasks = planner.extractTasksFromBody(body);
expect(tasks).toHaveLength(1);
expect(tasks[0].name).toBe('Indented task');
});
});
describe('extractFileMentions', () => {
it('should extract file paths in backticks', () => {
const text = 'Update `src/foo.ts` and `lib/bar.js`';
const files = planner.extractFileMentions(text);
expect(files).toContain('src/foo.ts');
expect(files).toContain('lib/bar.js');
});
it('should deduplicate file mentions', () => {
const text = 'See `src/foo.ts` and also `src/foo.ts`';
const files = planner.extractFileMentions(text);
expect(files).toHaveLength(1);
});
it('should handle text with no file mentions', () => {
const text = 'No files here';
expect(planner.extractFileMentions(text)).toEqual([]);
});
it('should extract files with extensions', () => {
const text = 'Check `config.json` and `README.md`';
const files = planner.extractFileMentions(text);
expect(files).toContain('config.json');
expect(files).toContain('README.md');
});
});
describe('inferLabelsToTags', () => {
it('should map known labels', () => {
expect(planner.inferLabelsToTags(['bug'])).toEqual(['fix']);
expect(planner.inferLabelsToTags(['enhancement'])).toEqual(['feature']);
expect(planner.inferLabelsToTags(['documentation'])).toEqual(['docs']);
});
it('should handle case insensitivity', () => {
expect(planner.inferLabelsToTags(['Bug'])).toEqual(['fix']);
expect(planner.inferLabelsToTags(['ENHANCEMENT'])).toEqual(['feature']);
});
it('should skip unknown labels', () => {
expect(planner.inferLabelsToTags(['unknown-label'])).toEqual([]);
});
it('should deduplicate tags', () => {
expect(planner.inferLabelsToTags(['bug', 'fix'])).toEqual(['fix']);
});
});
describe('fetchIssue', () => {
it('should fetch issue from current repo', () => {
const ghResponse = JSON.stringify({
number: 42,
title: 'Add dark mode',
body: '- [ ] Add theme provider\n- [ ] Update styles',
labels: [{ name: 'enhancement' }],
assignees: [{ login: 'user1' }],
url: 'https://github.com/test/repo/issues/42',
state: 'OPEN',
});
mockExecFileSync.mockReturnValue(ghResponse as any);
const issue = planner.fetchIssue('#42');
expect(mockExecFileSync).toHaveBeenCalledWith(
'gh',
[
'issue',
'view',
'42',
'--json',
'number,title,body,labels,assignees,url,state',
],
expect.objectContaining({ encoding: 'utf-8' })
);
expect(issue.number).toBe(42);
expect(issue.title).toBe('Add dark mode');
expect(issue.labels).toEqual(['enhancement']);
expect(issue.assignees).toEqual(['user1']);
});
it('should fetch issue from specific repo', () => {
const ghResponse = JSON.stringify({
number: 10,
title: 'Fix bug',
body: '',
labels: [],
assignees: [],
url: 'https://github.com/owner/repo/issues/10',
state: 'OPEN',
});
mockExecFileSync.mockReturnValue(ghResponse as any);
planner.fetchIssue('owner/repo#10');
expect(mockExecFileSync).toHaveBeenCalledWith(
'gh',
[
'issue',
'view',
'10',
'--json',
'number,title,body,labels,assignees,url,state',
'--repo',
'owner/repo',
],
expect.objectContaining({ encoding: 'utf-8' })
);
});
});
describe('generatePlan', () => {
const baseIssue: GitHubIssue = {
number: 42,
title: 'Add dark mode support',
body: 'We need dark mode.\n\n- [ ] Add theme context provider\n- [ ] Update component styles\n- [x] Research themes',
labels: ['enhancement'],
assignees: ['user1'],
url: 'https://github.com/test/repo/issues/42',
state: 'OPEN',
};
it('should generate plan from issue with checklist', () => {
const plan = planner.generatePlan(baseIssue);
expect(plan.name).toBe('Issue #42: Add dark mode support');
expect(plan.goal).toBe('We need dark mode.');
expect(plan.tasks).toHaveLength(3);
expect(plan.tasks[0].name).toBe('Add theme context provider');
expect(plan.tasks[1].name).toBe('Update component styles');
expect(plan.tasks[2].name).toBe('Research themes');
expect(plan.tasks[2].status).toBe('completed');
});
it('should set metadata correctly', () => {
const plan = planner.generatePlan(baseIssue, { agent: 'cursor' });
expect(plan.metadata).toBeDefined();
expect(plan.metadata!.issueNumber).toBe(42);
expect(plan.metadata!.issueUrl).toBe(
'https://github.com/test/repo/issues/42'
);
expect(plan.metadata!.agent).toBe('cursor');
expect(plan.metadata!.generatedAt).toBeDefined();
});
it('should infer tags from labels', () => {
const plan = planner.generatePlan(baseIssue);
expect(plan.tags).toContain('feature');
});
it('should create single task when no checklist', () => {
const issue: GitHubIssue = {
...baseIssue,
body: 'Just a description with no checkboxes.\n\nUpdate `src/theme.ts`.',
};
const plan = planner.generatePlan(issue);
expect(plan.tasks).toHaveLength(1);
expect(plan.tasks[0].name).toBe('Add dark mode support');
expect(plan.tasks[0].files.modify).toContain('src/theme.ts');
});
it('should extract file mentions into task files', () => {
const issue: GitHubIssue = {
...baseIssue,
body: '- [ ] Update `src/components/App.tsx` for theming',
};
const plan = planner.generatePlan(issue);
expect(plan.tasks[0].files.modify).toContain(
'src/components/App.tsx'
);
});
it('should respect includeTests option', () => {
const plan = planner.generatePlan(baseIssue, { includeTests: false });
for (const task of plan.tasks) {
const hasTestStep = task.steps.some((s) => s.type === 'test');
expect(hasTestStep).toBe(false);
}
});
it('should use custom tech stack', () => {
const plan = planner.generatePlan(baseIssue, {
techStack: ['React', 'TypeScript'],
});
expect(plan.techStack).toEqual(['React', 'TypeScript']);
});
});
describe('createIssuePlanner', () => {
it('should create an IssuePlanner instance', () => {
const p = createIssuePlanner();
expect(p).toBeInstanceOf(IssuePlanner);
});
});
});
+7
View File
@@ -27,6 +27,10 @@ export type { TaskTemplate } from './generator.js';
export { PlanExecutor, createPlanExecutor, dryRunExecutor, shellExecutor } from './executor.js';
export type { StepExecutor } from './executor.js';
// Issue Planner
export { IssuePlanner, createIssuePlanner } from './issue-planner.js';
export type { GitHubIssue, IssuePlanOptions } from './issue-planner.js';
// Types
export type {
// Core types
@@ -53,4 +57,7 @@ export type {
// Events
PlanEvent,
PlanEventListener,
// Issue Plan
IssuePlanMetadata,
} from './types.js';
+252
View File
@@ -0,0 +1,252 @@
import { execFileSync } from 'node:child_process';
import { PlanGenerator } from './generator.js';
import type { StructuredPlan, PlanTaskFiles, IssuePlanMetadata } from './types.js';
export type { IssuePlanMetadata };
export interface GitHubIssue {
number: number;
title: string;
body: string;
labels: string[];
assignees: string[];
url: string;
state: string;
}
export interface IssuePlanOptions {
agent?: string;
techStack?: string[];
outputPath?: string;
includeTests?: boolean;
}
interface ParsedRef {
owner?: string;
repo?: string;
number: number;
}
interface ExtractedTask {
name: string;
checked: boolean;
}
const LABEL_TAG_MAP: Record<string, string> = {
bug: 'fix',
fix: 'fix',
enhancement: 'feature',
feature: 'feature',
documentation: 'docs',
docs: 'docs',
refactor: 'refactor',
refactoring: 'refactor',
test: 'test',
testing: 'test',
security: 'security',
performance: 'performance',
'good first issue': 'beginner',
chore: 'chore',
maintenance: 'chore',
};
const FILE_PATH_REGEX = /`([a-zA-Z0-9_./\-]+\.[a-zA-Z0-9]+)`/g;
export class IssuePlanner {
parseIssueRef(ref: string): ParsedRef {
const urlMatch = ref.match(
/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/
);
if (urlMatch) {
return {
owner: urlMatch[1],
repo: urlMatch[2],
number: parseInt(urlMatch[3], 10),
};
}
const fullMatch = ref.match(/^([^/]+)\/([^#]+)#(\d+)$/);
if (fullMatch) {
return {
owner: fullMatch[1],
repo: fullMatch[2],
number: parseInt(fullMatch[3], 10),
};
}
const shortMatch = ref.match(/^#?(\d+)$/);
if (shortMatch) {
return { number: parseInt(shortMatch[1], 10) };
}
throw new Error(
`Invalid issue reference: "${ref}". Use #123, owner/repo#123, or a GitHub URL.`
);
}
fetchIssue(ref: string): GitHubIssue {
const parsed = this.parseIssueRef(ref);
const args = [
'issue',
'view',
String(parsed.number),
'--json',
'number,title,body,labels,assignees,url,state',
];
if (parsed.owner && parsed.repo) {
args.push('--repo', `${parsed.owner}/${parsed.repo}`);
}
const result = execFileSync('gh', args, {
encoding: 'utf-8',
timeout: 15_000,
});
let data: {
number: number;
title: string;
body?: string;
labels?: Array<{ name: string }>;
assignees?: Array<{ login: string }>;
url: string;
state: string;
};
try {
data = JSON.parse(result);
} catch {
throw new Error(`Failed to parse GitHub CLI response for issue ${parsed.number}`);
}
return {
number: data.number,
title: data.title,
body: data.body || '',
labels: (data.labels || []).map((l) => l.name),
assignees: (data.assignees || []).map((a) => a.login),
url: data.url,
state: data.state,
};
}
extractTasksFromBody(body: string): ExtractedTask[] {
const tasks: ExtractedTask[] = [];
const lines = body.split('\n');
for (const line of lines) {
const match = line.match(/^[\s]*-\s*\[([ xX])\]\s+(.+)$/);
if (match) {
tasks.push({
name: match[2].trim(),
checked: match[1] !== ' ',
});
}
}
return tasks;
}
extractFileMentions(text: string): string[] {
const files = new Set<string>();
let match: RegExpExecArray | null;
const regex = new RegExp(FILE_PATH_REGEX.source, 'g');
while ((match = regex.exec(text)) !== null) {
const path = match[1];
if (path.includes('/') || path.includes('.')) {
files.add(path);
}
}
return [...files];
}
inferLabelsToTags(labels: string[]): string[] {
const tags: string[] = [];
for (const label of labels) {
const tag = LABEL_TAG_MAP[label.toLowerCase()];
if (tag && !tags.includes(tag)) {
tags.push(tag);
}
}
return tags;
}
generatePlan(
issue: GitHubIssue,
options?: IssuePlanOptions
): StructuredPlan {
const agent = options?.agent || 'claude-code';
const includeTests = options?.includeTests !== false;
const bodyFirstParagraph =
issue.body.split('\n\n')[0]?.trim() || issue.title;
const generator = new PlanGenerator({
includeTests,
includeCommits: true,
techStack: options?.techStack,
});
const plan = generator.createPlan(
`Issue #${issue.number}: ${issue.title}`,
bodyFirstParagraph
);
plan.tags = this.inferLabelsToTags(issue.labels);
const checklist = this.extractTasksFromBody(issue.body);
const allFileMentions = this.extractFileMentions(issue.body);
if (checklist.length > 0) {
for (const item of checklist) {
const taskFiles = this.extractFileMentions(item.name);
const files: PlanTaskFiles = {};
if (taskFiles.length > 0) {
files.modify = taskFiles;
}
const task = generator.addTask(plan, item.name, {
files,
tags: item.checked ? ['done'] : undefined,
steps: [
{ type: 'implement', description: item.name },
...(includeTests
? [{ type: 'test' as const, description: `Write tests for ${item.name}` }]
: []),
],
});
if (item.checked) {
task.status = 'completed';
}
}
} else {
const files: PlanTaskFiles = {};
if (allFileMentions.length > 0) {
files.modify = allFileMentions;
}
generator.addTask(plan, issue.title, {
description: bodyFirstParagraph,
files,
steps: [
{ type: 'implement', description: issue.title },
...(includeTests
? [{ type: 'test' as const, description: `Write tests for ${issue.title}` }]
: []),
],
});
}
plan.metadata = {
issueNumber: issue.number,
issueUrl: issue.url,
issueLabels: issue.labels,
agent,
generatedAt: new Date().toISOString(),
} satisfies IssuePlanMetadata;
return plan;
}
}
export function createIssuePlanner(): IssuePlanner {
return new IssuePlanner();
}
+8
View File
@@ -270,3 +270,11 @@ export type PlanEventListener = (
task?: PlanTask,
result?: PlanTaskResult
) => void | Promise<void>;
export interface IssuePlanMetadata {
issueNumber: number;
issueUrl: string;
issueLabels: string[];
agent: string;
generatedAt: string;
}
+18 -15
View File
@@ -1,20 +1,23 @@
import type { GitProviderAdapter } from './base.js';
import type { GitProvider } from '../types.js';
import { GitHubProvider } from './github.js';
import { GitLabProvider } from './gitlab.js';
import { BitbucketProvider } from './bitbucket.js';
import { LocalProvider } from './local.js';
import { WellKnownProvider } from './wellknown.js';
import type { GitProviderAdapter } from "./base.js";
import type { GitProvider } from "../types.js";
import { GitHubProvider } from "./github.js";
import { GitLabProvider } from "./gitlab.js";
import { BitbucketProvider } from "./bitbucket.js";
import { LocalProvider } from "./local.js";
import { WellKnownProvider } from "./wellknown.js";
import { SkillsShProvider } from "./skills-sh.js";
export * from './base.js';
export * from './github.js';
export * from './gitlab.js';
export * from './bitbucket.js';
export * from './local.js';
export * from './wellknown.js';
export * from "./base.js";
export * from "./github.js";
export * from "./gitlab.js";
export * from "./bitbucket.js";
export * from "./local.js";
export * from "./wellknown.js";
export * from "./skills-sh.js";
const providers: GitProviderAdapter[] = [
new LocalProvider(),
new SkillsShProvider(),
new GitLabProvider(),
new BitbucketProvider(),
new WellKnownProvider(),
@@ -22,7 +25,7 @@ const providers: GitProviderAdapter[] = [
];
export function getProvider(type: GitProvider): GitProviderAdapter | undefined {
return providers.find(p => p.type === type);
return providers.find((p) => p.type === type);
}
export function getAllProviders(): GitProviderAdapter[] {
@@ -30,7 +33,7 @@ export function getAllProviders(): GitProviderAdapter[] {
}
export function detectProvider(source: string): GitProviderAdapter | undefined {
return providers.find(p => p.matches(source));
return providers.find((p) => p.matches(source));
}
export function parseSource(source: string): {
+122
View File
@@ -0,0 +1,122 @@
import { execFileSync } from "node:child_process";
import { existsSync, rmSync } from "node:fs";
import { join, basename, resolve } from "node:path";
import { tmpdir } from "node:os";
import { randomUUID } from "node:crypto";
import type { GitProviderAdapter, CloneOptions } from "./base.js";
import type { GitProvider, CloneResult } from "../types.js";
import { discoverSkills } from "../skills.js";
/**
* Resolves `skills.sh/owner/repo/skill` references to their underlying
* GitHub repos and clones them the same way the GitHubProvider does.
*/
export class SkillsShProvider implements GitProviderAdapter {
readonly type: GitProvider = "skills-sh";
readonly name = "Skills.sh";
readonly baseUrl = "https://skills.sh";
parseSource(
source: string,
): { owner: string; repo: string; subpath?: string } | null {
const cleaned = source
.replace(/^https?:\/\//, "")
.replace(/^skills\.sh\//, "");
if (!this.isSkillsShSource(source)) return null;
const parts = cleaned.split("/").filter(Boolean);
if (parts.length < 2) return null;
return {
owner: parts[0],
repo: parts[1],
subpath: parts.length > 2 ? parts.slice(2).join("/") : undefined,
};
}
matches(source: string): boolean {
return this.isSkillsShSource(source);
}
getCloneUrl(owner: string, repo: string): string {
return `https://github.com/${owner}/${repo}.git`;
}
getSshUrl(owner: string, repo: string): string {
return `git@github.com:${owner}/${repo}.git`;
}
async clone(
source: string,
_targetDir: string,
options: CloneOptions = {},
): Promise<CloneResult> {
const parsed = this.parseSource(source);
if (!parsed) {
return { success: false, error: `Invalid skills.sh source: ${source}` };
}
const { owner, repo, subpath } = parsed;
const cloneUrl = options.ssh
? this.getSshUrl(owner, repo)
: this.getCloneUrl(owner, repo);
const tempDir = join(tmpdir(), `skillkit-skillssh-${randomUUID()}`);
try {
const args = ["clone"];
if (options.depth) {
args.push("--depth", String(options.depth));
}
if (options.branch) {
args.push("--branch", options.branch);
}
args.push(cloneUrl, tempDir);
execFileSync("git", args, {
stdio: ["pipe", "pipe", "pipe"],
encoding: "utf-8",
});
const searchDir = subpath ? join(tempDir, subpath) : tempDir;
if (!resolve(searchDir).startsWith(resolve(tempDir))) {
rmSync(tempDir, { recursive: true, force: true });
return {
success: false,
error: `Invalid subpath in source: ${source}`,
};
}
const skills = discoverSkills(searchDir);
return {
success: true,
path: searchDir,
tempRoot: tempDir,
skills: skills.map((s) => s.name),
discoveredSkills: skills.map((s) => ({
name: s.name,
dirName: basename(s.path),
path: s.path,
})),
};
} catch (error) {
if (existsSync(tempDir)) {
rmSync(tempDir, { recursive: true, force: true });
}
const message = error instanceof Error ? error.message : String(error);
return { success: false, error: `Failed to clone: ${message}` };
}
}
private isSkillsShSource(source: string): boolean {
return (
source.startsWith("skills.sh/") ||
source.startsWith("https://skills.sh/") ||
source.startsWith("http://skills.sh/")
);
}
}
+97
View File
@@ -6,6 +6,18 @@ import type { GitProviderAdapter, CloneOptions } from './base.js';
import { isGitUrl, isLocalPath } from './base.js';
import type { GitProvider, CloneResult } from '../types.js';
function skillNameFromUrl(url: string): string {
try {
const parsed = new URL(url);
const segments = parsed.pathname.split('/').filter(Boolean);
return segments[segments.length - 1] || parsed.hostname.split('.')[0] || 'default';
} catch {
return basename(url) || 'default';
}
}
const FRONTMATTER_REGEX = /^---\s*\n[\s\S]*?name:\s*.+/;
function sanitizeSkillName(name: string): string | null {
if (!name || typeof name !== 'string') return null;
const base = basename(name);
@@ -29,6 +41,12 @@ export interface WellKnownIndex {
skills: WellKnownSkill[];
}
const MINTLIFY_PATHS = [
'/.well-known/skills/default/skill.md',
'/skill.md',
'/.well-known/skill.md',
];
export class WellKnownProvider implements GitProviderAdapter {
readonly type: GitProvider = 'wellknown';
readonly name = 'Well-Known';
@@ -66,6 +84,57 @@ export class WellKnownProvider implements GitProviderAdapter {
return '';
}
async discoverFromUrl(url: string): Promise<CloneResult> {
const baseUrl = url.replace(/\/$/, '');
const tempDir = join(tmpdir(), `skillkit-wellknown-${randomUUID()}`);
try {
mkdirSync(tempDir, { recursive: true });
for (const mintlifyPath of MINTLIFY_PATHS) {
const fullUrl = `${baseUrl}${mintlifyPath}`;
try {
const response = await fetch(fullUrl);
if (response.ok) {
const content = await response.text();
if (FRONTMATTER_REGEX.test(content)) {
const skillName = skillNameFromUrl(baseUrl);
const safeName = sanitizeSkillName(skillName) ?? 'default';
const skillDir = join(tempDir, safeName);
mkdirSync(skillDir, { recursive: true });
writeFileSync(join(skillDir, 'SKILL.md'), content);
return {
success: true,
path: tempDir,
tempRoot: tempDir,
skills: [safeName],
discoveredSkills: [{ name: safeName, dirName: safeName, path: skillDir }],
};
}
}
} catch {
continue;
}
}
const indexResult = await this.clone(baseUrl, '', {});
if (indexResult.success) {
rmSync(tempDir, { recursive: true, force: true });
return indexResult;
}
rmSync(tempDir, { recursive: true, force: true });
return { success: false, error: 'No well-known skills found' };
} catch (error) {
if (existsSync(tempDir)) {
rmSync(tempDir, { recursive: true, force: true });
}
const message = error instanceof Error ? error.message : String(error);
return { success: false, error: `Failed to discover skills: ${message}` };
}
}
async clone(source: string, _targetDir: string, _options: CloneOptions = {}): Promise<CloneResult> {
const tempDir = join(tmpdir(), `skillkit-wellknown-${randomUUID()}`);
@@ -95,6 +164,34 @@ export class WellKnownProvider implements GitProviderAdapter {
}
if (!index || !index.skills || index.skills.length === 0) {
for (const mintlifyPath of MINTLIFY_PATHS) {
const fullUrl = `${baseUrl}${mintlifyPath}`;
try {
const response = await fetch(fullUrl);
if (response.ok) {
const content = await response.text();
if (FRONTMATTER_REGEX.test(content)) {
const skillName = skillNameFromUrl(baseUrl);
const safeName = sanitizeSkillName(skillName) ?? 'default';
const skillDir = join(tempDir, safeName);
mkdirSync(skillDir, { recursive: true });
writeFileSync(join(skillDir, 'SKILL.md'), content);
return {
success: true,
path: tempDir,
tempRoot: tempDir,
skills: [safeName],
discoveredSkills: [{ name: safeName, dirName: safeName, path: skillDir }],
};
}
}
} catch {
continue;
}
}
rmSync(tempDir, { recursive: true, force: true });
return {
success: false,
error: `No skills found at ${baseUrl}/.well-known/skills/index.json`,
+30 -1
View File
@@ -559,10 +559,39 @@ export function evaluateSkillFile(filePath: string): QualityScore | null {
}
}
function checkNameDirectoryMatch(content: string, dirPath: string): string | null {
const frontmatter = extractFrontmatter(content);
if (!frontmatter || typeof frontmatter.name !== 'string') return null;
const dirName = basename(dirPath);
if (frontmatter.name !== dirName) {
return `Skill name "${frontmatter.name}" does not match directory "${dirName}"`;
}
return null;
}
function checkTokenBudget(content: string): string | null {
const normalizedContent = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
const fmMatch = normalizedContent.match(/^---\s*\n[\s\S]*?\n---\s*\n?/);
const body = fmMatch ? normalizedContent.slice(fmMatch[0].length) : normalizedContent;
const bodyLines = body.split('\n').length;
if (bodyLines > 500) {
return `Body is ${bodyLines} lines (exceeds 500). Consider moving content to references/ directory`;
}
return null;
}
export function evaluateSkillDirectory(dirPath: string): QualityScore | null {
const skillMdPath = join(dirPath, 'SKILL.md');
if (existsSync(skillMdPath)) {
return evaluateSkillFile(skillMdPath);
const result = evaluateSkillFile(skillMdPath);
if (result) {
const content = readFileSync(skillMdPath, 'utf-8');
const nameWarning = checkNameDirectoryMatch(content, dirPath);
if (nameWarning) result.warnings.push(nameWarning);
const budgetWarning = checkTokenBudget(content);
if (budgetWarning) result.warnings.push(budgetWarning);
}
return result;
}
const mdcFiles = ['index.mdc', `${basename(dirPath)}.mdc`];
+1 -1
View File
@@ -12,7 +12,7 @@ import { discoverSkills, extractFrontmatter } from '../skills.js';
export const KNOWN_SKILL_REPOS = [
{ owner: 'anthropics', repo: 'courses', description: 'Anthropic official courses and skills' },
{ owner: 'vercel-labs', repo: 'ai-sdk-preview-internal-knowledge-base', description: 'Vercel AI SDK skills' },
{ owner: 'composioHQ', repo: 'awesome-claude-code-skills', description: 'Curated Claude Code skills' },
{ owner: 'composioHQ', repo: 'awesome-claude-skills', description: 'Curated Claude Code skills' },
] as const;
/**
+30 -17
View File
@@ -10,7 +10,10 @@ export interface ExternalSkill {
export interface ExternalRegistry {
name: string;
search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]>;
search(
query: string,
options?: { limit?: number; timeoutMs?: number },
): Promise<ExternalSkill[]>;
}
export interface FederatedResult {
@@ -22,16 +25,21 @@ export interface FederatedResult {
export class RateLimitError extends Error {
constructor(registry: string) {
super(`Rate limited by ${registry} API. Authenticate with a token or wait before retrying.`);
this.name = 'RateLimitError';
super(
`Rate limited by ${registry} API. Authenticate with a token or wait before retrying.`,
);
this.name = "RateLimitError";
}
}
export class GitHubSkillRegistry implements ExternalRegistry {
name = 'github';
private baseUrl = 'https://api.github.com';
name = "github";
private baseUrl = "https://api.github.com";
async search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]> {
async search(
query: string,
options?: { limit?: number; timeoutMs?: number },
): Promise<ExternalSkill[]> {
const limit = options?.limit ?? 20;
const timeoutMs = options?.timeoutMs ?? 10_000;
const searchQuery = `SKILL.md ${query} in:path,file`;
@@ -41,8 +49,8 @@ export class GitHubSkillRegistry implements ExternalRegistry {
try {
const headers: Record<string, string> = {
Accept: 'application/vnd.github.v3+json',
'User-Agent': 'skillkit-cli',
Accept: "application/vnd.github.v3+json",
"User-Agent": "skillkit-cli",
};
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
if (token) {
@@ -89,15 +97,15 @@ export class GitHubSkillRegistry implements ExternalRegistry {
if (seen.has(repo)) continue;
seen.add(repo);
const pathParts = item.path.split('/');
const pathParts = item.path.split("/");
const skillName =
pathParts.length > 1
? pathParts[pathParts.length - 2]
: repo.split('/').pop() || repo;
: repo.split("/").pop() || repo;
skills.push({
name: skillName,
description: item.repository.description || '',
description: item.repository.description || "",
source: item.repository.html_url,
registry: this.name,
path: item.path,
@@ -115,7 +123,9 @@ export class GitHubSkillRegistry implements ExternalRegistry {
}
}
export { CommunityRegistry } from './community.js';
export { CommunityRegistry } from "./community.js";
export { SkillsShRegistry, resolveSkillsShUrl } from "./skills-sh.js";
export type { SkillsShStats } from "./skills-sh.js";
export class FederatedSearch {
private registries: ExternalRegistry[] = [];
@@ -124,10 +134,15 @@ export class FederatedSearch {
this.registries.push(registry);
}
async search(query: string, options?: { limit?: number }): Promise<FederatedResult> {
async search(
query: string,
options?: { limit?: number; timeoutMs?: number },
): Promise<FederatedResult> {
const limit = options?.limit ?? 20;
const results = await Promise.allSettled(
this.registries.map((r) => r.search(query, { limit })),
this.registries.map((r) =>
r.search(query, { limit, timeoutMs: options?.timeoutMs }),
),
);
const allSkills: ExternalSkill[] = [];
@@ -135,11 +150,9 @@ export class FederatedSearch {
for (let i = 0; i < results.length; i++) {
const result = results[i];
if (result.status === 'fulfilled' && result.value.length > 0) {
if (result.status === "fulfilled" && result.value.length > 0) {
allSkills.push(...result.value);
activeRegistries.push(this.registries[i].name);
} else if (result.status === 'rejected' && result.reason instanceof RateLimitError) {
throw result.reason;
}
}
+190
View File
@@ -0,0 +1,190 @@
import type { ExternalRegistry, ExternalSkill } from "./index.js";
const SKILLS_SH_BASE = "https://skills.sh";
const SKILLS_SH_CACHE_TTL = 10 * 60 * 1000; // 10 minutes
export interface SkillsShStats {
rank: number;
installs: number;
name: string;
source: string;
skillName: string;
}
interface CachedLeaderboard {
skills: ExternalSkill[];
fetchedAt: number;
}
export class SkillsShRegistry implements ExternalRegistry {
name = "skills.sh";
private cache: CachedLeaderboard | null = null;
async search(
query: string,
options?: { limit?: number; timeoutMs?: number },
): Promise<ExternalSkill[]> {
const limit = options?.limit ?? 20;
const skills = await this.fetchLeaderboard(options?.timeoutMs);
const q = query.toLowerCase();
return skills
.filter(
(s) =>
s.name.toLowerCase().includes(q) ||
s.description.toLowerCase().includes(q) ||
s.source.toLowerCase().includes(q),
)
.slice(0, limit);
}
async getLeaderboard(
limit = 50,
timeoutMs?: number,
): Promise<ExternalSkill[]> {
const skills = await this.fetchLeaderboard(timeoutMs);
return skills.slice(0, limit);
}
async getSkillStats(
owner: string,
repo: string,
skillName: string,
): Promise<SkillsShStats | null> {
const skills = await this.fetchLeaderboard();
const source = `${owner}/${repo}`;
for (let i = 0; i < skills.length; i++) {
const skill = skills[i];
if (skill.name === skillName && skill.source.endsWith(`/${source}`)) {
return {
rank: i + 1,
installs: skill.stars ?? 0,
name: skill.name,
source: skill.source,
skillName,
};
}
}
return null;
}
private async fetchLeaderboard(timeoutMs = 15_000): Promise<ExternalSkill[]> {
if (this.cache && Date.now() - this.cache.fetchedAt < SKILLS_SH_CACHE_TTL) {
return this.cache.skills;
}
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(SKILLS_SH_BASE, {
headers: {
Accept: "text/html",
"User-Agent": "skillkit-cli",
},
signal: controller.signal,
});
if (!response.ok) return this.cache?.skills ?? [];
const html = await response.text();
const skills = this.parseLeaderboard(html);
this.cache = { skills, fetchedAt: Date.now() };
return skills;
} catch {
return this.cache?.skills ?? [];
} finally {
clearTimeout(timer);
}
}
private parseLeaderboard(html: string): ExternalSkill[] {
const skills: ExternalSkill[] = [];
const lines = html.split("\n");
for (const line of lines) {
// Match patterns like: [1vercel-labs/skills290.0K] from the page links
const hrefMatch = line.match(
/href="\/([^/]+)\/([^/]+)\/([^"]+)".*?(\d[\d,.]*[KMB]?)\s*<\/a>/,
);
if (hrefMatch) {
const [, owner, repo, skillName, installStr] = hrefMatch;
const installs = this.parseInstallCount(installStr);
skills.push({
name: skillName,
description: `${owner}/${repo}`,
source: `https://github.com/${owner}/${repo}`,
registry: this.name,
path: skillName,
stars: installs,
});
}
}
// Fallback: try simpler pattern matching if structured parsing found nothing
if (skills.length === 0) {
const simplePattern = /skills\.sh\/([^/]+)\/([^/]+)\/([^/"]+)/g;
let match;
while ((match = simplePattern.exec(html)) !== null) {
const [, owner, repo, skillName] = match;
skills.push({
name: skillName,
description: `${owner}/${repo}`,
source: `https://github.com/${owner}/${repo}`,
registry: this.name,
path: skillName,
});
}
}
return skills;
}
private parseInstallCount(str: string): number {
if (!str) return 0;
const cleaned = str.replace(/,/g, "");
const multiplier = cleaned.endsWith("K")
? 1_000
: cleaned.endsWith("M")
? 1_000_000
: cleaned.endsWith("B")
? 1_000_000_000
: 1;
const num = parseFloat(cleaned.replace(/[KMB]$/, ""));
return Math.round(num * multiplier);
}
}
function parseSkillsShParts(
source: string,
): { owner: string; repo: string; rest?: string } | null {
const cleaned = source
.replace(/^https?:\/\//, "")
.replace(/^skills\.sh\//, "");
const parts = cleaned.split("/").filter(Boolean);
if (parts.length < 2) return null;
return {
owner: parts[0],
repo: parts[1],
rest: parts.length > 2 ? parts.slice(2).join("/") : undefined,
};
}
export function resolveSkillsShUrl(
source: string,
): { owner: string; repo: string; skillName?: string } | null {
const parsed = parseSkillsShParts(source);
if (!parsed) return null;
return {
owner: parsed.owner,
repo: parsed.repo,
skillName: parsed.rest,
};
}
+196
View File
@@ -0,0 +1,196 @@
import { existsSync, readFileSync } from 'node:fs';
import { basename, extname } from 'node:path';
import TurndownService from 'turndown';
import type { ExtractedContent, ExtractionOptions } from './types.js';
const LANGUAGE_MAP: Record<string, string> = {
'.ts': 'typescript',
'.tsx': 'typescript',
'.js': 'javascript',
'.jsx': 'javascript',
'.py': 'python',
'.rb': 'ruby',
'.go': 'go',
'.rs': 'rust',
'.java': 'java',
'.kt': 'kotlin',
'.swift': 'swift',
'.c': 'c',
'.cpp': 'cpp',
'.cs': 'csharp',
'.php': 'php',
'.sh': 'shell',
'.bash': 'shell',
'.zsh': 'shell',
'.yml': 'yaml',
'.yaml': 'yaml',
'.json': 'json',
'.toml': 'toml',
'.md': 'markdown',
'.mdx': 'markdown',
'.html': 'html',
'.css': 'css',
'.scss': 'scss',
'.sql': 'sql',
'.r': 'r',
'.lua': 'lua',
'.dart': 'dart',
'.ex': 'elixir',
'.exs': 'elixir',
'.zig': 'zig',
'.nim': 'nim',
'.vue': 'vue',
'.svelte': 'svelte',
};
const GITHUB_URL_PATTERN = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/;
const GITHUB_RAW_PATTERN = /^https?:\/\/raw\.githubusercontent\.com\//;
const FETCH_TIMEOUT = 30_000;
export class ContentExtractor {
private turndown: TurndownService;
constructor() {
this.turndown = new TurndownService({
headingStyle: 'atx',
codeBlockStyle: 'fenced',
});
}
async extractFromUrl(url: string, options?: ExtractionOptions): Promise<ExtractedContent> {
if (this.isGitHubUrl(url)) {
return this.fetchGitHubContent(url, options);
}
const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
if (!response.ok) {
throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
}
const contentType = response.headers.get('content-type') ?? '';
const body = await response.text();
if (contentType.includes('text/html')) {
const { title, content } = this.htmlToMarkdown(body, url);
const finalContent = options?.maxLength ? content.slice(0, options.maxLength) : content;
return {
title: options?.preferredTitle ?? title,
content: finalContent,
sourceUrl: url,
tags: [],
extractedAt: new Date().toISOString(),
contentType: 'webpage',
metadata: { url },
};
}
const title = options?.preferredTitle ?? new URL(url).pathname.split('/').pop() ?? 'Untitled';
const finalContent = options?.maxLength ? body.slice(0, options.maxLength) : body;
return {
title,
content: finalContent,
sourceUrl: url,
tags: [],
extractedAt: new Date().toISOString(),
contentType: 'text',
metadata: { url },
};
}
extractFromText(text: string, options?: ExtractionOptions): ExtractedContent {
const firstLine = text.split('\n')[0]?.trim() ?? '';
const title = options?.preferredTitle ?? (firstLine.length > 0 && firstLine.length <= 100 ? firstLine : 'Untitled');
const content = options?.maxLength ? text.slice(0, options.maxLength) : text;
return {
title,
content,
tags: [],
extractedAt: new Date().toISOString(),
contentType: 'text',
metadata: {},
};
}
extractFromFile(filePath: string, options?: ExtractionOptions): ExtractedContent {
if (!existsSync(filePath)) {
throw new Error(`File not found: ${filePath}`);
}
const raw = readFileSync(filePath, 'utf-8');
const name = basename(filePath);
const language = this.detectLanguage(name);
const isCode = language !== undefined && language !== 'markdown';
const title = options?.preferredTitle ?? name;
const content = options?.maxLength ? raw.slice(0, options.maxLength) : raw;
return {
title,
content: isCode ? `\`\`\`${language}\n${content}\n\`\`\`` : content,
sourcePath: filePath,
tags: language ? [language] : [],
extractedAt: new Date().toISOString(),
contentType: isCode ? 'code' : 'file',
language,
metadata: { filename: name },
};
}
private isGitHubUrl(url: string): boolean {
return GITHUB_URL_PATTERN.test(url) || GITHUB_RAW_PATTERN.test(url);
}
private async fetchGitHubContent(url: string, options?: ExtractionOptions): Promise<ExtractedContent> {
let rawUrl = url;
const match = url.match(GITHUB_URL_PATTERN);
if (match) {
const [, owner, repo, branch, path] = match;
rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
}
const response = await fetch(rawUrl, { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
if (!response.ok) {
throw new Error(`Failed to fetch GitHub content: ${response.status} ${response.statusText}`);
}
const body = await response.text();
const filename = rawUrl.split('/').pop() ?? 'file';
const language = this.detectLanguage(filename);
const isCode = language !== undefined && language !== 'markdown';
const title = options?.preferredTitle ?? filename;
const content = options?.maxLength ? body.slice(0, options.maxLength) : body;
return {
title,
content: isCode ? `\`\`\`${language}\n${content}\n\`\`\`` : content,
sourceUrl: url,
tags: language ? ['github', language] : ['github'],
extractedAt: new Date().toISOString(),
contentType: 'github',
language,
metadata: {
url,
rawUrl,
filename,
},
};
}
private htmlToMarkdown(html: string, url: string): { title: string; content: string } {
const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
const title = titleMatch?.[1]?.trim() ?? new URL(url).hostname;
const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
const bodyHtml = bodyMatch?.[1] ?? html;
const content = this.turndown.turndown(bodyHtml);
return { title, content };
}
private detectLanguage(filename: string): string | undefined {
const ext = extname(filename).toLowerCase();
return LANGUAGE_MAP[ext];
}
}
+5
View File
@@ -0,0 +1,5 @@
export { ContentExtractor } from './extractor.js';
export { AutoTagger } from './tagger.js';
export { SkillGenerator } from './skill-generator.js';
export type { ExtractedContent, ExtractionOptions } from './types.js';
export type { SaveGenerateOptions, SaveGeneratedSkill } from './skill-generator.js';
+121
View File
@@ -0,0 +1,121 @@
import { mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { homedir } from 'node:os';
import type { ExtractedContent } from './types.js';
import { AutoTagger } from './tagger.js';
export interface SaveGenerateOptions {
name?: string;
global?: boolean;
outputDir?: string;
}
export interface SaveGeneratedSkill {
skillPath: string;
skillMd: string;
name: string;
}
const MAX_NAME_LENGTH = 64;
const SUMMARY_LINE_LIMIT = 100;
const SPLIT_THRESHOLD = 500;
const DESCRIPTION_MAX = 200;
export class SkillGenerator {
private tagger = new AutoTagger();
generate(content: ExtractedContent, options: SaveGenerateOptions = {}): SaveGeneratedSkill {
const name = options.name
? this.slugify(options.name)
: this.slugify(content.title || 'untitled-skill');
const tags = this.tagger.detectTags(content);
const description = this.makeDescription(content.content);
const source = content.sourceUrl ?? content.sourcePath ?? '';
const frontmatter = this.buildFrontmatter(name, description, tags, source);
const lines = content.content.split('\n');
const needsSplit = lines.length > SPLIT_THRESHOLD;
const body = needsSplit
? lines.slice(0, SUMMARY_LINE_LIMIT).join('\n')
: content.content;
const skillMd = `${frontmatter}\n${body}\n`;
const outputDir = options.outputDir ?? this.defaultOutputDir(name, options.global);
mkdirSync(outputDir, { recursive: true });
const skillPath = join(outputDir, 'SKILL.md');
writeFileSync(skillPath, skillMd, 'utf-8');
if (needsSplit) {
const refsDir = join(outputDir, 'references');
mkdirSync(refsDir, { recursive: true });
writeFileSync(
join(refsDir, 'full-content.md'),
content.content,
'utf-8',
);
}
return { skillPath, skillMd, name };
}
private slugify(input: string): string {
const slug = input
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '')
.replace(/-{2,}/g, '-');
const trimmed = slug.slice(0, MAX_NAME_LENGTH).replace(/-+$/, '');
return trimmed || 'untitled-skill';
}
private makeDescription(content: string): string {
const firstLine = content.split('\n').find((l) => l.trim().length > 0) ?? '';
const cleaned = firstLine.replace(/^#+\s*/, '').trim();
return cleaned.length > DESCRIPTION_MAX
? cleaned.slice(0, DESCRIPTION_MAX - 3) + '...'
: cleaned || 'Saved skill';
}
private buildFrontmatter(
name: string,
description: string,
tags: string[],
source: string,
): string {
const yamlTags = tags.map((t) => ` - ${t}`).join('\n');
const savedAt = new Date().toISOString();
const lines = [
'---',
`name: ${name}`,
`description: ${this.yamlEscape(description)}`,
tags.length > 0 ? `tags:\n${yamlTags}` : null,
'metadata:',
source ? ` source: ${source}` : null,
` savedAt: ${savedAt}`,
'---',
].filter((l): l is string => l !== null);
return lines.join('\n') + '\n';
}
private yamlEscape(value: string): string {
const singleLine = value.replace(/\r?\n/g, ' ').trim();
if (/[:#{}[\],&*?|>!%@`]/.test(singleLine) || singleLine.startsWith("'") || singleLine.startsWith('"')) {
return `"${singleLine.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
}
return singleLine;
}
private defaultOutputDir(name: string, global?: boolean): string {
if (global) {
return join(homedir(), '.skillkit', 'skills', name);
}
return join('.skillkit', 'skills', name);
}
}
+98
View File
@@ -0,0 +1,98 @@
import type { ExtractedContent } from './types.js';
const TECH_KEYWORDS = new Set([
'react', 'vue', 'angular', 'svelte', 'nextjs', 'nuxt', 'remix',
'typescript', 'javascript', 'python', 'rust', 'go', 'java', 'ruby',
'node', 'deno', 'bun', 'docker', 'kubernetes', 'terraform',
'aws', 'gcp', 'azure', 'vercel', 'netlify', 'cloudflare',
'graphql', 'rest', 'grpc', 'websocket', 'redis', 'postgres',
'mongodb', 'sqlite', 'mysql', 'prisma', 'drizzle',
'tailwind', 'css', 'html', 'sass', 'webpack', 'vite', 'esbuild',
'git', 'ci', 'cd', 'testing', 'security', 'authentication',
'api', 'cli', 'sdk', 'mcp', 'llm', 'ai', 'ml', 'openai', 'anthropic',
]);
const TAG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
export class AutoTagger {
detectTags(content: ExtractedContent): string[] {
const tagCounts = new Map<string, number>();
this.extractFromUrl(content.sourceUrl, tagCounts);
this.extractFromHeadings(content.content, tagCounts);
this.extractFromCodeBlocks(content.content, tagCounts);
this.extractFromKeywords(content.content, tagCounts);
if (content.language) {
this.addTag(content.language.toLowerCase(), tagCounts, 3);
}
if (content.contentType !== 'text') {
this.addTag(content.contentType, tagCounts, 1);
}
return Array.from(tagCounts.entries())
.sort((a, b) => b[1] - a[1])
.slice(0, 10)
.map(([tag]) => tag);
}
private extractFromUrl(url: string | undefined, counts: Map<string, number>): void {
if (!url) return;
try {
const parsed = new URL(url);
const segments = parsed.pathname
.split('/')
.filter(Boolean)
.map((s) => s.toLowerCase().replace(/[^a-z0-9-]/g, ''));
for (const seg of segments) {
if (seg.length >= 2 && seg.length <= 30 && TAG_PATTERN.test(seg)) {
this.addTag(seg, counts, 2);
}
}
} catch {
// not a valid URL, skip
}
}
private extractFromHeadings(content: string, counts: Map<string, number>): void {
const headingRe = /^#{1,2}\s+(.+)$/gm;
let match: RegExpExecArray | null;
while ((match = headingRe.exec(content)) !== null) {
const words = match[1].toLowerCase().split(/\s+/);
for (const word of words) {
const cleaned = word.replace(/[^a-z0-9-]/g, '');
if (cleaned.length >= 2 && TAG_PATTERN.test(cleaned)) {
this.addTag(cleaned, counts, 2);
}
}
}
}
private extractFromCodeBlocks(content: string, counts: Map<string, number>): void {
const codeBlockRe = /^```(\w+)/gm;
let match: RegExpExecArray | null;
while ((match = codeBlockRe.exec(content)) !== null) {
const lang = match[1].toLowerCase();
if (lang.length >= 2 && TAG_PATTERN.test(lang)) {
this.addTag(lang, counts, 3);
}
}
}
private extractFromKeywords(content: string, counts: Map<string, number>): void {
const lower = content.toLowerCase();
for (const keyword of TECH_KEYWORDS) {
const re = new RegExp(`\\b${keyword}\\b`, 'i');
if (re.test(lower)) {
this.addTag(keyword, counts, 1);
}
}
}
private addTag(tag: string, counts: Map<string, number>, weight: number): void {
if (!TAG_PATTERN.test(tag)) return;
counts.set(tag, (counts.get(tag) ?? 0) + weight);
}
}
+17
View File
@@ -0,0 +1,17 @@
export interface ExtractedContent {
title: string;
content: string;
sourceUrl?: string;
sourcePath?: string;
tags: string[];
extractedAt: string;
contentType: 'webpage' | 'github' | 'text' | 'code' | 'file';
language?: string;
metadata: Record<string, string>;
}
export interface ExtractionOptions {
includeImages?: boolean;
maxLength?: number;
preferredTitle?: string;
}
+2 -2
View File
@@ -125,13 +125,13 @@ export function formatSarif(result: ScanResult): string {
driver: {
name: 'skillkit-scanner',
version: SCANNER_VERSION,
informationUri: 'https://agenstskills.com',
informationUri: 'https://skillkit.sh',
rules: [...rules.values()].map((r) => ({
id: r.ruleId,
name: r.ruleId,
shortDescription: { text: r.title },
fullDescription: { text: r.description },
helpUri: 'https://agenstskills.com/docs/security',
helpUri: 'https://skillkit.sh/docs/security',
defaultConfiguration: {
level: severityToSarif[r.severity] ?? 'warning',
},
@@ -0,0 +1,334 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { ActivityLog } from '../activity-log.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
}));
describe('ActivityLog', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.useFakeTimers();
vi.setSystemTime(new Date('2026-02-10T12:00:00Z'));
});
afterEach(() => {
vi.useRealTimers();
vi.resetAllMocks();
});
describe('constructor', () => {
it('should create an instance', () => {
vi.mocked(existsSync).mockReturnValue(false);
const log = new ActivityLog('/test/project');
expect(log).toBeDefined();
});
});
describe('record', () => {
it('should record a new activity entry', () => {
vi.mocked(existsSync).mockReturnValue(false);
const log = new ActivityLog('/test/project');
log.record({
commitSha: 'abc1234',
message: 'fix: parser edge case',
activeSkills: ['code-simplifier'],
filesChanged: ['src/index.ts'],
});
expect(vi.mocked(writeFileSync)).toHaveBeenCalledTimes(1);
const content = vi.mocked(writeFileSync).mock.calls[0][1] as string;
expect(content).toContain('abc1234');
expect(content).toContain('code-simplifier');
expect(content).toContain('src/index.ts');
expect(content).toContain('fix: parser edge case');
});
it('should prepend new activities (most recent first)', () => {
const existing = `
version: 1
activities:
- commitSha: "old1234"
committedAt: "2026-02-09T10:00:00.000Z"
activeSkills:
- remotion-best-practices
filesChanged:
- src/old.ts
message: "feat: old feature"
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existing);
const log = new ActivityLog('/test/project');
log.record({
commitSha: 'new5678',
message: 'fix: new fix',
activeSkills: ['code-simplifier'],
filesChanged: ['src/new.ts'],
});
const content = vi.mocked(writeFileSync).mock.calls[0][1] as string;
const newIdx = content.indexOf('new5678');
const oldIdx = content.indexOf('old1234');
expect(newIdx).toBeLessThan(oldIdx);
});
it('should cap activities at 500', () => {
const activityEntries = Array.from({ length: 500 }, (_, i) => `
- commitSha: "sha${i}"
committedAt: "2026-02-09T10:00:00.000Z"
activeSkills:
- skill-a
filesChanged:
- file.ts
message: "commit ${i}"`).join('');
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
`version: 1\nactivities:${activityEntries}`
);
const log = new ActivityLog('/test/project');
log.record({
commitSha: 'newsha',
message: 'new commit',
activeSkills: ['skill-b'],
filesChanged: ['new.ts'],
});
expect(vi.mocked(writeFileSync)).toHaveBeenCalledTimes(1);
const content = vi.mocked(writeFileSync).mock.calls[0][1] as string;
expect(content).toContain('newsha');
const commitMatches = content.match(/commitSha:/g);
expect(commitMatches!.length).toBe(500);
});
});
describe('getByCommit', () => {
it('should find activity by full SHA', () => {
const existing = `
version: 1
activities:
- commitSha: "abc1234567890"
committedAt: "2026-02-10T10:00:00.000Z"
activeSkills:
- code-simplifier
filesChanged:
- src/index.ts
message: "fix: edge case"
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existing);
const log = new ActivityLog('/test/project');
const result = log.getByCommit('abc1234567890');
expect(result).toBeDefined();
expect(result!.commitSha).toBe('abc1234567890');
});
it('should find activity by short SHA prefix', () => {
const existing = `
version: 1
activities:
- commitSha: "abc1234567890"
committedAt: "2026-02-10T10:00:00.000Z"
activeSkills:
- code-simplifier
filesChanged:
- src/index.ts
message: "fix: edge case"
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existing);
const log = new ActivityLog('/test/project');
const result = log.getByCommit('abc1234');
expect(result).toBeDefined();
expect(result!.commitSha).toBe('abc1234567890');
});
it('should return undefined for unknown SHA', () => {
vi.mocked(existsSync).mockReturnValue(false);
const log = new ActivityLog('/test/project');
const result = log.getByCommit('nonexistent');
expect(result).toBeUndefined();
});
});
describe('getBySkill', () => {
it('should filter activities by skill name', () => {
const existing = `
version: 1
activities:
- commitSha: "sha1"
committedAt: "2026-02-10T12:00:00.000Z"
activeSkills:
- code-simplifier
filesChanged:
- src/a.ts
message: "fix: a"
- commitSha: "sha2"
committedAt: "2026-02-10T11:00:00.000Z"
activeSkills:
- remotion-best-practices
filesChanged:
- src/b.ts
message: "feat: b"
- commitSha: "sha3"
committedAt: "2026-02-10T10:00:00.000Z"
activeSkills:
- code-simplifier
- remotion-best-practices
filesChanged:
- src/c.ts
message: "refactor: c"
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existing);
const log = new ActivityLog('/test/project');
const results = log.getBySkill('code-simplifier');
expect(results).toHaveLength(2);
expect(results[0].commitSha).toBe('sha1');
expect(results[1].commitSha).toBe('sha3');
});
it('should return empty array for unknown skill', () => {
vi.mocked(existsSync).mockReturnValue(false);
const log = new ActivityLog('/test/project');
const results = log.getBySkill('nonexistent');
expect(results).toEqual([]);
});
});
describe('getRecent', () => {
it('should return recent activities with default limit', () => {
const activities = Array.from({ length: 25 }, (_, i) => `
- commitSha: "sha${i}"
committedAt: "2026-02-10T12:${String(i).padStart(2, '0')}:00.000Z"
activeSkills:
- skill-a
filesChanged:
- file${i}.ts
message: "commit ${i}"
`).join('');
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
`version: 1\nactivities:\n${activities}`
);
const log = new ActivityLog('/test/project');
const results = log.getRecent();
expect(results).toHaveLength(20);
});
it('should respect custom limit', () => {
const activities = Array.from({ length: 10 }, (_, i) => `
- commitSha: "sha${i}"
committedAt: "2026-02-10T12:${String(i).padStart(2, '0')}:00.000Z"
activeSkills:
- skill-a
filesChanged:
- file${i}.ts
message: "commit ${i}"
`).join('');
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
`version: 1\nactivities:\n${activities}`
);
const log = new ActivityLog('/test/project');
const results = log.getRecent(3);
expect(results).toHaveLength(3);
});
it('should return empty array when no activities exist', () => {
vi.mocked(existsSync).mockReturnValue(false);
const log = new ActivityLog('/test/project');
const results = log.getRecent();
expect(results).toEqual([]);
});
});
describe('getMostUsedSkills', () => {
it('should return skills sorted by usage count', () => {
const existing = `
version: 1
activities:
- commitSha: "sha1"
committedAt: "2026-02-10T12:00:00.000Z"
activeSkills:
- code-simplifier
filesChanged:
- a.ts
message: "a"
- commitSha: "sha2"
committedAt: "2026-02-10T11:00:00.000Z"
activeSkills:
- remotion-best-practices
- code-simplifier
filesChanged:
- b.ts
message: "b"
- commitSha: "sha3"
committedAt: "2026-02-10T10:00:00.000Z"
activeSkills:
- remotion-best-practices
- code-simplifier
- visual-storyteller
filesChanged:
- c.ts
message: "c"
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existing);
const log = new ActivityLog('/test/project');
const topSkills = log.getMostUsedSkills();
expect(topSkills).toHaveLength(3);
expect(topSkills[0]).toEqual({ skill: 'code-simplifier', count: 3 });
expect(topSkills[1]).toEqual({ skill: 'remotion-best-practices', count: 2 });
expect(topSkills[2]).toEqual({ skill: 'visual-storyteller', count: 1 });
});
it('should return empty array when no activities exist', () => {
vi.mocked(existsSync).mockReturnValue(false);
const log = new ActivityLog('/test/project');
const topSkills = log.getMostUsedSkills();
expect(topSkills).toEqual([]);
});
});
describe('corrupted file handling', () => {
it('should handle corrupted YAML gracefully', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue('{{invalid yaml');
const log = new ActivityLog('/test/project');
const results = log.getRecent();
expect(results).toEqual([]);
});
});
});
@@ -0,0 +1,361 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { stringify } from 'yaml';
import { SessionHandoff } from '../handoff.js';
import type { SessionState } from '../types.js';
const TEST_DIR = join(process.cwd(), '.test-handoff-' + process.pid);
const SKILLKIT_DIR = join(TEST_DIR, '.skillkit');
function writeSessionState(state: SessionState): void {
mkdirSync(SKILLKIT_DIR, { recursive: true });
writeFileSync(join(SKILLKIT_DIR, 'session.yaml'), stringify(state));
}
function writeObservations(observations: Array<Record<string, unknown>>): void {
const dir = join(SKILLKIT_DIR, 'memory');
mkdirSync(dir, { recursive: true });
writeFileSync(
join(dir, 'observations.yaml'),
stringify({ version: 1, sessionId: 'test', observations })
);
}
beforeEach(() => {
mkdirSync(TEST_DIR, { recursive: true });
});
afterEach(() => {
if (existsSync(TEST_DIR)) {
rmSync(TEST_DIR, { recursive: true, force: true });
}
});
describe('SessionHandoff', () => {
it('should create handoff instance', () => {
const handoff = new SessionHandoff(TEST_DIR);
expect(handoff).toBeDefined();
});
it('should generate empty handoff when no data', () => {
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
expect(doc.generatedAt).toBeTruthy();
expect(doc.projectPath).toBe(TEST_DIR);
expect(doc.accomplished.tasks).toEqual([]);
expect(doc.pending.tasks).toEqual([]);
expect(doc.keyFiles).toEqual([]);
});
it('should collect accomplished tasks', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [],
decisions: [],
currentExecution: {
skillName: 'test-skill',
skillSource: 'test',
currentStep: 2,
totalSteps: 3,
status: 'running',
startedAt: '2026-02-12T10:00:00.000Z',
tasks: [
{
id: 't1',
name: 'Setup project',
type: 'auto',
status: 'completed',
startedAt: '2026-02-12T10:00:00.000Z',
completedAt: '2026-02-12T10:03:00.000Z',
commitSha: 'abc1234',
},
{
id: 't2',
name: 'Write tests',
type: 'auto',
status: 'completed',
startedAt: '2026-02-12T10:03:00.000Z',
completedAt: '2026-02-12T10:08:00.000Z',
},
{
id: 't3',
name: 'Update docs',
type: 'auto',
status: 'pending',
},
],
},
});
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
expect(doc.accomplished.tasks.length).toBe(2);
expect(doc.accomplished.tasks[0].name).toBe('Setup project');
expect(doc.accomplished.tasks[0].duration).toBe('3m');
expect(doc.accomplished.tasks[0].commitSha).toBe('abc1234');
});
it('should collect pending tasks', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [],
decisions: [],
currentExecution: {
skillName: 'test-skill',
skillSource: 'test',
currentStep: 0,
totalSteps: 2,
status: 'running',
startedAt: '2026-02-12T10:00:00.000Z',
tasks: [
{ id: 't1', name: 'Pending task', type: 'auto', status: 'pending' },
{ id: 't2', name: 'In progress task', type: 'auto', status: 'in_progress', startedAt: '2026-02-12T10:00:00.000Z' },
],
},
});
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
expect(doc.pending.tasks.length).toBe(2);
expect(doc.pending.tasks[0].name).toBe('Pending task');
expect(doc.pending.tasks[1].name).toBe('In progress task');
});
it('should collect key files from tasks and history', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'old-skill',
skillSource: 'test',
completedAt: '2026-02-11T15:00:00.000Z',
durationMs: 120000,
status: 'completed',
commits: [],
filesModified: ['src/old.ts', 'src/shared.ts'],
},
],
decisions: [],
currentExecution: {
skillName: 'test-skill',
skillSource: 'test',
currentStep: 1,
totalSteps: 1,
status: 'running',
startedAt: '2026-02-12T10:00:00.000Z',
tasks: [
{
id: 't1',
name: 'Task 1',
type: 'auto',
status: 'completed',
filesModified: ['src/new.ts', 'src/shared.ts'],
},
],
},
});
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
expect(doc.keyFiles.length).toBe(3);
const paths = doc.keyFiles.map((f) => f.path);
expect(paths).toContain('src/new.ts');
expect(paths).toContain('src/old.ts');
expect(paths).toContain('src/shared.ts');
});
it('should collect observations by type', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [],
decisions: [],
});
writeObservations([
{
id: 'o1',
timestamp: '2026-02-12T10:00:00.000Z',
sessionId: 'test',
agent: 'claude-code',
type: 'error',
content: { action: 'build', context: 'src', error: 'missing import' },
relevance: 90,
},
{
id: 'o2',
timestamp: '2026-02-12T10:01:00.000Z',
sessionId: 'test',
agent: 'claude-code',
type: 'solution',
content: { action: 'fix', context: 'src', solution: 'added import' },
relevance: 85,
},
{
id: 'o3',
timestamp: '2026-02-12T10:02:00.000Z',
sessionId: 'test',
agent: 'claude-code',
type: 'pattern',
content: { action: 'review', context: 'always check imports' },
relevance: 70,
},
]);
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
expect(doc.observations.errors.length).toBe(1);
expect(doc.observations.errors[0].error).toBe('missing import');
expect(doc.observations.solutions.length).toBe(1);
expect(doc.observations.solutions[0].solution).toBe('added import');
expect(doc.observations.patterns.length).toBe(1);
});
it('should generate recommendations from pending tasks', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [],
decisions: [],
currentExecution: {
skillName: 'test-skill',
skillSource: 'test',
currentStep: 0,
totalSteps: 1,
status: 'running',
startedAt: '2026-02-12T10:00:00.000Z',
tasks: [
{ id: 't1', name: 'Write documentation', type: 'auto', status: 'pending' },
],
},
});
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
expect(doc.recommendations.length).toBeGreaterThan(0);
expect(doc.recommendations[0]).toContain('Write documentation');
});
it('should format markdown output', () => {
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
const md = handoff.toMarkdown(doc);
expect(md).toContain('# Session Handoff');
expect(md).toContain('## Accomplished');
expect(md).toContain('## Pending');
});
it('should format JSON output', () => {
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
const json = handoff.toJson(doc);
const parsed = JSON.parse(json);
expect(parsed.projectPath).toBe(TEST_DIR);
expect(parsed.accomplished).toBeDefined();
expect(parsed.pending).toBeDefined();
});
it('should include history in accomplished', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'completed-skill',
skillSource: 'test',
completedAt: '2026-02-12T09:00:00.000Z',
durationMs: 300000,
status: 'completed',
commits: ['def5678'],
filesModified: ['src/foo.ts'],
},
],
decisions: [],
});
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false });
expect(doc.accomplished.tasks.length).toBe(1);
expect(doc.accomplished.tasks[0].name).toBe('completed-skill');
expect(doc.accomplished.tasks[0].duration).toBe('5m');
});
it('should respect maxObservations option', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [],
decisions: [],
});
writeObservations(
Array.from({ length: 10 }, (_, i) => ({
id: `o${i}`,
timestamp: `2026-02-12T10:${String(i).padStart(2, '0')}:00.000Z`,
sessionId: 'test',
agent: 'claude-code',
type: 'error',
content: { action: `action-${i}`, context: 'src', error: `error-${i}` },
relevance: 90 - i,
}))
);
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false, maxObservations: 3 });
const totalObs =
doc.observations.errors.length +
doc.observations.solutions.length +
doc.observations.patterns.length;
expect(totalObs).toBeLessThanOrEqual(3);
});
it('should skip observations when disabled', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [],
decisions: [],
});
writeObservations([
{
id: 'o1',
timestamp: '2026-02-12T10:00:00.000Z',
sessionId: 'test',
agent: 'claude-code',
type: 'error',
content: { action: 'build', context: 'src', error: 'fail' },
relevance: 90,
},
]);
const handoff = new SessionHandoff(TEST_DIR);
const doc = handoff.generate({ includeGit: false, includeObservations: false });
expect(doc.observations.errors).toEqual([]);
expect(doc.observations.solutions).toEqual([]);
expect(doc.observations.patterns).toEqual([]);
});
});
@@ -0,0 +1,554 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { stringify } from 'yaml';
import { SkillLineage } from '../lineage.js';
import type { SessionState } from '../types.js';
const TEST_DIR = join(process.cwd(), '.test-lineage-' + process.pid);
const SKILLKIT_DIR = join(TEST_DIR, '.skillkit');
function writeSessionState(state: SessionState): void {
mkdirSync(SKILLKIT_DIR, { recursive: true });
writeFileSync(join(SKILLKIT_DIR, 'session.yaml'), stringify(state));
}
function writeActivityLog(activities: Array<Record<string, unknown>>): void {
mkdirSync(SKILLKIT_DIR, { recursive: true });
writeFileSync(
join(SKILLKIT_DIR, 'activity.yaml'),
stringify({ version: 1, activities })
);
}
function writeObservations(observations: Array<Record<string, unknown>>): void {
const dir = join(SKILLKIT_DIR, 'memory');
mkdirSync(dir, { recursive: true });
writeFileSync(
join(dir, 'observations.yaml'),
stringify({ version: 1, sessionId: 'test', observations })
);
}
beforeEach(() => {
mkdirSync(TEST_DIR, { recursive: true });
});
afterEach(() => {
if (existsSync(TEST_DIR)) {
rmSync(TEST_DIR, { recursive: true, force: true });
}
});
describe('SkillLineage', () => {
it('should create lineage instance', () => {
const lineage = new SkillLineage(TEST_DIR);
expect(lineage).toBeDefined();
});
it('should return empty lineage when no data', () => {
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
expect(data.skills).toEqual([]);
expect(data.files).toEqual([]);
expect(data.stats.totalSkillExecutions).toBe(0);
expect(data.stats.mostImpactfulSkill).toBeNull();
});
it('should build lineage from execution history', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'code-simplifier',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 120000,
status: 'completed',
commits: ['abc1234', 'def5678'],
filesModified: ['src/index.ts', 'src/utils.ts'],
},
{
skillName: 'code-simplifier',
skillSource: 'test',
completedAt: '2026-02-12T11:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['ghi9012'],
filesModified: ['src/index.ts'],
},
{
skillName: 'pro-workflow',
skillSource: 'test',
completedAt: '2026-02-12T12:00:00.000Z',
durationMs: 180000,
status: 'completed',
commits: ['jkl3456'],
filesModified: ['src/index.ts', 'README.md'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
expect(data.skills.length).toBe(2);
const cs = data.skills.find((s) => s.skillName === 'code-simplifier');
expect(cs).toBeDefined();
expect(cs!.executions).toBe(2);
expect(cs!.totalDurationMs).toBe(180000);
expect(cs!.commits.length).toBe(3);
expect(cs!.filesModified).toContain('src/index.ts');
expect(cs!.filesModified).toContain('src/utils.ts');
const pw = data.skills.find((s) => s.skillName === 'pro-workflow');
expect(pw).toBeDefined();
expect(pw!.executions).toBe(1);
});
it('should build file lineage', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'skill-a',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['abc'],
filesModified: ['src/shared.ts'],
},
{
skillName: 'skill-b',
skillSource: 'test',
completedAt: '2026-02-12T11:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['def'],
filesModified: ['src/shared.ts', 'src/only-b.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
const shared = data.files.find((f) => f.path === 'src/shared.ts');
expect(shared).toBeDefined();
expect(shared!.skills.length).toBe(2);
expect(shared!.skills).toContain('skill-a');
expect(shared!.skills).toContain('skill-b');
});
it('should compute stats', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'big-skill',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['a', 'b'],
filesModified: ['f1.ts', 'f2.ts', 'f3.ts'],
},
{
skillName: 'small-skill',
skillSource: 'test',
completedAt: '2026-02-12T11:00:00.000Z',
durationMs: 30000,
status: 'completed',
commits: ['c'],
filesModified: ['f1.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
expect(data.stats.totalSkillExecutions).toBe(2);
expect(data.stats.totalCommits).toBe(3);
expect(data.stats.totalFilesChanged).toBe(3);
expect(data.stats.mostImpactfulSkill).toBe('big-skill');
});
it('should filter by skill name', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'target',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['a'],
filesModified: ['src/a.ts'],
},
{
skillName: 'other',
skillSource: 'test',
completedAt: '2026-02-12T11:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['b'],
filesModified: ['src/b.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build({ skill: 'target' });
expect(data.skills.length).toBe(1);
expect(data.skills[0].skillName).toBe('target');
expect(data.files.every((f) => f.skills.includes('target'))).toBe(true);
});
it('should filter by file path', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'skill-a',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['a'],
filesModified: ['src/target.ts', 'src/other.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build({ file: 'target.ts' });
expect(data.files.length).toBe(1);
expect(data.files[0].path).toBe('src/target.ts');
});
it('should filter by since date', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'old',
skillSource: 'test',
completedAt: '2026-01-01T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['a'],
filesModified: ['old.ts'],
},
{
skillName: 'recent',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['b'],
filesModified: ['recent.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build({ since: '2026-02-01' });
expect(data.skills.length).toBe(1);
expect(data.skills[0].skillName).toBe('recent');
});
it('should include current execution in lineage', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [],
decisions: [],
currentExecution: {
skillName: 'active-skill',
skillSource: 'test',
currentStep: 1,
totalSteps: 2,
status: 'running',
startedAt: '2026-02-12T10:00:00.000Z',
tasks: [
{
id: 't1',
name: 'Task 1',
type: 'auto',
status: 'completed',
commitSha: 'abc',
filesModified: ['src/active.ts'],
},
],
},
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
expect(data.skills.length).toBe(1);
expect(data.skills[0].skillName).toBe('active-skill');
expect(data.skills[0].commits).toContain('abc');
expect(data.skills[0].filesModified).toContain('src/active.ts');
});
it('should merge activity log data', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'my-skill',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['abc'],
filesModified: ['src/a.ts'],
},
],
decisions: [],
});
writeActivityLog([
{
commitSha: 'xyz',
committedAt: '2026-02-12T11:00:00.000Z',
activeSkills: ['my-skill'],
filesChanged: ['src/b.ts'],
message: 'extra commit',
},
]);
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
const skill = data.skills.find((s) => s.skillName === 'my-skill');
expect(skill).toBeDefined();
expect(skill!.commits).toContain('xyz');
});
it('should match observations by timestamp overlap', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'test-skill',
skillSource: 'test',
completedAt: '2026-02-12T11:00:00.000Z',
durationMs: 3600000,
status: 'completed',
commits: [],
filesModified: [],
},
],
decisions: [],
});
writeObservations([
{
id: 'obs1',
timestamp: '2026-02-12T10:30:00.000Z',
sessionId: 'test',
agent: 'claude-code',
type: 'error',
content: { action: 'build', context: 'src', files: ['src/buggy.ts'] },
relevance: 80,
},
]);
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
expect(data.stats.errorProneFiles).toContain('src/buggy.ts');
});
it('should getSkillLineage for a specific skill', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'target-skill',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['abc'],
filesModified: ['src/foo.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const entry = lineage.getSkillLineage('target-skill');
expect(entry).toBeDefined();
expect(entry!.skillName).toBe('target-skill');
expect(entry!.executions).toBe(1);
});
it('should getFileLineage for a specific file', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'skill-a',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['abc'],
filesModified: ['src/target.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const fl = lineage.getFileLineage('src/target.ts');
expect(fl).toBeDefined();
expect(fl!.path).toBe('src/target.ts');
expect(fl!.skills).toContain('skill-a');
});
it('should format text output', () => {
const lineage = new SkillLineage(TEST_DIR);
const data = {
projectPath: TEST_DIR,
skills: [
{
skillName: 'test-skill',
executions: 3,
totalDurationMs: 180000,
commits: ['a', 'b'],
filesModified: ['f1.ts', 'f2.ts'],
observationIds: [],
firstSeen: '2026-02-12T08:00:00.000Z',
lastSeen: '2026-02-12T12:00:00.000Z',
},
],
files: [
{ path: 'f1.ts', skills: ['test-skill', 'other'], commitCount: 5, lastModified: '2026-02-12T12:00:00.000Z' },
],
stats: {
totalSkillExecutions: 3,
totalCommits: 2,
totalFilesChanged: 2,
mostImpactfulSkill: 'test-skill',
mostChangedFile: 'f1.ts',
errorProneFiles: ['f1.ts'],
},
};
const text = lineage.formatText(data);
expect(text).toContain('Skill Lineage');
expect(text).toContain('test-skill');
expect(text).toContain('3 runs');
expect(text).toContain('File Hotspots');
expect(text).toContain('Stats');
});
it('should format JSON output', () => {
const lineage = new SkillLineage(TEST_DIR);
const data = {
projectPath: TEST_DIR,
skills: [],
files: [],
stats: {
totalSkillExecutions: 0,
totalCommits: 0,
totalFilesChanged: 0,
mostImpactfulSkill: null,
mostChangedFile: null,
errorProneFiles: [],
},
};
const json = lineage.formatJson(data);
const parsed = JSON.parse(json);
expect(parsed.projectPath).toBe(TEST_DIR);
});
it('should handle empty lineage in text format', () => {
const lineage = new SkillLineage(TEST_DIR);
const data = {
projectPath: TEST_DIR,
skills: [],
files: [],
stats: {
totalSkillExecutions: 0,
totalCommits: 0,
totalFilesChanged: 0,
mostImpactfulSkill: null,
mostChangedFile: null,
errorProneFiles: [],
},
};
const text = lineage.formatText(data);
expect(text).toContain('No skill executions found');
});
it('should deduplicate commits and files', () => {
writeSessionState({
version: 1,
lastActivity: new Date().toISOString(),
projectPath: TEST_DIR,
history: [
{
skillName: 'dup-skill',
skillSource: 'test',
completedAt: '2026-02-12T10:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['abc', 'abc'],
filesModified: ['src/a.ts', 'src/a.ts', 'src/b.ts'],
},
],
decisions: [],
});
const lineage = new SkillLineage(TEST_DIR);
const data = lineage.build();
const skill = data.skills.find((s) => s.skillName === 'dup-skill');
expect(skill!.commits.length).toBe(1);
expect(skill!.filesModified.length).toBe(2);
});
});
@@ -0,0 +1,332 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { SessionExplainer } from '../session-explainer.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
unlinkSync: vi.fn(),
}));
vi.mock('node:child_process', () => ({
execSync: vi.fn().mockReturnValue(''),
}));
const sessionYaml = `
version: 1
lastActivity: "2026-02-10T14:00:00.000Z"
projectPath: /test/project
currentExecution:
skillName: code-simplifier
skillSource: claude-code
currentStep: 2
totalSteps: 3
status: running
startedAt: "2026-02-10T12:00:00.000Z"
tasks:
- id: task-1
name: Refactor SessionManager
type: auto
status: completed
startedAt: "2026-02-10T12:00:00.000Z"
completedAt: "2026-02-10T12:45:00.000Z"
filesModified:
- src/session/manager.ts
- id: task-2
name: Add snapshot tests
type: auto
status: completed
startedAt: "2026-02-10T12:45:00.000Z"
completedAt: "2026-02-10T13:17:00.000Z"
filesModified:
- src/session/__tests__/snapshot.test.ts
- id: task-3
name: Update documentation
type: auto
status: paused
history:
- skillName: remotion-best-practices
skillSource: local
completedAt: "2026-02-10T11:00:00.000Z"
durationMs: 120000
status: completed
commits:
- sha1
filesModified:
- src/video.ts
decisions:
- key: snapshot-format
value: YAML
madeAt: "2026-02-10T12:30:00.000Z"
- key: storage-location
value: ".skillkit/snapshots/"
madeAt: "2026-02-10T12:35:00.000Z"
`;
const observationsYaml = `
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2026-02-10T12:10:00.000Z"
sessionId: session-1
agent: claude-code
type: error
content:
action: Build failed
context: Type error
relevance: 90
- id: obs-2
timestamp: "2026-02-10T12:15:00.000Z"
sessionId: session-1
agent: claude-code
type: solution
content:
action: Fixed type
context: Added annotation
relevance: 85
- id: obs-3
timestamp: "2026-02-10T12:20:00.000Z"
sessionId: session-1
agent: claude-code
type: pattern
content:
action: Detected pattern
context: Recurring fix
relevance: 70
- id: obs-4
timestamp: "2026-02-10T12:25:00.000Z"
sessionId: session-1
agent: claude-code
type: error
content:
action: Test failed
context: Assertion error
relevance: 80
- id: obs-5
timestamp: "2026-02-10T12:30:00.000Z"
sessionId: session-1
agent: claude-code
type: solution
content:
action: Fixed test
context: Updated assertion
relevance: 75
`;
describe('SessionExplainer', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.useFakeTimers();
vi.setSystemTime(new Date('2026-02-10T14:34:00Z'));
});
afterEach(() => {
vi.useRealTimers();
vi.resetAllMocks();
});
describe('explain', () => {
it('should return a full explanation with active session', () => {
vi.mocked(existsSync).mockImplementation((filepath: any) => {
const path = String(filepath);
if (path.includes('session.yaml')) return true;
if (path.includes('.git')) return false;
return false;
});
vi.mocked(readFileSync).mockImplementation((filepath: any) => {
const path = String(filepath);
if (path.includes('session.yaml')) return sessionYaml;
return '';
});
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
expect(explanation.agent).toBe('claude-code');
expect(explanation.duration).toBeDefined();
expect(explanation.skillsUsed).toHaveLength(2);
expect(explanation.skillsUsed[0].name).toBe('code-simplifier');
expect(explanation.skillsUsed[0].status).toBe('running');
expect(explanation.skillsUsed[1].name).toBe('remotion-best-practices');
expect(explanation.skillsUsed[1].status).toBe('completed');
expect(explanation.tasks).toHaveLength(3);
expect(explanation.tasks[0].name).toBe('Refactor SessionManager');
expect(explanation.tasks[0].duration).toBe('45m');
expect(explanation.tasks[1].name).toBe('Add snapshot tests');
expect(explanation.tasks[1].duration).toBe('32m');
expect(explanation.tasks[2].name).toBe('Update documentation');
expect(explanation.filesModified).toContain('src/session/manager.ts');
expect(explanation.filesModified).toContain('src/video.ts');
expect(explanation.decisions).toHaveLength(2);
expect(explanation.decisions[0].key).toBe('snapshot-format');
expect(explanation.decisions[0].value).toBe('YAML');
});
it('should deduplicate files across current execution and history', () => {
const sessionWithDupes = `
version: 1
lastActivity: "2026-02-10T14:00:00.000Z"
projectPath: /test/project
currentExecution:
skillName: skill-a
skillSource: local
currentStep: 1
totalSteps: 1
status: completed
startedAt: "2026-02-10T12:00:00.000Z"
tasks:
- id: task-1
name: Task A
type: auto
status: completed
filesModified:
- src/shared.ts
- src/a.ts
history:
- skillName: skill-b
skillSource: local
completedAt: "2026-02-10T11:00:00.000Z"
durationMs: 60000
status: completed
commits: []
filesModified:
- src/shared.ts
- src/b.ts
decisions: []
`;
vi.mocked(existsSync).mockImplementation((filepath: any) => {
return String(filepath).includes('session.yaml');
});
vi.mocked(readFileSync).mockReturnValue(sessionWithDupes);
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
expect(explanation.filesModified).toHaveLength(3);
expect(explanation.filesModified).toContain('src/shared.ts');
expect(explanation.filesModified).toContain('src/a.ts');
expect(explanation.filesModified).toContain('src/b.ts');
});
it('should return empty explanation when no session exists', () => {
vi.mocked(existsSync).mockReturnValue(false);
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
expect(explanation.agent).toBe('unknown');
expect(explanation.skillsUsed).toEqual([]);
expect(explanation.tasks).toEqual([]);
expect(explanation.filesModified).toEqual([]);
expect(explanation.decisions).toEqual([]);
expect(explanation.gitCommits).toBe(0);
});
it('should skip git when includeGit is false', () => {
vi.mocked(existsSync).mockReturnValue(false);
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
expect(explanation.gitCommits).toBe(0);
});
it('should default observation counts to zero when store is unavailable', () => {
vi.mocked(existsSync).mockReturnValue(false);
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
expect(explanation.observationCounts).toEqual({
errors: 0,
solutions: 0,
patterns: 0,
total: 0,
});
});
});
describe('formatText', () => {
it('should format explanation as readable text', () => {
vi.mocked(existsSync).mockImplementation((filepath: any) => {
const path = String(filepath);
if (path.includes('session.yaml')) return true;
if (path.includes('observations.yaml')) return true;
return false;
});
vi.mocked(readFileSync).mockImplementation((filepath: any) => {
const path = String(filepath);
if (path.includes('session.yaml')) return sessionYaml;
if (path.includes('observations.yaml')) return observationsYaml;
return '';
});
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
const text = explainer.formatText(explanation);
expect(text).toContain('Session Summary');
expect(text).toContain('Duration:');
expect(text).toContain('Agent:');
expect(text).toContain('Skills Used');
expect(text).toContain('code-simplifier');
expect(text).toContain('Tasks');
expect(text).toContain('Refactor SessionManager');
expect(text).toContain('Files Modified:');
expect(text).toContain('Decisions');
expect(text).toContain('snapshot-format');
expect(text).toContain('Observations:');
});
it('should handle empty explanation', () => {
vi.mocked(existsSync).mockReturnValue(false);
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
const text = explainer.formatText(explanation);
expect(text).toContain('Session Summary');
expect(text).toContain('Agent:');
expect(text).toContain('Files Modified: 0 files');
});
});
describe('formatJson', () => {
it('should format explanation as valid JSON', () => {
vi.mocked(existsSync).mockReturnValue(false);
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
const json = explainer.formatJson(explanation);
const parsed = JSON.parse(json);
expect(parsed.date).toBeDefined();
expect(parsed.agent).toBe('unknown');
expect(parsed.skillsUsed).toEqual([]);
expect(parsed.observationCounts).toBeDefined();
});
it('should output valid JSON for a full explanation', () => {
vi.mocked(existsSync).mockImplementation((filepath: any) => {
const path = String(filepath);
if (path.includes('session.yaml')) return true;
return false;
});
vi.mocked(readFileSync).mockReturnValue(sessionYaml);
const explainer = new SessionExplainer('/test/project');
const explanation = explainer.explain({ includeGit: false });
const json = explainer.formatJson(explanation);
const parsed = JSON.parse(json);
expect(parsed.skillsUsed).toHaveLength(2);
expect(parsed.tasks).toHaveLength(3);
expect(parsed.decisions).toHaveLength(2);
});
});
});
@@ -0,0 +1,376 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import {
existsSync,
readFileSync,
writeFileSync,
mkdirSync,
readdirSync,
unlinkSync,
} from 'node:fs';
import { SnapshotManager } from '../snapshot-manager.js';
import type { SessionState } from '../types.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
readdirSync: vi.fn(),
unlinkSync: vi.fn(),
}));
const mockSessionState: SessionState = {
version: 1,
lastActivity: '2026-02-10T12:00:00.000Z',
projectPath: '/test/project',
history: [
{
skillName: 'code-simplifier',
skillSource: 'local',
completedAt: '2026-02-10T11:00:00.000Z',
durationMs: 60000,
status: 'completed',
commits: ['sha1'],
filesModified: ['src/index.ts'],
},
],
decisions: [
{
key: 'format',
value: 'yaml',
madeAt: '2026-02-10T10:00:00.000Z',
},
],
};
const mockObservations = [
{
id: 'obs-1',
timestamp: '2026-02-10T10:00:00.000Z',
sessionId: 'session-1',
agent: 'claude-code',
type: 'error',
content: { action: 'Build failed', context: 'TS error' },
relevance: 80,
},
];
describe('SnapshotManager', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.useFakeTimers();
vi.setSystemTime(new Date('2026-02-10T12:00:00Z'));
});
afterEach(() => {
vi.useRealTimers();
vi.resetAllMocks();
});
describe('save', () => {
it('should save a snapshot to disk', () => {
vi.mocked(existsSync).mockReturnValue(false);
const manager = new SnapshotManager('/test/project');
manager.save('my-feature', mockSessionState, mockObservations, 'Before refactor');
expect(vi.mocked(mkdirSync)).toHaveBeenCalledWith(
expect.stringContaining('snapshots'),
{ recursive: true }
);
expect(vi.mocked(writeFileSync)).toHaveBeenCalledTimes(1);
const content = vi.mocked(writeFileSync).mock.calls[0][1] as string;
expect(content).toContain('my-feature');
expect(content).toContain('Before refactor');
expect(content).toContain('code-simplifier');
});
it('should save without description', () => {
vi.mocked(existsSync).mockReturnValue(true);
const manager = new SnapshotManager('/test/project');
manager.save('quick-save', mockSessionState, []);
const content = vi.mocked(writeFileSync).mock.calls[0][1] as string;
expect(content).toContain('quick-save');
});
});
describe('restore', () => {
it('should restore a snapshot from disk', () => {
const snapshotYaml = `
version: 1
name: my-feature
createdAt: "2026-02-10T12:00:00.000Z"
description: Before refactor
sessionState:
version: 1
lastActivity: "2026-02-10T12:00:00.000Z"
projectPath: /test/project
history:
- skillName: code-simplifier
skillSource: local
completedAt: "2026-02-10T11:00:00.000Z"
durationMs: 60000
status: completed
commits:
- sha1
filesModified:
- src/index.ts
decisions:
- key: format
value: yaml
madeAt: "2026-02-10T10:00:00.000Z"
observations:
- id: obs-1
timestamp: "2026-02-10T10:00:00.000Z"
sessionId: session-1
agent: claude-code
type: error
content:
action: Build failed
context: TS error
relevance: 80
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(snapshotYaml);
const manager = new SnapshotManager('/test/project');
const result = manager.restore('my-feature');
expect(result.sessionState.version).toBe(1);
expect(result.sessionState.history).toHaveLength(1);
expect(result.sessionState.history[0].skillName).toBe('code-simplifier');
expect(result.observations).toHaveLength(1);
expect(result.observations[0].id).toBe('obs-1');
});
it('should throw if snapshot does not exist', () => {
vi.mocked(existsSync).mockReturnValue(false);
const manager = new SnapshotManager('/test/project');
expect(() => manager.restore('nonexistent')).toThrow(
'Snapshot "nonexistent" not found'
);
});
});
describe('list', () => {
it('should list all snapshots sorted by creation date', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readdirSync).mockReturnValue([
'old-snap.yaml',
'new-snap.yaml',
] as unknown as ReturnType<typeof readdirSync>);
vi.mocked(readFileSync).mockImplementation((filepath: any) => {
if (String(filepath).includes('old-snap')) {
return `
version: 1
name: old-snap
createdAt: "2026-02-09T10:00:00.000Z"
sessionState:
version: 1
lastActivity: "2026-02-09T10:00:00.000Z"
projectPath: /test/project
history: []
decisions: []
observations: []
`;
}
return `
version: 1
name: new-snap
createdAt: "2026-02-10T10:00:00.000Z"
description: Latest snapshot
sessionState:
version: 1
lastActivity: "2026-02-10T10:00:00.000Z"
projectPath: /test/project
history:
- skillName: code-simplifier
skillSource: local
completedAt: "2026-02-10T09:00:00.000Z"
durationMs: 30000
status: completed
commits: []
filesModified: []
decisions: []
observations: []
`;
});
const manager = new SnapshotManager('/test/project');
const snapshots = manager.list();
expect(snapshots).toHaveLength(2);
expect(snapshots[0].name).toBe('new-snap');
expect(snapshots[0].description).toBe('Latest snapshot');
expect(snapshots[0].skillCount).toBe(1);
expect(snapshots[1].name).toBe('old-snap');
expect(snapshots[1].skillCount).toBe(0);
});
it('should return empty array when no snapshots dir exists', () => {
vi.mocked(existsSync).mockReturnValue(false);
const manager = new SnapshotManager('/test/project');
const snapshots = manager.list();
expect(snapshots).toEqual([]);
});
it('should skip corrupted snapshot files', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readdirSync).mockReturnValue([
'good.yaml',
'bad.yaml',
] as unknown as ReturnType<typeof readdirSync>);
vi.mocked(readFileSync).mockImplementation((filepath: any) => {
if (String(filepath).includes('bad')) {
return '{{invalid yaml';
}
return `
version: 1
name: good
createdAt: "2026-02-10T10:00:00.000Z"
sessionState:
version: 1
lastActivity: "2026-02-10T10:00:00.000Z"
projectPath: /test/project
history: []
decisions: []
observations: []
`;
});
const manager = new SnapshotManager('/test/project');
const snapshots = manager.list();
expect(snapshots).toHaveLength(1);
expect(snapshots[0].name).toBe('good');
});
});
describe('get', () => {
it('should return snapshot by name', () => {
const snapshotYaml = `
version: 1
name: test-snap
createdAt: "2026-02-10T12:00:00.000Z"
sessionState:
version: 1
lastActivity: "2026-02-10T12:00:00.000Z"
projectPath: /test/project
history: []
decisions: []
observations: []
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(snapshotYaml);
const manager = new SnapshotManager('/test/project');
const snapshot = manager.get('test-snap');
expect(snapshot).toBeDefined();
expect(snapshot!.name).toBe('test-snap');
});
it('should return undefined for nonexistent snapshot', () => {
vi.mocked(existsSync).mockReturnValue(false);
const manager = new SnapshotManager('/test/project');
const snapshot = manager.get('nonexistent');
expect(snapshot).toBeUndefined();
});
});
describe('delete', () => {
it('should delete a snapshot file', () => {
vi.mocked(existsSync).mockReturnValue(true);
const manager = new SnapshotManager('/test/project');
const result = manager.delete('my-feature');
expect(result).toBe(true);
expect(vi.mocked(unlinkSync)).toHaveBeenCalledWith(
expect.stringContaining('my-feature.yaml')
);
});
it('should return false for nonexistent snapshot', () => {
vi.mocked(existsSync).mockReturnValue(false);
const manager = new SnapshotManager('/test/project');
const result = manager.delete('nonexistent');
expect(result).toBe(false);
expect(vi.mocked(unlinkSync)).not.toHaveBeenCalled();
});
});
describe('exists', () => {
it('should return true when snapshot file exists', () => {
vi.mocked(existsSync).mockReturnValue(true);
const manager = new SnapshotManager('/test/project');
expect(manager.exists('my-feature')).toBe(true);
});
it('should return false when snapshot file does not exist', () => {
vi.mocked(existsSync).mockReturnValue(false);
const manager = new SnapshotManager('/test/project');
expect(manager.exists('nonexistent')).toBe(false);
});
});
describe('path traversal protection', () => {
it('should reject names with path separators', () => {
const manager = new SnapshotManager('/test/project');
expect(() => manager.exists('../../etc/passwd')).toThrow('Invalid snapshot name');
expect(() => manager.exists('../config')).toThrow('Invalid snapshot name');
});
it('should reject names with special characters', () => {
const manager = new SnapshotManager('/test/project');
expect(() => manager.exists('snap shot')).toThrow('Invalid snapshot name');
expect(() => manager.exists('snap.shot')).toThrow('Invalid snapshot name');
});
it('should allow valid names with hyphens and underscores', () => {
vi.mocked(existsSync).mockReturnValue(false);
const manager = new SnapshotManager('/test/project');
expect(() => manager.exists('my-feature_v2')).not.toThrow();
});
});
describe('restore validation', () => {
it('should throw on corrupted YAML', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue('{{invalid yaml');
const manager = new SnapshotManager('/test/project');
expect(() => manager.restore('corrupted')).toThrow('Failed to read snapshot');
});
it('should throw on missing sessionState', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(`
version: 1
name: broken
createdAt: "2026-02-10T12:00:00.000Z"
observations: []
`);
const manager = new SnapshotManager('/test/project');
expect(() => manager.restore('broken')).toThrow('corrupted or invalid');
});
});
});

Some files were not shown because too many files have changed in this diff Show More