Agent Skills: Git Operations

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• dev/guidelines/git-workflow.md
• dev/adr/0001-adopt-canonical-agentic-structure.md
• skills-lock.json
• tasks.py
• pyproject.toml

Agent Skills for Git Operations define the automated and semi-automated workflows used by AI coding assistants to interact with the nornir-infrahub repository. These skills ensure that all contributions follow the standardized OpsMill agentic structure and adhere to the project's strict quality gates. The system relies on a vendor-neutral source of truth for agent behavior, enabling portability between different AI tools such as Claude Code or Codex.

The repository uses the opsmill-dev shared skills library, which includes version-pinned capabilities for committing code, managing pull requests, and performing rebases. These operations are integrated with local development tools like invoke and towncrier to maintain repository integrity and clear communication of changes.

Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:12-25, skills-lock.json:4-46, AGENTS.md:1-15

Agentic Structure and Layout

The repository implements a canonical OpsMill agentic layout to prevent configuration drift between different AI agents. All agent-consumed content lives in the .agents/ directory, which serves as the engine-agnostic source of truth.

Source of Truth Mapping

Specific adapters for tools like Claude are implemented as committed symlinks to the .agents/ directory. This ensures that every agent accesses the exact same bytes for skill definitions.

The diagram shows how tool-specific directories link back to the unified .agents/skills/ source of truth.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:27-37

Core Git Workflow

The project follows a specific branching and contribution model. The stable branch is the default protected branch, and all work must target it through feature branches and pull requests.

Branching Rules

• Stable Branch: The only target for feature branches. Direct pushes to stable are prohibited.
• Legacy Refs: main and develop branches are stale and must be ignored.
• Origin: origin/HEAD always resolves to origin/stable.

Sources: dev/guidelines/git-workflow.md:7-12, AGENTS.md:127-130

Pull Request Lifecycle

Agents manage the lifecycle of changes from local formatting to remote merging. All PRs must pass the CI workflow, which includes linting for Python, YAML, and Markdown.

The sequence illustrates the mandatory pre-commit and CI gates required for pull requests.
Sources: dev/guidelines/git-workflow.md:14-25, tasks.py:16-66

Operational Skills

The skills-lock.json file pins specific versions of shared OpsMill dev skills. These skills are identified by content hashes to ensure consistency across the OpsMill ecosystem.

Key Skills Table

Skill Name	Source Path	Purpose
commit	opsmill-dev/skills/commit/SKILL.md	Standardizes conventional commit messages.
pr	opsmill-dev/skills/pr/SKILL.md	Manages PR creation and description formatting.
rebase	opsmill-dev/skills/rebase/SKILL.md	Handles branch synchronization with stable.
monitoring-pull-requests	opsmill-dev/skills/monitoring-pull-requests/SKILL.md	Tracks PR status and CI feedback.

Sources: skills-lock.json:5-46, dev/adr/0001-adopt-canonical-agentic-structure.md:41-45

Commit Conventions

Agents must use imperative, scoped subjects. While no rigid convention is enforced beyond high-level patterns, history shows a preference for conventional-commit prefixes:

• fix: for bug fixes.
• docs(dev): for internal documentation changes.
• chore(agentic): for structural or maintenance work.

Sources: dev/guidelines/git-workflow.md:31-36

Automated Quality Gates

Before any Git operation involving a push, agents must execute the project's quality suite via invoke tasks. This process is mandatory and gates all contributions.

Pre-commit Verification Sequence

1. Formatting: ruff format . and rumdl fmt . are executed to standardize code and markdown.
2. Linting: A comprehensive suite including yamllint, ruff, pylint, ty (type checking), and rumdl (markdown) must return zero errors.
3. Testing: pytest runs the unit test suite locally.

# tasks.py - The primary interface for Agent Quality Gates
@task(name="lint")
def lint_all(context: Context):
    """Run all linters."""
    lint_yaml(context)
    lint_ruff(context)
    lint_pylint(context)
    lint_ty(context)
    lint_markdown(context)

Sources: tasks.py:16-66, dev/guidelines/git-workflow.md:14-25, AGENTS.md:94-110

Changelog Management

Agents use towncrier to manage the CHANGELOG.md file. Instead of editing the changelog directly, agents create fragment files under the changelog/ directory.

Fragment Types

Fragments are named using the format <issue-or-pr>.<type>.md. Supported types defined in pyproject.toml include:

• security, removed, deprecated, added, changed, fixed, housekeeping.

Sources: dev/guidelines/git-workflow.md:41-58, pyproject.toml:228-266

Summary

Agent Skills for Git Operations provide a structured, automated framework for interacting with the nornir-infrahub repository. By centralizing skill definitions in .agents/ and enforcing strict quality gates via invoke tasks and CI workflows, the project maintains a high degree of technical consistency and prevents configuration drift across different AI toolsets.