agentleFS
prime-radiant-incprime-radiant-inc/greenfield/skills/contract-detection/SKILL.md

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.

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
  1. Distinctive:

    When multiple contract types are present (e.g., both OpenAPI and GraphQL, or OpenAPI with JSON Schema references), correlate them:

    line 386
  2. Distinctive:

    Do the endpoint definitions agree on field names and types?

    line 388
  3. Distinctive:

    Do version numbers align?

    line 390
  4. Very specific:

    Document correlations and discrepancies in workspace/public/contracts/cross-contract-notes.md.

    line 393
  5. Very specific:

    All claims from contract detection use source=machine-readable-contract:

    line 399
  6. Very specific:

    Every behavioral claim gets an inline citation immediately after the claim.

    line 414

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-docs

Extraction

For each OpenAPI/Swagger specification, extract:

Endpoints

FieldWhat It Tells You
pathsEvery endpoint the API exposes
HTTP methodThe operation type (GET=read, POST=create, PUT=replace, PATCH=update, DELETE=remove)
operationIdThe canonical name for the operation
summary / descriptionBehavioral description of what the endpoint does
tagsLogical grouping of endpoints

Parameters

FieldWhat It Tells You
parameters (path, query, header, cookie)Required inputs and their types
requiredWhether the parameter is mandatory
schema with enumAllowed values (behavioral constraint)
schema with minimum / maximumValue range (behavioral constraint)
schema with patternValidation regex (behavioral constraint)
schema with defaultDefault value when omitted

Request/Response Schemas

FieldWhat It Tells You
requestBodyWhat the endpoint accepts (content type, schema)
responsesEvery possible response code and its schema
responses.4xxClient error conditions and their structure
responses.5xxServer error conditions
components/schemasShared data models with field types, constraints, and relationships

Authentication

FieldWhat It Tells You
securityDefinitions / components/securitySchemesAuth 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)

ElementWhat It Tells You
Query type fieldsEvery read operation the API exposes
ArgumentsRequired and optional parameters with types
Return typesShape of the response data
Directives (@deprecated, @auth)Behavioral modifiers

Mutations (Write Operations)

ElementWhat It Tells You
Mutation type fieldsEvery write operation the API exposes
Input typesShape of the data the operation accepts
Return typesWhat the operation returns after modification
Error handling patternsUnion types for success/error returns

Subscriptions (Real-Time Operations)

ElementWhat It Tells You
Subscription type fieldsEvents the client can subscribe to
ArgumentsSubscription filters
Payload typesShape of the real-time data

Type System

ElementWhat It Tells You
Object typesData entities and their fields
Enum typesAllowed values for categorical fields
Interface typesShared behavioral contracts across types
Union typesPolymorphic response shapes
Input typesStructured input shapes for mutations
Custom scalarsDomain-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/null

Extraction

For each .proto file, extract:

Services

ElementWhat It Tells You
service definitionsLogical groupings of RPC methods
rpc methodsEvery callable operation
Request/response typesInput and output shapes
Streaming modifiersstream on request, response, or both

Messages

ElementWhat It Tells You
message definitionsData structures used in requests and responses
Field types and numbersSchema with wire-format compatibility rules
repeated fieldsArray/list fields
oneof fieldsUnion types (exactly one field set)
optional / requiredField presence requirements
map fieldsKey-value pair fields

Enums

ElementWhat It Tells You
enum definitionsAllowed categorical values
option allow_aliasWhether multiple names map to the same value

Options

ElementWhat It Tells You
option java_packageTarget language packaging
option go_packageGo module path
Custom optionsDomain-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

ElementWhat It Tells You
typeThe data type (object, array, string, number, boolean, null)
propertiesNamed fields with their own schemas
requiredFields that must be present
additionalPropertiesWhether unknown fields are allowed

Validation Rules

ElementWhat It Tells You
minLength / maxLengthString length constraints
minimum / maximumNumeric range constraints
patternRegex validation for strings
formatSemantic format (email, uri, date-time, uuid)
enumAllowed values
constFixed required value
minItems / maxItemsArray length constraints
uniqueItemsWhether array elements must be unique

Composition

ElementWhat It Tells You
$refReferences to shared schema definitions
allOfSchema intersection (all must match)
anyOfSchema union (at least one must match)
oneOfSchema exclusive union (exactly one must match)
notSchema negation
if / then / elseConditional validation

Defaults and Examples

ElementWhat It Tells You
defaultDefault value when field is omitted
examplesExample values (behavioral documentation)
descriptionHuman-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 10

Cross-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.json

Note: 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

  1. Contracts are PUBLIC -- machine-readable contracts are published interface definitions. Output goes to workspace/public/, not workspace/raw/.
  2. Exhaustive extraction -- extract EVERY endpoint, field, constraint, and error code. Contracts are finite and complete. Do not sample.
  3. Preserve precision -- contracts define exact types, constraints, and enums. Do not paraphrase "minLength: 1, maxLength: 100" as "limited length." Preserve the exact constraints.
  4. Note versions -- contracts have version fields. Always record the version. Behavioral claims from contracts are version-specific.
  5. 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).
  6. Copy originals -- place copies of discovered contract files in workspace/public/contracts/raw/ for downstream reference.
  7. Cite as you go -- every behavioral claim gets an inline <!-- cite: --> comment immediately after the claim. Never defer citation to a later step.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.