clawhub

package
v0.12.1 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package clawhub provides ClawHub skills marketplace integration.

ClawHub is a marketplace for discovering, publishing, and managing AI agent skills. This package provides:

Hub Client

Hub provides access to the ClawHub API:

hub := clawhub.New(
    clawhub.WithAPIKey("your-api-key"),
)

// Search for skills
results, err := hub.Search(ctx, "meeting")
for _, skill := range results {
    fmt.Println(skill.Name, skill.Version, skill.Description)
}

// Get a specific skill
info, err := hub.GetSkill(ctx, "meeting-pm")
fmt.Println(info.Repository, info.LatestVersion)

// Download a skill
content, err := hub.Download(ctx, "meeting-pm", "1.0.0")

Manifest

Manifest represents the CLAWHUB.json file required for published skills:

{
    "name": "meeting-pm",
    "version": "1.0.0",
    "description": "Meeting program manager skill",
    "author": "Jane Smith",
    "repository": "https://github.com/example/meeting-pm",
    "license": "MIT",
    "keywords": ["meeting", "calendar", "productivity"],
    "dependencies": [
        {"name": "google-calendar", "version": ">=1.0.0"}
    ],
    "permissions": ["calendar.read", "calendar.write"]
}

Use LoadManifest to load a manifest:

manifest, err := clawhub.LoadManifest("./CLAWHUB.json")

Dependency Resolution

DependencyResolver resolves dependencies with version constraints:

resolver := clawhub.NewDependencyResolver(hub)
deps, err := resolver.Resolve(ctx, manifest)
for _, dep := range deps {
    fmt.Printf("%s@%s (transitive: %v)\n", dep.Name, dep.Version, dep.Transitive)
}

Security Scanning

SecurityScanner analyzes skills for security issues:

scanner := &clawhub.SecurityScanner{
    StrictMode:      true,
    AllowedCommands: []string{"git", "npm", "go"},
}

issues, err := scanner.ScanDirectory("./skill")
for _, issue := range issues {
    fmt.Printf("[%s] %s: %s\n", issue.Severity, issue.File, issue.Description)
}

The scanner checks for:

  • Dangerous shell commands
  • Suspicious patterns (eval, exec)
  • Hardcoded credentials
  • Unsafe file operations

Publishing Skills

To publish a skill to ClawHub:

  1. Create a CLAWHUB.json manifest

  2. Run security scanning

  3. Push to the ClawHub registry

    err := hub.Publish(ctx, manifest, "./skill")

Package clawhub provides ClawHub skills marketplace integration.

Index

Constants

View Source
const (
	// DefaultHubURL is the default ClawHub API endpoint.
	DefaultHubURL = "https://api.clawhub.ai/v1"
)
View Source
const ManifestFile = "CLAWHUB.json"

ManifestFile is the name of the manifest file in a skill repository.

Variables

This section is empty.

Functions

func ValidateSignature

func ValidateSignature(manifest *Manifest, publicKey string) error

ValidateSignature validates a skill's cryptographic signature.

Types

type CategoryInfo added in v0.11.0

type CategoryInfo struct {
	// Name is the category name (e.g., "file", "code", "ai").
	Name string `json:"name"`

	// Description describes what this category covers.
	Description string `json:"description"`

	// SkillCount is the number of skills in this category.
	SkillCount int `json:"skillCount"`

	// Capabilities lists capabilities in this category.
	Capabilities []string `json:"capabilities"`
}

CategoryInfo describes a capability category.

type Dependency

type Dependency struct {
	// Name is the dependency name (e.g., "@clawhub/web-search").
	Name string `json:"name"`

	// Version is the version constraint (e.g., "^1.0.0", ">=2.0.0").
	Version string `json:"version"`

	// Optional indicates if the dependency is optional.
	Optional bool `json:"optional,omitempty"`
}

Dependency represents a skill dependency.

type DependencyResolver

type DependencyResolver struct {
	// contains filtered or unexported fields
}

DependencyResolver resolves skill dependencies.

