Commit Graph
135 Commits
Author SHA1 Message Date
Willie 2c3003e04f feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
Restructure the entire documentation site following the Diátaxis framework
(Learn / How-to / Understand / Reference) with new content across 110 files.

## Information Architecture (M1)
- Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/)
- Add client-redirects plugin for old URL compatibility
- Rewrite sidebar, navbar, and footer to match new IA
- Update all internal cross-references

## Homepage + Quickstarts (M2)
- Add scenario entry cards to homepage with hand-drawn design
- 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation),
  Codex, Multiple Tools, Dev Containers, Playground

## Blog + Changelog (M3)
- Enable Docusaurus blog plugin with authors.yml
- 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills
  comparison, team sharing patterns, write your first skill
- Static /changelog page from CHANGELOG.md

## Recipes + Philosophy (M4)
- 5 recipe pages: CI/CD validation, enterprise skills, project setup,
  cross-machine sync, team onboarding
- 3 philosophy pages: why-local-first, security-first, sync-modes-explained

## Content Polish
- Cross-validate all content against CLI source (19 inaccuracies fixed)
- Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.)
- Add registry.yaml to file structure and Key Paths docs
- Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea,
  Azure DevOps, AtomGit, Codeberg)
- Standardize brew install command
- Add AsciinemaPlayer component (cast recordings pending)
2026-02-26 04:52:29 +08:00
Willie efa3a34599 feat(update): add --prune for stale skills, stale detection in check, refactor update handlers
- update --prune: detect skills deleted upstream and move them to trash
  (batch + single-target paths), clean registry entries after prune
- update without --prune: warn about stale skills with suggestion
- check: report "stale" status for skills whose subdir no longer exists
  in the remote repo (previously misreported as update_available)
- Refactor updateTrackedRepo, updateRegularSkill, updateTrackedRepoQuick,
  updateSkillFromMeta to accept *updateContext instead of 7-10 individual
  params; delete dead updateSkillOrRepo function
- Add integration tests for prune (standalone, nested, all-stale,
  registry cleanup) and project-mode prune
- Update website docs for update --prune and check stale status
2026-02-26 01:07:15 +08:00
Willie 071aa70857 docs: add missing flags to update and uninstall options tables
update.md: add --audit-verbose, --project/-p, --global/-g
uninstall.md: add --project/-p, --global/-g

Both sets of flags exist in source (printUpdateHelp, printUninstallHelp)
but were missing from the docs options tables.
2026-02-25 07:02:54 +08:00
Willie cfa6d4017b fix(docs,test): add replit badge and project-mode integration tests
Add missing replit badge + id anchor in supported-targets.md.
Add project-mode integration tests for audit, check, diff, and log
commands to close gaps found in codebase audit.
2026-02-25 07:02:54 +08:00
Willie c81e7d7459 docs(backup): fix cleanup size cap from 100 MB to 500 MB
The actual default in internal/backup/cleanup.go is MaxSizeMB: 500.
2026-02-25 07:02:54 +08:00
Willie 6958cfc575 docs(faq): add Q&A for "unknown target" warning
Explains the common `unknown target "*"` warning from `check`/`doctor`,
why wildcard syntax is unsupported, and the correct way to target all CLIs.
2026-02-25 07:02:54 +08:00
Willie 173803e8cb chore(targets): remove deprecated openclaude target
OpenClaude has been superseded by OpenClaw. Upstream (vercel-labs/skills)
already removed it. Remove from targets.yaml and supported-targets docs.
2026-02-25 07:02:54 +08:00
Willie 76ef4ff07e feat(log): add interactive TUI with fuzzy filter and detail panel
On TTY, `skillshare log` now launches a bubbletea TUI (same pattern as
`list`) with fuzzy filtering by timestamp/command/status/source/detail,
keyboard navigation, and a colorized detail panel showing structured
args per entry. Operations and audit entries are merged and sorted by
time in the combined view.

Also refactors the 979-line log.go into three focused files:
- log.go (303) — entry, dispatch, help
- log_format.go (495) — data→string conversion, logArg* helpers
- log_render.go (189) — TTY/non-TTY terminal output

