agentsclimarketplace

Octo devtools

Skill meshmakers/octo-claude-skills/skills/octo-devtools

Drives OctoMesh local development through the octo-tools PowerShell cmdlets — building repos in dependency order, starting and stopping services (always non-interactively for agents via Start-Octo -nonInteractive $true / Stop-Octo), managing Docker or local kind Kubernetes infrastructure, syncing and branching git repos, NuGet package propagation, certificates, and octo-cli context/auth setup. Use it for any OctoMesh dev-environment or DevOps task. Trigger on build, compile, dotnet build, start services, stop services, Start-Octo, Stop-Octo, Invoke-BuildAll, Invoke-Build, infrastructure, docker compose, kind, Kubernetes, Install-OctoKubernetes, Deploy-OctoOperator, git sync, pull repos, push repos, Get-AllGitRepStatus, branch management, test branch, NuGet packages, clean build, kill dotnet, certificates, clone repos, register context, login local/staging/production, infrastructure backup, or any OctoMesh PowerShell cmdlet name.From its SKILL.md

Install
npx -y skills add meshmakers/octo-claude-skills --skill octo-devtools

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

20.9 KB, as published. Nobody here has run it

OctoMesh Development Tools — Natural Language Interface

Overview

Single entry point for OctoMesh development operations: /octo-devtools <natural language>

Claude translates the user's intent into the appropriate PowerShell cmdlet from octo-tools/modules/profile.ps1 — with safety checks for destructive operations and warnings for interactive/session-blocking commands.

Prerequisites

  • PowerShell (pwsh) must be installed and on PATH
  • The monorepo workspace must contain octo-tools/ with modules/profile.ps1
  • For build commands: .NET SDK must be installed
  • For infrastructure commands: Docker must be running

Invocation Pattern

All commands are executed through the wrapper script, which loads the OctoMesh profile automatically:

bash "${CLAUDE_PLUGIN_ROOT}/skills/octo-devtools/scripts/run_pwsh.sh" '<PowerShell command>'

CRITICAL — quoting and path examples:

  • CORRECT: bash "${CLAUDE_PLUGIN_ROOT}/skills/octo-devtools/scripts/run_pwsh.sh" 'Get-AllGitRepStatus'
  • CORRECT: bash "${CLAUDE_PLUGIN_ROOT}/skills/octo-devtools/scripts/run_pwsh.sh" 'Invoke-BuildAll -configuration DebugL -excludeFrontend $true'
  • WRONG: bash "..." "Invoke-BuildAll -excludeFrontend $true" (double quotes — bash eats $true!)
  • WRONG: pwsh -Command "Get-AllGitRepStatus" (profile not loaded!)
  • WRONG: cd ... && bash scripts/run_pwsh.sh '...' (causes permission prompts!)

Always use single quotes around the PowerShell command argument so that PowerShell variables like $true and $false are not consumed by bash.

Build Strategy — CRITICAL

OctoMesh is a monorepo where repos produce NuGet packages consumed by downstream repos. The build system handles copying these NuGet packages between repos automatically — but ONLY when using Invoke-BuildAll.

The one difference that matters: Invoke-Build does NOT propagate NuGet packages between repos, Invoke-BuildAll does. A repo built with Invoke-Build writes its package nowhere the other repos can see it, so every consumer keeps compiling and running against the previous version. That is why Invoke-BuildAll is the default and Invoke-Build is the narrow exception.

The only sanctioned way to make a build cheaper is -excludeFrontend $true. Do not narrow the build any further to save time — see the warning under the examples below.

When to use Invoke-BuildAll (DEFAULT CHOICE)

Use Invoke-BuildAll whenever building after code changes that could affect NuGet packages, or when unsure. This is the safe default. It builds repos in dependency order AND copies NuGet packages to the shared nuget/ folder between each step.

# Full build (all repos including frontends)
Invoke-BuildAll -configuration DebugL

# Backend only — skips Angular frontends (saves significant time)
Invoke-BuildAll -configuration DebugL -excludeFrontend $true

