skills

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 17, 2026 License: MIT Imports: 18 Imported by: 2

README

skills (Go 移植版)

本项目是对 Vercel 的技能管理 CLI 的 Go 语言移植实现,主要用于发现、安装、列出与移除 Agent Skills(基于 SKILL.md)。

原项目:

安装

安装到全局(推荐):

go install github.com/looplj/skills/cmd/find-skills@latest

安装后可直接使用:

find-skills --help

从源码构建:

go build -o find-skills ./cmd/find-skills

或直接运行:

go run ./cmd/find-skills --help

快速开始

搜索技能:

find-skills find "browser automation" --limit 10

以可直接用于安装的格式输出搜索结果:

find-skills find "pdf" --format add

安装技能(支持本地目录、Git 仓库、URL、well-known 等来源):

find-skills add vercel-labs/agent-skills --global --yes

列出已安装技能:

find-skills list --global

移除技能:

find-skills remove --global my-skill

生成 SKILL.md 模板:

find-skills init MySkill

检查并更新通过 GitHub 安装的全局技能:

find-skills check
find-skills update

作为库使用

该 Go 版本不仅提供可执行文件,也可以直接作为库引入,在你的程序里完成技能的发现/安装/移除等逻辑。

安装技能(启用 Agent 自动发现;若需安装到指定目录,见下一个示例):

package main

import (
	"context"
	"fmt"

	skills "github.com/looplj/skills"
)

func main() {
	ctx := context.Background()
	res, err := skills.Add(ctx, skills.AddOptions{
		Source:               "vercel-labs/agent-skills",
		Global:               true,
		Yes:                  true,
		EnableAgentDiscovery: true,
	})
	if err != nil {
		panic(err)
	}
	for _, s := range res.Installed {
		fmt.Println(s.InstallName, s.Name)
	}
}

安装技能(显式指定目标目录;适合嵌入到你自己的目录结构中):

package main

import (
	"context"

	skills "github.com/looplj/skills"
)

func main() {
	ctx := context.Background()
	_, err := skills.Add(ctx, skills.AddOptions{
		Source:               "vercel-labs/agent-skills",
		Yes:                  true,
		Dirs:                 []string{".agents/skills"},
		EnableAgentDiscovery: false,
	})
	if err != nil {
		panic(err)
	}
}

列出与移除:

package main

import (
	"fmt"

	skills "github.com/looplj/skills"
)

func main() {
	items, err := skills.List(skills.ListOptions{
		Global:               true,
		EnableAgentDiscovery: true,
	})
	if err != nil {
		panic(err)
	}
	for _, it := range items {
		fmt.Println(it.InstallName, it.Name)
	}
}
package main

import (
	skills "github.com/looplj/skills"
)

func main() {
	_, err := skills.Remove(skills.RemoveOptions{
		Global:               true,
		Skills:               []string{"my-skill"},
		EnableAgentDiscovery: true,
	})
	if err != nil {
		panic(err)
	}
}

可嵌入 CLI(Cobra)

项目同时提供了可嵌入的 Cobra 命令集合,可作为你自己 CLI 的子命令使用。

将 find-skills 作为子命令挂到你的根命令下:

package main

import (
	"os"

	skillscmd "github.com/looplj/skills/skillscmd"
	"github.com/spf13/cobra"
)

func main() {
	root := &cobra.Command{Use: "myapp"}
	root.AddCommand(skillscmd.NewRootCommand(skillscmd.RootOptions{
		Use:                  "find-skills",
		Stdout:               os.Stdout,
		Stderr:               os.Stderr,
		EnableAgentDiscovery: true,
	}))
	if err := root.Execute(); err != nil {
		os.Exit(1)
	}
}

如果你不希望依赖自动发现,也可以通过 WorkspaceDir / GlobalDir 指定技能目录(安装/列出/移除会直接作用在这些目录上):

package main

import (
	"os"

	skillscmd "github.com/looplj/skills/skillscmd"
)