Other changes:
- --no-tui flag to skip TUI and print plain text
- Shared applyTUIFilterStyle() for cyan filter cursor in both TUIs
- Update website docs and built-in skill references
2026-02-25 07:02:54 +08:00
Willie 1fb5219cd2 feat(list): add interactive TUI with search, filter, sort, and detail panel
Replace basic text output with bubbletea-based interactive TUI for the
list command. Falls back to plain text with --no-tui or non-TTY output.

- Bubbletea TUI: fuzzy filtering, keyboard navigation, detail panel
- Detail panel: description (SKILL.md), disk path, files, synced targets
- Search: `skillshare list <pattern>` filters by name/path/source
- Filter: `--type git|local` to filter by installation type
- Sort: `--sort name|date|type` with mode-specific defaults
- JSON: `--json` for CI/scripting consumption
- Pager: less/more wrapper for --no-tui plain text output
- 29 integration tests covering all new functionality
2026-02-25 07:02:54 +08:00
Willie bd4200c076 docs: update output examples to match new compact audit UI
- update.md: replace HeaderBox example with lightweight header, change
  "Aggregate risk" to "risk:" format
- install.md: add --audit-verbose flag to Options table, update risk
  score description
- uninstall.md: remove batch size labels (SectionLabel now unconditional)
- README.md: "aggregate risk" → "risk score" wording
2026-02-24 01:47:38 +08:00
Willie 93aa257292 feat(uninstall): add --all flag to remove all skills from source
Support bulk uninstall via 'skillshare uninstall --all' in both global
and project modes. Uses glob-based discovery to find all skills and
tracked repos, with --dry-run preview and --force to skip confirmation.