Do NOT reach for -excludeAdditional $true to save time. It stops after the core library chain and skips the service repos, so a changed contract lands in the shared nuget/ folder while identity, asset-repo and the other services keep running against the old one. The failure surfaces later, at service startup or at runtime, far away from the build that caused it. The parameter is documented in references/command-reference.md because it exists — not because it is a recommended shortcut.

Use Invoke-BuildAll for:

  • After pulling latest changes (Sync-AllGitRepos)
  • After switching branches
  • When changes touch repos in the explicit build order (mm-common, octo-distributedEventHub, octo-construction-kit-engine, octo-sdk, octo-construction-kit-engine-mongodb, octo-common-services, octo-mesh-adapter, octo-bot-services, octo-communication-controller-services) — these produce NuGet packages consumed downstream
  • When unsure whether changes affect NuGet packages
  • Clean builds after deleting bin/obj folders
  • First build after clone

When Invoke-Build is safe (SINGLE REPO, NO NUGET IMPACT)

Invoke-Build builds one repo in isolation. It does NOT handle NuGet package propagation.

Invoke-Build is ONLY appropriate when:

  • Making changes within a single service repo (e.g., octo-asset-repo-services, octo-identity-services)
  • The changes do NOT affect any NuGet package produced by that repo
  • All upstream NuGet dependencies are already up-to-date in the nuget/ folder
# Safe: editing a controller in asset repo services
Invoke-Build -repositoryPath ./octo-asset-repo-services -configuration DebugL

NEVER use Invoke-Build to propagate NuGet changes. Do not attempt to manually chain Invoke-Build + Copy-NuGetPackages to replicate what Invoke-BuildAll does — use Invoke-BuildAll instead (with -excludeFrontend $true when the frontends are not needed).

Command Quick Reference

For full parameter details, read references/command-reference.md in this skill directory. For common multi-step workflows, read references/workflows.md in this skill directory.

Build & Compilation

CmdletDescriptionSafety
Invoke-BuildAllBuild repos in dependency order WITH NuGet propagation — use this by defaultMutating (local)
Invoke-BuildBuild a single repo WITHOUT NuGet handling — only for isolated service changesMutating (local)
Invoke-BuildFrontendBuild Angular frontendsMutating (local)
Invoke-PublishPublish a .NET projectMutating (local)
Invoke-BuildAndStartOctoBuild all + start services — chains into interactive Start-Octo. Do NOT use from an agent session (see safety rules)Interactive
Invoke-BuildZenonPlugBuild Zenon plug-inMutating (local)

Service Management

CmdletDescriptionSafety
Start-OctoStart OctoMesh services. From an agent always pass -nonInteractive $trueMutating (interactive only when -nonInteractive is not set)
Stop-OctoStop services started in non-interactive mode (writes a .octo-stop signal file)Mutating
Start-OctoInfrastructureStart Docker containers (MongoDB, RabbitMQ, CrateDB)Mutating
Stop-OctoInfrastructureStop Docker containersMutating

Infrastructure

CmdletDescriptionSafety
Install-OctoInfrastructureFirst-time Docker setupMutating
Uninstall-OctoInfrastructureRemove Docker containers + volumesDestructive
Get-OctoInfrastructureStatusShow container statusRead-only
Invoke-CleanupInfraContainerDisksClean unused Docker disk spaceDestructive
Backup-OctoInfrastructureBack up infra Docker volumes (Mongo + CrateDB)Mutating (local)
Restore-OctoInfrastructureRestore infra volumes from a named backupDestructive
Get-OctoInfrastructureBackupList available infra backupsRead-only
Remove-OctoInfrastructureBackupDelete a named infra backupDestructive

Local Kubernetes (kind) dev environment

An alternative to the docker-compose infra: MongoDB / RabbitMQ / CrateDB, the CRDs, and the Communication Operator run inside a local kind cluster (the .NET services still run as host processes via Start-Octo). The two infra modes share the same host ports and CANNOT run at the same time — Install-OctoKubernetes refuses to start while docker-compose infra containers are up. Full runbook: C:\dev\meshmakers\octo-tools\kubernetes\README.md; from-scratch setup: C:\dev\meshmakers\octo-tools\kubernetes\QUICKSTART.md.

