skill

package
v1.9.3 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package skill provides core skill manipulation and security checking logic.

Package skill provides core skill manipulation and security checking logic.

Package skill provides core skill manipulation, validation, and security checking logic.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CalculateEntropy added in v1.0.0 

func CalculateEntropy(s string) float64

CalculateEntropy calculates the Shannon entropy of a string. Higher entropy indicates more randomness, which is common in secrets/keys.

func CreateSkillTemplate added in v0.2.0 

func CreateSkillTemplate(name, destDir string) error

CreateSkillTemplate creates a new skill directory with template files

func CreateSkillTemplateWithData added in v1.7.7 

func CreateSkillTemplateWithData(data TemplateData, destDir string) error

CreateSkillTemplateWithData creates a new skill directory using provided template data

func FindSkillMD 

func FindSkillMD(skillPath string) bool

FindSkillMD checks if a skill has a SKILL.md file. Uses Lstat to avoid following symlinks.

func GenerateReport added in v1.0.0 

func GenerateReport(result *CheckResult, format string) (string, error)

GenerateReport generates a report in the specified format ("md", "html", or "json")

func GenerateSARIFReport added in v1.7.5 

func GenerateSARIFReport(result *CheckResult, version string) (string, error)

GenerateSARIFReport generates a SARIF v2.1.0 formatted security report

func GetGitAuthor added in v1.8.1 

func GetGitAuthor() string

GetGitAuthor returns the git author name from git config. Falls back to "User" if git config is unavailable.

func GradeBelowThreshold added in v1.7.8 

func GradeBelowThreshold(grade, threshold ScoreGrade) bool

GradeBelowThreshold returns true if grade is worse than the threshold

func WatchAndCheck added in v1.7.6 

func WatchAndCheck(ctx context.Context, skillPath string, callback func(event string, result *CheckResult, err error)) error

WatchAndCheck watches a skill directory for file changes and re-runs security checks. It blocks until the context is canceled or an unrecoverable error occurs. The callback is invoked after each check with the result (nil result on error).

Types

type CheckConfig added in v1.7.6 

type CheckConfig struct {
	// Ignore lists rule IDs to suppress (e.g., ["SECRET-GENERIC-TOKEN", "CMD-SUDO"])
	Ignore []string `yaml:"ignore"`
	// IgnorePaths lists file/directory glob patterns to skip (e.g., ["vendor/**", "*.test.js"])
	IgnorePaths []string `yaml:"ignore_paths"`
	// Rules defines additional custom rules
	Rules []CustomRuleDef `yaml:"rules"`

	// SkillBundled indicates the config was loaded from within a skill directory.
	// When true, CRITICAL severity built-in rules cannot be ignored.
	// This prevents a malicious skill from bundling a config that disables its own security audit.
	SkillBundled bool `yaml:"-"`
}

CheckConfig represents a .askcheck.yaml configuration file

func LoadCheckConfig added in v1.7.6 

func LoadCheckConfig(dir string) (*CheckConfig, error)

LoadCheckConfig loads .askcheck.yaml from the given directory. Returns nil (no error) if the file does not exist.

func (*CheckConfig) BuildRules added in v1.7.6 

func (cc *CheckConfig) BuildRules() []Rule

BuildRules returns the effective rule set: default rules (minus ignored) plus custom rules. When SkillBundled is true, built-in CRITICAL rules cannot be ignored.

func (*CheckConfig) IsPathIgnored added in v1.7.6 

func (cc *CheckConfig) IsPathIgnored(relPath string) bool

IsPathIgnored returns true if the relative path matches any ignore_paths pattern.

type CheckResult added in v1.0.0 

type CheckResult struct {
	SkillName      string
	Findings       []Finding
	ScannedModules []string // List of all modules scanned, including clean ones
}

CheckResult contains all findings for a skill

func CheckSafety added in v1.0.0 

func CheckSafety(skillPath string) (*CheckResult, error)