func NewDependencyResolver

func NewDependencyResolver(hub *Hub) *DependencyResolver

NewDependencyResolver creates a new dependency resolver.

func (*DependencyResolver) Resolve

func (r *DependencyResolver) Resolve(ctx context.Context, manifest *Manifest) ([]ResolvedDependency, error)

Resolve resolves all dependencies for a manifest.

type DiscoverOptions added in v0.11.0

type DiscoverOptions struct {
	// Page is the page number (1-indexed).
	Page int

	// PerPage is the number of results per page.
	PerPage int

	// MinStars filters to skills with at least this many stars.
	MinStars int

	// SecurityVerified filters to skills that passed security review.
	SecurityVerified bool
}

DiscoverOptions configures capability-based discovery.

type Hub

type Hub struct {
	// contains filtered or unexported fields
}

Hub provides access to the ClawHub skills marketplace API.

func New

func New(opts ...Option) *Hub

New creates a new Hub client.

func (*Hub) Browse added in v0.11.0

func (h *Hub) Browse(ctx context.Context, opts *DiscoverOptions) ([]SkillsByCategory, error)

Browse returns skills organized by capability category for exploration.

func (*Hub) Discover added in v0.11.0

func (h *Hub) Discover(ctx context.Context, capability string, opts *DiscoverOptions) (*SearchResult, error)

Discover searches ClawHub for skills providing the given capability. The capability should be in "category:action" format (e.g., "file:read").

func (*Hub) DiscoverMultiple added in v0.11.0

func (h *Hub) DiscoverMultiple(ctx context.Context, capabilities []string, opts *DiscoverOptions) (*SearchResult, error)

DiscoverMultiple searches for skills providing any of the given capabilities.

func (*Hub) Get

func (h *Hub) Get(ctx context.Context, name string) (*SkillInfo, error)

Get retrieves information about a specific skill.

func (*Hub) GetVersion

func (h *Hub) GetVersion(ctx context.Context, name, version string) (*SkillInfo, error)

GetVersion retrieves information about a specific version of a skill.

func (*Hub) ListCapabilities added in v0.11.0

func (h *Hub) ListCapabilities(ctx context.Context, category string) ([]string, error)

ListCapabilities returns all capabilities in a category.

func (*Hub) ListCategories added in v0.11.0

func (h *Hub) ListCategories(ctx context.Context) ([]CategoryInfo, error)

ListCategories returns all capability categories available in ClawHub.

func (*Hub) ListVersions

func (h *Hub) ListVersions(ctx context.Context, name string) ([]string, error)

ListVersions lists all versions of a skill.

func (*Hub) RecommendSkills added in v0.11.0

func (h *Hub) RecommendSkills(ctx context.Context, need string, opts *RecommendOptions) (*RecommendResult, error)

RecommendSkills recommends skills based on a natural language description of need. Example: "I need to read and write files, and make HTTP requests"

func (*Hub) Resolve

func (h *Hub) Resolve(ctx context.Context, ref string) (*SkillInfo, error)

Resolve resolves a skill reference to a SkillInfo with repository details.

func (*Hub) Search

func (h *Hub) Search(ctx context.Context, query string, page, perPage int) (*SearchResult, error)

Search searches for skills matching the query.

type IssueType

type IssueType string

IssueType represents the type of security issue.

const (
	IssueTypeSecretLeak    IssueType = "secret_leak"
	IssueTypeDangerousCmd  IssueType = "dangerous_command"
	IssueTypeNetworkAccess IssueType = "network_access"
	IssueTypeFileAccess    IssueType = "file_access"
	IssueTypeMalicious     IssueType = "malicious"
	IssueTypeUnsigned      IssueType = "unsigned"
)

type Manifest

