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: API client for searching and fetching skills
- Manifest: CLAWHUB.json manifest file parsing
- DependencyResolver: Dependency resolution with version constraints
- SecurityScanner: Security scanning for skill packages
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:
Create a CLAWHUB.json manifest
Run security scanning
Push to the ClawHub registry
err := hub.Publish(ctx, manifest, "./skill")
Package clawhub provides ClawHub skills marketplace integration.
Index ¶
- Constants
- func ValidateSignature(manifest *Manifest, publicKey string) error
- type CategoryInfo
- type Dependency
- type DependencyResolver
- type DiscoverOptions
- type Hub
- func (h *Hub) Browse(ctx context.Context, opts *DiscoverOptions) ([]SkillsByCategory, error)
- func (h *Hub) Discover(ctx context.Context, capability string, opts *DiscoverOptions) (*SearchResult, error)
- func (h *Hub) DiscoverMultiple(ctx context.Context, capabilities []string, opts *DiscoverOptions) (*SearchResult, error)
- func (h *Hub) Get(ctx context.Context, name string) (*SkillInfo, error)
- func (h *Hub) GetVersion(ctx context.Context, name, version string) (*SkillInfo, error)
- func (h *Hub) ListCapabilities(ctx context.Context, category string) ([]string, error)
- func (h *Hub) ListCategories(ctx context.Context) ([]CategoryInfo, error)
- func (h *Hub) ListVersions(ctx context.Context, name string) ([]string, error)
- func (h *Hub) RecommendSkills(ctx context.Context, need string, opts *RecommendOptions) (*RecommendResult, error)
- func (h *Hub) Resolve(ctx context.Context, ref string) (*SkillInfo, error)
- func (h *Hub) Search(ctx context.Context, query string, page, perPage int) (*SearchResult, error)
- type IssueType
- type Manifest
- type Option
- type RecommendOptions
- type RecommendResult
- type Recommendation
- type ResolutionError
- type ResolvedDependency
- type ScanResult
- type SearchResult
- type SecurityIssue
- type SecurityScanner
- type SecurityState
- type Severity
- type SkillInfo
- type SkillsByCategory
Constants ¶
const (
// DefaultHubURL is the default ClawHub API endpoint.
DefaultHubURL = "https://api.clawhub.ai/v1"
)
const ManifestFile = "CLAWHUB.json"
ManifestFile is the name of the manifest file in a skill repository.
Variables ¶
This section is empty.
Functions ¶
func ValidateSignature ¶
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 (*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) GetVersion ¶
GetVersion retrieves information about a specific version of a skill.
func (*Hub) ListCapabilities ¶ added in v0.11.0
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 ¶
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"
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 ¶
LoadManifest loads a manifest from a file path.
func ParseManifest ¶
ParseManifest parses a manifest from JSON data.
func (*Manifest) HasPermission ¶
HasPermission checks if the skill requests a specific permission.
func (*Manifest) SaveManifest ¶
SaveManifest saves a manifest to a file path.
type Option ¶
type Option func(*Hub)
Option is a functional option for configuring the Hub.
func WithAPIKey ¶
WithAPIKey sets the API key for authenticated requests.
func WithBaseURL ¶
WithBaseURL sets a custom base URL for the Hub API.
func WithHTTPClient ¶
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 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.