Tools, skills, and the lifecycle of repository instructions

A tool provides an executable capability such as searching files, running a command, or applying a patch. A skill packages reusable instructions and sometimes supporting scripts or reference material for a particular workflow. It can tell an agent how to perform a review, but it does not grant operating-system access by itself. The launcher and tool broker still enforce actual permissions.

This distinction helps diagnose failures. If the agent knows the correct test command but cannot access the environment, the problem is capability or setup. If it can run commands but repeatedly chooses the wrong validation, the problem may be guidance or context. More instruction text cannot repair a missing dependency automatically, and a more powerful shell does not ensure the agent understands the repository's conventions. Treat both interfaces as parts of an engineered workflow.

The Agent Skills specification describes a directory with a SKILL.md file and optional supporting resources. A practical lifecycle begins with lightweight metadata so the agent can identify relevant guidance, then loads the full instructions when the task warrants it. This limits context consumption while keeping specialized procedures available. Selection should depend on the actual work, not merely a keyword appearing in a user message.

Record the source and version of loaded guidance. If a skill invokes a script, inspect its contract and ensure it matches the repository and runtime. Guidance can become stale when commands, file paths, or APIs change. The example hashes a small instruction bundle and demonstrates that changing a test command changes its identity. A hash helps detect a changed bundle; it does not establish trust, correctness, or permission to execute every command in it.

Repositories may use AGENTS.md to explain setup, coding conventions, test commands, and review expectations. Instruction scope and precedence depend on the agent product, so check its documented rules rather than inventing a universal hierarchy. Within that hierarchy, repository guidance should help implement the user's task and must not become an excuse to expand authority beyond what was granted.

A downloaded example file or a comment inside an issue can contain imperative text, but that does not automatically make it an instruction source. Keep trusted workflow guidance separate from arbitrary repository data and tool output. If an unfamiliar instruction asks for secrets, external publication, or unrelated changes, evaluate its authority and scope before acting. A markdown extension is a format, not a trust signal. This matters because coding agents routinely read files that someone else can modify.

Instruction changes can alter tool selection, patch size, approval behavior, and test coverage even when no application code changes. Version them and review their effects. A useful instruction explains a concrete repository fact, such as the supported environment command or where integration tests live. Vague mandates like always be perfect add little actionable information and can compete with more precise guidance.

Test a proposed instruction on representative tasks. For example, a new requirement to run all integration tests may catch regressions but also fail on machines lacking credentials. Clarify the actual required gate and the documented fallback, while preserving any necessary approval boundary. Compare task completion, command failures, and unnecessary user interruptions before and after the change. An instruction package is maintained software-facing documentation, not a magical optimization that improves every task simply by being longer.

A coding run should be able to report which guidance influenced its decisions, which files were changed, and which checks established the result. Store references or content hashes where appropriate so a later investigation can distinguish a code regression from a changed instruction bundle. When a task resumes after a checkpoint, verify that important instructions still correspond to the current repository version.

The code below implements a tiny in-memory catalog and explicit activation. It is not a full Agent Skills loader: it does not parse frontmatter, resolve resources, enforce precedence, or run scripts. Those are deliberate extension points. The learning goal is lifecycle discipline: discover the right guidance, load its actual content, apply it within the existing authority model, and validate the resulting behavior. The same discipline prevents a cached summary from silently overriding a corrected instruction.

The catalog separates brief discovery metadata from activated instructions and detects a changed bundle. All strings are local teaching fixtures. This is not a conforming Agent Skills parser or an authorization mechanism.