CheckSafety performs security checks on a skill directory. It loads .askcheck.yaml (if present) to support custom rules, rule ignoring, and path exclusions.

type CustomRuleDef added in v1.7.6 

type CustomRuleDef struct {
	ID          string `yaml:"id"`
	Pattern     string `yaml:"pattern"`
	Severity    string `yaml:"severity"`
	Description string `yaml:"description"`
}

CustomRuleDef represents a user-defined rule in .askcheck.yaml

type Deduction added in v1.7.8 

type Deduction struct {
	Reason string  `json:"reason"`
	Points float64 `json:"points"`
}

Deduction represents a single score deduction

type Finding added in v1.0.0 

type Finding struct {
	RuleID      string
	Severity    Severity
	Description string
	Module      string // The skill or module name where this finding occurred
	File        string
	Line        int
	Match       string
}

Finding represents a single security issue found in a skill

type Meta added in v1.0.0 

type Meta struct {
	Name          string            `yaml:"name"`
	Description   string            `yaml:"description"`
	Version       string            `yaml:"version"`
	Author        string            `yaml:"author"`
	Dependencies  []string          `yaml:"dependencies"`
	Tags          []string          `yaml:"tags"`
	License       string            `yaml:"license"`
	Compatibility string            `yaml:"compatibility"`
	Metadata      map[string]string `yaml:"metadata"`
	AllowedTools  []string          `yaml:"allowed-tools"`
}

Meta represents metadata parsed from SKILL.md

func ParseSkillMD 

func ParseSkillMD(skillPath string) (*Meta, error)

ParseSkillMD parses a SKILL.md file and extracts frontmatter metadata. Uses Lstat pre-check for symlinks, then open-then-fstat for size validation.

type PublisherInfo added in v1.7.8 

type PublisherInfo struct {
	Owner      string
	IsOrg      bool
	RepoStars  int
	AccountAge int // years
	HasLicense bool
	RepoForks  int
}

PublisherInfo holds metadata about the skill publisher

type Rule added in v1.0.0 

type Rule struct {
	ID          string
	Description string
	Severity    Severity
	Regex       *regexp.Regexp
	Entropy     float64 // Minimum entropy threshold (0 to ignore)
	Tags        []string
}

Rule represents a security check rule

type SARIFArtifactLocation added in v1.7.5 

type SARIFArtifactLocation struct {
	URI string `json:"uri"`
}

SARIFArtifactLocation represents the artifact (file) URI

type SARIFDriver added in v1.7.5 

type SARIFDriver struct {
	Name    string      `json:"name"`
	Version string      `json:"version"`
	Rules   []SARIFRule `json:"rules,omitempty"`
}

SARIFDriver represents the driver (scanner) information

type SARIFLocation added in v1.7.5 

type SARIFLocation struct {
	PhysicalLocation SARIFPhysicalLocation `json:"physicalLocation"`
}

SARIFLocation represents the location of a finding

type SARIFMessage added in v1.7.5 

type SARIFMessage struct {
	Text string `json:"text"`
}

SARIFMessage represents a text message in the SARIF report

type SARIFPhysicalLocation added in v1.7.5 

type SARIFPhysicalLocation struct {
	ArtifactLocation SARIFArtifactLocation `json:"artifactLocation"`
	Region           *SARIFRegion          `json:"region,omitempty"`
}

SARIFPhysicalLocation represents the physical file location

type SARIFRegion added in v1.7.5 

type SARIFRegion struct {
	StartLine int `json:"startLine"`
}

SARIFRegion represents a region within a file

type SARIFReport added in v1.7.5 

type SARIFReport struct {
	Schema  string     `json:"$schema"`
	Version string     `json:"version"`
	Runs    []SARIFRun `json:"runs"`
}

SARIFReport represents a SARIF v2.1.0 report

type SARIFResult added in v1.7.5 

type SARIFResult struct {
	RuleID    string          `json:"ruleId"`
	Level     string          `json:"level"`
	Message   SARIFMessage    `json:"message"`
	Locations []SARIFLocation `json:"locations,omitempty"`
}