CmdletDescriptionSafety
Install-OctoKubernetesCreate kind cluster + CRDs + in-cluster infra + ingress-nginx/cert-manager, then deploy the operatorMutating
Deploy-OctoOperator(Re)deploy the Communication Operator from the dev registry (:main-latest)Mutating
Get-OctoKubernetesStatusShow pods, Helm releases, and host-port reachabilityRead-only
Uninstall-OctoKubernetesDelete the kind cluster and ALL its data (Mongo + CrateDB PVCs)Destructive
Import-OctoImageToKindLoad a locally-built image into the kind nodeMutating
Add-OctoLocalCaTrust / Remove-OctoLocalCaTrustTrust / untrust the local root CA in the OS storeMutating (Destructive for Remove)

Git Repository Management

CmdletDescriptionSafety
Sync-AllGitReposPull all repos (rebase)Mutating
Sync-GitRepoPull a single repoMutating
Push-AllGitReposPush all repos to remoteMutating (remote)
Push-GitRepoPush a single repoMutating (remote)
Get-AllGitRepStatusGit status across all reposRead-only
Find-AllGitReposDiscover all repos in workspaceRead-only
Invoke-CloneMainReposClone all main reposMutating
Sync-AllSubmodulesSync git submodulesMutating
Invoke-CleanAllGitReposClean all repos (remove untracked)Destructive

Branch Management

CmdletDescriptionSafety
New-TestBranchCreate test branch across all reposMutating
Remove-TestBranchDelete test branch from all reposDestructive
Sync-TestBranchMerge base into test branchMutating
Invoke-SwitchAllBranchesSwitch all repos to a branchMutating
Compare-BranchStatusCompare branch statusRead-only

NuGet Package Management

CmdletDescriptionSafety
Copy-AllNuGetPackagesCopy NuGet packages to shared folderMutating (local)
Copy-NuGetPackagesCopy packages from specific directoryMutating (local)
Sync-NuGetPackagesSynchronize NuGet cacheMutating (local)
Remove-GlobalNuGetPackagesClear global NuGet cacheDestructive

Cleanup & Maintenance

CmdletDescriptionSafety
Invoke-KillDotnetKill all dotnet processesMutating
Remove-BinAndObjFoldersDelete all bin/ and obj/ foldersDestructive

Authentication / Context (octo-cli)

CmdletDescriptionSafety
Register-OctoCliContextRecommended — register a named octo-cli context for any installation (local, test-2, staging-1, prod-1, prod-2)Mutating
Invoke-OctoCliLoginLocalLog in to local environment (-tenantId, -includeReporting)Mutating
Invoke-OctoCliLoginTest2Log in to test-2 environmentMutating
Invoke-OctoCliLoginStagingLegacy — old *.meshmakers.cloud domains; prefer Register-OctoCliContext -Installation staging-1Mutating
Invoke-OctoCliLoginProductionLegacy — old *.meshmakers.cloud domains; prefer Register-OctoCliContext -Installation prod-1/prod-2Mutating
Invoke-OctoCliReconfigureLogLevelReconfigure service log levels (3 mandatory params)Mutating
Invoke-SetDebugConfigurationRegister the Admin Panel debug OAuth client + scopes (run after local login)Mutating
Register-AiBastionRegister an Anthropic subscription token on a tenant (device-code OAuth)Mutating (remote)
Get-AiBastionStatusRead current AI Bastion lease metadata for a tenantRead-only

Certificates

CmdletDescriptionSafety
New-RootCertificateGenerate root CA certificateMutating
New-ServerCertificateGenerate server certificateMutating
New-AspNetDeveloperCertificateSet up ASP.NET dev HTTPS certMutating
Test-AspNetDeveloperCertificateCheck the ASP.NET dev cert statusRead-only
Remove-AspNetDeveloperCertificateRemove the ASP.NET dev certDestructive

Kubernetes helpers / DB access

CmdletDescriptionSafety
Join-KubeConfigsMerge kubeconfig filesMutating
Remove-KubeConfigDelete a named context/cluster/user from ~/.kube/config (interactive prompt)Destructive
Invoke-MongoPortForwardPort-forward MongoDB from K8sMutating

