docs(agentskill): describe lock-file-free mode in agent skills

Emit agent skills and instruction files that match the mode azldev is
running in. A catalog selects the content: the default mode keeps the
lock-file workflow and the azldev-update-component skill, while
lock-file-free mode documents the generated upstream-commit workflow and
the azldev-refresh-upstream-commit skill.

Skills, instruction wrappers, and the emitted layout are shared. Only the
documents whose subject differs get a mode-specific template, layered over
the default template of the same name, and a small registry replaces the
skill entries and instruction trigger text that name the command. The
bindings injected into the content now carry both the lock directory and
the generated upstream-commit directory.

'docs agent install' and 'docs agent show' select the catalog from the
environment, so the emitted files, the served skill documents, and the
read-only MCP tool all describe the commands the user actually has.

Refs: microsoft#323

Author: Copilot

.github/instructions/agent-skills.instructions.md

@@ -65,9 +65,32 @@ Before shipping any skill/instruction:
   `TestOverlaysSkillCoversAllOverlayTypes` extracts the overlay-type enum from the jsonschema tag
   on `projectconfig.ComponentOverlay.Type` and fails if the skill omits a type.
 
+## Mode-specific content
+
+azldev has two modes, and the emitted content follows the one it runs in. A `Catalog`
+(`NewCatalog(withoutLockfile)`) resolves the skills, instruction wrappers, and templates;
+the package-level `Skills`, `Instructions`, `FindSkill`, `SkillDocument`, and `Files`
+helpers are the default (lock-file) mode.
+
+- **Shared by default.** Registry entries and templates under `content/` describe the
+  default mode and are used by both, so most edits need nothing extra.
+- **Replace only what differs.** `withoutLockfileSkills` replaces registry entries by the
+  name of the default-mode skill it supersedes, and `withoutLockfileInstructions` replaces
+  instruction descriptions. Pointers to a replaced skill are rewritten automatically.
+- **Templates layer.** A template under `content/withoutlockfile/` replaces the
+  same-named default template for that mode; add one only when the document's content
+  actually differs.
+
+When you add or edit a skill, check whether its content names a command that exists in
+only one mode (for example `comp update` versus `comp refresh-upstream-commit`) and, if
+so, provide the mode-specific variant. Verify both with
+`./out/bin/azldev docs agent show --skill <name>` and
+`./out/bin/azldev --without-lockfile docs agent show --skill <name>`.
+
 ## Config-resolved bindings
 
-Repo-specific values (lock dir, rendered-specs dir, work dir) are resolved from the target `azldev.toml` in
+Repo-specific values (lock dir, generated upstream-commit dir, rendered-specs dir, work
+dir) are resolved from the target `azldev.toml` in
 [cmds/docs/agent.go](../../internal/app/azldev/cmds/docs/agent.go) and degrade to azldev's defaults
 when no config is present. To add a binding, extend `Bindings`, resolve it in `resolveBindings`, and
 reference it in a template as `{{ .FieldName }}`.

internal/app/azldev/agentskill/agentskill.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"path"
 	"slices"
+	"strings"
 	"text/template"
 )
 
@@ -31,16 +32,27 @@ const (
 )
 
 // The embedded templates rendered into the emitted files and the served skill
-// documents.
+// documents. Templates under 'content/withoutlockfile' replace the same-named
+// template when lock-file-free mode is selected.
 //
-//go:embed content/*.tmpl
+//go:embed content/*.tmpl content/withoutlockfile/*.tmpl
 var content embed.FS
 
-// templates holds all parsed templates, keyed by their base file name.
+// templates holds all parsed templates for azldev's default mode, keyed by their
+// base file name.
 //
 //nolint:gochecknoglobals // parsed templates are effectively constant and safe for concurrent use.
 var templates = template.Must(template.ParseFS(content, "content/*.tmpl"))
 
