interface-contract
Skill0 starsChanged 3 days agoMITView on GitHub
Engineering interface contract standard. Unifies input, output, field types, invocation method, exception handling, and compatibility between modules.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- June74/agentic-workflowtheir own version, first seen Aug 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- June74/agentic-workflow★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository17 other files it gives its agents.
- .cursor/rules/engineering-context.mdcCursor rule
- change-report-deliverySkill
- code-asset-inventorySkill
- data-audit-reproducibilitySkill
- data-first-executionSkill
- documentation-structureSkill
- engineering-context-completenessSkill
- engineering-transparencySkill
- explicit-instruction-fidelitySkill
- language-expressionSkill
- production-loggingSkill
- repository-publication-hygieneSkill
- task-execution-governanceSkill
- technical-documentationSkill
- testing-verificationSkill
- unfinished-work-trackingSkill
- user-intent-prioritySkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
No module may have only an implementation and no interface.
- Distinctive: line 13
No module may have only an output and no format definition.
- Distinctive: line 15
No downstream module may complete development by guessing the upstream data structure.
- Distinctive: line 115
If conversion is genuinely needed:
- Distinctive: line 127
Before modifying an existing interface, must:
- Distinctive: line 129
Search for all callers.
- Distinctive: line 130
Check input data sources.
- Distinctive: line 131
Check output data consumers.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Engineering Interface Contract Standard
I. Core Principle
No module may have only an implementation and no interface.
No module may have only an output and no format definition.
No downstream module may complete development by guessing the upstream data structure.
There must be explicit, stable, and verifiable interface contracts between modules.
II. Module Responsibilities Must Be Defined Before Development
Clarify:
- What problem the module solves.
- Which work the module is responsible for.
- Which work does not belong to that module.
- Who provides the data upstream.
- Who uses the results downstream.
- Whether reusable existing modules exist.
It is forbidden to place unrelated responsibilities into a single module.
III. Input Contract
Must make clear:
- Input source.
- Input format.
- Input structure.
- Required fields.
- Optional fields.
- Field types.
- Field meanings.
- Whether null is allowed.
- Default values.
- Enumeration ranges.
- Data constraints.
- How missing fields are handled.
- How invalid input is handled.
Must distinguish:
- Field not provided.
- Field value is null.
- Empty string.
- Empty array.
- Empty object.
- Type error.
These cases must not be treated as identical without prior definition.
IV. Output Contract
Must make clear:
- Output content.
- Output format.
- Output location.
- Field names.
- Field types.
- Field meanings.
- Required and optional rules.
- Data status.
- Error message structure.
- How downstream reads it.
Output formats should preferentially follow the project's existing conventions.
Existing field names and types must not be changed without authorization.
V. Invocation Contract
Clarify:
- Invocation entry point.
- Invocation parameters.
- Parameter types.
- Default values.
- Execution method.
- Success return value.
- Failure return value.
- Timeout handling.
- Retry strategy.
- External dependencies.
- Whether batch processing is supported.
VI. Module Responsibility Boundaries
Each module is responsible only for the work within the agreed scope.
For example:
- A collection module is responsible for obtaining raw data.
- A parsing module is responsible for parsing data.
- A normalization module is responsible for unifying data formats.
- An analysis module is responsible for computation and judgment.
- An output module is responsible for producing the final results.
The specific responsibilities are determined by the actual project architecture.
Multiple modules must not separately maintain the same set of business rules.
VII. Field Consistency
The same category of data should preferentially use unified field names and data types.
If conversion is genuinely needed:
- Clarify the original field.
- Clarify the target field.
- Clarify the conversion rule.
- Clarify which module is responsible for it.
- Clarify whether the original value is retained after conversion.
Each downstream module must not implement field conversion on its own.
VIII. Interface Changes
Before modifying an existing interface, must:
- Search for all callers.
- Check input data sources.
- Check output data consumers.
- Assess field changes.
- Assess type changes.
- Assess compatibility.
- Determine the migration plan.
Compatible extension is preferred.
Fields must not be deleted or types changed directly without assessment.
8.1 Existing Field Names Must Not Be Renamed on the Agent's Initiative
An existing field name must not be changed on the agent's own initiative.
Where historical data, interface compatibility, or a database migration is involved, the impact must be analyzed and a proposal put forward first, covering:
- Which callers, data sources, and consumers are affected.
- Whether historical data must be migrated, and how.
- Whether a compatibility window is needed for external consumers.
- Whether the two names must be carried simultaneously, and for how long.
- How the migration is verified.
A name that is unclear may still be retained. A clearer name does not by itself authorize a rename.
8.2 Relationship to Naming Rules
How a new name is chosen is governed by language-expression, section IX, which forbids arbitrary abbreviation and compressed naming. Whether an existing name may be changed is governed by this section.
IX. Exception Contract
Exceptions must clearly distinguish:
- Input validation failure.
- Business rule violation.
- External service failure.
- Data parsing failure.
- File read/write failure.
- Database operation failure.
- Internal program error.
Exceptions should preserve the original cause and provide an identifiable error type.
Real errors must not be masked by returning empty data.
X. Interface Verification
Must verify:
- Normal input.
- Missing fields.
- Empty data.
- Invalid types.
- Boundary values.
- Normal output.
- Exceptional output.
- Upstream and downstream compatibility.
XI. Final Principle
A module must not only be able to run independently; it must also be callable correctly by other modules.
An interface is not a supplementary explanation after development is complete, but an agreement that must be defined before development begins.
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.