type Manifest struct {
	// Name is the skill name (required).
	Name string `json:"name"`

	// Version is the semantic version (required).
	Version string `json:"version"`

	// Description is a brief description of the skill.
	Description string `json:"description"`

	// Author is the skill author's name or organization.
	Author string `json:"author"`

	// Repository is the source repository URL.
	Repository string `json:"repository"`

	// License is the SPDX license identifier.
	License string `json:"license"`

	// Keywords are searchable tags for the skill.
	Keywords []string `json:"keywords,omitempty"`

	// Dependencies lists other skills this skill depends on.
	Dependencies []Dependency `json:"dependencies,omitempty"`

	// Permissions lists the permissions the skill requires.
	Permissions []string `json:"permissions,omitempty"`

	// Entry is the entry point file (defaults to SKILL.md).
	Entry string `json:"entry,omitempty"`

	// Signature is the cryptographic signature for verification.
	Signature string `json:"signature,omitempty"`

	// MinAgentVersion is the minimum omniagent version required.
	MinAgentVersion string `json:"minAgentVersion,omitempty"`
}

Manifest represents the CLAWHUB.json manifest file.

func LoadManifest

func LoadManifest(path string) (*Manifest, error)

LoadManifest loads a manifest from a file path.

func ParseManifest

func ParseManifest(data []byte) (*Manifest, error)

ParseManifest parses a manifest from JSON data.

func (*Manifest) EntryFile

func (m *Manifest) EntryFile() string

EntryFile returns the entry point file, defaulting to SKILL.md.

func (*Manifest) FullName

func (m *Manifest) FullName() string

FullName returns the full name including scope if present.

func (*Manifest) HasPermission

func (m *Manifest) HasPermission(perm string) bool

HasPermission checks if the skill requests a specific permission.

func (*Manifest) SaveManifest

func (m *Manifest) SaveManifest(dir string) error

SaveManifest saves a manifest to a file path.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks that the manifest has all required fields.

type Option

type Option func(*Hub)

Option is a functional option for configuring the Hub.

func WithAPIKey

func WithAPIKey(apiKey string) Option

WithAPIKey sets the API key for authenticated requests.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL sets a custom base URL for the Hub API.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client.

type RecommendOptions added in v0.11.0

type RecommendOptions struct {
	// MaxResults is the maximum number of recommendations.
	MaxResults int

	// IncludeRationale includes explanation for why each skill was recommended.
	IncludeRationale bool

	// SecurityVerified filters to verified skills only.
	SecurityVerified bool
}

RecommendOptions configures skill recommendations.

type RecommendResult added in v0.11.0

type RecommendResult struct {
	// Recommendations is the list of recommended skills.
	Recommendations []Recommendation `json:"recommendations"`

	// ParsedNeed is how the system interpreted the need.
	ParsedNeed string `json:"parsedNeed,omitempty"`

	// InferredCapabilities are capabilities inferred from the need.
	InferredCapabilities []string `json:"inferredCapabilities,omitempty"`
}

RecommendResult contains skill recommendations.

type Recommendation added in v0.11.0

type Recommendation struct {
	// Skill is the recommended skill.
	Skill SkillInfo `json:"skill"`

	// Score is the relevance score (0.0-1.0).
	Score float64 `json:"score"`

	// Rationale explains why this skill was recommended.
	Rationale string `json:"rationale,omitempty"`

	// MatchedCapabilities are the capabilities that matched the need.
	MatchedCapabilities []string `json:"matchedCapabilities,omitempty"`
}

Recommendation represents a skill recommendation with optional rationale.

type ResolutionError

type ResolutionError struct {
	// Dependency is the name of the dependency that failed.
	Dependency string

	// Constraint is the version constraint that couldn't be satisfied.
	Constraint string

	// Reason is the error reason.
	Reason string
}

ResolutionError represents an error during dependency resolution.

func (*ResolutionError) Error

func (e *ResolutionError) Error() string

type ResolvedDependency

type ResolvedDependency struct {
	// Name is the dependency name.
	Name string

	// Version is the resolved version.
	Version string

	// Repository is the source repository URL.
	Repository string

	// Optional indicates if this is an optional dependency.
	Optional bool

	// Transitive indicates if this is a transitive dependency.
	Transitive bool
}

ResolvedDependency represents a fully resolved dependency.

