Evaluate flow

The evaluate command is the primary entry point for scoring a single skill.

Resolution chain

User input (path or key)
    │
    ▼
resolveRepoRoot(flag)
    │   Uses `--repo-root` flag or walks up from CWD
    │   looking for .git/ or go.mod
    ▼
resolveSkillPath(arg, repoRoot)
    │   ├── Absolute path / ./ / ../ prefix → used directly
    │   ├── Bare "domain/skill-name"        → <repoRoot>/skills/domain/skill-name/SKILL.md
    │   └── Appends SKILL.md if not present
    ▼
canonicalSkillKey(path, root)
        Strips <repoRoot>/skills/ prefix and SKILL.md suffix
        → "domain/skill-name"

Source: cmd/evaluate.go

Core scoring pipeline

scorer.Score(ctx, skillPath)
  │
  ├── ioutil.ReadFile(skillPath)         → skill content (string)
  ├── resolveEvalsDir(skillPath)         → evals directory
  │
  └── scorer.ScoreFromContent(ctx, skillPath, content, evalsDir)
        │
        ├── newValidatorBridge(skillDir)
        │     ├── orchestrate.RunContentAnalysis(skillDir)
        │     └── structure.Validate(skillDir, options)
        │     → ContentReport + Structure (cached)
        │
        ├── builds dimensionEntry registry (D1–D9)
        │
        ├── for each entry:
        │     ├── entry.fn(content, skillDir, bridge) → (score, []Diagnostic)
        │     ├── accumulate total += score
        │     └── collect diagnostics
        │
        └── returns Result{
              Skill, Date, Total, MaxTotal, Grade,
              Lines, HasReferences, ReferenceCount,
              Errors, Warnings,
              ErrorDetails, WarningDetails,
              Dimensions map[string]int
            }

Source: scorer/scorer.go

Validator bridge

The validatorBridge wraps the external github.com/agent-ecosystem/skill-validator library:

• newValidatorBridge(skillDir) runs content analysis and structure validation
• Results are cached and accessed lazily by dimension scorers
• Key accessors: skillMDTokens(), descriptionLen(), rawDescription(), hasInternalLinkWarning()

Source: scorer/validator_bridge.go

Dimension execution order

Each scorer returns (int, []Diagnostic) — a numeric score and a slice of error/warning/hint diagnostics.

Source: scorer/dimensions.go (registry), individual scorer/dN_*.go files

Grade bands

Max total: 140pts.

Source: scorer/grades.go

Output

• Default: JSON to stdout
• --markdown flag: human-readable text
• --store flag: persists to .context/audits/<skill-key>/<date>/
  • audit.json — raw scorer.Result
  • Analysis.md — rendered markdown report
  • Remediation.md — simple remediation advice

Source: cmd/evaluate.go, reporter/store.go