func main() {
	cmd := skillscmd.NewRootCommand(skillscmd.RootOptions{
		Use:                  "find-skills",
		Stdout:               os.Stdout,
		Stderr:               os.Stderr,
		WorkspaceDir:         ".agents/skills",
		GlobalDir:            "~/.agents/skills",
		EnableAgentDiscovery: false,
	})
	if err := cmd.Execute(); err != nil {
		os.Exit(1)
	}
}

如果你还需要暴露一层 bundled skills 作为 list/get 的回退来源,可以直接从代码注入 BundledSkills。Skill.Name 会作为 install name 使用。当 bundled skill 与已安装 skill 同名时,已安装的 global/workspace skill 会覆盖 bundled 版本:

root.AddCommand(skillscmd.NewRootCommand(skillscmd.RootOptions{
	Use:          "find-skills",
	WorkspaceDir: ".agents/skills",
	GlobalDir:    "~/.agents/skills",
	BundledSkills: []skills.Skill{
		{
			Name:        "seo-audit",
			Description: "Bundled SEO audit skill",
			Content:     "---\nname: seo-audit\ndescription: Bundled SEO audit skill\n---\n",
		},
	},
}))

认证

在检查/更新 GitHub 技能时,若遇到限流或私有仓库访问需求,可配置以下任一方式:

  • 环境变量 GITHUB_TOKEN 或 GH_TOKEN
  • 已登录的 GitHub CLI(gh auth login),工具会尝试读取 gh auth token

许可证

MIT,见 LICENSE。本项目保持与上游项目声明一致的开源协议。

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrSourceRequired         = errors.New("source is required")
	ErrAgentDiscoveryRequired = errors.New("target dirs are required when agent discovery is disabled")
	ErrNoTargetDirs           = errors.New("no target dirs specified")
	ErrNoSkillsFound          = errors.New("no skills found")
	ErrNoSkillsSpecified      = errors.New("no skills specified")
	ErrSkillNameRequired      = errors.New("skill name is required")
	ErrMultipleSkills         = errors.New("multiple skills found; specify --skill or --yes")
	ErrMultipleWellKnown      = errors.New("multiple well-known skills found; specify --skill or --yes")
	ErrUnsupportedSourceType  = errors.New("unsupported source type")
	ErrUnknownInstallMode     = errors.New("unknown install mode")
	ErrUnrecognizedSource     = errors.New("unrecognized source format")
	ErrMissingFrontmatter     = errors.New("missing frontmatter")
	ErrMissingName            = errors.New("frontmatter missing name")
	ErrMissingDescription     = errors.New("frontmatter missing description")
	ErrHomeNotFound           = errors.New("home directory not found")
	ErrNoWellKnownIndex       = errors.New("no well-known skills index found")
	ErrUnsafeFilePath         = errors.New("unsafe file path in well-known index")
	ErrSkillAlreadyExists     = errors.New("SKILL.md already exists")
	ErrSkillNotFound          = errors.New("skill not found")
)

Functions

func AddSkillToLock

func AddSkillToLock(lock *SkillLock, installName string, entry LockEntry)

func AgentSkillsDir

func AgentSkillsDir(agent AgentType, global bool, cwd string) (string, error)

func CanonicalSkillsDir

func CanonicalSkillsDir(global bool, cwd string) (string, error)

func ClaudeHome

func ClaudeHome() (string, error)

func CodexHome

func CodexHome() (string, error)

func FetchGitHubSkillFolderHash

func FetchGitHubSkillFolderHash(ctx context.Context, ownerRepo string, skillPath string, token string) (string, error)

func GetGitHubToken

func GetGitHubToken() string

func HomeDir

func HomeDir() (string, error)

func Init

func Init(opts InitOptions) (string, error)

Init creates a SKILL.md template on disk and returns the created file path.

By default it writes "SKILL.md" in the working directory. If opts.Name is provided, it writes "<dir>/<name>/SKILL.md". If opts.Dir is provided, it is used as the base directory instead of the current working directory.

func IsUniversalAgent

func IsUniversalAgent(agent AgentType) (bool, error)

func RemoveSkillFromLock

func RemoveSkillFromLock(lock *SkillLock, installName string)

func SkillLockPath

func SkillLockPath() (string, error)

