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.
Substituted values (Params) ¶
The {{ .Field }} placeholders in the templates are filled from Params, resolved by the 'docs agent' command:
- Version — the azldev version stamped into every file.
- TopLevelCommands — generated from the Cobra command tree, so the overview skill's command list never goes stale.
- Bindings — repo-specific paths (LockDir, RenderedSpecsDir, WorkDir) read from the target azldev.toml, degrading to azldev's defaults when no config is present.
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.
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.
func SkillDocument ¶
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.
Types ¶
type Bindings ¶
type Bindings struct {
// LockDir is the repo-relative directory holding per-component lock files.
LockDir 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 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.
func Files ¶
func Files(layout Layout, params Params, full bool) ([]EmittedFile, error)
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.
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.
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'.
type Params ¶
type Params struct {
// Version is the azldev version stamped into the generated content.
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