adding-a-functional-endpoint
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.
When & Why to Use This Skill
This Claude skill automates the end-to-end process of creating or modifying functional endpoints within a microservice architecture. It streamlines the development workflow by guiding the agent through YAML definitions, boilerplate Go code generation, custom type implementation, and comprehensive testing. By enforcing a structured checklist—from initial configuration in service.yaml to final versioning—it ensures consistency, reduces manual coding errors, and maintains high-quality documentation for microservices.
Use Cases
- Rapid API Development: Accelerate the creation of new RPC or functional endpoints by automating boilerplate generation and signature definitions in Go-based microservices.
- Microservice Refactoring: Efficiently modify existing endpoint signatures, including renaming functions and updating data structures, while ensuring business logic and tests are correctly migrated.
- Automated Documentation Maintenance: Keep technical documentation in sync with code changes by automatically updating AGENTS.md files with design rationale and context.
- Standardized Testing Integration: Generate and adjust integration tests in service_test.go to ensure new endpoints meet quality standards and handle downstream dependencies correctly.
| 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
Copy this checklist and track your progress:
Creating or modifying a functional endpoint:
- [ ] Step 1: Read local AGENTS.md file
- [ ] Step 2: Define in service.yaml
- [ ] Step 3: Generate Boilerplate Code
- [ ] Step 4: Define Custom Types
- [ ] Step 5: Move Implementation and Test if Renamed
- [ ] Step 6: Implement the Business Logic
- [ ] Step 7: Test the Function
- [ ] Step 8: Document the Microservice
- [ ] Step 9: Versioning
Step 1: Read local AGENTS.md file
Check for and read a local AGENTS.md file in that microservice's directory. The local AGENTS.md file contains microservice-specific instructions that should take precedence over global instructions.
Step 2: Define in service.yaml
Define the functional endpoint in the functions array in the service.yaml of the microservice.
- The
signatureof the functional endpoint must follow Go function syntax exactly. Do not include acontext.Contextinput argument nor anerroroutput argument. - The
descriptionshould explain what the function is doing. It should start with the name of the function. - A
methodrestricts requests to a specific HTTP method such asGET,POST,DELETE,PUT,PATCH,OPTIONSorHEAD. The defaultANYaccepts all requests regardless of the method.
functions:
- signature: MyNewFunction(primitiveParam string, customParam CustomType) (result string)
description: MyNewFunction does X, Y and Z.
method: ANY
Step 3: Generate Boilerplate Code
If you've made changes to service.yaml, run go generate to generate the boilerplate code.
Step 4: Define Custom Types
If the new function is using non-primitive custom types such as structs, look for their definition in the API directory.
- Define the properties of any custom types as needed. Property names should be in PascalCase.
- Define JSON tags for all properties. JSON tag names should be in camelCase. Include
,omitzeroin all JSON tags.
// CustomType is X, Y, Z
type CustomType struct {
PropertyName string `json:"propertyName,omitzero"`
}
Step 5: Move Implementation and Test if Renamed
If you made a change to the name of the method in the signature field, you need to move over its implementation in service.go from under the old name to the new name. Similarly, you'll need to move over the implementation of the tests in service_test.go.
Step 6: Implement the Business Logic
Look for the function declaration in service.go and implement or adjust its logic appropriately.
func (svc *Service) MyNewFunction(ctx context.Context, primitiveParam string, customParam CustomType) (result string, err error) {
// Implement logic here
return result, err
}
Step 7: Test the Function
Look for the integration test created in service_test.go for the function and implement or adjust it appropriately.
- Follow the pattern recommendation in the code
- Add downstream microservices or their mocks to the testing app
func TestMyservice_MyNewFunction(t *testing.T) {
// Implement testing here
}
Step 8: Document the Microservice
Generate documentation for this microservice that captures its purpose, context, and design rationale. Focus on the reasons behind decisions rather than describing what the code does. Explain design choices, tradeoffs, and the context needed for someone to safely evolve this microservice in the future. Store the result in the microservice's local AGENTS.md file.
Step 9: Versioning
Run go generate to version the code.