contract-detection
Skill284 starsChanged 6 months agoApache-2.0View on GitHub
Layer 1 skill for parsing machine-readable API contracts. OpenAPI/Swagger, GraphQL, Protobuf/gRPC, and JSON Schema detection, extraction, and behavioral claim generation. Loaded by the analyzer agent during Layer 1.
In this repository21 other files it gives its agents.
- analysis-pipelineSkill
- autonomous-discoverySkill
- behavioral-spec-writingSkill
- binary-analysisSkill
- community-intelligenceSkill
- container-executionSkill
- doc-researchSkill
- ecosystem-analysisSkill
- fidelity-validationSkill
- git-archaeologySkill
- incremental-analysisSkill
- multi-source-synthesisSkill
- provenance-methodologySkill
- runtime-observationSkill
- second-pass-reviewSkill
- source-analysisSkill
- source-completenessSkill
- spec-sanitizationSkill
- test-suite-analysisSkill
- validation-methodologySkill
- visual-explorationSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 386
When multiple contract types are present (e.g., both OpenAPI and GraphQL, or OpenAPI with JSON Schema references), correlate them:
- Distinctive: line 388
Do the endpoint definitions agree on field names and types?
- Distinctive: line 390
Do version numbers align?
- Very specific: line 393
Document correlations and discrepancies in workspace/public/contracts/cross-contract-notes.md.
- Very specific: line 399
All claims from contract detection use source=machine-readable-contract:
- Very specific: line 414
Every behavioral claim gets an inline citation immediately after the claim.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Contract Detection Methodology
Extract behavioral intelligence from machine-readable API contracts. These are formal, published definitions of system interfaces -- the strongest possible specification source. A contract file is an explicit promise about what the system accepts and returns.
When to Use This Mode
Contract detection activates when:
- The target repository or documentation contains API specification files
- The discovery inventory identifies machine-readable contract files
- Other modes discover machine-readable contracts during analysis
This mode runs independently of all other intelligence sources. All output is PUBLIC -- machine-readable contracts are published definitions intended for external consumption. Output goes to workspace/public/contracts/.
Why Contracts Are the Strongest Source
Machine-readable contracts are unique among intelligence sources because they are:
- Formal -- they use standardized schemas with unambiguous semantics
- Published -- they are intended for external consumers to rely on
- Machine-verifiable -- they can be validated against implementations automatically
- Versioned -- they explicitly track breaking changes through version fields
A single OpenAPI specification can contain more behavioral intelligence than the entire official documentation site, because every endpoint, parameter, response schema, and error code is defined with machine precision.
OpenAPI / Swagger
Detection
# Find OpenAPI/Swagger files
find . -maxdepth 5 -type f \( \
-name "openapi.*" -o -name "swagger.*" -o \
-name "api-spec.*" -o -name "api-docs.*" \
\) \( -name "*.json" -o -name "*.yaml" -o -name "*.yml" \) 2>/dev/null
# Check for OpenAPI version markers in YAML/JSON files
grep -rl '"openapi":\|openapi:' --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | head -20
grep -rl '"swagger":\|swagger:' --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | head -20
# Check for hosted spec endpoints (common locations)
# /api-docs, /swagger.json, /openapi.json, /v2/api-docs, /v3/api-docsExtraction
For each OpenAPI/Swagger specification, extract:
Endpoints
| Field | What It Tells You |
paths | Every endpoint the API exposes |
| HTTP method | The operation type (GET=read, POST=create, PUT=replace, PATCH=update, DELETE=remove) |
operationId | The canonical name for the operation |
summary / description | Behavioral description of what the endpoint does |
tags | Logical grouping of endpoints |
Parameters
| Field | What It Tells You |
parameters (path, query, header, cookie) | Required inputs and their types |
required | Whether the parameter is mandatory |
schema with enum | Allowed values (behavioral constraint) |
schema with minimum / maximum | Value range (behavioral constraint) |
schema with pattern | Validation regex (behavioral constraint) |
schema with default | Default value when omitted |
Request/Response Schemas
| Field | What It Tells You |
requestBody | What the endpoint accepts (content type, schema) |
responses | Every possible response code and its schema |
responses.4xx | Client error conditions and their structure |
responses.5xx | Server error conditions |
components/schemas | Shared data models with field types, constraints, and relationships |
Authentication
| Field | What It Tells You |
securityDefinitions / components/securitySchemes | Auth methods (API key, OAuth2, Bearer, Basic) |
security (global or per-operation) | Which endpoints require which auth |
Output Format
Write to workspace/public/contracts/openapi-summary.md:
## API: {title} v{version}
### Endpoints
| Method | Path | Operation | Auth Required | Description |
|--------|------|-----------|---------------|-------------|
| GET | /users | listUsers | Bearer | List all users with pagination |
| POST | /users | createUser | Bearer | Create a new user |
### Data Models
#### User
| Field | Type | Required | Constraints | Description |
|-------|------|----------|-------------|-------------|
| id | string (uuid) | yes | read-only | Unique identifier |
| email | string | yes | format: email | User's email address |
### Error Responses
| Code | Meaning | Schema |
|------|---------|--------|
| 400 | Validation error | { message: string, errors: [{field, code}] } |
| 401 | Unauthorized | { message: string } |
| 404 | Not found | { message: string } |GraphQL
Detection
# Find GraphQL schema files
find . -maxdepth 5 -type f \( \
-name "schema.graphql" -o -name "*.graphqls" -o -name "schema.gql" -o \
-name "*.graphql" \
\) 2>/dev/null
# Find GraphQL codegen config (indicates GraphQL usage)
find . -maxdepth 3 -type f \( \
-name "codegen.*" -o -name ".graphqlrc*" -o -name "apollo.config.*" \
\) 2>/dev/null
# Check for GraphQL in dependencies
grep -l "graphql\|apollo\|@graphql" package.json requirements.txt Gemfile go.mod 2>/dev/null
# Check for introspection endpoint (if running instance available)
# POST /graphql with { "query": "{ __schema { types { name } } }" }Extraction
For each GraphQL schema, extract:
Queries (Read Operations)
| Element | What It Tells You |
| Query type fields | Every read operation the API exposes |
| Arguments | Required and optional parameters with types |
| Return types | Shape of the response data |
Directives (@deprecated, @auth) | Behavioral modifiers |
Mutations (Write Operations)
| Element | What It Tells You |
| Mutation type fields | Every write operation the API exposes |
| Input types | Shape of the data the operation accepts |
| Return types | What the operation returns after modification |
| Error handling patterns | Union types for success/error returns |
Subscriptions (Real-Time Operations)
| Element | What It Tells You |
| Subscription type fields | Events the client can subscribe to |
| Arguments | Subscription filters |
| Payload types | Shape of the real-time data |
Type System
| Element | What It Tells You |
| Object types | Data entities and their fields |
| Enum types | Allowed values for categorical fields |
| Interface types | Shared behavioral contracts across types |
| Union types | Polymorphic response shapes |
| Input types | Structured input shapes for mutations |
| Custom scalars | Domain-specific value types (DateTime, JSON, URL) |
Output Format
Write to workspace/public/contracts/graphql-summary.md:
## GraphQL Schema
### Queries
| Query | Arguments | Returns | Description |
|-------|-----------|---------|-------------|
| users | filter: UserFilter, page: Int | [User!]! | List users with filtering |
| user | id: ID! | User | Get user by ID |
### Mutations
| Mutation | Input | Returns | Description |
|----------|-------|---------|-------------|
| createUser | input: CreateUserInput! | User! | Create a new user |
| deleteUser | id: ID! | Boolean! | Delete user by ID |
### Subscriptions
| Subscription | Arguments | Payload | Description |
|-------------|-----------|---------|-------------|
| userCreated | — | User! | Fires when a new user is created |
### Types
#### User
| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| id | ID | no | Unique identifier |
| email | String | no | Email address |
| role | UserRole | no | Enum: ADMIN, USER, VIEWER |Protobuf / gRPC
Detection
# Find .proto files
find . -maxdepth 5 -type f -name "*.proto" 2>/dev/null
# Check for gRPC in dependencies
grep -l "grpc\|protobuf" package.json requirements.txt Gemfile go.mod Cargo.toml 2>/dev/null
# Find generated gRPC code
find . -maxdepth 5 -type f \( -name "*_grpc.pb.go" -o -name "*_pb2_grpc.py" -o -name "*_grpc.rb" \) 2>/dev/nullExtraction
For each .proto file, extract:
Services
| Element | What It Tells You |
service definitions | Logical groupings of RPC methods |
rpc methods | Every callable operation |
| Request/response types | Input and output shapes |
| Streaming modifiers | stream on request, response, or both |
Messages
| Element | What It Tells You |
message definitions | Data structures used in requests and responses |
| Field types and numbers | Schema with wire-format compatibility rules |
repeated fields | Array/list fields |
oneof fields | Union types (exactly one field set) |
optional / required | Field presence requirements |
map fields | Key-value pair fields |
Enums
| Element | What It Tells You |
enum definitions | Allowed categorical values |
option allow_alias | Whether multiple names map to the same value |
Options
| Element | What It Tells You |
option java_package | Target language packaging |
option go_package | Go module path |
| Custom options | Domain-specific metadata |
Output Format
Write to workspace/public/contracts/protobuf-summary.md:
## Protobuf/gRPC Services
### Service: UserService
| RPC | Request | Response | Streaming | Description |
|-----|---------|----------|-----------|-------------|
| GetUser | GetUserRequest | User | none | Get user by ID |
| ListUsers | ListUsersRequest | ListUsersResponse | none | List users with pagination |
| WatchUsers | WatchUsersRequest | User | server-stream | Stream user updates |
### Messages
#### User
| Field | Number | Type | Label | Description |
|-------|--------|------|-------|-------------|
| id | 1 | string | — | Unique identifier |
| email | 2 | string | — | Email address |
| role | 3 | UserRole | — | User role |
### Enums
#### UserRole
| Name | Number |
|------|--------|
| USER_ROLE_UNSPECIFIED | 0 |
| USER_ROLE_ADMIN | 1 |
| USER_ROLE_USER | 2 |JSON Schema
Detection
# Find JSON Schema files
find . -maxdepth 5 -type f -name "*.schema.json" 2>/dev/null
find . -maxdepth 5 -type f -name "*.json" -exec grep -l '"$schema"' {} \; 2>/dev/null | head -20
# Check for JSON Schema in config files
grep -rl '"$schema":\|"\$ref"' --include="*.json" . 2>/dev/null | head -20
# Find JSON Schema in OpenAPI components (already covered above, but note cross-reference)Extraction
For each JSON Schema, extract:
Type Definitions
| Element | What It Tells You |
type | The data type (object, array, string, number, boolean, null) |
properties | Named fields with their own schemas |
required | Fields that must be present |
additionalProperties | Whether unknown fields are allowed |
Validation Rules
| Element | What It Tells You |
minLength / maxLength | String length constraints |
minimum / maximum | Numeric range constraints |
pattern | Regex validation for strings |
format | Semantic format (email, uri, date-time, uuid) |
enum | Allowed values |
const | Fixed required value |
minItems / maxItems | Array length constraints |
uniqueItems | Whether array elements must be unique |
Composition
| Element | What It Tells You |
$ref | References to shared schema definitions |
allOf | Schema intersection (all must match) |
anyOf | Schema union (at least one must match) |
oneOf | Schema exclusive union (exactly one must match) |
not | Schema negation |
if / then / else | Conditional validation |
Defaults and Examples
| Element | What It Tells You |
default | Default value when field is omitted |
examples | Example values (behavioral documentation) |
description | Human-readable behavioral description |
Output Format
Write to workspace/public/contracts/json-schema-summary.md:
## JSON Schema: {title}
### Type: CreateUserRequest
| Property | Type | Required | Constraints | Default | Description |
|----------|------|----------|-------------|---------|-------------|
| email | string | yes | format: email | — | User email address |
| name | string | yes | minLength: 1, maxLength: 100 | — | Display name |
| role | string | no | enum: [admin, user, viewer] | "user" | User role |
| tags | array of string | no | maxItems: 10, uniqueItems: true | [] | User tags |
### Validation Rules
- `email` must match email format (RFC 5322)
- `name` must be 1-100 characters
- `role` defaults to "user" when omitted
- `tags` must contain unique strings, maximum 10Cross-Contract Correlation
When multiple contract types are present (e.g., both OpenAPI and GraphQL, or OpenAPI with JSON Schema references), correlate them:
- Do the endpoint definitions agree on field names and types?
- Are the same data models defined consistently across contracts?
- Do version numbers align?
- Are there endpoints in one contract that are missing from another?
Document correlations and discrepancies in workspace/public/contracts/cross-contract-notes.md.
Provenance Rules
Source Type
All claims from contract detection use source=machine-readable-contract:
- The /users endpoint accepts a `role` query parameter with values: admin, user, viewer
<!-- cite: source=machine-readable-contract, ref=openapi.yaml:/paths/~1users/get/parameters/0, confidence=confirmed, agent=contract-detector -->Confidence Levels
- confirmed -- the behavioral claim is explicitly defined in the contract schema (endpoint exists, field has this type, parameter has this constraint). Machine-readable contracts are formal specifications; their explicit definitions are confirmed by definition.
- inferred -- the behavioral claim is derived from contract structure rather than explicit definition (e.g., "this API follows REST conventions" inferred from path patterns)
- assumed -- the behavioral claim extrapolates beyond what the contract defines (e.g., "this endpoint probably supports pagination" because similar endpoints do)
Cite As You Go
Every behavioral claim gets an inline citation immediately after the claim. The ref field should be <file-path>:<json-path-or-line>.
Output Structure
workspace/public/contracts/
openapi-summary.md # OpenAPI/Swagger extraction
graphql-summary.md # GraphQL schema extraction
protobuf-summary.md # Protobuf/gRPC extraction
json-schema-summary.md # JSON Schema extraction
cross-contract-notes.md # Correlations and discrepancies across contract types
raw/ # Copies of discovered contract files for reference
openapi.yaml
schema.graphql
service.proto
config.schema.jsonNote: Output goes to workspace/public/contracts/ -- not workspace/raw/. Machine-readable contracts are published definitions intended for external consumption. They contain no proprietary implementation details.
Rules
- Contracts are PUBLIC -- machine-readable contracts are published interface definitions. Output goes to
workspace/public/, notworkspace/raw/. - Exhaustive extraction -- extract EVERY endpoint, field, constraint, and error code. Contracts are finite and complete. Do not sample.
- Preserve precision -- contracts define exact types, constraints, and enums. Do not paraphrase "minLength: 1, maxLength: 100" as "limited length." Preserve the exact constraints.
- Note versions -- contracts have version fields. Always record the version. Behavioral claims from contracts are version-specific.
- Detect staleness -- a contract file may be outdated relative to the implementation. Flag contracts that appear unmaintained (old modification dates, version mismatches with the codebase).
- Copy originals -- place copies of discovered contract files in
workspace/public/contracts/raw/for downstream reference. - Cite as you go -- every behavioral claim gets an inline
<!-- cite: -->comment immediately after the claim. Never defer citation to a later step.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

