Agent Skills

Skills are predefined workflows in .claude/skills/ that guide a coding agent step by step through complex multi-step tasks. When a developer’s prompt matches a skill, the agent follows that skill’s workflow rather than improvising. This makes the agent’s behavior predictable and its output consistent across microservices and developers.

Without skills, a coding agent must infer the right approach from general patterns, which leads to inconsistencies: different naming conventions, missing test coverage, forgotten manifest updates, or structural drift between microservices. Skills eliminate that variance by encoding Microbus’s conventions into an explicit recipe the agent follows every time.

Anatomy of a Skill

Each skill lives in its own directory under .claude/skills/ and contains a SKILL.md file. The file has three parts:

Frontmatter declares the skill’s name and when to use it:

---
name: Adding a Functional Endpoint
description: Creates or modify a functional endpoint of a microservice. Use when
  explicitly asked by the user to create or modify a functional or RPC endpoint
  of a microservice.
---

Workflow checklist gives the agent a copy-paste tracking list so it can mark off steps as it goes:

Creating or modifying a functional endpoint:
- [ ] Step 1: Read local CLAUDE.md file
- [ ] Step 2: Determine signature
- [ ] Step 3: Extend the ToDo interface
...

Detailed steps expand each item in the checklist with precise instructions, constraints and code templates the agent copies verbatim. Templates include all necessary imports, struct definitions, function signatures and test patterns.

How Skills Guide the Agent

Skills enforce several principles that keep agent output reliable:

Self-contained templates - Most skills explicitly state that they are self-contained and that an agent should not explore or analyze existing microservices before starting its work. This prevents the agent from looking at other microservices and mimicking patterns that may be outdated or non-standard.

Marker comments - Skills instruct the agent to include MARKER comments throughout the generated code. These comments act as waypoints for future edits. When a feature needs to be modified or removed, the agent locates the relevant code by scanning for its marker rather than guessing.

if example { // MARKER: FeatureName
	// ...
}

Comprehensive coverage - A single skill touches every file that needs updating: implementation, API client stubs, mocks, tests, OpenAPI descriptors, the manifest and documentation. Nothing is left for the developer to wire up manually.

Incremental development - Each skill adds or modifies a single feature without disrupting existing code. Tests are written or updated in the same pass, and the manifest is kept in sync.

Common Skills

Most day-to-day work happens through the per-feature skills. These add or modify one capability of a microservice in a single pass, keeping implementation, tests, manifest, and generated artifacts in sync:

  • Scaffold a new microservice in the project - directory layout, intermediate code, manifest, and an empty service.go ready for features.
  • Add a function, web, inbound event, outbound event, task, or workflow - the eight features of a microservice each have a dedicated skill.
  • Add a supporting concern - a typed configuration property, a recurring ticker, or a metric.
  • Modify or remove a previously-added feature - located by its MARKER comment so the rest of the microservice stays consistent.
  • Regenerate boilerplate - refreshes the framework-generated files (intermediate, client, mock, OpenAPI) when a manifest change requires it.

Beyond the per-feature skills, a handful of larger skills handle longer-running jobs that span an entire microservice or the whole project:

  • Bootstrap a new project - lays down the project skeleton and .claude/ setup from a single prompt.
  • Scaffold a SQL CRUD microservice - generates a complete database-backed service from a single prompt: tables, migrations, REST API, multi-tenancy, the lot.
  • Scaffold a Python-backed microservice - generates a microservice that delegates its compute to a Python subprocess: lifecycle wiring, deferred subscriptions, typed function or workflow-task endpoints, and in-memory mocking.
  • Import an OpenAPI microservice - turns a third-party REST API’s OpenAPI document into a faithful one-for-one delegating microservice: normalized specs file, typed endpoints, credential config, and HTTP egress wiring, with more endpoints importable later.
  • Upgrade Microbus - walks the project through a framework version bump: bumping the module, refreshing framework-owned files, regenerating code, adapting callsites for breaking changes, and verifying the build.

Two cross-cutting skills run alongside the per-feature and specialized skills:

  • Housekeeping runs automatically after every microservice change. It re-reads the microservice’s manifest, refreshes the timestamp, regenerates derived artifacts, and verifies that MARKER and HINT comments, tests, and the manifest are all in sync. Missing housekeeping is the most common source of structural drift, so it is enforced rather than optional.

  • Microservice review is a design audit. It inspects a single microservice end-to-end - signatures, tests, manifest, generated code, and design notes in CLAUDE.md - and reports inconsistencies, missing coverage, or deviations from framework conventions. Run it before merging non-trivial microservice changes.

Backward Agent Rules Automatic Documentation Forward