type ScanResult

type ScanResult struct {
	// Issues is the list of security issues found.
	Issues []SecurityIssue

	// FileHashes contains SHA256 hashes of all files.
	FileHashes map[string]string

	// Passed indicates if the scan passed.
	Passed bool
}

ScanResult contains the results of a security scan.

type SearchResult

type SearchResult struct {
	// Skills is the list of matching skills.
	Skills []SkillInfo `json:"skills"`

	// Total is the total number of matching skills.
	Total int `json:"total"`

	// Page is the current page number.
	Page int `json:"page"`

	// PerPage is the number of results per page.
	PerPage int `json:"perPage"`
}

SearchResult contains the result of a skill search.

type SecurityIssue

type SecurityIssue struct {
	// Severity is the issue severity.
	Severity Severity

	// Type is the issue type.
	Type IssueType

	// File is the file where the issue was found.
	File string

	// Line is the line number (0 if not applicable).
	Line int

	// Description describes the issue.
	Description string

	// Recommendation suggests how to fix the issue.
	Recommendation string
}

SecurityIssue represents a security finding.

type SecurityScanner

type SecurityScanner struct {
	// StrictMode fails on any warning when true.
	StrictMode bool

	// AllowedCommands is a list of allowed shell commands.
	AllowedCommands []string

	// BlockedPatterns are regex patterns that are not allowed.
	BlockedPatterns []*regexp.Regexp
}

SecurityScanner scans skill packages for security issues.

func NewSecurityScanner

func NewSecurityScanner() *SecurityScanner

NewSecurityScanner creates a new security scanner with defaults.

func (*SecurityScanner) Scan

func (s *SecurityScanner) Scan(dir string) (*ScanResult, error)

Scan scans a skill directory for security issues.

type SecurityState

type SecurityState string

SecurityState represents the security verification state of a skill.

const (
	// SecurityStateUnknown indicates the skill has not been verified.
	SecurityStateUnknown SecurityState = "unknown"

	// SecurityStatePending indicates verification is in progress.
	SecurityStatePending SecurityState = "pending"

	// SecurityStateVerified indicates the skill passed security checks.
	SecurityStateVerified SecurityState = "verified"

	// SecurityStateFlagged indicates security issues were found.
	SecurityStateFlagged SecurityState = "flagged"
)

type Severity

type Severity string

Severity represents the severity of a security issue.

const (
	SeverityCritical Severity = "critical"
	SeverityHigh     Severity = "high"
	SeverityMedium   Severity = "medium"
	SeverityLow      Severity = "low"
	SeverityInfo     Severity = "info"
)

type SkillInfo

type SkillInfo struct {
	// Name is the skill name.
	Name string `json:"name"`

	// Version is the latest version.
	Version string `json:"version"`

	// Description is the skill description.
	Description string `json:"description"`

	// Author is the skill author.
	Author string `json:"author"`

	// Repository is the source repository URL.
	Repository string `json:"repository"`

	// Downloads is the total download count.
	Downloads int `json:"downloads"`

	// Stars is the star count.
	Stars int `json:"stars"`

	// License is the SPDX license identifier.
	License string `json:"license"`

	// Keywords are searchable tags.
	Keywords []string `json:"keywords"`

	// CreatedAt is when the skill was first published.
	CreatedAt time.Time `json:"createdAt"`

	// UpdatedAt is when the skill was last updated.
	UpdatedAt time.Time `json:"updatedAt"`

	// SecurityState indicates the security verification state.
	SecurityState SecurityState `json:"securityState"`

	// Versions lists all available versions.
	Versions []string `json:"versions,omitempty"`
}

SkillInfo contains information about a skill from the Hub.

type SkillsByCategory added in v0.11.0

type SkillsByCategory struct {
	// Category is the capability category.
	Category string `json:"category"`

	// Skills are the skills in this category.
	Skills []SkillInfo `json:"skills"`
}

SkillsByCategory returns skills grouped by their primary capability category.

Jump to

Keyboard shortcuts

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