SARIFResult represents a single finding result

type SARIFRule added in v1.7.5 

type SARIFRule struct {
	ID               string          `json:"id"`
	ShortDescription SARIFMessage    `json:"shortDescription"`
	DefaultConfig    SARIFRuleConfig `json:"defaultConfiguration"`
}

SARIFRule represents a rule definition in the SARIF report

type SARIFRuleConfig added in v1.7.5 

type SARIFRuleConfig struct {
	Level string `json:"level"`
}

SARIFRuleConfig represents the default configuration for a rule

type SARIFRun added in v1.7.5 

type SARIFRun struct {
	Tool    SARIFTool     `json:"tool"`
	Results []SARIFResult `json:"results"`
}

SARIFRun represents a single run in a SARIF report

type SARIFTool added in v1.7.5 

type SARIFTool struct {
	Driver SARIFDriver `json:"driver"`
}

SARIFTool represents the tool that produced the SARIF report

type ScanResult added in v1.5.1 

type ScanResult struct {
	Path string `json:"path"`
	Meta *Meta  `json:"meta"`
}

ScanResult represents a found skill on disk

func ScanDirectory added in v1.5.1 

func ScanDirectory(root string, limitDepth int) ([]ScanResult, error)

ScanDirectory recursively scans a directory for skills (directories containing SKILL.md) limitDepth prevents infinite recursion. Default recommendation: 3-5

type ScoreCategory added in v1.7.8 

type ScoreCategory struct {
	Name    string      `json:"name"`
	Score   float64     `json:"score"`   // 0-100
	Weight  float64     `json:"weight"`  // 0-1.0
	Details string      `json:"details"` // Human-readable explanation
	Deducts []Deduction `json:"deductions,omitempty"`
}

ScoreCategory represents a scored dimension

type ScoreGrade added in v1.7.8 

type ScoreGrade string

ScoreGrade represents the trust grade of a skill 

const (
	GradeA ScoreGrade = "A" // 90-100: Excellent
	GradeB ScoreGrade = "B" // 80-89: Good
	GradeC ScoreGrade = "C" // 70-79: Acceptable
	GradeD ScoreGrade = "D" // 60-69: Poor
	GradeF ScoreGrade = "F" // 0-59: Fail
)

Score grades from A (best) to F (worst)

type ScoreResult added in v1.7.8 

type ScoreResult struct {
	SkillName  string          `json:"skill_name"`
	TotalScore float64         `json:"total_score"` // 0-100 weighted
	Grade      ScoreGrade      `json:"grade"`
	Categories []ScoreCategory `json:"categories"`
	Summary    string          `json:"summary"`
	ScoredAt   time.Time       `json:"scored_at"`
}

ScoreResult contains the full trust score for a skill

func ScoreSkill added in v1.7.8 

func ScoreSkill(skillPath string, publisher *PublisherInfo) (*ScoreResult, error)

ScoreSkill computes a comprehensive trust score for a skill directory

type Severity added in v1.0.0 

type Severity string

Severity represents the severity of a security finding 

const (
	// SeverityInfo indicates informational findings
	SeverityInfo Severity = "INFO"
	// SeverityWarning indicates potential issues
	SeverityWarning Severity = "WARNING"
	// SeverityCritical indicates critical vulnerabilities
	SeverityCritical Severity = "CRITICAL"
)

type TemplateData added in v1.0.0 

type TemplateData struct {
	Name        string
	Description string
	Author      string
	Version     string
	Tags        []string
}

TemplateData holds data for the skill template

type ValidationError added in v1.6.0 

type ValidationError struct {
	Field    string
	Message  string
	Severity Severity
}

ValidationError represents a validation issue with a SKILL.md file

func ValidateMeta added in v1.6.0 

func ValidateMeta(meta *Meta, dirName string) []ValidationError

ValidateMeta validates the Meta struct against the Agent Skills specification https://agentskills.io/specification

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.