- Parse --all with mutual exclusion vs skill names and --group
- Global: discover skills + tracked repos from source directory
- Project: discover from .skillshare/skills/ directory
- Prune orphan symlinks from targets after removal
- Integration tests for --all, --all --dry-run, and conflict errors
- Update uninstall docs with --all examples
- Add AI runbook for uninstall --all glob testing
2026-02-24 01:47:38 +08:00
Willie 3721d69b54 fix: prune orphaned real directories in merge mode via manifest (#45)
- Extend .skillshare-manifest.json tracking from copy mode to merge mode.
- Update PruneOrphanLinks to prioritize manifest records over naming patterns.
- Ensure SyncTargetMerge writes to manifest for all linked/updated skills.
- Add integration tests for uninstall + sync orphan directory cleanup.
- Maintain backward compatibility for targets without existing manifests.
2026-02-24 01:47:38 +08:00
Willie 0694fbdc9c docs(guides): add skill design guide with determinism and CLI wrapper patterns
New guide covering 5 principles for writing reliable skills:
determinism first, CLI wrapper pattern, progressive disclosure,
risk-matched complexity, and interface-first design. Draws from
Peter Steinberger's CLI-first practices and Pahud Hsieh's
"SKILL + single binary CLI" paradigm.
2026-02-24 01:47:38 +08:00
Willie 06c14b6a9d feat(init): add --mode flag and per-target compatibility hints
Closes #42

Some AI CLIs (Cursor, Antigravity, Copilot, OpenCode) skip symlinks
when scanning skill directories, causing symlinked skills to be
silently ignored during auto-discovery.

Changes:
- `init --mode <merge|copy|symlink>` / `-m`: set default sync mode at
  init time (global and project); interactive prompt when TTY detected
- `init --discover --mode`: applies mode only to newly added targets,
  leaving existing targets unchanged
- Per-target mode hint after `sync` and `doctor`: suggests `copy` for
  known compatibility-sensitive targets (cursor → antigravity →
  copilot → opencode); suppressed when only claude/codex configured
- Neutral decision matrix in sync-modes.md for constraint-based choice
- By-target override examples in target.md, sync.md, first-sync.md
- Integration tests for mode flag, discover+mode, hint presence/absence
2026-02-24 01:47:38 +08:00
Willie cd5902c590 feat: unify update audit threshold gate and docs 2026-02-23 04:18:01 +08:00
Willie 3ad814d3ba fix: add audit gate to install --track and tracked repo updates
InstallTrackedRepo and updateTrackedRepo had no security audit,
allowing --track to bypass all supply-chain checks. This adds
auditTrackedRepo (removes repo on block for fresh installs) and
auditTrackedRepoUpdate (git reset rollback for updates), plus
input validation, testable removeAll, and hardened error handling
across audit/install/uninstall paths.
2026-02-23 04:18:01 +08:00
Willie a35110037c docs: update docs to reflect --diff for regular skills and audit risk score
--diff works for both tracked repos (git diff) and regular skills (hash
comparison) but docs only mentioned tracked repos. Also document the
audit risk score display in CLI/Web UI after updates, and add missing
flags (--diff, --skip-audit, --group) to built-in skill reference.
2026-02-23 04:18:01 +08:00
Willie 684b0da971 docs: add v0.15.4 changelog, update SKILL.md, README, and UI for supply-chain security
- Add v0.15.4 CHANGELOG entry (audit gate, content hash pinning, --diff,
  source-repository-link rule, severity-based risk floor, bug fixes)
- Bump SKILL.md version to v0.15.4 with supply-chain security keywords
- Update README Recent Updates table to reference v0.15.4
- Fix security.md rule count 25→31 to match audit.md
- DashboardPage: include blocked count in update summary toast
- SkillDetailPage: show ConfirmDialog on blocked update with
  "Skip Audit & Update" retry option
2026-02-23 04:18:01 +08:00
Willie ae6620e484 docs: add supply-chain security lifecycle flowchart to security guide
Mermaid flowchart showing 3 phases: Install gate (audit + hash pinning),
Update gate (post-pull audit + auto-rollback), Integrity verification
(SHA-256 hash comparison). Color-coded nodes for pass/block/warning states.
2026-02-23 04:18:01 +08:00
Willie 5ce6507799 fix: server rollback error reporting and isSecurityError classification
- handler_update.go: check git.ResetHard return value; if rollback
  fails, append explicit warning to blocked message instead of
  silently claiming rolled back
- update.go: add "post-update audit" to isSecurityError keywords
  so install.Install audit failures are correctly classified as
  security blocks in batch exit code
2026-02-23 04:18:01 +08:00
Willie b216e3539e docs: update audit and update command docs for supply-chain security features
- update.md: add --skip-audit and --diff flags, security audit gate
  section, file change summary section, batch exit code behavior
- audit.md: add source-repository-link rule, content integrity checks,
  severity-based risk floor, update-time scanning, built-in rule table
2026-02-23 04:18:01 +08:00
Willie a248e758ab docs: update pull.md for merge-by-default and add v0.15.3 changelog
- pull.md: reflect new merge behavior when both sides have skills
- CHANGELOG: add v0.15.3 entries (multi-name audit, external-link
  rule, hub auth tokens, parallel scan, pull merge-by-default)
2026-02-22 15:13:10 +08:00
Willie 8778adddcc feat: add external-link-0 audit rule to detect external URLs in markdown links
Detect `[text](https://...)` patterns in skill files as a LOW severity
finding. External links may indicate prompt injection vectors or waste
tokens. Localhost/127.0.0.1/0.0.0.0 links are excluded via the rule's
exclude regex.

Closes #38
2026-02-22 15:13:10 +08:00
Willie 8a4f61ffec docs: clarify dangling-link is a structural check, not in rules.yaml
The built-in rule IDs table listed dangling-link alongside regex-based
rules with a "source of truth" link to rules.yaml, but dangling-link
uses filesystem lookups (os.Stat) and is not defined there. Add a note
explaining the distinction to avoid confusion.
2026-02-22 15:13:10 +08:00
Willie 0d3799d770 feat: add multi-name and --group support for audit command
Allow `skillshare audit a b c` and `--group`/`-G` flags to filter
which skills are scanned, matching the existing check/update pattern.
Single-name audit preserves detailed output; multi-target uses batch
format with parallel scanning.
2026-02-22 15:13:10 +08:00
Willie 506b60a1ee fix init remote flow and clarify interactive setup docs 2026-02-22 08:08:35 +08:00
Willie d1d528f192 feat: add --audit flag to hub index for security risk enrichment
Enrich hub index with per-skill audit scores so teammates can assess
skill safety before installing. Uses existing audit.ScanSkill() engine
(25 rules, 0-100 risk score) without modifying the audit package.

- SkillEntry gains riskScore (*int), riskLabel, auditedAt (omitempty)
- BuildIndex accepts variadic auditSkills param (backward compatible)
- search index deserializes and displays risk badges in hub results
- Schema stays v1; fields omitted when --audit not used
2026-02-22 08:08:35 +08:00
Willie a8f04320ea docs: add required token scopes per platform for auth errors
- environment-variables.md: add token creation steps and required scopes
  for GitLab (read_repository + write_repository) and Bitbucket
  (repository access token vs app password)
- common-errors.md: add token permissions quick-reference table
- CLI auth hint: append docs URL for detailed scope info
2026-02-22 08:08:35 +08:00
Willie 83d13f6e10 feat: add platform-specific token setup hints for auth errors
- CLI auth hint now shows PowerShell syntax on Windows, export on Unix
- Docs: add Windows PowerShell examples for GITLAB_TOKEN, BITBUCKET_TOKEN,
  SKILLSHARE_GIT_TOKEN in environment-variables.md
- Docs: rewrite auth error section in common-errors.md with token env var
  options, Windows syntax, and GitLab token type warning
2026-02-22 08:08:35 +08:00
Willie cea26ea7fb feat: add dangling local markdown link detection to audit
Scan .md files in skill directories for broken relative links during
audit. Targets that don't exist on disk produce a LOW severity finding
(pattern: dangling-link). External URLs, anchors, and fragments are
skipped.

Integrated into the existing walk (zero extra IO) and disableable via
audit-rules.yaml (- id: dangling-link / enabled: false). The init-rules
template, built-in skill reference, and website docs are updated.
2026-02-21 21:12:51 +08:00
Willie 8e58cc7383 docs: add missing flags to diff and restore command pages
diff.md: add Options table (--target/-t, --project/-p, --global/-g)
restore.md: document -f shorthand for --from
2026-02-21 21:12:51 +08:00
Willie 6d5c95a19a docs: align cross-machine-sync guide with new push/pull behavior
Update pseudo-code and error messages to match actual CLI output
after the push/pull/init overhaul.
2026-02-21 21:12:51 +08:00
Willie 89055804ff fix: harden pull/push first-sync flow and add regression coverage 2026-02-21 21:12:51 +08:00
Willie 2b6386463f docs(faq): add per-skill target routing FAQ entry
Address common user question about syncing specific skills to specific
CLIs. Covers both SKILL.md targets field and config include/exclude
filters. Ref: discussions#34
2026-02-21 10:27:13 +08:00
Willie 2bb7312e9d test(install): add auth integration tests and fix docs gaps
Add offline tests verifying token env vars don't interfere with file://
clones and git pull updates. Add online tests for HTTPS public/private
repo auth, error message format, and token redaction in output.

Also fix install.md: add --global/-g to Options table, add --exclude
to no-arg restriction note. Update CHANGELOG for v0.15.0.
2026-02-21 06:07:35 +08:00
Willie 084d93bf94 feat(devcontainer): add credential-helper toggle and token forwarding
Add tooling for testing private repo auth inside the devcontainer:

- credential-helper script (on/off/status) with --eval mode to
  toggle both git credential helper and token env vars in one command
- remoteEnv forwards host token env vars (GITHUB_TOKEN, GITLAB_TOKEN,
  BITBUCKET_TOKEN, BITBUCKET_USERNAME, SKILLSHARE_GIT_TOKEN)
- docker-compose env_file for .devcontainer/.env (optional, gitignored)
- start-dev.sh auto-detects GITHUB_TOKEN from gh CLI on container start
- .env.example template for all supported tokens
- docker-sandbox.md documents token sources and private repo testing
2026-02-21 06:07:35 +08:00
Willie a972a0c943 feat(install): add HTTPS token auth for private repos
Automatically detect GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN, or
SKILLSHARE_GIT_TOKEN and inject credentials via transient GIT_CONFIG_*
env vars during clone and pull. Tokens are never persisted to disk.

Key changes:
- Platform detection (GitHub/GitLab/Bitbucket) with per-platform
  username conventions (x-access-token, oauth2, x-token-auth)
- GIT_CONFIG_COUNT safe append — reads existing count to avoid
  overriding CI pipeline git config entries
- Token-aware error messages: "no token" shows 3 options (SSH, env
  var, credential helper); "token rejected" suggests checking
  permissions and expiry
- sanitizeTokens redacts all credential values (including
  BITBUCKET_USERNAME) from stderr before surfacing errors
- gitPull also injects auth via getRemoteURL(), fixing the previous
  limitation where update failed after HTTPS+token install
2026-02-21 06:07:35 +08:00
Willie f5893a845c docs(sync): reframe copy mode as a first-class choice, not a workaround
Cursor 2.5 fixed symlink discovery, so copy mode no longer needs to be
positioned as a bug workaround. Add "Why copy mode?" section highlighting
three standalone motivations: defensive design (cross-platform symlink
variance), sandboxed environments (CI/containers), and user preference
(transparency/portability).
2026-02-21 06:07:35 +08:00
Willie 89060c0190 docs(sync): fix copy mode schema and document --force flag
- Add "copy" to project-config.schema.json mode enum
- Update include/exclude descriptions from "merge mode only" to
  "merge and copy modes" in both schemas
- Add --force/-f flag documentation to sync command page
- Add copy mode row to project-skills.md Mode Restrictions table
- Expand copy mode use cases: vendoring, CI pipelines, air-gapped
2026-02-21 06:07:35 +08:00
Willie 14257b1925 docs(skillshare): clarify copy-mode sync and doctor duplicate rules 2026-02-21 06:07:35 +08:00
Willie 3b721ee3e2 feat(sync): add copy mode for AI CLIs that can't follow symlinks
Add a third sync mode (`copy`) that copies skills as real files instead
of symlinks, with a `.skillshare-manifest.json` tracking managed skills
and SHA256 checksums for incremental updates.

- Manifest-based tracking: skip unchanged, update modified, --force all
- Pruning: remove managed copies no longer in source
- Mode conversion: bidirectional merge↔copy and symlink↔copy
- Full command support: sync, status, doctor, diff, target, collect
- Server API + Web UI: targets list, drift detection, filter editing
- include/exclude filters work in both merge and copy modes
- 12 integration tests covering all acceptance criteria
- Documentation updated across 13 pages

Closes #31
2026-02-21 06:07:35 +08:00
Willie 864a7056e2 docs: add centralized vs local-first architecture comparison
Help users understand the trade-offs between centralized skill
registries and skillshare's local-first approach, including the
hub system for decentralized discovery and self-hosted metrics.
2026-02-20 23:04:29 +08:00
Willie 7f742278f0 refactor(build): simplify Make/mise targets from 34 to 21
Sandbox (8→2): consolidate into `make playground` + `playground-down`,
add scripts/sandbox.sh wrapper for advanced ops (up/down/shell/reset/
status/logs/bare).

Test (7→5): remove test-cover and test-install from Make (still
available via scripts directly).

Dev Docker (3→2): merge dev-docker-up and dev-docker-watch into
`make dev-docker` (defaults to Compose Watch for auto-rebuild),
keep dev-docker-down.

Update all docs references: README, CLAUDE.md, quick-reference,
docker-sandbox guide, ui command page.
2026-02-20 22:13:33 +08:00
Willie 595fe84c6b refactor(devcontainer): simplify dev server management
Replace dev-servers with self-contained `ui` and `docs` commands:
- `ui` / `ui -p`: build binary, start API (global/project) + Vite
- `ui stop`: stop API + Vite
- `docs` / `docs stop`: start/stop Docusaurus
- Remove `ui-p` script (merged into `ui -p`)
- Fix PID reuse false-positive in is_running() via /proc/cmdline
- Fix process tree cleanup in do_stop() (kill children before parent)
- Fix pkill pattern to match `skillshare-dev` binary name
- Update devcontainer.json port labels and ordering
- Update docker-sandbox.md to reflect new commands
2026-02-20 22:13:33 +08:00
Willie aef35a9b40 feat(check): support multiple names and --group/-G flag
Allow `check` to target specific skills/repos instead of always scanning
everything. Adds parseCheckArgs, runCheckFiltered with spinner, and
positional group auto-detection — reusing resolve logic from update.

No args = check all (existing behavior preserved).
2026-02-20 13:28:13 +08:00
Willie a202557192 feat(update): support multiple names and --group/-G flag
Allow `update` to accept multiple positional names and a repeatable
`--group/-G` flag, matching the UX already available in `uninstall`.

- Add `updateOptions` struct and `parseUpdateArgs` (mirrors `parseUninstallArgs`)
- Add `resolveGroupUpdatable` to walk a group dir for updatable items only
  (tracked repos or skills with metadata; local skills silently skipped)
- Add `isGroupDir` to auto-detect positional args that are group directories
  (checked before basename resolution so "feature-radar" expands the group
  rather than matching the nested "feature-radar/feature-radar" by basename)
- Refactor `cmdUpdate` (global) and `cmdUpdateProject` (project) to use the
  shared parser and support batch updates
- `--all` is mutually exclusive with names/groups
- Project mode preserves default `--all` when no args given
- 10 new integration tests (8 global + 2 project)
- Update docs with multi-name, --group examples and options table
2026-02-20 13:10:46 +08:00
Willie 1b5056d0ea refactor(docker): unify versions, consolidate init scripts, add sandbox-logs
- Add `make sandbox-logs` / `mise run sandbox:logs` convenience target
- Unify Docker build versions via ARG: Node 24, pnpm 10.28.0, Go 1.25.5
- Extract shared demo content to scripts/create-demo-content.sh, slim down
  setup.sh and sandbox_playground_up.sh from ~150 duplicated lines each
- Move devcontainer scripts (ui, ui-p, docs) to .devcontainer/bin/
  (source-controlled, survives make clean) with auto mode-switching
2026-02-20 12:22:02 +08:00
Willie 626f0f2240 feat(devcontainer): add Node.js 24, auto-start dev servers, and dev-servers manager
Enable full frontend development inside the devcontainer without
falling back to the host. Three dev servers (Go API :19420, Vite :5173,
Docusaurus :3000) start automatically via postStartCommand and can be
managed with the `dev-servers` CLI (start/stop/restart/status/logs).

Key changes:
- Add Node.js 24 + pnpm devcontainer feature
- Auto-install ui/ and website/ dependencies in setup.sh
- Add dev-servers.sh process manager with PID tracking
- Replace shell aliases with PATH scripts (ss, skillshare-ui, etc.)
- Set Vite server.host: true for container accessibility
- Make ui-dev Go server host configurable via SKILLSHARE_UI_HOST env var
- Forward ports 5173 and 3000 alongside 19420
- Harden setup.sh with environment guard and safe_cleanup helpers
- Update docker-sandbox.md with frontend development section
2026-02-20 04:12:34 +08:00
Willie 941a64867e docs: reposition hub as organization-first with private source examples
Hub docs previously used public github.com URLs in examples, making it
unclear why users would choose hub over GitHub Search. Reframe hub as
the go-to solution for organization-wide skill distribution with private
sources (GHE, internal GitLab, VPN-only servers).

- Rename "Community Hub" to "Public Hub" (dual role: default catalog + fork template)
- Add "Organization Deployment" end-to-end workflow with GHE URLs
- Add admonition explaining why hub exists vs GitHub Search
- Update hand-written index examples with internal URLs
2026-02-20 01:31:29 +08:00
Willie 82fc7e8a99 docs: add security guide with cross-references
New guide at docs/guides/security.md covering threat model,
defense-in-depth layers, security checklist, organizational policy,
and real-world CI/CD example from skillshare-hub.

Cross-linked from sidebar (Advanced), guides index, audit command
See Also, best-practices Security section, and README.
2026-02-20 01:02:00 +08:00