func SkillsAPIURL

func SkillsAPIURL() string

func WriteSkillLock

func WriteSkillLock(lock *SkillLock) error

func XDGConfigHome

func XDGConfigHome() (string, error)

Types

type AddOptions

type AddOptions struct {
	// Source is the install source string (local dir, git repo reference, direct URL,
	// or a well-known index URL).
	Source string

	// Dirs are explicit target directories to install into. When provided, agent discovery is
	// bypassed and Add installs directly to these directories.
	Dirs []string

	// Global installs into the global skills locations rather than project-local ones.
	// When agent discovery is enabled, global installs may also be tracked in the lock file
	// for future update checks.
	Global bool
	// Agents is an optional allowlist of agent types to install for. When empty and agent
	// discovery is enabled, installed agents may be auto-detected.
	Agents []AgentType
	// Skills selects which skills to install from a multi-skill source. Entries may match
	// either the skill folder name or the parsed skill name. "*" selects all discovered skills.
	Skills []string
	// ListOnly discovers and returns available skills without installing anything.
	ListOnly bool
	// Yes enables non-interactive defaults when a choice is required (for example, when a
	// source contains multiple skills and no explicit selection was provided).
	Yes bool
	// All installs all discovered skills. In Add, this implies Yes and sets Skills to "*".
	All bool
	// FullDepth enables deep scanning for SKILL.md files within the source directory tree.
	FullDepth bool
	// Mode controls how skill files are installed (for example, via symlinks or copying).
	Mode InstallMode

	// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
	// and agent-specific skills dirs when Dirs is not provided.
	EnableAgentDiscovery bool
}

type AddResult

type AddResult struct {
	Available []Skill
	Installed []InstalledSkill
}

func Add

func Add(ctx context.Context, opts AddOptions) (AddResult, error)

Add installs skills from opts.Source and returns what is available and/or installed.

The source may be a local directory, a git repository reference, a direct URL, or a well-known skills index. Behavior is controlled by opts:

  • If opts.ListOnly is true, the function only discovers and returns skills (no install).
  • If opts.All is true, it implies non-interactive mode and installs all discovered skills.
  • If opts.Mode is empty, it defaults to symlink-based installation.
  • If opts.Dirs is provided, it installs into those directories directly and skips agent discovery.
  • Otherwise, agent discovery must be enabled and target directories are derived from the canonical skills dir plus per-agent skills dirs (agents may be auto-detected when omitted).

When installing globally with agent discovery enabled, Add also records entries in the skill lock file so CheckUpdates/Update can detect and apply future updates for supported sources.

type AgentConfig

type AgentConfig struct {
	Name              AgentType
	DisplayName       string
	ProjectSkillsDir  string
	GlobalSkillsDir   string
	ShowInUniversal   bool
	DetectProjectPath string
	DetectGlobalPath  string
}

func AgentConfigFor

func AgentConfigFor(agent AgentType) (AgentConfig, error)

type AgentType

type AgentType string

func AllAgentTypes

func AllAgentTypes() []AgentType

func DetectInstalledAgents

func DetectInstalledAgents(cwd string) ([]AgentType, error)

type GetOptions

type GetOptions struct {
	// Dirs are explicit directories to search. When provided, agent discovery is bypassed and
	// Get searches only these directories.
	Dirs []string
	// BundledSkills are fallback skills injected directly from code. Skill.Name is used as the
	// install name. When the same install name exists in both BundledSkills and Dirs, entries
	// from Dirs take precedence.
	BundledSkills []Skill

	// Skill is the install name of the skill to load.
	Skill string
	// Global searches the global install locations rather than project-local ones.
	Global bool
	// Agents is an optional allowlist of agent types to search. When empty and agent discovery
	// is enabled, installed agents may be auto-detected.
	Agents []AgentType

	// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
	// and agent-specific skills dirs when Dirs is not provided.
	EnableAgentDiscovery bool
}

type GetResult

type GetResult struct {
	InstallName string
	Skill       Skill
}

func Get

func Get(opts GetOptions) (GetResult, error)

Get returns the full content and metadata of an installed skill by name.

