Documentation
¶
Overview ¶
Package agentskill is the single source of truth for the AI-agent skill and instruction files that describe how to use the azldev CLI. Everything is embedded in the binary, so the files written into a repo, the CLI output, and the MCP tool response are always in lock-step with the azldev version that produced them.
Mental model ¶
At heart this is "a few text files with find/replace": the text lives in content/*.md.tmpl, and the "replace" is Go text/template substitution of a small set of dynamic values (see Params). Two Go registries name the files and carry the bits that can't live in a single shared template:
- skills — each Skill is {Name, Description, bodyTemplate}. The body template under content/ holds the real, substantive guidance for one topic.
- instructions — each Instruction is {Name, ApplyTo, Description, Title, Intro, Skills}. An instruction is a lightweight, path-scoped pointer: its applyTo glob decides which files it covers, and it only tells the agent which skill(s) to read.
Put substantive content in a skill; keep instructions thin.
Two renderings of every skill ¶
A skill can be emitted two ways from the same registry entry:
- full body — the skill's own bodyTemplate (e.g. azldev.md.tmpl), the complete content. Used by 'docs agent show', the docs-agent-show MCP tool, and 'docs agent install --full'.
- redirect wrapper — one generic skill-wrapper.md.tmpl for all skills, a thin SKILL.md that points the agent at the docs-agent-show MCP tool for always-fresh content. This is the default on-disk file 'docs agent install' writes.
Because the redirect wrapper is generic, it cannot hard-code each skill's name and description in its front matter — they are handed to it as data. That is the only reason Skill.Description exists as a field rather than living in the template front matter: holding it once in the registry lets both the full body and the shared wrapper render the same name/description without duplicating the text. Instruction files work the same way: one shared instruction-wrapper.md.tmpl renders every instruction, so each instruction's Description/ApplyTo/etc. are data too.
Where a Description ends up ¶
renderSkill copies Skill.Description into the template data; the template (full body or shared wrapper) emits it as the YAML front-matter "description:" line, which agent runtimes read to decide whether to load the skill. renderInstruction does the same via the instruction wrapper. That front-matter line is the description's only destination.
Dynamic values (Params) ¶
Params is resolved by the 'docs agent' command and consumed by the Markdown templates and the provenance renderer:
- Version — passed only to the provenance renderer and recorded once in the central provenance file; it is not substituted into Markdown templates.
- TopLevelCommands — generated from the Cobra command tree, so the overview skill's command list never goes stale.
- Bindings — repo-specific paths (LockDir, UpstreamCommitsDir, RenderedSpecsDir, WorkDir) read from the target azldev.toml, degrading to azldev's defaults when no config is present.
Modes ¶
A Catalog selects the content for one of azldev's two modes. The default mode documents the lock-file workflow; the mode selected by the global '--without-lockfile' flag documents the generated upstream-commit workflow. Skills, instruction files, and emitted layout are shared; templates under 'content/withoutlockfile' replace the same-named default template, and a small registry replaces the skills whose subject differs.
Outputs (three sinks, one registry) ¶
skills[] / instructions[] --render(Params)--> install --> write files into a repo
+ content/*.md.tmpl show --> print to stdout
MCP --> docs-agent-show returns text
All three enumerate the same registries, so the on-disk files, the CLI, and the MCP tool cannot drift from one another. Installed trees record the generator version and full/wrapper mode once in a hidden JSON file at the skill-root directory.
Maintenance ¶
The rules for adding or editing a skill/instruction — front-matter limits, drift-guard tests, and the mandatory "validate every claim against the current code" step — live in .github/instructions/agent-skills.instructions.md.
Index ¶
Constants ¶
const ( // SkillName is the stable base identifier of the primary azldev skill. It is the // name passed to 'azldev docs agent show'. SkillName = "azldev" // ShowSkillToolName is the name of the read-only MCP tool that returns a skill // document. The emitted wrapper files point agents at this tool. ShowSkillToolName = "docs-agent-show" // ConfigGlob is the 'applyTo' glob for the azldev project-config instructions file; // it matches azldev project configuration files. ConfigGlob = "**/azldev.toml" )
Variables ¶
This section is empty.
Functions ¶
func InstructionFile ¶
func InstructionFile(inst Instruction) string
InstructionFile returns the repo-relative file path for an instruction.
Types ¶
type Bindings ¶
type Bindings struct {
// LockDir is the repo-relative directory holding per-component lock files.
// Only meaningful in azldev's default mode.
LockDir string
// UpstreamCommitsDir is the repo-relative directory holding the generated
// per-component commit TOMLs. Only meaningful in lock-file-free mode.
UpstreamCommitsDir string
// RenderedSpecsDir is the repo-relative directory holding rendered component specs.
RenderedSpecsDir string
// WorkDir is the repo-relative temporary working directory. Skills use it for
// throwaway scratch output so agents stay within the project's configured layout
// instead of writing to /tmp.
WorkDir string
}
Bindings are the target-repo values resolved from the repo's azldev.toml and injected into skill content. The caller (the 'docs agent' command) is responsible for populating every field: from a loaded configuration when one is available, or from azldev's built-in defaults when it is not, so the emitted documentation stays accurate for a default project even with no configuration present.
type Catalog ¶ added in v1.0.0
type Catalog struct {
// contains filtered or unexported fields
}
Catalog exposes the skills and instruction files for one of azldev's modes. The registries are shared; only the documents and pointers that describe how resolved component state is maintained differ.
func NewCatalog ¶ added in v1.0.0
NewCatalog returns the catalog for the selected mode. Pass true to describe lock-file-free mode, as selected by the global '--without-lockfile' flag.
func (Catalog) Files ¶ added in v1.0.0
Files renders the set of agent files to write into a target repository using the given layout. When full is true, each on-disk SKILL.md contains the complete skill document instead of a light MCP wrapper (useful when the azldev MCP server is not available in the target environment). Instruction files are always light wrappers that point at the relevant skills.
func (Catalog) FindSkill ¶ added in v1.0.0
FindSkill returns the catalog's skill with the given name.
func (Catalog) Instructions ¶ added in v1.0.0
func (c Catalog) Instructions() []Instruction
Instructions returns the catalog's instruction files in emission order.
func (Catalog) SkillDocument ¶ added in v1.0.0
SkillDocument renders the full document for the named skill. It is served verbatim by the read-only MCP tool and by 'azldev docs agent show'. The default layout is used since a served document has no on-disk directory.
type Command ¶
Command is a top-level azldev command with its one-line summary. The list is generated from the Cobra command tree so the overview skill's command list never goes stale.
type EmittedFile ¶
type EmittedFile struct {
// RelPath is the repository-relative destination path, always forward-slash separated.
RelPath string `json:"relPath"`
// Content is the fully rendered file content.
Content string `json:"-"`
}
EmittedFile is a single file to be written into a target repository.
type Instruction ¶
type Instruction struct {
// Name is the file-name stem; the emitted file is "<Name>.instructions.md".
Name string
// ApplyTo is the front-matter glob selecting the files this instruction applies to.
// It may reference binding fields (e.g. '{{ .RenderedSpecsDir }}') and is rendered
// against [Params] at emission time.
ApplyTo string
// Description is the front-matter description.
Description string
// Title is the body heading.
Title string
// Intro is the body's opening sentence describing the file kind.
Intro string
// Skills lists the skills this wrapper points agents at, in order, each with a purpose.
// The first skill is required for every matching file; remaining skills are loaded only when
// their purpose matches the task.
Skills []SkillPointer
}
Instruction describes a single emitted path-specific instruction file. Instruction files are lightweight wrappers, selected automatically by their 'applyTo' glob, that point agents at the relevant skill(s); the substantive, always-current guidance lives in the skills, keeping a single source of truth. An instruction only names the skills to read — how a skill's content is delivered (a thin wrapper served by docs-agent-show, or the full body inlined by '--full') is the skill's concern, not the instruction's.
func Instructions ¶
func Instructions() []Instruction
Instructions returns the registered instruction files in emission order for azldev's default mode.
type Layout ¶
type Layout struct {
// SkillsDir is the repo-relative parent directory that holds skill directories.
SkillsDir string
}
Layout controls where emitted skill files are written in a target repository.
func DefaultLayout ¶
func DefaultLayout() Layout
DefaultLayout returns the default emission layout: skills under the tool-neutral '.agents/skills' location from the Agent Skills open standard, and instructions under '.github/instructions'.
func (Layout) ProvenanceFile ¶ added in v1.0.0
ProvenanceFile returns the repo-relative path of the central generator provenance file.
type Params ¶
type Params struct {
// Version is the azldev version recorded in the generator provenance file.
Version string
// TopLevelCommands is the sorted list of top-level azldev commands with summaries.
TopLevelCommands []Command
// Bindings are the target-repo values resolved from the repo's configuration
// (or azldev defaults when none is available). Embedded so templates can reference
// its fields directly (e.g. '{{ .LockDir }}').
Bindings
}
Params carries the dynamic values injected into the emitted and served content.
type Skill ¶
type Skill struct {
// Name is the stable base identifier (lowercase, hyphen-delimited). It is the
// argument to 'azldev docs agent show' and the on-disk skill directory name.
Name string
// Description is the discovery text placed in the skill's front matter.
Description string
// contains filtered or unexported fields
}
Skill describes a single emitted Agent Skill.
type SkillPointer ¶
type SkillPointer struct {
// Skill is the name of the skill to read.
Skill string
// Purpose is a short phrase describing when to read the skill (e.g. "to add or
// change overlays"). It follows the skill name in the rendered wrapper.
Purpose string
}
SkillPointer names a skill an instruction file points at, together with a short purpose describing when to read it ("read the `azldev-overlays` skill to add or change overlays").
Source Files