+// withoutLockfileTemplates holds the same templates with the lock-file-free
+// variants layered on top: parsing a template whose base name already exists
+// replaces it, so only the differing documents need their own file.
+//
+//nolint:gochecknoglobals // parsed templates are effectively constant and safe for concurrent use.
+var withoutLockfileTemplates = template.Must(template.ParseFS(
+	content, "content/*.tmpl", "content/withoutlockfile/*.tmpl",
+))
+
 // Skill describes a single emitted Agent Skill.
 type Skill struct {
 	// Name is the stable base identifier (lowercase, hyphen-delimited). It is the
@@ -156,14 +168,81 @@ var skills = []Skill{
 	},
 }
 
-// Skills returns the registered skills in emission order.
-func Skills() []Skill {
-	return slices.Clone(skills)
+// withoutLockfileSkills replaces registry entries when lock-file-free mode is
+// selected, keyed by the name of the default-mode skill it replaces. Everything
+// else — order, remaining skills, and the emitted layout — is shared.
+//
+//nolint:gochecknoglobals // effectively a constant registry of the mode's skills.
+var withoutLockfileSkills = map[string]Skill{
+	"azldev": {
+		Name: "azldev",
+		Description: "Read this before running azldev or editing azldev config, and whenever working " +
+			"in a repo that contains an azldev.toml file; do not guess azldev's commands or config. " +
+			"Explains how to use the azldev CLI to build a distro from TOML config, including the core " +
+			"concepts (components, overlays, distros, rendered specs, upstream commit config), running " +
+			"azldev (repo root or -C, plus the -q and -O json flags), the common commands, and where to " +
+			"go for each workflow. Triggers include azldev, comp build, comp render, " +
+			"comp refresh-upstream-commit, build a component, add a component, distro config.",
+		bodyTemplate: "azldev.md.tmpl",
+	},
+	"azldev-update-component": {
+		Name: "azldev-refresh-upstream-commit",
+		Description: "Read this before finalizing a component change, changing source resolution, or " +
+			"editing generated upstream commit TOML by hand. Explains how to refresh commits with " +
+			"'azldev comp refresh-upstream-commit', covering when to refresh versus render, the " +
+			"update/render/commit/re-render/amend workflow, and per-component versus -a refresh. " +
+			"Triggers include comp refresh-upstream-commit, refresh upstream commit, bump pin, change " +
+			"snapshot, upstream distro, commit drift, version bump, finalize component.",
+		bodyTemplate: "refresh-upstream-commit.md.tmpl",
+	},
 }
 
-// FindSkill returns the registered skill with the given name.
-func FindSkill(name string) (Skill, error) {
-	for _, skill := range skills {
+// updateComponentSkillName is the default mode's finalization skill; lock-file-free
+// mode replaces it with the refresh-upstream-commit skill.
+const updateComponentSkillName = "azldev-update-component"
+
+// 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.
+type Catalog struct {
+	withoutLockfile bool
+}
+
+// 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 NewCatalog(withoutLockfile bool) Catalog {
+	return Catalog{withoutLockfile: withoutLockfile}
+}
+
+// templates returns the parsed template set for the catalog's mode.
+func (c Catalog) templates() *template.Template {
+	if c.withoutLockfile {
+		return withoutLockfileTemplates
+	}
+
+	return templates
+}
+
+// Skills returns the catalog's skills in emission order.
+func (c Catalog) Skills() []Skill {
+	result := slices.Clone(skills)
+
+	if !c.withoutLockfile {
+		return result
+	}
+
+	for idx := range result {
+		if replacement, ok := withoutLockfileSkills[result[idx].Name]; ok {
+			result[idx] = replacement
+		}
+	}
+
+	return result
+}
+
+// FindSkill returns the catalog's skill with the given name.
+func (c Catalog) FindSkill(name string) (Skill, error) {
+	for _, skill := range c.Skills() {
 		if skill.Name == name {
 			return skill, nil
 		}
@@ -172,6 +251,48 @@ func FindSkill(name string) (Skill, error) {
 	return Skill{}, fmt.Errorf("unknown skill %#q", name)
 }
 
+// Instructions returns the catalog's instruction files in emission order.
+func (c Catalog) Instructions() []Instruction {
+	result := slices.Clone(instructions)
+	for idx := range result {
+		result[idx].Skills = slices.Clone(result[idx].Skills)
+	}
+
+	if !c.withoutLockfile {
+		return result
+	}
+
+	refresh := withoutLockfileSkills[updateComponentSkillName]
+
+	for instIdx := range result {
+		if replacement, ok := withoutLockfileInstructions[result[instIdx].Name]; ok {
+			result[instIdx].Description = replacement.Description
+		}
+
+		for skillIdx := range result[instIdx].Skills {
+			pointer := &result[instIdx].Skills[skillIdx]
+			if pointer.Skill != updateComponentSkillName {
+				continue
+			}
+
+			pointer.Skill = refresh.Name
+			pointer.Purpose = strings.ReplaceAll(pointer.Purpose, "lock", "upstream commit")
+		}
+	}
+
+	return result
+}
+
+// Skills returns the registered skills in emission order for azldev's default mode.
+func Skills() []Skill {
+	return NewCatalog(false).Skills()
+}
+
+// FindSkill returns the registered skill with the given name in azldev's default mode.
+func FindSkill(name string) (Skill, error) {
+	return NewCatalog(false).FindSkill(name)
+}
+
 // 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").
@@ -268,14 +389,24 @@ var instructions = []Instruction{
 	},
 }
 
-// Instructions returns the registered instruction files in emission order.
-func Instructions() []Instruction {
-	result := slices.Clone(instructions)
-	for i := range result {
-		result[i].Skills = slices.Clone(result[i].Skills)
-	}
+// withoutLockfileInstructions replaces instruction descriptions when lock-file-free
+// mode is selected, keyed by instruction name. Skill pointers are rewritten
+// automatically, so only the free-form trigger text lives here.
+//
+//nolint:gochecknoglobals // effectively a constant registry of the mode's instructions.
+var withoutLockfileInstructions = map[string]Instruction{
+	SkillName: {
+		Description: "This repo is an azldev distro project (azldev.toml present). Before running azldev " +
+			"or editing its config, load the azldev skill; do not guess azldev's commands or config. " +
+			"Triggers include azldev, comp build, comp render, comp refresh-upstream-commit, build a " +
+			"component, add a component, distro config.",
+	},
+}
 
-	return result
+// Instructions returns the registered instruction files in emission order for
+// azldev's default mode.
+func Instructions() []Instruction {
+	return NewCatalog(false).Instructions()
 }
 
 // Layout controls where emitted skill files are written in a target repository.
@@ -322,8 +453,13 @@ type Command struct {
 // accurate for a default project even with no configuration present.
 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
 
@@ -356,7 +492,7 @@ type EmittedFile struct {
 	Content string `json:"-"`
 }
 
-func renderSkill(templateName string, skill Skill, params Params) (string, error) {
+func (c Catalog) renderSkill(templateName string, skill Skill, params Params) (string, error) {
 	var buf bytes.Buffer
 
 	data := struct {
@@ -369,16 +505,16 @@ func renderSkill(templateName string, skill Skill, params Params) (string, error
 		ShowSkillToolName: ShowSkillToolName,
 	}
 
-	err := templates.ExecuteTemplate(&buf, templateName, data)
+	err := c.templates().ExecuteTemplate(&buf, templateName, data)
 	if err != nil {
 		return "", fmt.Errorf("failed to render agent skill template %#q:\n%w", templateName, err)
 	}
 
 	return buf.String(), nil
 }
 
-func renderInstruction(inst Instruction, params Params) (string, error) {
-	if err := validateInstruction(inst); err != nil {
+func (c Catalog) renderInstruction(inst Instruction, params Params) (string, error) {
+	if err := c.validateInstruction(inst); err != nil {
 		return "", err
 	}
 
@@ -398,21 +534,21 @@ func renderInstruction(inst Instruction, params Params) (string, error) {
 		Instruction: inst,
 	}
 
-	err = templates.ExecuteTemplate(&buf, "instruction-wrapper.md.tmpl", data)
+	err = c.templates().ExecuteTemplate(&buf, "instruction-wrapper.md.tmpl", data)
 	if err != nil {
 		return "", fmt.Errorf("failed to render instruction template for %#q:\n%w", inst.Name, err)
 	}
 
 	return buf.String(), nil
 }
 
-func validateInstruction(inst Instruction) error {
+func (c Catalog) validateInstruction(inst Instruction) error {
 	if len(inst.Skills) == 0 {
 		return fmt.Errorf("instruction %#q must reference at least one skill", inst.Name)
 	}
 
 	for _, pointer := range inst.Skills {
-		if _, err := FindSkill(pointer.Skill); err != nil {
+		if _, err := c.FindSkill(pointer.Skill); err != nil {
 			return fmt.Errorf("instruction %#q references unknown skill %#q:\n%w",
 				inst.Name, pointer.Skill, err)
 		}
@@ -442,39 +578,46 @@ func renderInline(name, text string, params Params) (string, error) {
 // 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.
-func SkillDocument(name string, params Params) (string, error) {
-	skill, err := FindSkill(name)
+func (c Catalog) SkillDocument(name string, params Params) (string, error) {
+	skill, err := c.FindSkill(name)
 	if err != nil {
 		return "", err
 	}
 
-	return renderSkill(skill.bodyTemplate, skill, params)
+	return c.renderSkill(skill.bodyTemplate, skill, params)
+}
+
+// SkillDocument renders the named skill's document for azldev's default mode.
+func SkillDocument(name string, params Params) (string, error) {
+	return NewCatalog(false).SkillDocument(name, params)
 }
 
 // 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 Files(layout Layout, params Params, full bool) ([]EmittedFile, error) {
-	files := make([]EmittedFile, 0, len(skills)+len(instructions))
+func (c Catalog) Files(layout Layout, params Params, full bool) ([]EmittedFile, error) {
+	catalogSkills := c.Skills()
+	catalogInstructions := c.Instructions()
+	files := make([]EmittedFile, 0, len(catalogSkills)+len(catalogInstructions))
 
-	for _, skill := range skills {
+	for _, skill := range catalogSkills {
 		templateName := "skill-wrapper.md.tmpl"
 		if full {
 			templateName = skill.bodyTemplate
 		}
 
-		rendered, err := renderSkill(templateName, skill, params)
+		rendered, err := c.renderSkill(templateName, skill, params)
 		if err != nil {
 			return nil, err
 		}
 
 		files = append(files, EmittedFile{RelPath: layout.SkillFile(skill), Content: rendered})
 	}
 
-	for _, inst := range instructions {
-		rendered, err := renderInstruction(inst, params)
+	for _, inst := range catalogInstructions {
+		rendered, err := c.renderInstruction(inst, params)
 		if err != nil {
 			return nil, err
 		}
@@ -484,3 +627,8 @@ func Files(layout Layout, params Params, full bool) ([]EmittedFile, error) {
 
 	return files, nil
 }
+
+// Files renders the agent files for azldev's default mode.
+func Files(layout Layout, params Params, full bool) ([]EmittedFile, error) {
+	return NewCatalog(false).Files(layout, params, full)
+}

internal/app/azldev/agentskill/agentskill_internal_test.go

@@ -31,7 +31,7 @@ func TestRenderInstructionRejectsInvalidSkillPointers(t *testing.T) {
 
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
-			_, err := renderInstruction(Instruction{
+			_, err := NewCatalog(false).renderInstruction(Instruction{
 				Name:   "test-instruction",
 				Skills: test.skills,
 			}, Params{})