Diagnostics & Comparison

CmdletDescriptionSafety
Compare-CkVersionsDiff CK model (ckModel.yaml) versions between two branch checkoutsRead-only
Compare-PipelinesDiff local pipeline YAML against the deployed versions in a tenantRead-only
Get-BranchAvailabilityList repos where a given branch exists on remoteRead-only

Versioning & Templates

CmdletDescriptionSafety
Sync-YamlTemplatesSync CI/CD YAML templatesMutating
Update-MeshmakerVersionBump version numbersMutating

Safety Rules

Read-only (execute directly, no confirmation)

Get-AllGitRepStatus, Get-OctoInfrastructureStatus, Get-OctoKubernetesStatus, Get-OctoInfrastructureBackup, Find-AllGitRepos, Compare-BranchStatus, Compare-CkVersions, Compare-Pipelines, Get-BranchAvailability, Test-AspNetDeveloperCertificate, Get-AiBastionStatus

Mutating — local (execute with brief confirmation)

Invoke-BuildAll, Invoke-Build, Invoke-BuildFrontend, Invoke-Publish, Invoke-BuildZenonPlug, Start-OctoInfrastructure, Stop-OctoInfrastructure, Install-OctoInfrastructure, Backup-OctoInfrastructure, Install-OctoKubernetes, Deploy-OctoOperator, Import-OctoImageToKind, Add-OctoLocalCaTrust, Sync-AllGitRepos, Sync-GitRepo, Invoke-CloneMainRepos, Sync-AllSubmodules, New-TestBranch, Sync-TestBranch, Invoke-SwitchAllBranches, Copy-AllNuGetPackages, Copy-NuGetPackages, Sync-NuGetPackages, Register-OctoCliContext, Invoke-OctoCliLogin*, Invoke-OctoCliReconfigureLogLevel, Invoke-SetDebugConfiguration, New-RootCertificate, New-ServerCertificate, New-AspNetDeveloperCertificate, Join-KubeConfigs, Invoke-MongoPortForward, Sync-YamlTemplates, Update-MeshmakerVersion, Invoke-KillDotnet, Stop-Octo

Mutating — remote (confirm with emphasis)

Push-AllGitRepos, Push-GitRepo, Register-AiBastion (writes a token to a remote tenant — see note below)

Destructive (explicit confirmation + warning)

Remove-BinAndObjFolders, Remove-GlobalNuGetPackages, Invoke-CleanAllGitRepos, Uninstall-OctoInfrastructure, Restore-OctoInfrastructure, Remove-OctoInfrastructureBackup, Uninstall-OctoKubernetes, Remove-KubeConfig, Remove-TestBranch, Invoke-CleanupInfraContainerDisks, Remove-AspNetDeveloperCertificate, Remove-OctoLocalCaTrust

Service startup — non-interactive is the agent default — CRITICAL

Start-Octo blocks the session waiting for a keypress only when -nonInteractive is not set. When Claude (or any agent / CI job) starts services it MUST ALWAYS run:

Start-Octo -nonInteractive $true -configuration DebugL

In this mode Start-Octo blocks until a service fails or a .octo-stop signal file appears — it never waits for a keypress. Stop the services from another invocation with:

Stop-Octo

Stop-Octo is a standalone cmdlet that writes the .octo-stop signal file (it has a -branch parameter mirroring Start-Octo/Install-OctoKubernetes). This non-interactive start + Stop-Octo pair is a firm repo convention — never start services interactively from an agent session.

NEVER use Invoke-BuildAndStartOcto from an agent session — it chains into the interactive Start-Octo (no -nonInteractive pass-through) and will block the session indefinitely. Build with Invoke-BuildAll, then start with Start-Octo -nonInteractive $true instead.

Interactive (only when a human runs it directly)

Interactive blocking applies to Start-Octo (without -nonInteractive $true) and Invoke-BuildAndStartOcto. If a human explicitly asks for an interactive foreground run, warn first:

Warning: This command will block the current session until you press a key to stop the services. The session will not be available for other commands while services are running.

AI Bastion secret handling

Register-AiBastion drives the Anthropic device-code OAuth flow and POSTs the token to the AI Adapter's POST /{tenantId}/v1/credentials/register. The bearer token comes from -BearerToken or $env:OCTO_BASTION_TOKEN; token material is held in memory only and zeroed in a finally block. Never echo, log, or persist the bearer token or the device-code output.

Smart Behaviors

Natural language mapping

  • "build everything" / "build all" → Invoke-BuildAll -configuration DebugL
  • "build without frontend" / "build backend" → Invoke-BuildAll -configuration DebugL -excludeFrontend $true
  • "build asset repo" → Invoke-Build -repositoryPath ./octo-asset-repo-services -configuration DebugL (only if no NuGet changes!)
  • "rebuild after pull" / "sync and build" → Sync-AllGitRepos then Invoke-BuildAll -configuration DebugL
  • "git status" / "repo status" → Get-AllGitRepStatus
  • "pull latest" / "sync repos" → Sync-AllGitRepos
  • "push everything" → Push-AllGitRepos (confirm first!)
  • "start services" / "start octo" → Start-Octo -nonInteractive $true -configuration DebugL (agent default; never block the session)
  • "stop services" / "stop octo" → Stop-Octo
  • "start infra" / "start docker" → Start-OctoInfrastructure
  • "stop infra" / "stop docker" → Stop-OctoInfrastructure
  • "infra status" / "docker status" → Get-OctoInfrastructureStatus
  • "backup infra" / "backup before testing" → Backup-OctoInfrastructure (stop infra first)
  • "restore infra" / "list backups" → Restore-OctoInfrastructure -Name <name> / Get-OctoInfrastructureBackup
  • "set up local kubernetes" / "kind cluster" / "install k8s" → Install-OctoKubernetes (refuses if docker-compose infra is up)
  • "deploy operator" → Deploy-OctoOperator
  • "k8s status" / "kubernetes status" → Get-OctoKubernetesStatus
  • "tear down kind" / "uninstall kubernetes" → Uninstall-OctoKubernetes (destructive — confirm)
  • "clean build" → confirm, then Remove-BinAndObjFolders + Invoke-BuildAll -configuration DebugL
  • "clean everything" → confirm each destructive step separately
  • "switch to local" / "login local" → Invoke-OctoCliLoginLocal (or Register-OctoCliContext -Installation local -TenantId <tenant>)
  • "register context for staging" / "add context for production" → Register-OctoCliContext -Installation staging-1|prod-1|prod-2 -TenantId <tenant>
  • "compare CK versions" / "diff ck models between branches" → Compare-CkVersions <otherBranch>
  • "create test branch" → New-TestBranch with user-provided version + description

Default configuration

Always use -configuration DebugL for build commands unless the user explicitly specifies a different configuration. This is the standard local development configuration.

Build order awareness

When the user asks to build, default to Invoke-BuildAll, narrowing it at most with -excludeFrontend $true — do NOT attempt to manually orchestrate Invoke-Build calls in dependency order or manually copy NuGet packages. The Invoke-BuildAll script already handles the correct build order and NuGet propagation. Only use Invoke-Build for a single service repo where no NuGet packages are affected.

Workflow suggestions

When the user describes a high-level goal (e.g., "set up a fresh dev environment"), suggest the appropriate multi-step workflow from references/workflows.md and offer to execute it step by step.

Execution Flow

  1. Parse intent — Map natural language to cmdlet(s) from the tables above
  2. Check safety level — Determine if read-only, mutating, destructive, or interactive
  3. Confirm if needed — For mutating/destructive ops, show the command + summary, wait for confirmation
  4. Non-interactive services — When starting services, always use Start-Octo -nonInteractive $true and stop with Stop-Octo. Never run Invoke-BuildAndStartOcto from an agent session. Only warn about session blocking if a human explicitly requests an interactive foreground run.
  5. Execute — Run via the wrapper script and present results clearly
  6. Suggest next steps — After completion, suggest logical follow-up actions (e.g., after build → start services)

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.