Commit Graph
41 Commits
Author SHA1 Message Date
Willie f52ae74c5f feat(audit): remember findings accepted via --force across updates
Overriding the audit gate with --force was per-invocation, so skills that
legitimately quote attack strings (security scanners, red-team docs) had to
be forced on every `update --all`. The only alternative, disabling the rule,
was global and turned it off for every skill.

Record the accepted findings (rule + file + matched text, no line number) in
.metadata.json under `audit_accepted`, keyed by skill relPath so it survives
entry rewrites and works for tracked repos. Later updates mark matching
findings as acknowledged and exclude them from the block decision; any new
finding, or the same rule matching different text, still blocks.

Staged installs audit a temp directory, so InstallOptions gains an
AuditAcceptRoot/AuditAcceptPath override pointing at the final destination.

Refs #279
2026-09-17 10:24:18 +08:00
Rusty ShacklefordandWillie 60e19f96d5 feat(project): support a visible skillshare/ project directory (#256) (#258)
* fix(project): refuse to re-init a project that lost its config.yaml

Every project-mode command auto-initializes when .skillshare/config.yaml
is missing. That is right for a repository with no project directory at
all, and for the shared skills repo produced by 'init -p --config local',
which gitignores config.yaml so each developer regenerates their own.

It was wrong for the case in between. A .skillshare/ that already held
skills or agents, whose config.yaml was simply gone, was re-initialized
into an empty config. Every configured target was dropped, the target
symlinks were left behind pointing at a project the config no longer
described, and the command exited 0. Nothing said anything had happened.

Add ensureProjectConfig, which replaces the open-coded auto-init at every
project command entry point. It initializes as before when there is no
project directory, and when config.yaml is gitignored, so both intentional
cases keep working untouched. When the directory holds skills or agents
and its config is neither present nor gitignored, it now returns an error
pointing at version control or an explicit 'skillshare init -p' instead of
writing over the project.

The gitignore check is treated as inconclusive on error, so a repository
that cannot be inspected is guarded rather than overwritten.

* feat(project): support a visible skillshare/ project directory

Project mode is identified only by .skillshare/config.yaml, and trash,
backups, logs and audit-rules.yaml anchor to that same hidden directory.
The sources option (#153) made project content relocatable, but the
marker and operational state stay hidden, so repositories that treat
skills as reviewable content still carry a hidden directory whose only
job is to hold config.yaml.

Resolve the project directory through a new leaf package that checks
.skillshare/config.yaml first and skillshare/config.yaml second, and
derive every config, state, source-default and gitignore path from the
result. The hidden name wins whenever both exist, so an existing project
never moves and no migration is needed. The package imports nothing else
internal because internal/audit cannot import internal/config without a
cycle.

Add init -p --visible to create the visible layout. Default init -p
behaviour and output are unchanged.

Two ambiguities the visible name introduces:

- The global config directory is also called skillshare
  (<config-home>/skillshare), so the two places that infer scope from a
  config path now exclude the global location by full path rather than
  by directory name. TestLogDir_Global asserted a fixture path without
  declaring a config home, which hid this; it now sets XDG_CONFIG_HOME.
- An unrelated directory named skillshare/ must not be adopted as a
  partially initialized project, so the visible name is only claimed
  when it carries a marker of its own: a skills/ or agents/ directory,
  or a .gitignore that ignores config.yaml.

The missing-config guard added in the previous commit is generalized to
resolve through the new package, so it covers both layouts. The
gitignored-config marker matters there too. A repository shared by
'init -p --visible --config local' before any skill was committed clones
with nothing but that .gitignore, because git drops the empty skills/
and agents/ directories; recognizing it keeps the repair pointed at the
visible directory instead of writing a hidden one beside it.

Refs #256

* fix(project): reconcile visible directory support with main

Consolidate the missing-config guard and regression tests already merged in #260. Preserve both directory layouts and document and test resyncing target links after a rename. Follow-up for #258.

---------

Co-authored-by: Willie <egg358358@gmail.com>
2026-09-05 12:07:00 +08:00
Willie e780fbf1ab fix(sync): honour agent frontmatter targets when syncing agents
The agent discovery already parsed the `targets` frontmatter list into
DiscoveredResource.Targets, but no agent sync path ever applied it, so an
agent declared for one tool was still delivered to every agent-capable
target. Agents have no shared schema across harnesses, so this gives authors
a way to keep a per-tool variant of the same agent without cross-polluting
targets. Applied in CLI sync (global and project), the dashboard sync
handler, doctor's expected count and the target summary so all views agree.

Refs #267
2026-09-02 13:36:30 +08:00
Willie 9143b467e0 fix(targets): split gemini out of antigravity and correct global path
Antigravity and Gemini CLI read different global skill directories, so
folding gemini into antigravity as an alias made one of them wrong for
every user. Antigravity loads ~/.gemini/config/skills; Gemini CLI loads
~/.gemini/skills. Restore gemini as its own target so both resolve
correctly.

Also document that Antigravity's skill scanner skips symlinks entirely
(surfacing as "Incorrect function" on Windows, silent absence elsewhere)
along with the two available workarounds.

Closes #255
2026-08-02 22:38:56 +08:00
Willie 060886c281 chore: release v0.20.12 2026-06-11 01:18:10 +08:00
Willie 10d94a3542 fix: suggest install for missing tracked repos 2026-06-10 15:54:23 +08:00
Willie 6c29934a4f feat: add agents path to copilot target
Copilot CLI uses the same .agent.md format Skillshare already syncs to
Claude and OpenCode, so no transformation is needed — only a missing
registry path. Add global (~/.copilot/agents) and project (.github/agents)
agent paths per GitHub's documented custom-agent locations.

Closes #184
2026-06-01 15:08:22 +08:00
Willie caf22760b3 docs: global config sources map (Phase 7)
- CHANGELOG.md + website changelog: Unreleased entry for v0.19.16
  covering the global `sources:` map feature plus the two behavior
  changes (extras init no longer silently backfills extras_source;
  extras source command writes to whichever field the user already
  configured).
- website/docs/understand/source-and-targets.md: add "Custom Source
  Directories" section for global mode mirroring the project-mode
  writeup, with examples, backward-compat notes, and a cross-link to
  the project-skills page.
2026-05-21 15:13:36 +08:00
Willie b1907cd611 docs: document custom project source directories
- Add 'Custom Source Directories' section to project-skills.md covering
  the sources map, common layouts, and constraints (no target alias,
  external paths skip gitignore, .skillshare/ for ops dirs, init seeds
  default paths).
- Add troubleshooting entries for the two new error classes: malformed
  project config (fail-closed) and source/target path overlap.
2026-05-20 18:39:16 +08:00
Willie 3b9cb44be6 chore: release v0.19.14 2026-05-20 14:07:51 +08:00
Willie 9307fc521c chore: release v0.19.12 2026-05-14 23:43:43 +08:00
Willie fb821b7328 fix(project): add backups/ to .skillshare/.gitignore managed dirs
Project mode agent backup (sync --agents, backup -p) creates
.skillshare/backups/ but it was not gitignored — backup artifacts
could be accidentally committed.

Agent backup was added in 95c46ca8 (2026-04-06), after the gitignore
fix in 90c096b8 (2026-03-16) which only covered logs/ and trash/.
2026-05-13 03:49:40 +08:00
Willie 57b0649d20 feat(targets): add 8 new agent targets and update cursor project path
Add AiderDesk, CodeArts Agent (Huawei), Code Studio (Syncfusion),
Devin for Terminal (Cognition), Dexto, ForgeCode, Rovo Dev (Atlassian),
and Tabnine CLI as built-in targets (56 → 64).

Update Cursor's project-level skill path from .cursor/skills to
.agents/skills to match Cursor's official documentation, which now
lists both paths as supported with .agents/skills as the ecosystem
standard convention. Global path (~/.cursor/skills) and agents paths
are unchanged.

All paths verified against official documentation or source code.
Codemaker excluded — no official docs confirm SKILL.md support.
2026-05-05 11:55:26 +08:00
Willie 806045d392 docs(agents): expand docs + skillshare SKILL.md for agent workflows
- skills/skillshare/SKILL.md: mention agents commands/flags in description
- website: document agents source dir, agent backup/restore, ignores,
  file structure, config fields, and project-mode agent rules
2026-04-11 00:41:29 +08:00
Willie 788f9bc6e9 feat(agents): JSON output + audit gate for install/update
Extend install/update with agent-aware --json output and apply the same
audit block-threshold gate skills already use.

Install:
- install --json: imply --force; imply --all only when neither
  --skill nor --agent is set (so explicit selectors still work)
- project-mode install now routes through cmdInstallProjectParsed
  so --json suppresses UI and emits a pure-JSON payload
- agent installs propagate SourceDir so metadata lands in the
  agents root, not the install subdir
- validation error lists --agent / --kind / --branch explicitly

Update agents:
- update agents supports --force, --skip-audit, --audit-threshold
- tracked agent repos + metadata-backed single-file agents now run
  the same audit gate as skills; blocks roll back from a temp stage
- JSON output returns the final per-agent status
  (updated/skipped/failed/up_to_date/...) by merging check results
  with batch update outcomes

Audit:
- auditInstalledAgent shares one helper with auditInstalledSkill
  (scan + cleanup callbacks); single-file agent scans now use
  audit.ScanFile / ScanFileForProject instead of staging the file
  into a temp directory
- UpdateAgentFromDiscovery stages to temp, audits, then renames
  atomically (rename already overwrites on POSIX)

Refactors pulled in while reworking these paths:
- extract jsonUISuppressor helper in json_output.go and use it
  from install/update/update_agents; collapses 4 copies of the
  suppress/restore closure dance and the per-error failJSON block
- drop relPath plumbing from installAgentFromDiscoveryInternal
  now that ScanFile doesn't need a staged relative path
- list.go render functions now use theme.ANSI() so NO_COLOR is
  respected in plain-text output

Tests:
- add TestInstallAgentFromDiscovery_HighFindingBlocked (unit)
- add TestUpdate_Agents_HighFindingBlockedByThreshold (integration)
- add TestInstall_Project_JSON_Agent_PureJSON,
  TestUpdate_Agents_JSON_ReportsFinalStatus
- fix TestList_SKILLSHARE_THEME_Light / TestList_NO_COLOR to
  write a config before invoking list
- fix TestTargetList_NoTUI_FallsBackToPlainText assertion to match
  the new structured Mode: merge output
- fix TestDoctor_AllGood_PassesAll by pinning SKILLSHARE_THEME=dark
  so the no-TTY theme fallback warning doesn't fire
- add list_tui_content_test.go covering light/dark glamour base
- list detail pane now picks LightStyleConfig on light terminals

Docs:
- update install.md, update.md, understand/agents.md for the new
  flags, JSON shapes, and agents update workflow
2026-04-10 23:27:26 +08:00
Willie 22e7028747 docs: update target/filtering docs for agent filters and metadata.targets
- Add --agent-mode, --add-agent-include/exclude flags to target command docs
- Update filtering reference with agent filter examples and storage paths
- Prefer metadata.targets over top-level targets in all examples
- Note agent filter limitations (merge/copy only, requires agents path)
- Update skill-format docs with metadata.targets precedence note
- Update built-in skill references/targets.md with agent filter examples
2026-04-09 03:14:58 +08:00
Willie 081348d39b refactor(collect): unify skills/agents flow with collectPlan + generics
Replace duplicated runCollectSkills/runCollectAgents (~110 lines of 95%
identical code) with a single runCollectPlan function driven by a
collectPlan struct + toCollectResources[T] generic converter.

Key changes:

- Add collectPlan/collectResources types and runCollectPlan unified flow
- Add toCollectResources[T] generic to bridge typed slices into the
  shared pipeline (scan → display → dry-run → confirm → pull → render)
- Replace fragile err.Error() == "already exists in source" string
  matching with ErrAlreadyExists sentinel error + errors.Is()
- Move os.MkdirAll from per-agent PullAgent to PullAgents (call once)
- Add FindLocalAgents/PullAgent/PullAgents to match FindLocalSkills API
- Add target selection, --force/--dry-run/--json support for agent collect
- Add integration tests for agent collect (target filter, dry-run, force,
  JSON, oplog, project mode)
- Update collect.md, agents.md, ui.md docs for agent collect support
2026-04-09 00:36:39 +08:00
Willie 4a84796160 docs: document agents_source config field
The agents_source field was already implemented but had no
documentation, unlike extras_source which was fully documented.

- Add agents_source to Full Example in configuration.md
- Add dedicated agents_source field reference section
- Add Custom Source Directory section to understand/agents.md
- Note agents_source in Skills vs Agents comparison table
2026-04-08 22:04:15 +08:00
Willie 9025fb35bf docs: update website docs for centralized .metadata.json format 2026-04-08 15:14:22 +08:00
Willie 9896aa7cd6 docs: add Agents concepts page to website documentation
Create website/docs/understand/agents.md covering:
- Skills vs Agents comparison table
- Directory structure (global + project)
- Agent file format and naming conventions
- Supported targets (claude, cursor, opencode, augment)
- Sync modes (merge/symlink/copy)
- .agentignore usage
- Install from repos with auto-detection
- CLI commands reference
- Data flow diagram

Update sidebar ordering to include agents between skill-format and
project-skills.
2026-04-07 18:05:40 +08:00
Willie 7d4e6cad42 docs: add v0.18.9 changelog and document relative symlinks in project mode 2026-04-07 17:26:37 +08:00
Willie 67893a402a docs: document --branch flag for install and tracked repositories
Adds --branch to options table, usage examples for branch installs,
and Branch Tracking section in tracked-repositories guide.

Closes #90
2026-04-01 00:32:49 +08:00
Willie ccdafd3293 feat(sync): add target_naming config option (flat/standard)
Add per-target target_naming setting that controls how skill directories
are named in sync targets. 'flat' (default) preserves the existing
flattened __ separator behavior. 'standard' uses the SKILL.md name field
directly, following the Agent Skills specification.

Standard mode:
- Validates SKILL.md names match directory basenames
- Detects and skips name collisions with warnings
- Auto-migrates managed entries when switching from flat to standard
- Preserves legacy entries when bare name is already occupied

Also includes:
- Per-target toggle via CLI (--target-naming), TUI (N key), and Web UI
- Collision output redesigned as deduplicated compact summary
- Config inheritance: global target_naming → per-target override
- JSON schema + UI validation for the new field

Closes #110
2026-04-01 00:32:49 +08:00
Willie acedd77f20 docs: update registry.yaml path and init --remote behavior
- registry.yaml now lives in skills/ dir (synced via git)
- Updated file-structure, declarative-manifest, appendix, init docs
- Added migration note for v0.19+ users
2026-03-26 23:06:37 +08:00
Willie c57391ea39 feat: add Hermes Agent (Nous Research) target support
Hermes Agent is a CLI tool by Nous Research with skills support.
Paths: ~/.hermes/skills (global), .hermes/skills (project).
Ref: https://hermes-agent.nousresearch.com/docs/reference/optional-skills-catalog

Also updates target count from 55+ to 56+ across docs and homepage.
2026-03-19 03:57:08 +08:00
Willie 0ae936a3c1 docs: document metadata.targets in skill format page
Add the new metadata: block placement for targets, explain the
priority rule (metadata wins over top-level), and describe the
metadata block as an ecosystem convention.
2026-03-18 22:35:02 +08:00
Willie 26760157b6 docs: add pattern and category fields to skill format reference 2026-03-18 22:35:02 +08:00
Willie c4bfcb0a44 docs: add skill design patterns guide and update new command reference
Add comprehensive skill design patterns page covering five structural
templates (Tool Wrapper, Generator, Reviewer, Inversion, Pipeline) with
a decision flowchart, use-case categories, and detailed examples.

Update `new` command reference with -P/--pattern flag documentation and
a scaffold directories table. Cross-link from skill-design.md.
2026-03-18 22:35:02 +08:00
Willie 603ea03ddc docs: add v0.17.3 changelog, target list TUI docs, and trash gitignore refs
- CHANGELOG.md + website changelog: v0.17.3 entry (target list TUI,
  web UI error guidance, init --help fix, project trash gitignore)
- RELEASE_NOTES_0.17.3.md: full release notes
- target.md: document interactive TUI, --no-tui flag, options table
- tui.md: add target list to TUI-enabled commands list
- SKILL.md: add target list to --no-tui command list
- project-skills, tracked-repositories, project-setup, install:
  update .gitignore references to include trash/
2026-03-17 04:48:42 +08:00
Willie 6a94c69e47 docs: update docs and changelog for v0.17.1
Add documentation for new features (UI theme system, init --subdir),
bug fixes (collect .git skip, actionable git errors), and release notes.
Update CHANGELOG.md, website changelog, and 6 doc pages.
2026-03-13 14:09:40 +08:00
Willie dfaf34215c docs: update website and built-in skill for extras first-class support
- diff.md: add --extras and --all flags
- status.md: add Extras section for sync status display
- doctor.md: add Extras health check section
- quick-reference.md: add Extras Management table and extras path
- project-skills.md: add extras to Mode Restrictions (supported) and directory structure
- sync-modes.md: add Extras Sync Modes section
- declarative-manifest.md: add Extras Configuration section
- SKILL.md: add extras commands to Quick Lookup table
2026-03-12 16:45:02 +08:00
Willie 7c582cbe21 docs: update v0.16.13 changelog to match project style
Expand bug fix descriptions, add grouped layout ASCII example,
and sync website changelog.
2026-03-06 23:10:48 +08:00
Willie 9b5429a3fd feat(targets): add Warp, Purecode AI, Witsy targets
Add 3 new AI agent targets discovered from vercel-labs/skills PRs:
- warp: universal path (~/.agents/skills)
- purecode (alias: purecode-ai): ~/.purecode/skills (global), .agents/skills (project)
- witsy: universal path (~/.agents/skills)

Update website docs: badge grid, path table, alias table, universal
info box, and target counts (50+ → 55+).
2026-03-06 23:10:48 +08:00
Willie 6730760215 feat(audit): add hardcoded secret detection (10 rules)
Detect inline API keys, tokens, and passwords in skill files via 10 new
hardcoded-secret-* rules (HIGH severity): Google API keys, AWS access
keys, GitHub PATs (classic + fine-grained), Slack tokens, OpenAI keys,
Anthropic keys, Stripe keys, PEM private key blocks, and generic
api_key/password assignments.

Closes a gap where GitHub Secret Scanning caught a Google API key in a
skill file but our audit engine missed it entirely.
2026-03-05 02:34:24 +08:00
Willie 2af44f1d3f chore(skills): strengthen built-in skill descriptions and content
Improve all 5 active skills with pushy descriptions for better
triggering accuracy, following devcontainer as the gold standard.

- changelog: add trigger scenarios (release notes, version prep)
- cli-e2e-test: add trigger scenarios (runbook, E2E validation)
- codebase-audit: add 3 new audit dimensions (handler split, oplog
  coverage, web API consistency) and trigger scenarios
- implement-feature: add project patterns reference (handler split,
  dual-mode, TUI, web API, oplog) and trigger scenarios
- update-docs: expand scope to all 7 doc categories with code-to-doc
  mapping guide and trigger scenarios

Also remove empty .skillshare/skills/frontend/ directory.
2026-03-05 02:13:21 +08:00
Willie 6caf73faf0 docs(audit): split monolith audit.md into focused pages
The 1294-line audit.md mixed command reference, conceptual teaching,
rule management, and CI/CD recipes. Split into:

- understand/audit-engine.md — threat model, detection rules, risk
  scoring, command tiering, cross-skill analysis
- reference/commands/audit-rules.md — rule management, custom rules,
  built-in rule IDs table (adds 4 cross-skill finding IDs)
- how-to/recipes/ci-cd-skill-validation.md — absorb output format
  docs (SARIF, Markdown, JSON+jq, exit codes)
- reference/commands/audit.md — slim to ~370 lines, link to new pages

Also fixes:
- Replace ghost rule `system-writes-0` with `insecure-http-0` in all
  docs (the old ID no longer exists in rules.yaml)
- Update 3 cross-page links in security.md
- Update 1 rule ID in configuration.md
- Add sidebar entries for both new pages
2026-03-04 12:16:32 +08:00
Willie 8a820bbe5e docs: add symlinked directory sync E2E runbook
Covers 13 test scenarios for dotfiles manager symlink support:
symlinked source/target, chained symlinks, merge/copy modes,
status/diff/list/collect through symlinks, and idempotency.
2026-03-02 10:05:57 +08:00
Willie 1327586f30 docs: fix 17 factual errors across website documentation
Full content audit identified inaccuracies verified against source code:

Critical fixes:
- declarative-manifest: skills: migrated from config.yaml to registry.yaml
- private-enterprise-skills: fix token list, add --track, fix dir separator
- supported-targets: fix universal canonical name, kimi/replit paths, aliases
- with-multiple-tools: fix target list output format, opencode path

Moderate fixes:
- tracked-repositories, project-skills: update config examples for registry.yaml
- skill-format: name rule "underscore" -> "number" (per validSkillNameRegex)
- understand/index: fix opencode path in diagram, add copy mode
- comparison: ~/.cursor/rules -> ~/.cursor/skills
- configuration: fix backups path, add registry migration note
- with-devcontainer: add non-interactive flags for postCreateCommand
- migration: .source -> .skillshare-meta.json
- docker-sandbox: make --cmd -> ./scripts/test_docker.sh --cmd
- security: audit rule count 31 -> 32
- ci-cd-skill-validation: production -> CI docker image
- cross-machine-sync-recipe: replace unimplemented ignore with include/exclude
- environment-variables: add GH_TOKEN entry
2026-02-26 22:27:23 +08:00
Willie 631b3ef292 docs: add AtomGit and Gitee to supported platform listings
- Add AtomGit/Gitee HTTPS examples in url-formats.md
- Add AtomGit/Gitee column to Platform Support table
- Update intro.md and comparison.md platform lists
- Add AtomGit install E2E runbook (geo-restriction noted)
2026-02-26 22:27:23 +08:00
Willie 37881c5dad docs: highlight non-GitHub git platform support as competitive advantage
Vercel skills issue #386 (8 commenters) confirms this is the #1 pain point
for enterprise users — their update/check is hardcoded to GitHub Trees API.
Skillshare uses local git operations, working with any remote out of the box.
2026-02-26 22:27:23 +08:00
Willie caa525b8aa 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 22:27:23 +08:00