Documentation
¶
Index ¶
- Constants
- func FallbackSkillDescriptions(commands []SkillCommand) []string
- func RemoveSkill(path string) error
- func RenderCommandSkill(c SkillCommand) string
- func RenderRootSkill(meta SkillMetadata, commands []SkillCommand) string
- func Skill(ctx context.Context, v any, name string) string
- func SkillsPath(path string) string
- func WriteSkill(path string, meta SkillMetadata, commands []SkillCommand) ([]string, error)
- type ArgInfo
- type Catalog
- type CommandInfo
- type Completer
- type FlagInfo
- type Lister
- type Plugin
- type Provider
- type SkillCommand
- type SkillLister
- type SkillMetadata
- type SkillMetadataer
Constants ¶
const ( RootSkillName = "posh" CommandSkillPrefix = "posh-" )
Skill directory naming. The root skill is RootSkillName; every command gets CommandSkillPrefix + its name.
The prefix is the uninstall contract: `agent skill uninstall` removes what matches it and nothing else, so a hand-written skill sitting in the same directory survives. Keeping it a constant shared by writer and remover is what stops the two from drifting - a manifest would be the alternative, but it is extra on-disk state that can itself go stale.
const CatalogSchemaVersion = "3"
CatalogSchemaVersion is the current version of the Catalog shape.
const CatalogType = "posh.command_catalog"
CatalogType is the discriminator carried by Catalog.
const DefaultSkillsPath = ".claude/skills"
DefaultSkillsPath is the skills directory `posh agent skill install` writes into unless given an explicit path.
Variables ¶
This section is empty.
Functions ¶
func FallbackSkillDescriptions ¶ added in v0.22.0
func FallbackSkillDescriptions(commands []SkillCommand) []string
FallbackSkillDescriptions returns the paths of the commands that did not supply a frontmatter description, so a caller can report the gap rather than let it pass silently.
The description is the only thing an agent runtime matches a request against, so a derived one usually means that command's skill never loads.
func RemoveSkill ¶ added in v0.21.0
RemoveSkill deletes every generated skill directory under the skills directory at path, falling back to DefaultSkillsPath when empty.
Only the root skill and directories carrying CommandSkillPrefix are removed, so a hand-written skill in the same directory survives. A missing directory is not an error, so uninstall is idempotent - and it deliberately needs no config or resolved plugin, so cleanup still works when the shell itself is broken.
func RenderCommandSkill ¶ added in v0.22.0
func RenderCommandSkill(c SkillCommand) string
RenderCommandSkill renders one command's own SKILL.md: its runnable paths and whatever prose it contributes.
func RenderRootSkill ¶ added in v0.22.0
func RenderRootSkill(meta SkillMetadata, commands []SkillCommand) string
RenderRootSkill renders the root SKILL.md: how to invoke posh, how to set it up, and an index of every command.
It deliberately carries no per-command detail and no hazard prose. Nothing routes off it - each command that has more to say gets its own skill, which an agent loads on its own - so the root stays small enough to be worth loading unconditionally.
func Skill ¶ added in v0.21.0
Skill returns the extra SKILL.md markdown a command contributes under name, see command.Skill.
func SkillsPath ¶ added in v0.22.0
SkillsPath resolves a user supplied skills directory, falling back to DefaultSkillsPath when empty.
func WriteSkill ¶ added in v0.21.0
func WriteSkill(path string, meta SkillMetadata, commands []SkillCommand) ([]string, error)
WriteSkill generates the root skill and one skill per command into the skills directory at path, creating it if needed. Passing an empty path writes to DefaultSkillsPath.
One skill per command rather than one file for all of them: a single file means an agent pays for every command in the project in order to use one. Only commands that Describes() get their own; the rest are covered by the root skill's index.
Previously generated skills are removed first, so a command that was renamed or dropped since the last run leaves nothing behind - regenerating is what keeps the result honest, and a stale directory would otherwise survive indefinitely because nothing ever revisits it. Hand-written skills alongside them are untouched, see CommandSkillPrefix.
It returns the paths written, in the order written.
Types ¶
type Catalog ¶ added in v0.21.0
type Catalog struct {
Type string `json:"type"`
SchemaVersion string `json:"schema_version"`
Commands []CommandInfo `json:"commands"`
}
Catalog is the payload of `posh agent catalog`.
Unlike command results, which are emitted bare, the catalog keeps its type/schema_version discriminator: the shape is a published contract mirroring other agent-facing CLIs, and consumers dispatch on the marker.
func NewCatalog ¶ added in v0.21.0
func NewCatalog(commands []CommandInfo) Catalog
NewCatalog wraps commands in a Catalog with the current type and version.
type CommandInfo ¶ added in v0.21.0
type CommandInfo = command.CommandInfo
CommandInfo describes one command for the `posh agent catalog` catalog.
func Describe ¶ added in v0.21.0
func Describe(ctx context.Context, name, description string, v any) CommandInfo
Describe builds a CommandInfo for a single command, see command.Describe.
func List ¶ added in v0.21.0
func List(ctx context.Context, plg any) ([]CommandInfo, error)
List asks plg for its command catalog, requiring the optional Lister interface. It returns a descriptive error when the plugin does not implement it, rather than leaving callers to repeat the type assertion.
Resolving the plugin itself is the caller's job: the posh CLI holds its provider in package state, and a downstream shell may have one in hand already.
type Completer ¶ added in v0.19.0
type Completer interface {
Complete(ctx context.Context, args []string, toComplete string) []string
}
Completer is an optional Plugin extension that produces shell completion suggestions for `posh execute`. Returned strings use the cobra format: "value\tdescription" (description optional).
type Lister ¶ added in v0.21.0
type Lister interface {
List(ctx context.Context) []CommandInfo
}
Lister is an optional Plugin extension that exposes the catalog of commands, used by `posh agent catalog` to give an AI coding agent a machine-readable answer to "what can I run" without parsing human-formatted help text.
type SkillCommand ¶ added in v0.21.0
type SkillCommand struct {
CommandInfo
// Skill is the markdown contributed by command.Skiller, or empty.
Skill string
// Metadata is the frontmatter contributed by command.SkillMetadataer. Unset
// fields fall back to values derived from the command.
Metadata SkillMetadata
}
SkillCommand pairs a described command with the extra markdown and frontmatter its command.Skiller and command.SkillMetadataer implementations contributed, if any.
The catalog shape stays untouched: skill prose is a rendering concern, so it rides alongside CommandInfo rather than inside it.
func ListSkill ¶ added in v0.21.0
func ListSkill(ctx context.Context, plg any) ([]SkillCommand, error)
ListSkill asks plg for its command catalog together with the extra SKILL.md markdown each command contributes.
A plugin implementing only Lister falls back to a catalog without prose, so the skill still renders for shells that have not opted in.
func (SkillCommand) Describes ¶ added in v0.22.0
func (c SkillCommand) Describes() bool
Describes reports whether a command says anything a skill of its own is worth spending tokens on: prose from command.Skiller, or a subcommand tree whose runnable leaf paths a flat index cannot show.
Arguments and flags deliberately do not count. A skill never prints them - it points at `posh agent catalog` and `posh help` instead, see skillDetails - so a command whose only structure is an argument list would get a file saying nothing its index entry does not already say.
The test is deliberately structural rather than "does it implement the interfaces". command.Describe already collapses a non-Describer into a CommandInfo carrying only a path and description, so by the time it arrives here a command that never opted in is indistinguishable from a Describer that legitimately describes a bare leaf - and both are equally uninformative.
A command that fails the test still appears in the root skill's index with its name and description; it just does not get a skill of its own.
func (SkillCommand) SkillName ¶ added in v0.22.0
func (c SkillCommand) SkillName() string
SkillName is the directory name this command's skill is generated into.
type SkillLister ¶ added in v0.21.0
type SkillLister interface {
ListSkill(ctx context.Context) []SkillCommand
}
SkillLister is an optional Plugin extension that lists commands together with the extra SKILL.md markdown each one contributes via command.Skiller.
A plugin implementing only Lister still renders a skill, just without the extra prose.
type SkillMetadata ¶ added in v0.21.0
type SkillMetadata = command.SkillMetadata
SkillMetadata is the frontmatter of a generated SKILL.md. It lives in pkg/command so a command can supply its own, see command.SkillMetadataer.
func SkillMetadataFor ¶ added in v0.22.0
func SkillMetadataFor(ctx context.Context, v any, name string) SkillMetadata
SkillMetadataFor returns the frontmatter a command supplies for its own generated skill, see command.SkillMetadataOf.
It is named apart from SkillMetadataOf, which answers the same question for a plugin: both take an `any`, so one name for both would resolve by accident rather than by intent.
func SkillMetadataOf ¶ added in v0.21.0
func SkillMetadataOf(ctx context.Context, plg any) SkillMetadata
SkillMetadataOf returns the root SKILL.md frontmatter plg supplies, or the zero value - which renders posh's defaults - when it does not implement SkillMetadataer.
This is the plugin-level frontmatter, covering the root skill only. A command supplies its own through command.SkillMetadataer.
type SkillMetadataer ¶ added in v0.21.0
type SkillMetadataer interface {
SkillMetadata(ctx context.Context) SkillMetadata
}
SkillMetadataer is an optional Plugin extension supplying the generated SKILL.md frontmatter. Unset fields fall back to posh's defaults.
Source Files