agentleFS
Topaz1618Topaz1618/pawskills/skills/interface-contract/SKILL.md

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

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

    No module may have only an implementation and no interface.

    line 11
  2. Distinctive:

    No module may have only an output and no format definition.

    line 13
  3. Distinctive:

    No downstream module may complete development by guessing the upstream data structure.

    line 15
  4. Distinctive:

    If conversion is genuinely needed:

    line 115
  5. Distinctive:

    Before modifying an existing interface, must:

    line 127
  6. Distinctive:

    Search for all callers.

    line 129
  7. Distinctive:

    Check input data sources.

    line 130
  8. Distinctive:

    Check output data consumers.

    line 131

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

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

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:

  1. What problem the module solves.
  2. Which work the module is responsible for.
  3. Which work does not belong to that module.
  4. Who provides the data upstream.
  5. Who uses the results downstream.
  6. 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:

  1. Clarify the original field.
  2. Clarify the target field.
  3. Clarify the conversion rule.
  4. Clarify which module is responsible for it.
  5. 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:

  1. Search for all callers.
  2. Check input data sources.
  3. Check output data consumers.
  4. Assess field changes.
  5. Assess type changes.
  6. Assess compatibility.
  7. 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:

  1. Which callers, data sources, and consumers are affected.
  2. Whether historical data must be migrated, and how.
  3. Whether a compatibility window is needed for external consumers.
  4. Whether the two names must be carried simultaneously, and for how long.
  5. 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.

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.