Steering

Steering files are markdown documents that provide persistent instructions to AI agents. Unlike skills (which are domain knowledge tied to specific repos), steering files apply globally to the entire workspace — they define how your team works, not what it works on.

What is Steering?

A steering file is a .md file in the steering/ directory at your hub root. Each file contains instructions that every AI agent follows, regardless of which repo it’s working on.

steering/
├── pr-desc.md        # PR description template
├── delivery.md       # Deployment and notification rules
└── code-standards.md # Team coding conventions

Think of steering as your team’s operating manual for AI agents. Common use cases:

• PR description templates
• Delivery workflows (branch naming, Slack notifications)
• Code review checklists
• Language and formatting preferences
• Security and compliance rules

How it works

Steering files are convention-based — just place .md files in the steering/ directory. No hub.yaml configuration needed.

When you run hub generate, steering files are copied to each editor in its native format:

Front-matter (if present in the source file) is automatically stripped during the copy, so your canonical files stay editor-agnostic.

Creating a Steering File

Just create a markdown file in steering/:

# Code Review Standards

When reviewing code:

1. Check for proper error handling
2. Verify naming conventions match the project style
3. Ensure new endpoints have corresponding tests
4. Flag any hardcoded secrets or credentials
5. Confirm database queries are indexed

Be concise. Group feedback by severity.

No special syntax or front-matter required. The content is the instruction.

Example: PR Description Template

# PR-DESC (Generate Pull Request Description)

When asked to generate a "PR-DESC":

1. Analyze the current branch and identify what changes were made
2. Generate a PR description using the template below
3. Fill in the template with specific information about the branch changes

Template:

## Descricao
<!-- Descreva suas mudancas em detalhes -->

## Etiquetas (Labels)
- [ ] Nova Funcionalidade
- [ ] Correcao de Bug
- [ ] Estrutura
- [ ] Testes

## Como Isso Foi Testado?
- [ ] Testes Unitarios
- [ ] Testes de Integracao
- [ ] Testes e2e
- [ ] Nenhum (por que?)

Example: Delivery Rules

# Delivery

## Pull Requests
Branch naming: `{task_id}-{slug}`
Create a PR-DESC and use it as the PR description.

## Slack Notifications
Post to `#eng-prs` with format:
":point_right: [PR](pr_link) para [task_name](task_link)"

Steering vs Skills vs Commands

Steering is always active — agents read it on every interaction. Skills are loaded when working on a specific repo. Commands are triggered explicitly by the user.

Syncing from Editor Directories

If you create rules directly in an editor-specific folder (like .cursor/rules/ or .kiro/steering/), hub scan can detect them and offer to sync them back to the canonical steering/ directory. This ensures rules created in one editor are available to all editors.

hub scan

Scanning for unsynced skills, agents, and steering...

Found 1 unsynced asset(s):

  code-standards.md (steering from .cursor)

? Select assets to sync to canonical folders:
  ◉ code-standards.md (steering from .cursor)

  Synced steering: code-standards.md (from .cursor)

After syncing, run hub generate to distribute the file to all editors.

Auto-generated Files

The orchestrator.md steering file is auto-generated by hub generate and should not be edited manually. It contains the workflow pipeline, repository list, and agent instructions derived from your hub.yaml.