If opts.Dirs is provided, it searches only those directories. Otherwise, agent discovery must be enabled and Get searches the canonical skills directory first and then per-agent skills directories (filtered by opts.Agents when provided).

type InitOptions

type InitOptions struct {
	// Name is an optional folder name used to place the template under "<dir>/<name>/SKILL.md".
	Name string
	// Dir is the base directory to write into. When empty, the current working directory is used.
	Dir string
}

type InstallMode

type InstallMode string
const (
	InstallModeSymlink InstallMode = "symlink"
	InstallModeCopy    InstallMode = "copy"
)

type InstalledSkill

type InstalledSkill struct {
	InstallName string
	Name        string
	Description string
	Source      SkillSource
	Agents      []AgentType
	Global      bool
}

type ListOptions

type ListOptions struct {
	// Dirs are explicit directories to list install names from. When provided, agent discovery
	// is bypassed and List reads only these directories.
	Dirs []string
	// BundledSkills are fallback skills injected directly from code. Skill.Name is used as the
	// install name. When the same install name exists in both BundledSkills and Dirs, entries
	// from Dirs take precedence.
	BundledSkills []Skill

	// Global lists from the global install locations rather than project-local ones.
	Global bool
	// Agents is an optional allowlist of agent types to list for. When empty and agent
	// discovery is enabled, installed agents may be auto-detected.
	Agents []AgentType

	// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
	// and agent-specific skills dirs when Dirs is not provided.
	EnableAgentDiscovery bool
}

type ListedSkill

type ListedSkill struct {
	InstallName string
	Name        string
	Description string
	Global      bool
	Agents      []AgentType
}

func List

func List(opts ListOptions) ([]ListedSkill, error)

List returns installed skills.

If opts.Dirs is provided, it lists install names from those directories directly. Otherwise, agent discovery must be enabled and List scans the canonical skills directory plus per-agent skills directories (filtered by opts.Agents when provided).

type LockEntry

type LockEntry struct {
	Source          SkillSource `json:"source"`
	SourceType      string      `json:"source_type"`
	SourceURL       string      `json:"source_url"`
	SkillPath       string      `json:"skill_path,omitempty"`
	SkillFolderHash string      `json:"skill_folder_hash,omitempty"`
	InstalledAt     time.Time   `json:"installed_at"`
	UpdatedAt       time.Time   `json:"updated_at"`
}

func (*LockEntry) UnmarshalJSON

func (e *LockEntry) UnmarshalJSON(b []byte) error

type RemoveOptions

type RemoveOptions struct {
	// Dirs are explicit target directories to remove from. When provided, agent discovery is
	// bypassed and Remove deletes directly from these directories.
	Dirs []string
	// Global removes from the global install locations rather than project-local ones.
	Global bool
	// Agents is an optional allowlist of agent types to remove from. When empty and agent
	// discovery is enabled, installed agents may be auto-detected.
	Agents []AgentType
	// Skills is the list of install names to remove. When empty, All must be set.
	Skills []string
	// All removes all installed skills found in the resolved target directories.
	All bool
	// Yes is reserved for non-interactive defaults. It is currently unused by Remove.
	Yes bool

	// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
	// and agent-specific skills dirs when Dirs is not provided.
	EnableAgentDiscovery bool
}

type RemoveResult

type RemoveResult struct {
	Removed []InstalledSkill
}

func Remove

func Remove(opts RemoveOptions) (RemoveResult, error)

Remove deletes installed skills and returns what was removed.

If opts.Dirs is provided, it removes from those directories directly:

  • opts.All removes all install names found under the given dirs.
  • opts.Skills removes only the specified install names.

Otherwise, agent discovery must be enabled and Remove deletes from the canonical skills directory and per-agent skills directories (filtered by opts.Agents when provided). When removing from global installs, it also updates the skill lock so removed entries no longer participate in update checks.

type SearchResult

type SearchResult struct {
	ID       string `json:"id"`
	SkillID  string `json:"skill_id"`
	Name     string `json:"name"`
	Installs int    `json:"installs"`
	Source   string `json:"source"`
}
func Search(ctx context.Context, query string, limit int) ([]SearchResult, error)

