Job Targeting

When you have multiple jobs and skills, Atkins provides flexible syntax for targeting exactly which job to run. You can target jobs by name, by skill namespace, or by alias. Understanding the resolution order helps when job names overlap.

Basic Targeting

Run by Name

  # Run a job by its name
atkins build

# Equivalent to
atkins --job build

Namespaced Jobs

Jobs from skills use skill:job syntax:

  # Run 'test' job from 'go' skill
atkins go:test

# Run 'build' job from 'docker' skill
atkins docker:build

The Default Job

When running atkins without arguments:

Looks for a job named default
Falls back to a job with default in its aliases

  jobs:
  all:
    aliases: [default]
    depends_on: [lint, test, build]

If no default is found, Atkins shows available jobs:

  atkins: Available jobs for this project:
* build:       Build the application
* test:        Run tests
atkins: Job "default" does not exist

Root Job Targeting (`:` Prefix)

The : prefix bypasses alias resolution and targets jobs directly.

Target Main Pipeline

  # Target 'build' in main pipeline (bypasses aliases)
atkins :build

Use this when:

A skill has aliased build but you want the main pipeline's build
You want explicit, unambiguous job targeting

Target Skill Pipeline

  # Target 'build' job in 'go' skill explicitly
atkins :go:build

# Target 'test' job in 'docker' skill
atkins :docker:test

Cross-Pipeline Task References

Within a pipeline, steps can reference tasks from other pipelines using : syntax.

Reference Main Pipeline

  # In a skill pipeline
jobs:
  deploy:
    steps:
      # Call 'build' from main pipeline
      - task: :build
      - run: echo "Deploying..."

Reference Other Skills

  # In release skill
jobs:
  release:
    steps:
      # Call tasks from other skills
      - task: :go:build
      - task: :docker:build
      - task: :docker:push

Example: Multi-Skill Coordination

Main pipeline (atkins.yml):

  name: My App

jobs:
  build:
    steps:
      - run: go build -o app

  deploy:
    steps:
      - task: :go:test      # From go skill
      - task: :docker:build  # From docker skill
      - run: kubectl apply -f k8s/

Go skill (.atkins/skills/go.yml):

  name: Go Skill
when:
  files: [go.mod]

jobs:
  test:
    steps:
      - run: go test ./...

Docker skill (.atkins/skills/docker.yml):

  name: Docker Skill
when:
  files: [Dockerfile]

jobs:
  build:
    steps:
      - run: docker build -t app .

Aliases

Jobs can have alternative names:

  name: Job Namespace Example

jobs:
  build:
    aliases: [default]
    desc: Main build job
    steps:
      - run: echo "Building from main pipeline..."

  test:
    desc: Main test job
    steps:
      - run: echo "Testing from main pipeline..."

  deploy:
    desc: Deploy using skill jobs
    steps:
      # Reference jobs from other skills using :skill:job syntax
      - task: :build
      - run: echo "Deploying application..."

  name: Job Aliases Example

jobs:
  docker_build:
    desc: Build Docker image
    aliases: [build, b, db]
    steps:
      - run: echo "Building Docker image..."

  docker_push:
    desc: Push Docker image
    aliases: [push, p]
    steps:
      - run: echo "Pushing Docker image..."

  all:
    desc: Build and push
    aliases: [default]
    depends_on: [docker_build, docker_push]

Now all of these work:

  atkins docker:build  # Full name
atkins build         # Alias
atkins b             # Short alias
atkins db            # Another alias

Job Resolution Order

When you invoke atkins <name> , resolution follows this precedence:

Explicit root reference (: prefix) - bypasses all other rules
Prefixed job reference (skill:job syntax) - explicit skill targeting
Exact main pipeline match - job name matches exactly in main pipeline
Alias match - job alias in any pipeline
Skill ID with default - name matches skill with default job
Skill ID (listing only) - name matches skill name
Fuzzy match - substring/suffix match (single match only)
Fallback - main pipeline with name as-is

Main pipeline jobs take precedence over aliases. If your main pipeline has a job named up , running atkins up will invoke it even if a skill has an alias up pointing elsewhere.

Fuzzy Matching

If no exact match is found, Atkins tries fuzzy matching:

  # If 'docker:build' exists
atkins build  # Matches via suffix

When multiple matches exist:

  INFO: found 2 matching jobs:

  - go:build
  - docker:build

Use the full name or : prefix to disambiguate.

Nested Jobs

Jobs with : in their name are nested and not directly executable:

  jobs:
  build:
    steps:
      - task: build:linux
      - task: build:darwin

  build:linux:    # Nested - only runs via 'build'
    steps:
      - run: GOOS=linux go build

  build:darwin:   # Nested - only runs via 'build'
    steps:
      - run: GOOS=darwin go build

  atkins build         # Runs build:linux and build:darwin
atkins build:linux   # Error - nested job

Examples

Common Invocations

  # Run default job
atkins

# Run specific job from main pipeline
atkins test
atkins up

# Run skill job (explicit)
atkins go:lint
atkins docker:build

Root Reference (`:` prefix)

  # Force main pipeline job (bypasses aliases)
atkins :up
atkins :build

# Force skill job (explicit targeting)
atkins :go:build
atkins :docker:push

When to Use `:` Prefix

Use the : prefix when:

You want to ensure the main pipeline job runs (not an alias)
You need explicit, unambiguous targeting
A skill has aliased a common name you want to bypass

  # Main pipeline has 'up' job, skill has 'up' alias → runs main pipeline
atkins up

# Force main pipeline 'up' even if you're unsure about aliases
atkins :up

Full Example

  # Run default job
atkins

# Run 'build' from main pipeline
atkins build

# Run 'test' from go skill
atkins go:test

# Run 'up' from main pipeline (explicit)
atkins :up

# Run 'build' from docker skill (explicit)
atkins :docker:build

# Using alias (if 'b' is alias for build)
atkins b

# With file flag
atkins -f ci/test.yml integration