Initial commit
This commit is contained in:
Zhongwei Li
15
.claude-plugin/plugin.json
Normal file
15
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"name": "api-contract-generator",
|
||||||
|
"description": "Generate API contracts for consumer-driven contract testing",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Jeremy Longshore",
|
||||||
|
"email": "[email protected]"
|
||||||
|
},
|
||||||
|
"skills": [
|
||||||
|
"./skills"
|
||||||
|
],
|
||||||
|
"commands": [
|
||||||
|
"./commands"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# api-contract-generator
|
||||||
|
|
||||||
|
Generate API contracts for consumer-driven contract testing
|
||||||
600
commands/generate-contract.md
Normal file
600
commands/generate-contract.md
Normal file
@@ -0,0 +1,600 @@
|
|||||||
|
---
|
||||||
|
description: Generate comprehensive API contracts for consumer-driven contract testing
|
||||||
|
shortcut: contract
|
||||||
|
category: api
|
||||||
|
difficulty: intermediate
|
||||||
|
estimated_time: 3-5 minutes
|
||||||
|
version: 2.0.0
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- DESIGN DECISIONS -->
|
||||||
|
<!-- API contracts enable safe microservice evolution by ensuring compatibility
|
||||||
|
between consumers and providers. This command generates contracts in multiple
|
||||||
|
formats (Pact, Spring Cloud Contract, OpenAPI) to support various testing frameworks. -->
|
||||||
|
|
||||||
|
<!-- ALTERNATIVES CONSIDERED -->
|
||||||
|
<!-- Manual contract writing: Rejected due to error-prone nature and time consumption
|
||||||
|
Schema-only validation: Rejected as it doesn't capture behavioral contracts
|
||||||
|
Record-replay testing: Rejected as it doesn't enable consumer-driven development -->
|
||||||
|
|
||||||
|
# Generate API Contract
|
||||||
|
|
||||||
|
Creates comprehensive API contracts for consumer-driven contract testing, enabling safe evolution of microservices by validating interactions between service consumers and providers. Supports Pact, Spring Cloud Contract, and OpenAPI specifications with automated verification and CI/CD integration.
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
|
||||||
|
Use this command when:
|
||||||
|
- Building microservices that need to evolve independently
|
||||||
|
- Implementing consumer-driven contract testing (CDCT)
|
||||||
|
- Preventing breaking changes between API versions
|
||||||
|
- Setting up automated compatibility testing in CI/CD
|
||||||
|
- Documenting API expectations between teams
|
||||||
|
- Migrating from monolithic to microservice architecture
|
||||||
|
- Establishing service boundaries and contracts
|
||||||
|
|
||||||
|
Do NOT use this command for:
|
||||||
|
- Internal function testing (use unit tests instead)
|
||||||
|
- UI testing (use end-to-end tests)
|
||||||
|
- Performance testing (use load testing tools)
|
||||||
|
- Security testing (use security scanning tools)
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before running this command, ensure:
|
||||||
|
- [ ] API endpoints are defined (at least conceptually)
|
||||||
|
- [ ] Consumer and provider services are identified
|
||||||
|
- [ ] Testing framework is chosen (Pact, Spring Cloud Contract, etc.)
|
||||||
|
- [ ] API documentation exists or requirements are clear
|
||||||
|
- [ ] Version control is set up for contract storage
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
### Step 1: Analyze API Requirements
|
||||||
|
The command examines your API specifications to generate appropriate contracts:
|
||||||
|
- Identifies HTTP methods and endpoints
|
||||||
|
- Extracts request/response schemas
|
||||||
|
- Determines required headers and parameters
|
||||||
|
- Captures validation rules and constraints
|
||||||
|
- Notes authentication requirements
|
||||||
|
|
||||||
|
### Step 2: Generate Contract Definitions
|
||||||
|
Based on the analysis, creates contract files that include:
|
||||||
|
- Consumer expectations (what the consumer needs)
|
||||||
|
- Provider capabilities (what the provider offers)
|
||||||
|
- Interaction definitions (request/response pairs)
|
||||||
|
- State management (preconditions for tests)
|
||||||
|
- Metadata for versioning and identification
|
||||||
|
|
||||||
|
### Step 3: Create Verification Tests
|
||||||
|
Generates test code to verify contracts:
|
||||||
|
- Consumer-side tests to ensure correct API usage
|
||||||
|
- Provider-side tests to verify implementation
|
||||||
|
- Mock server configurations for isolated testing
|
||||||
|
- Integration points for CI/CD pipelines
|
||||||
|
- Breaking change detection logic
|
||||||
|
|
||||||
|
### Step 4: Configure Contract Management
|
||||||
|
Sets up infrastructure for contract lifecycle:
|
||||||
|
- Contract versioning strategies
|
||||||
|
- Pact Broker or contract repository configuration
|
||||||
|
- CI/CD pipeline integration scripts
|
||||||
|
- Webhook configurations for automated testing
|
||||||
|
- Documentation generation from contracts
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
The command generates multiple files based on your chosen framework:
|
||||||
|
|
||||||
|
```
|
||||||
|
api-contracts/
|
||||||
|
├── consumers/
|
||||||
|
│ ├── [consumer-name]/
|
||||||
|
│ │ ├── pacts/
|
||||||
|
│ │ │ └── [consumer]-[provider].json
|
||||||
|
│ │ └── tests/
|
||||||
|
│ │ └── contract.test.js
|
||||||
|
├── providers/
|
||||||
|
│ ├── [provider-name]/
|
||||||
|
│ │ ├── contracts/
|
||||||
|
│ │ │ └── [provider]-contract.groovy
|
||||||
|
│ │ └── tests/
|
||||||
|
│ │ └── contract-verification.test.js
|
||||||
|
├── shared/
|
||||||
|
│ ├── schemas/
|
||||||
|
│ │ └── api-schema.json
|
||||||
|
│ └── states/
|
||||||
|
│ └── provider-states.js
|
||||||
|
└── docs/
|
||||||
|
└── contract-documentation.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output Files Explained:**
|
||||||
|
- `pacts/`: Pact contract files in JSON format
|
||||||
|
- `contracts/`: Spring Cloud Contract definitions in Groovy/YAML
|
||||||
|
- `tests/`: Generated test files for contract verification
|
||||||
|
- `schemas/`: Shared schema definitions (JSON Schema, OpenAPI)
|
||||||
|
- `states/`: Provider state setup for test scenarios
|
||||||
|
- `docs/`: Human-readable contract documentation
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
### Example 1: REST API User Service Contract
|
||||||
|
|
||||||
|
**Scenario:** Generate contract for a user service with CRUD operations
|
||||||
|
|
||||||
|
**User Input:**
|
||||||
|
```
|
||||||
|
/generate-contract --service user-api --consumer mobile-app --framework pact
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generated Pact Contract:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"consumer": {
|
||||||
|
"name": "mobile-app"
|
||||||
|
},
|
||||||
|
"provider": {
|
||||||
|
"name": "user-api"
|
||||||
|
},
|
||||||
|
"interactions": [
|
||||||
|
{
|
||||||
|
"description": "a request to get a user",
|
||||||
|
"providerState": "user with ID 123 exists",
|
||||||
|
"request": {
|
||||||
|
"method": "GET",
|
||||||
|
"path": "/api/users/123",
|
||||||
|
"headers": {
|
||||||
|
"Accept": "application/json",
|
||||||
|
"Authorization": "Bearer [token]"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": {
|
||||||
|
"status": 200,
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json"
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"id": "123",
|
||||||
|
"email": "[email protected]",
|
||||||
|
"name": "John Doe",
|
||||||
|
"createdAt": "2025-01-15T10:00:00Z"
|
||||||
|
},
|
||||||
|
"matchingRules": {
|
||||||
|
"$.body.email": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body.createdAt": {
|
||||||
|
"match": "regex",
|
||||||
|
"regex": "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"description": "a request to create a user",
|
||||||
|
"providerState": "no user exists",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"path": "/api/users",
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json",
|
||||||
|
"Authorization": "Bearer [token]"
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"email": "[email protected]",
|
||||||
|
"name": "Jane Smith",
|
||||||
|
"password": "SecurePass123!"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": {
|
||||||
|
"status": 201,
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json",
|
||||||
|
"Location": "/api/users/124"
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"id": "124",
|
||||||
|
"email": "[email protected]",
|
||||||
|
"name": "Jane Smith",
|
||||||
|
"createdAt": "2025-01-15T11:00:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"metadata": {
|
||||||
|
"pactSpecification": {
|
||||||
|
"version": "2.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generated Consumer Test:**
|
||||||
|
```javascript
|
||||||
|
// consumer-tests/user-api.test.js
|
||||||
|
const { Pact } = require('@pact-foundation/pact');
|
||||||
|
const { getUserById, createUser } = require('../src/api-client');
|
||||||
|
|
||||||
|
describe('User API Consumer Tests', () => {
|
||||||
|
const provider = new Pact({
|
||||||
|
consumer: 'mobile-app',
|
||||||
|
provider: 'user-api',
|
||||||
|
port: 8080,
|
||||||
|
log: path.resolve(process.cwd(), 'logs', 'pact.log'),
|
||||||
|
dir: path.resolve(process.cwd(), 'pacts'),
|
||||||
|
logLevel: 'warn'
|
||||||
|
});
|
||||||
|
|
||||||
|
beforeAll(() => provider.setup());
|
||||||
|
afterEach(() => provider.verify());
|
||||||
|
afterAll(() => provider.finalize());
|
||||||
|
|
||||||
|
describe('GET /api/users/:id', () => {
|
||||||
|
it('should return a user when user exists', async () => {
|
||||||
|
// Arrange
|
||||||
|
await provider.addInteraction({
|
||||||
|
state: 'user with ID 123 exists',
|
||||||
|
uponReceiving: 'a request to get a user',
|
||||||
|
withRequest: {
|
||||||
|
method: 'GET',
|
||||||
|
path: '/api/users/123',
|
||||||
|
headers: {
|
||||||
|
'Accept': 'application/json',
|
||||||
|
'Authorization': 'Bearer valid-token'
|
||||||
|
}
|
||||||
|
},
|
||||||
|
willRespondWith: {
|
||||||
|
status: 200,
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json'
|
||||||
|
},
|
||||||
|
body: {
|
||||||
|
id: '123',
|
||||||
|
email: '[email protected]',
|
||||||
|
name: 'John Doe',
|
||||||
|
createdAt: '2025-01-15T10:00:00Z'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// Act
|
||||||
|
const user = await getUserById('123', 'valid-token');
|
||||||
|
|
||||||
|
// Assert
|
||||||
|
expect(user.id).toBe('123');
|
||||||
|
expect(user.email).toBe('[email protected]');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Example 2: Spring Cloud Contract for Payment Service
|
||||||
|
|
||||||
|
**Scenario:** Generate contract for payment processing service
|
||||||
|
|
||||||
|
**User Input:**
|
||||||
|
```
|
||||||
|
/contract --service payment-service --consumer checkout-app --framework spring
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generated Spring Cloud Contract (Groovy):**
|
||||||
|
```groovy
|
||||||
|
// contracts/payment/process-payment.groovy
|
||||||
|
package contracts.payment
|
||||||
|
|
||||||
|
import org.springframework.cloud.contract.spec.Contract
|
||||||
|
|
||||||
|
Contract.make {
|
||||||
|
description "Process a payment transaction"
|
||||||
|
label "process_payment"
|
||||||
|
|
||||||
|
request {
|
||||||
|
method POST()
|
||||||
|
url "/api/payments"
|
||||||
|
headers {
|
||||||
|
contentType(applicationJson())
|
||||||
|
header("Authorization", "Bearer ${anyNonEmptyString()}")
|
||||||
|
}
|
||||||
|
body([
|
||||||
|
amount: 99.99,
|
||||||
|
currency: "USD",
|
||||||
|
customerId: anyUuid(),
|
||||||
|
paymentMethod: [
|
||||||
|
type: "CARD",
|
||||||
|
cardNumber: regex('[0-9]{16}'),
|
||||||
|
expiryMonth: regex('(0[1-9]|1[0-2])'),
|
||||||
|
expiryYear: regex('20[2-9][0-9]'),
|
||||||
|
cvv: regex('[0-9]{3}')
|
||||||
|
],
|
||||||
|
orderId: anyUuid()
|
||||||
|
])
|
||||||
|
}
|
||||||
|
|
||||||
|
response {
|
||||||
|
status 200
|
||||||
|
headers {
|
||||||
|
contentType(applicationJson())
|
||||||
|
}
|
||||||
|
body([
|
||||||
|
transactionId: anyUuid(),
|
||||||
|
status: "APPROVED",
|
||||||
|
amount: 99.99,
|
||||||
|
currency: "USD",
|
||||||
|
processedAt: anyIso8601DateTime(),
|
||||||
|
authorizationCode: regex('[A-Z0-9]{6}')
|
||||||
|
])
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generated Provider Verification Test:**
|
||||||
|
```java
|
||||||
|
// PaymentContractVerificationTest.java
|
||||||
|
@RunWith(SpringRunner.class)
|
||||||
|
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
|
||||||
|
@AutoConfigureMockMvc
|
||||||
|
@AutoConfigureWebTestClient
|
||||||
|
public class PaymentContractVerificationTest {
|
||||||
|
|
||||||
|
@LocalServerPort
|
||||||
|
private int port;
|
||||||
|
|
||||||
|
@MockBean
|
||||||
|
private PaymentService paymentService;
|
||||||
|
|
||||||
|
@TestTarget
|
||||||
|
public final Target target = new SpringBootHttpTarget();
|
||||||
|
|
||||||
|
@Before
|
||||||
|
public void setup() {
|
||||||
|
RestAssuredMockMvc.webAppContextSetup(context);
|
||||||
|
}
|
||||||
|
|
||||||
|
@State("payment service is available")
|
||||||
|
public void paymentServiceAvailable() {
|
||||||
|
// Setup mock responses
|
||||||
|
PaymentResponse response = PaymentResponse.builder()
|
||||||
|
.transactionId(UUID.randomUUID().toString())
|
||||||
|
.status("APPROVED")
|
||||||
|
.amount(99.99)
|
||||||
|
.currency("USD")
|
||||||
|
.processedAt(Instant.now())
|
||||||
|
.authorizationCode("ABC123")
|
||||||
|
.build();
|
||||||
|
|
||||||
|
when(paymentService.processPayment(any(PaymentRequest.class)))
|
||||||
|
.thenReturn(response);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Example 3: OpenAPI Contract with Validation
|
||||||
|
|
||||||
|
**Scenario:** Generate OpenAPI contract with request/response validation
|
||||||
|
|
||||||
|
**User Input:**
|
||||||
|
```
|
||||||
|
/generate-contract --service product-catalog --format openapi --with-validation
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generated OpenAPI Specification:**
|
||||||
|
```yaml
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Product Catalog API Contract
|
||||||
|
version: 1.0.0
|
||||||
|
description: Contract for product catalog service interactions
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/api/products:
|
||||||
|
get:
|
||||||
|
operationId: getProducts
|
||||||
|
summary: List products with pagination
|
||||||
|
parameters:
|
||||||
|
- name: page
|
||||||
|
in: query
|
||||||
|
required: false
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
minimum: 1
|
||||||
|
default: 1
|
||||||
|
- name: limit
|
||||||
|
in: query
|
||||||
|
required: false
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
minimum: 1
|
||||||
|
maximum: 100
|
||||||
|
default: 20
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful response
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ProductList'
|
||||||
|
examples:
|
||||||
|
success:
|
||||||
|
value:
|
||||||
|
products:
|
||||||
|
- id: "prod-123"
|
||||||
|
name: "Widget Pro"
|
||||||
|
price: 29.99
|
||||||
|
stock: 150
|
||||||
|
pagination:
|
||||||
|
page: 1
|
||||||
|
limit: 20
|
||||||
|
total: 45
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
ProductList:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- products
|
||||||
|
- pagination
|
||||||
|
properties:
|
||||||
|
products:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Product'
|
||||||
|
pagination:
|
||||||
|
$ref: '#/components/schemas/Pagination'
|
||||||
|
|
||||||
|
Product:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- id
|
||||||
|
- name
|
||||||
|
- price
|
||||||
|
- stock
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
pattern: '^prod-[a-z0-9]+$'
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 200
|
||||||
|
price:
|
||||||
|
type: number
|
||||||
|
minimum: 0
|
||||||
|
multipleOf: 0.01
|
||||||
|
stock:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Error: Missing API Documentation
|
||||||
|
**Symptoms:** No OpenAPI spec or API documentation available
|
||||||
|
**Cause:** API not yet documented or in early development
|
||||||
|
**Solution:**
|
||||||
|
```
|
||||||
|
The command will guide you through interactive API definition:
|
||||||
|
- Define endpoints and methods
|
||||||
|
- Specify request/response formats
|
||||||
|
- Add validation rules
|
||||||
|
- Generate initial documentation
|
||||||
|
```
|
||||||
|
**Prevention:** Document APIs as part of development process
|
||||||
|
|
||||||
|
### Error: Incompatible Contract Versions
|
||||||
|
**Symptoms:** Consumer and provider contracts don't match
|
||||||
|
**Cause:** Services evolved independently without coordination
|
||||||
|
**Solution:**
|
||||||
|
```
|
||||||
|
Contract Version Migration:
|
||||||
|
1. Identify breaking changes
|
||||||
|
2. Create compatibility layer
|
||||||
|
3. Version contracts appropriately
|
||||||
|
4. Implement gradual migration
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error: Contract Verification Failure
|
||||||
|
**Symptoms:** Provider tests fail against consumer contracts
|
||||||
|
**Cause:** Implementation doesn't match contract expectations
|
||||||
|
**Solution:**
|
||||||
|
```
|
||||||
|
Debug Contract Mismatches:
|
||||||
|
1. Review failed interaction details
|
||||||
|
2. Check request/response differences
|
||||||
|
3. Update implementation or contract
|
||||||
|
4. Re-run verification tests
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration Options
|
||||||
|
|
||||||
|
The contract generation can be customized with:
|
||||||
|
|
||||||
|
### Option: `--framework`
|
||||||
|
- **Purpose:** Choose contract testing framework
|
||||||
|
- **Values:** `pact`, `spring`, `openapi`, `postman`
|
||||||
|
- **Default:** `pact`
|
||||||
|
- **Example:** `/contract --framework spring`
|
||||||
|
|
||||||
|
### Option: `--strict`
|
||||||
|
- **Purpose:** Enable strict validation rules
|
||||||
|
- **Default:** false
|
||||||
|
- **Example:** `/contract --strict`
|
||||||
|
|
||||||
|
### Option: `--version`
|
||||||
|
- **Purpose:** Specify contract version
|
||||||
|
- **Default:** Auto-incremented
|
||||||
|
- **Example:** `/contract --version 2.0.0`
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
✅ **DO:**
|
||||||
|
- Version your contracts alongside API versions
|
||||||
|
- Run contract tests in CI/CD pipeline
|
||||||
|
- Use contract broker for centralized management
|
||||||
|
- Document breaking changes clearly
|
||||||
|
- Test both happy path and error scenarios
|
||||||
|
|
||||||
|
❌ **DON'T:**
|
||||||
|
- Modify generated contracts manually without updating source
|
||||||
|
- Skip contract verification before deployment
|
||||||
|
- Use contracts as replacement for all testing
|
||||||
|
- Ignore contract test failures
|
||||||
|
|
||||||
|
💡 **TIPS:**
|
||||||
|
- Start with consumer-driven contracts for better API design
|
||||||
|
- Use semantic versioning for contract versions
|
||||||
|
- Implement backwards compatibility when possible
|
||||||
|
- Share contracts between teams early in development
|
||||||
|
|
||||||
|
## Related Commands
|
||||||
|
|
||||||
|
- `/api-versioning-manager` - Manage API versions and migrations
|
||||||
|
- `/api-documentation-generator` - Generate comprehensive API docs
|
||||||
|
- `/api-mock-server` - Create mock servers from contracts
|
||||||
|
- `/api-testing-suite` - Generate integration test suites
|
||||||
|
|
||||||
|
## Performance Considerations
|
||||||
|
|
||||||
|
- **Generation time:** 2-5 seconds for typical API
|
||||||
|
- **Contract size:** Usually <100KB per service pair
|
||||||
|
- **Test execution:** Milliseconds for contract tests
|
||||||
|
- **Scaling:** Supports hundreds of service interactions
|
||||||
|
|
||||||
|
## Security Notes
|
||||||
|
|
||||||
|
⚠️ **Security Considerations:**
|
||||||
|
- Never include real credentials in contracts
|
||||||
|
- Use token placeholders for authentication
|
||||||
|
- Sanitize sensitive data in examples
|
||||||
|
- Store contracts in version control securely
|
||||||
|
- Implement contract access controls in broker
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Issue: Contracts not being published
|
||||||
|
**Solution:** Check broker credentials and network connectivity
|
||||||
|
|
||||||
|
### Issue: Mock server not starting
|
||||||
|
**Solution:** Verify port availability and permissions
|
||||||
|
|
||||||
|
### Issue: Contract tests timing out
|
||||||
|
**Solution:** Increase timeout values for slow services
|
||||||
|
|
||||||
|
### Getting Help
|
||||||
|
- Pact documentation: https://docs.pact.io
|
||||||
|
- Spring Cloud Contract: https://spring.io/projects/spring-cloud-contract
|
||||||
|
- OpenAPI specification: https://swagger.io/specification/
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
- **v2.0.0** - Complete rewrite with multi-framework support
|
||||||
|
- **v1.0.0** - Initial Pact-only implementation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Last updated: 2025-10-11*
|
||||||
|
*Quality score: 9+/10*
|
||||||
|
*Tested with: Pact v10, Spring Cloud Contract v4, OpenAPI v3.0.3*
|
||||||
93
plugin.lock.json
Normal file
93
plugin.lock.json
Normal file
@@ -0,0 +1,93 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/api-development/api-contract-generator",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "5bc6465e2de2fa26b48460e36e2871ca658794c9",
|
||||||
|
"treeHash": "f1ac1033dcda9a769111d70ebefdad405150a43a0671cd81fab1a0229c40953d",
|
||||||
|
"generatedAt": "2025-11-28T10:18:05.576403Z",
|
||||||
|
"toolVersion": "publish_plugins.py@0.2.0"
|
||||||
|
},
|
||||||
|
"origin": {
|
||||||
|
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||||
|
"branch": "master",
|
||||||
|
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||||
|
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||||
|
},
|
||||||
|
"manifest": {
|
||||||
|
"name": "api-contract-generator",
|
||||||
|
"description": "Generate API contracts for consumer-driven contract testing",
|
||||||
|
"version": "1.0.0"
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "0c4b24244f6a1dc47898187a0c26440e5ad5a235db23bdb9364792f0458acaa4"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "b67be2305fbc0dd846ae13bdcfdf8278fa0b8b23cf71195ccc2fc9846d1344ce"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/generate-contract.md",
|
||||||
|
"sha256": "ecee3e4fe310eb97061c68ff621b17b100042b5cfc1c3dda6e0f58c664217acd"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/references/examples.md",
|
||||||
|
"sha256": "922bbc3c4ebf38b76f515b5c1998ebde6bf902233e00e2c5a0e9176f975a7572"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/references/best-practices.md",
|
||||||
|
"sha256": "c8f32b3566252f50daacd346d7045a1060c718ef5cfb07c55a0f2dec5f1fb39e"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/references/README.md",
|
||||||
|
"sha256": "df9b0461ffc6a1e67571c5ebeb662b14c14889c1ce38dd6bb774e118a0e19d2b"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/scripts/helper-template.sh",
|
||||||
|
"sha256": "0881d5660a8a7045550d09ae0acc15642c24b70de6f08808120f47f86ccdf077"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/scripts/validation.sh",
|
||||||
|
"sha256": "92551a29a7f512d2036e4f1fb46c2a3dc6bff0f7dde4a9f699533e446db48502"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/scripts/README.md",
|
||||||
|
"sha256": "83a993fa262758c346e37548ef93893ff5f036cd6e02bf7c78d930d5c61699cb"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/test-data.json",
|
||||||
|
"sha256": "ac17dca3d6e253a5f39f2a2f1b388e5146043756b05d9ce7ac53a0042eee139d"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/example_contract.json",
|
||||||
|
"sha256": "d84c642a7d7f117366991b044695c456d5fcb7f4bda87af716d81dd34d33737c"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/README.md",
|
||||||
|
"sha256": "580f317577d5bc9444f4ec648084aaffa4262a09a9b70992ae34b29dd3f8724e"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/contract_template.json",
|
||||||
|
"sha256": "b2ad3d2cd23c4688ec99ae539576670a632ed3f6671b9c178ff1cf609bea5fdd"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/skill-schema.json",
|
||||||
|
"sha256": "f5639ba823a24c9ac4fb21444c0717b7aefde1a4993682897f5bf544f863c2cd"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/config-template.json",
|
||||||
|
"sha256": "0c2ba33d2d3c5ccb266c0848fc43caa68a2aa6a80ff315d4b378352711f83e1c"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "f1ac1033dcda9a769111d70ebefdad405150a43a0671cd81fab1a0229c40953d"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
6
skills/skill-adapter/assets/README.md
Normal file
6
skills/skill-adapter/assets/README.md
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
# Assets
|
||||||
|
|
||||||
|
Bundled resources for api-contract-generator skill
|
||||||
|
|
||||||
|
- [ ] contract_template.json: A JSON template for the Pact contract, allowing customization of the contract structure.
|
||||||
|
- [ ] example_contract.json: An example of a generated Pact contract.
|
||||||
32
skills/skill-adapter/assets/config-template.json
Normal file
32
skills/skill-adapter/assets/config-template.json
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
{
|
||||||
|
"skill": {
|
||||||
|
"name": "skill-name",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"enabled": true,
|
||||||
|
"settings": {
|
||||||
|
"verbose": false,
|
||||||
|
"autoActivate": true,
|
||||||
|
"toolRestrictions": true
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"triggers": {
|
||||||
|
"keywords": [
|
||||||
|
"example-trigger-1",
|
||||||
|
"example-trigger-2"
|
||||||
|
],
|
||||||
|
"patterns": []
|
||||||
|
},
|
||||||
|
"tools": {
|
||||||
|
"allowed": [
|
||||||
|
"Read",
|
||||||
|
"Grep",
|
||||||
|
"Bash"
|
||||||
|
],
|
||||||
|
"restricted": []
|
||||||
|
},
|
||||||
|
"metadata": {
|
||||||
|
"author": "Plugin Author",
|
||||||
|
"category": "general",
|
||||||
|
"tags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
85
skills/skill-adapter/assets/contract_template.json
Normal file
85
skills/skill-adapter/assets/contract_template.json
Normal file
@@ -0,0 +1,85 @@
|
|||||||
|
{
|
||||||
|
"_comment": "Pact contract template. Customize this to match your API's structure.",
|
||||||
|
"provider": {
|
||||||
|
"name": "YourProviderAPI"
|
||||||
|
},
|
||||||
|
"consumer": {
|
||||||
|
"name": "YourConsumer"
|
||||||
|
},
|
||||||
|
"interactions": [
|
||||||
|
{
|
||||||
|
"_comment": "Example interaction. Modify as needed.",
|
||||||
|
"description": "A request for a user",
|
||||||
|
"request": {
|
||||||
|
"method": "GET",
|
||||||
|
"path": "/users/123",
|
||||||
|
"headers": {
|
||||||
|
"Accept": "application/json"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": {
|
||||||
|
"status": 200,
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json; charset=utf-8"
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"id": 123,
|
||||||
|
"name": "John Doe",
|
||||||
|
"email": "john.doe@example.com",
|
||||||
|
"address": {
|
||||||
|
"street": "123 Main St",
|
||||||
|
"city": "Anytown",
|
||||||
|
"zip": "12345"
|
||||||
|
},
|
||||||
|
"_comment": "You can use Pact matchers here, e.g., using a regex to validate email format.",
|
||||||
|
"email_verification_status": "verified"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"providerStates": [
|
||||||
|
{
|
||||||
|
"name": "User 123 exists",
|
||||||
|
"params": {
|
||||||
|
"user_id": 123
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"_comment": "Another example interaction - creating a new user.",
|
||||||
|
"description": "Creating a new user",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"path": "/users",
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json"
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"name": "Jane Smith",
|
||||||
|
"email": "jane.smith@example.com"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": {
|
||||||
|
"status": 201,
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json; charset=utf-8",
|
||||||
|
"Location": "/users/456"
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"id": 456,
|
||||||
|
"name": "Jane Smith",
|
||||||
|
"email": "jane.smith@example.com"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"providerStates": [
|
||||||
|
{
|
||||||
|
"name": "The user service is available"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"metadata": {
|
||||||
|
"pactSpecification": {
|
||||||
|
"version": "3.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
129
skills/skill-adapter/assets/example_contract.json
Normal file
129
skills/skill-adapter/assets/example_contract.json
Normal file
@@ -0,0 +1,129 @@
|
|||||||
|
{
|
||||||
|
"_comment": "Pact contract example generated by the api-contract-generator plugin.",
|
||||||
|
"provider": {
|
||||||
|
"name": "Article Service"
|
||||||
|
},
|
||||||
|
"consumer": {
|
||||||
|
"name": "Article Reader"
|
||||||
|
},
|
||||||
|
"interactions": [
|
||||||
|
{
|
||||||
|
"_comment": "An interaction represents a single request-response pair.",
|
||||||
|
"description": "a request for an article with ID 123",
|
||||||
|
"request": {
|
||||||
|
"method": "GET",
|
||||||
|
"path": "/articles/123",
|
||||||
|
"headers": {
|
||||||
|
"Accept": "application/json"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": {
|
||||||
|
"status": 200,
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json; charset=utf-8"
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"_comment": "Example article data.",
|
||||||
|
"id": 123,
|
||||||
|
"title": "My First Article",
|
||||||
|
"content": "This is the content of my first article.",
|
||||||
|
"author": "John Doe",
|
||||||
|
"publicationDate": "2024-01-01T00:00:00Z",
|
||||||
|
"tags": ["news", "technology"]
|
||||||
|
},
|
||||||
|
"matchingRules": {
|
||||||
|
"_comment": "Define rules for matching request and response elements.",
|
||||||
|
"$.body.id": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body.title": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body.content": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body.author": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body.publicationDate": {
|
||||||
|
"match": "regex",
|
||||||
|
"regex": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
|
||||||
|
},
|
||||||
|
"$.body.tags": {
|
||||||
|
"match": "type"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"providerStates": [
|
||||||
|
{
|
||||||
|
"name": "an article with ID 123 exists",
|
||||||
|
"params": {
|
||||||
|
"articleId": 123
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"_comment": "Another interaction representing a request for all articles.",
|
||||||
|
"description": "a request for all articles",
|
||||||
|
"request": {
|
||||||
|
"method": "GET",
|
||||||
|
"path": "/articles",
|
||||||
|
"headers": {
|
||||||
|
"Accept": "application/json"
|
||||||
|
},
|
||||||
|
"query": "page=1&limit=10"
|
||||||
|
},
|
||||||
|
"response": {
|
||||||
|
"status": 200,
|
||||||
|
"headers": {
|
||||||
|
"Content-Type": "application/json; charset=utf-8"
|
||||||
|
},
|
||||||
|
"body": [
|
||||||
|
{
|
||||||
|
"id": 123,
|
||||||
|
"title": "My First Article",
|
||||||
|
"content": "This is the content of my first article.",
|
||||||
|
"author": "John Doe",
|
||||||
|
"publicationDate": "2024-01-01T00:00:00Z",
|
||||||
|
"tags": ["news", "technology"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 456,
|
||||||
|
"title": "Another Article",
|
||||||
|
"content": "This is another article.",
|
||||||
|
"author": "Jane Smith",
|
||||||
|
"publicationDate": "2024-01-05T10:00:00Z",
|
||||||
|
"tags": ["sports", "local"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"matchingRules": {
|
||||||
|
"$.body[*].id": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body[*].title": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body[*].content": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body[*].author": {
|
||||||
|
"match": "type"
|
||||||
|
},
|
||||||
|
"$.body[*].publicationDate": {
|
||||||
|
"match": "regex",
|
||||||
|
"regex": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
|
||||||
|
},
|
||||||
|
"$.body[*].tags": {
|
||||||
|
"match": "type"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"metadata": {
|
||||||
|
"pactSpecification": {
|
||||||
|
"version": "3.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
28
skills/skill-adapter/assets/skill-schema.json
Normal file
28
skills/skill-adapter/assets/skill-schema.json
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
{
|
||||||
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||||
|
"title": "Claude Skill Configuration",
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name", "description"],
|
||||||
|
"properties": {
|
||||||
|
"name": {
|
||||||
|
"type": "string",
|
||||||
|
"pattern": "^[a-z0-9-]+$",
|
||||||
|
"maxLength": 64,
|
||||||
|
"description": "Skill identifier (lowercase, hyphens only)"
|
||||||
|
},
|
||||||
|
"description": {
|
||||||
|
"type": "string",
|
||||||
|
"maxLength": 1024,
|
||||||
|
"description": "What the skill does and when to use it"
|
||||||
|
},
|
||||||
|
"allowed-tools": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Comma-separated list of allowed tools"
|
||||||
|
},
|
||||||
|
"version": {
|
||||||
|
"type": "string",
|
||||||
|
"pattern": "^\\d+\\.\\d+\\.\\d+$",
|
||||||
|
"description": "Semantic version (x.y.z)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
27
skills/skill-adapter/assets/test-data.json
Normal file
27
skills/skill-adapter/assets/test-data.json
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
{
|
||||||
|
"testCases": [
|
||||||
|
{
|
||||||
|
"name": "Basic activation test",
|
||||||
|
"input": "trigger phrase example",
|
||||||
|
"expected": {
|
||||||
|
"activated": true,
|
||||||
|
"toolsUsed": ["Read", "Grep"],
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Complex workflow test",
|
||||||
|
"input": "multi-step trigger example",
|
||||||
|
"expected": {
|
||||||
|
"activated": true,
|
||||||
|
"steps": 3,
|
||||||
|
"toolsUsed": ["Read", "Write", "Bash"],
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"fixtures": {
|
||||||
|
"sampleInput": "example data",
|
||||||
|
"expectedOutput": "processed result"
|
||||||
|
}
|
||||||
|
}
|
||||||
7
skills/skill-adapter/references/README.md
Normal file
7
skills/skill-adapter/references/README.md
Normal file
@@ -0,0 +1,7 @@
|
|||||||
|
# References
|
||||||
|
|
||||||
|
Bundled resources for api-contract-generator skill
|
||||||
|
|
||||||
|
- [ ] pact_best_practices.md: A document outlining best practices for using Pact for consumer-driven contract testing.
|
||||||
|
- [ ] api_specification_schema.json: A JSON schema defining the structure of the API specification used for contract generation.
|
||||||
|
- [ ] example_api_spec.yaml: An example API specification in YAML format.
|
||||||
69
skills/skill-adapter/references/best-practices.md
Normal file
69
skills/skill-adapter/references/best-practices.md
Normal file
@@ -0,0 +1,69 @@
|
|||||||
|
# Skill Best Practices
|
||||||
|
|
||||||
|
Guidelines for optimal skill usage and development.
|
||||||
|
|
||||||
|
## For Users
|
||||||
|
|
||||||
|
### Activation Best Practices
|
||||||
|
|
||||||
|
1. **Use Clear Trigger Phrases**
|
||||||
|
- Match phrases from skill description
|
||||||
|
- Be specific about intent
|
||||||
|
- Provide necessary context
|
||||||
|
|
||||||
|
2. **Provide Sufficient Context**
|
||||||
|
- Include relevant file paths
|
||||||
|
- Specify scope of analysis
|
||||||
|
- Mention any constraints
|
||||||
|
|
||||||
|
3. **Understand Tool Permissions**
|
||||||
|
- Check allowed-tools in frontmatter
|
||||||
|
- Know what the skill can/cannot do
|
||||||
|
- Request appropriate actions
|
||||||
|
|
||||||
|
### Workflow Optimization
|
||||||
|
|
||||||
|
- Start with simple requests
|
||||||
|
- Build up to complex workflows
|
||||||
|
- Verify each step before proceeding
|
||||||
|
- Use skill consistently for related tasks
|
||||||
|
|
||||||
|
## For Developers
|
||||||
|
|
||||||
|
### Skill Development Guidelines
|
||||||
|
|
||||||
|
1. **Clear Descriptions**
|
||||||
|
- Include explicit trigger phrases
|
||||||
|
- Document all capabilities
|
||||||
|
- Specify limitations
|
||||||
|
|
||||||
|
2. **Proper Tool Permissions**
|
||||||
|
- Use minimal necessary tools
|
||||||
|
- Document security implications
|
||||||
|
- Test with restricted tools
|
||||||
|
|
||||||
|
3. **Comprehensive Documentation**
|
||||||
|
- Provide usage examples
|
||||||
|
- Document common pitfalls
|
||||||
|
- Include troubleshooting guide
|
||||||
|
|
||||||
|
### Maintenance
|
||||||
|
|
||||||
|
- Keep version updated
|
||||||
|
- Test after tool updates
|
||||||
|
- Monitor user feedback
|
||||||
|
- Iterate on descriptions
|
||||||
|
|
||||||
|
## Performance Tips
|
||||||
|
|
||||||
|
- Scope skills to specific domains
|
||||||
|
- Avoid overlapping trigger phrases
|
||||||
|
- Keep descriptions under 1024 chars
|
||||||
|
- Test activation reliability
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
- Never include secrets in skill files
|
||||||
|
- Validate all inputs
|
||||||
|
- Use read-only tools when possible
|
||||||
|
- Document security requirements
|
||||||
70
skills/skill-adapter/references/examples.md
Normal file
70
skills/skill-adapter/references/examples.md
Normal file
@@ -0,0 +1,70 @@
|
|||||||
|
# Skill Usage Examples
|
||||||
|
|
||||||
|
This document provides practical examples of how to use this skill effectively.
|
||||||
|
|
||||||
|
## Basic Usage
|
||||||
|
|
||||||
|
### Example 1: Simple Activation
|
||||||
|
|
||||||
|
**User Request:**
|
||||||
|
```
|
||||||
|
[Describe trigger phrase here]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Skill Response:**
|
||||||
|
1. Analyzes the request
|
||||||
|
2. Performs the required action
|
||||||
|
3. Returns results
|
||||||
|
|
||||||
|
### Example 2: Complex Workflow
|
||||||
|
|
||||||
|
**User Request:**
|
||||||
|
```
|
||||||
|
[Describe complex scenario]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
1. Step 1: Initial analysis
|
||||||
|
2. Step 2: Data processing
|
||||||
|
3. Step 3: Result generation
|
||||||
|
4. Step 4: Validation
|
||||||
|
|
||||||
|
## Advanced Patterns
|
||||||
|
|
||||||
|
### Pattern 1: Chaining Operations
|
||||||
|
|
||||||
|
Combine this skill with other tools:
|
||||||
|
```
|
||||||
|
Step 1: Use this skill for [purpose]
|
||||||
|
Step 2: Chain with [other tool]
|
||||||
|
Step 3: Finalize with [action]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 2: Error Handling
|
||||||
|
|
||||||
|
If issues occur:
|
||||||
|
- Check trigger phrase matches
|
||||||
|
- Verify context is available
|
||||||
|
- Review allowed-tools permissions
|
||||||
|
|
||||||
|
## Tips & Best Practices
|
||||||
|
|
||||||
|
- ✅ Be specific with trigger phrases
|
||||||
|
- ✅ Provide necessary context
|
||||||
|
- ✅ Check tool permissions match needs
|
||||||
|
- ❌ Avoid vague requests
|
||||||
|
- ❌ Don't mix unrelated tasks
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
**Issue:** Skill doesn't activate
|
||||||
|
**Solution:** Use exact trigger phrases from description
|
||||||
|
|
||||||
|
**Issue:** Unexpected results
|
||||||
|
**Solution:** Check input format and context
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- Main SKILL.md for full documentation
|
||||||
|
- scripts/ for automation helpers
|
||||||
|
- assets/ for configuration examples
|
||||||
6
skills/skill-adapter/scripts/README.md
Normal file
6
skills/skill-adapter/scripts/README.md
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
# Scripts
|
||||||
|
|
||||||
|
Bundled resources for api-contract-generator skill
|
||||||
|
|
||||||
|
- [ ] generate_pact_contract.py: A script to generate a Pact contract based on user input and API specifications.
|
||||||
|
- [ ] validate_contract.py: A script to validate the generated Pact contract against a schema or API definition.
|
||||||
42
skills/skill-adapter/scripts/helper-template.sh
Executable file
42
skills/skill-adapter/scripts/helper-template.sh
Executable file
@@ -0,0 +1,42 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Helper script template for skill automation
|
||||||
|
# Customize this for your skill's specific needs
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
function show_usage() {
|
||||||
|
echo "Usage: $0 [options]"
|
||||||
|
echo ""
|
||||||
|
echo "Options:"
|
||||||
|
echo " -h, --help Show this help message"
|
||||||
|
echo " -v, --verbose Enable verbose output"
|
||||||
|
echo ""
|
||||||
|
}
|
||||||
|
|
||||||
|
# Parse arguments
|
||||||
|
VERBOSE=false
|
||||||
|
|
||||||
|
while [[ $# -gt 0 ]]; do
|
||||||
|
case $1 in
|
||||||
|
-h|--help)
|
||||||
|
show_usage
|
||||||
|
exit 0
|
||||||
|
;;
|
||||||
|
-v|--verbose)
|
||||||
|
VERBOSE=true
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
echo "Unknown option: $1"
|
||||||
|
show_usage
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
# Your skill logic here
|
||||||
|
if [ "$VERBOSE" = true ]; then
|
||||||
|
echo "Running skill automation..."
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✅ Complete"
|
||||||
32
skills/skill-adapter/scripts/validation.sh
Executable file
32
skills/skill-adapter/scripts/validation.sh
Executable file
@@ -0,0 +1,32 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Skill validation helper
|
||||||
|
# Validates skill activation and functionality
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
echo "🔍 Validating skill..."
|
||||||
|
|
||||||
|
# Check if SKILL.md exists
|
||||||
|
if [ ! -f "../SKILL.md" ]; then
|
||||||
|
echo "❌ Error: SKILL.md not found"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Validate frontmatter
|
||||||
|
if ! grep -q "^---$" "../SKILL.md"; then
|
||||||
|
echo "❌ Error: No frontmatter found"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check required fields
|
||||||
|
if ! grep -q "^name:" "../SKILL.md"; then
|
||||||
|
echo "❌ Error: Missing 'name' field"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! grep -q "^description:" "../SKILL.md"; then
|
||||||
|
echo "❌ Error: Missing 'description' field"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✅ Skill validation passed"
|
||||||
Reference in New Issue
Block a user