Search searches the skills registry and returns matching results.

func SearchSkills

func SearchSkills(ctx context.Context, query string, limit int) ([]SearchResult, error)

func (*SearchResult) UnmarshalJSON

func (r *SearchResult) UnmarshalJSON(b []byte) error

type Skill

type Skill struct {
	Name          string
	Description   string
	Compatibility string
	AllowedTools  []string
	Dir           string
	Content       string
	Metadata      map[string]any
}

func DiscoverSkills

func DiscoverSkills(baseDir string, fullDepth bool) ([]Skill, error)

func FetchDirectSkillToDir

func FetchDirectSkillToDir(ctx context.Context, skillURL string) (dir string, skill Skill, installName string, err error)

func FetchWellKnownSkillToDir

func FetchWellKnownSkillToDir(ctx context.Context, resolvedBase string, entry WellKnownSkillEntry) (dir string, skill Skill, installName string, err error)

func ParseSkillMarkdown

func ParseSkillMarkdown(content string) (Skill, error)

type SkillLock

type SkillLock struct {
	Skills             map[string]LockEntry `json:"skills"`
	LastSelectedAgents []AgentType          `json:"last_selected_agents,omitempty"`
	Dismissed          map[string]bool      `json:"dismissed,omitempty"`
}

func ReadSkillLock

func ReadSkillLock() (*SkillLock, error)

func (*SkillLock) UnmarshalJSON

func (l *SkillLock) UnmarshalJSON(b []byte) error

type SkillSource

type SkillSource struct {
	Type         SkillSourceType `json:"type"`
	SourceURL    string          `json:"source_url,omitempty"`
	Owner        string          `json:"owner,omitempty"`
	Repo         string          `json:"repo,omitempty"`
	Ref          string          `json:"ref,omitempty"`
	Subpath      string          `json:"subpath,omitempty"`
	SkillFilter  string          `json:"skill_filter,omitempty"`
	ProviderID   string          `json:"provider_id,omitempty"`
	InstallName  string          `json:"install_name,omitempty"`
	WellKnownURL string          `json:"well_known_url,omitempty"`
}

func ParseSource

func ParseSource(input string) (SkillSource, error)

func (*SkillSource) UnmarshalJSON

func (s *SkillSource) UnmarshalJSON(b []byte) error

type SkillSourceType

type SkillSourceType string
const (
	SkillSourceTypeLocal      SkillSourceType = "local"
	SkillSourceTypeGitHub     SkillSourceType = "github"
	SkillSourceTypeGitLab     SkillSourceType = "gitlab"
	SkillSourceTypeGit        SkillSourceType = "git"
	SkillSourceTypeDirectURL  SkillSourceType = "direct-url"
	SkillSourceTypeWellKnown  SkillSourceType = "well-known"
	SkillSourceTypeSearchHint SkillSourceType = "search-hint"
)

type UpdateCheck

type UpdateCheck struct {
	InstallName string
	Entry       LockEntry
	CurrentHash string
	RemoteHash  string
}

func CheckUpdates

func CheckUpdates(ctx context.Context) ([]UpdateCheck, error)

CheckUpdates compares globally installed skills recorded in the skill lock against their remote source state and returns any detected updates.

Currently, this only checks GitHub-based installs that have both a recorded skill folder path and a recorded folder hash.

func Update

func Update(ctx context.Context) ([]UpdateCheck, error)

Update applies updates for skills reported by CheckUpdates and returns the post-update status.

Updates are applied by re-installing the recorded skill path from GitHub into the global target directories, using symlink install mode and non-interactive defaults.

type WellKnownIndex

type WellKnownIndex struct {
	Skills []WellKnownSkillEntry `json:"skills"`
}

func FetchWellKnownIndex

func FetchWellKnownIndex(ctx context.Context, baseURL string) (index WellKnownIndex, resolvedBase string, err error)

type WellKnownSkillEntry

type WellKnownSkillEntry struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Files       []string `json:"files"`
}

Directories

Path Synopsis
cmd
find-skills module
skillscmd module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL