cli

type ListSkillsOptions struct {
	// IncludeMigrationSkills opts relevance=migration skills back into
	// the listing (e.g. for an upgrade-assistant surface).
	IncludeMigrationSkills bool
}

type Skill struct {
	// Path is the skill identifier (e.g. "db", "frontend/state").
	Path string
	// Name is the human-readable name from the SKILL.md frontmatter.
	Name string
	// Description is the one-line summary from the SKILL.md frontmatter.
	Description string
	// Scope is where the skill was discovered: "forge", "project", or "user".
	Scope string
	// Emit declares which audience the skill targets — "forge" (framework
	// skills, default when frontmatter omits the field), "general"
	// (methodology that applies to any project), or "both" (mixed
	// content, with framework-specific portions inside @forge-only
	// blocks the renderer strips for general audiences). Consumers use
	// this to decide whether to surface a skill outside a forge project.
	Emit string
	// Relevance classifies when the skill is worth surfacing: "" (always —
	// the default) or "migration" (a one-time upgrade-transition playbook).
	// ListSkills excludes relevance=migration skills; ListSkillsWithOptions
	// can opt them back in. Consumers building their own retrieval layer
	// should treat migration skills as transition-scoped, not steady-state.
	Relevance string
	// AppliesFrom / AppliesTo are the migration skill's declared version
	// bounds (half-open [from, to) over the project's pinned forge_version),
	// passed through verbatim from the `applies-from:` / `applies-to:`
	// frontmatter for consumers that want to do their own version gating.
	// Forge itself gates listings on the relevance class only (binary
	// versions are routinely dev builds / pseudo-versions, which are not
	// meaningfully comparable); the authoritative project-aware range +
	// detection gate is `forge upgrade list`. Empty when undeclared.
	AppliesFrom string
	AppliesTo   string

	// SkillForgeVersion is the forge version whose embedded templates the
	// skill content comes from — i.e. the forge module linked into THIS
	// process, not the project's pin. Empty for project/user-scope skills.
	SkillForgeVersion string
	// ProjectForgeVersion is the forge_version pinned in the project's
	// forge.yaml ("" when projectRoot was empty, no pin is declared, or the
	// file could not be read).
	ProjectForgeVersion string
	// VersionSkew is true when the serving forge version and the project's
	// pin are both real release versions and differ. Harness consumers
	// should surface skewed skills with caution: the guidance may describe
	// a different forge version than the one that generated the project.
	VersionSkew bool
}