cli

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

type RenderSkillOptions struct {
	// Audience filters the body the same way as [LoadSkillForAudience]:
	// "general" strips `@forge-only` blocks, "forge" or "" keeps the full
	// body (which is what `skill load` prints).
	Audience string
	// CLIName is the command a reader types to invoke forge — "forge" for
	// the standalone binary, "reliant forge" when forge is mounted inside
	// reliant. Every bare `forge ` command reference in the body is
	// rewritten to it. "" means the name this process reports for itself,
	// the same one [RenderProjectMemory] renders, so a harness that injects
	// both gets one consistent spelling.
	CLIName string
}

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
	// Version is the release that introduced the breaking change this
	// migration skill covers, passed through verbatim from the `version:`
	// frontmatter for consumers that want to do their own version gating.
	// A project needs the migration when its pin is BELOW this version and
	// it still exhibits the old shape.
	//
	// 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 version +
	// detection gate is `forge project upgrade list`. Empty when undeclared
	// and for non-migration skills.
	Version 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
}