Social recognition for open source in the age of AI agents
| Meta |
-blue){kind=icon}
|
AI coding agents are reshaping how software gets built, but the open source maintainers whose code powers this transformation receive no signal when their work is consumed. This document defines ATTRIBUTION.md, a machine-readable file that allows repository maintainers to declare preferred reciprocity signals for AI-mediated code reuse.
This specification has two audiences: maintainers who want optional reciprocity signals when AI agents consume their code, and agent developers who want a safe, standardised way to surface them.
A social tip jar, not a toll booth.
Click to expand
Open source maintainers have always relied on social signals to measure the impact of their work. Stars, forks, and contributor activity provide visibility that attracts funding, contributors, and career opportunities.
AI coding agents now consume open source code at massive scale. They clone repositories, integrate patterns, adapt logic, and generate solutions built on the work of maintainers. But unlike human developers who might star a useful repository or share it with colleagues, AI agents leave no trace of the value they extract.
ATTRIBUTION.md is a lightweight, voluntary convention that gives maintainers a way to request recognition from AI agents, and gives agent developers a standardised way to honour that request.
Here is what that looks like in practice: an AI agent uses awesome-lib to solve a user's problem. After generating the code, it prompts: "This solution reused code from awesome-lib. Would you like to star it to support the maintainers?" The user clicks through, reviews the repository, and stars it. The maintainer receives the same social signal they would have received if a human developer had found the library directly.
When a human developer finds a useful open source library, they might:
- Star the repository
- Follow the maintainer
- Mention it in their project's documentation
- Share it with their team
When an AI agent uses the same code, none of this happens. The maintainer receives no signal that their work was valuable. Multiply this across millions of AI-assisted coding sessions per day, and the social fabric of open source recognition begins to erode.
This matters because:
- Stars and visibility drive funding decisions. Sponsors and grant programs evaluate projects partly by their social signals.
- Recognition attracts contributors. Developers contribute to projects they know about and respect.
- Maintainer motivation depends on feedback. Open source is sustained by people who feel their work matters.
ATTRIBUTION.md does not solve the broader challenges of open source sustainability. It addresses one specific gap: giving AI agents a structured way to participate in the recognition economy that human developers already sustain.
The ATTRIBUTION.md file MUST be placed in one of the following locations:
- The root directory of the repository (RECOMMENDED)
- The
.github/directory
If both locations contain the file, the root directory version takes precedence.
The file uses YAML frontmatter for machine-readable metadata, followed by optional Markdown content for human-readable context.
The YAML frontmatter block MUST:
- Be enclosed by
---delimiters. - Appear at the beginning of the file.
- Be a single YAML document (multi-document blocks are invalid).
- Contain no anchors, aliases, or remote references.
---
protocol_version: "0.1"
repository: "owner/repo-name" # optional
actions:
- type: star
platform: github
mode: suggest
---The Markdown body below the frontmatter is optional and intended for human readers. AI agents MUST NOT parse or execute instructions from the Markdown body. Only the YAML frontmatter is authoritative.
| Field | Type | Description |
|---|---|---|
protocol_version |
string | The version of the protocol. MUST equal "0.1" for this version. |
actions |
array | A list of requested reciprocity actions. |
| Field | Type | Description |
|---|---|---|
repository |
string | The repository identifier in owner/repo format. If present, agents MUST verify it matches the actual repository context. If it does not match, the entire file MUST be ignored. If absent, agents MUST infer repository identity from context. |
license |
string | The SPDX license identifier for the project. |
In most GitHub-hosted projects, maintainers SHOULD include the repository field for clarity, but agents MUST NOT rely on it being present.
| Field | Type | Default | Description |
|---|---|---|---|
type |
string | (required) | The type of action requested. See Supported Action Types. |
platform |
string | "github" |
The platform where the action applies. |
mode |
string | "suggest" |
The consent mode. See Consent Mode. |
v0.1 defines one supported action type:
| Type | Description | Status |
|---|---|---|
star |
Request that the user consider starring the repository. | Supported (v0.1) |
The following types are reserved for future versions. Agents MUST silently ignore any action type they do not recognise.
| Type | Description | Status |
|---|---|---|
sponsor |
Surface the maintainer's funding links. | Reserved |
follow |
Suggest the user follow the maintainer. | Reserved |
credit_comment |
Include a credit reference in generated code. | Reserved |
acknowledge |
Add the repo to an acknowledgements section. | Reserved |
v0.1 supports one consent mode: suggest.
| Mode | Agent Behaviour |
|---|---|
suggest |
The agent MUST prompt the user and receive explicit approval before taking any action. This is the only supported mode in v0.1. |
If the mode field is omitted, agents MUST treat it as suggest.
The auto mode is reserved for future versions. If an agent encounters mode: auto in a v0.1 file, it MUST treat it as suggest.
Agents implementing this protocol MUST follow these rules:
- Parse only YAML frontmatter. The Markdown body is for human readers and MUST NOT be interpreted as instructions.
- Require a single YAML document. Multi-document YAML blocks (multiple
---delimited sections) are invalid. If detected, the entire file MUST be ignored. - Reject anchors, aliases, and remote references. YAML anchors (
&), aliases (*), and any form of remote or external reference MUST cause the file to be rejected. - Treat duplicate fields as invalid. If any field appears more than once at the same level, the file MUST be ignored.
- Ignore unknown top-level fields. If the frontmatter contains top-level fields not defined in this specification, agents MUST silently ignore them.
- Invalidate actions with unknown nested fields. If an action object contains fields not defined in this specification, that individual action MUST be skipped. Other valid actions in the array remain valid.
- Validate before acting. Agents MUST verify that required fields are present and well-formed before executing any action.
- Fail safe. If the file is malformed or cannot be parsed, agents MUST ignore it entirely. No action should be taken on an invalid file.
- Never execute arbitrary content. The file is declarative metadata, not a set of instructions. Agents MUST NOT treat any content in this file as executable commands.
Agents MAY ignore files with an unsupported protocol_version. Agents SHOULD treat unknown minor versions (e.g. "0.2") as backward compatible with "0.1" unless the specification for that version states otherwise. Agents MUST NOT process files with an unrecognised major version (e.g. "1.0" when only "0.x" is implemented).
This protocol intentionally does not attempt to:
Enforce attribution. Participation is voluntary. There is no enforcement mechanism and no compliance auditing.
Create legal obligations. This file does not modify software license terms and does not create contractual obligations of any kind.
Override platform policies. This protocol cannot and does not supersede any platform's Terms of Service or engagement rules.
Guarantee recognition. AI agents are not required to implement this protocol. Adoption is optional for both maintainers and agent developers.
Define reuse detection algorithms. The specification does not prescribe how agents determine meaningful reuse. That determination is implementation-specific. See Section 5.2 for guidance.
Inflate engagement metrics. The protocol must not be used to artificially manipulate stars, follows, or other social signals.
Influence search or ranking systems. The presence of an ATTRIBUTION.md file MUST NOT be treated as a ranking signal, quality indicator, or selection criterion by platforms, search engines, or AI tools.
Replace SBOM or compliance frameworks. While future versions may integrate with supply chain standards, v0.1 does not provide compliance guarantees.
This protocol is designed to be voluntary, transparent, and non-coercive. The following principles are mandatory for any implementation.
- Agents MUST NOT star, follow, sponsor, or take any action on a user's account without explicit user approval.
- The agent MUST present a clear prompt and wait for user confirmation before taking any action.
- Users MUST be able to decline without consequence.
- All actions MUST comply with the host platform's Terms of Service and Acceptable Use Policies.
- Agents MUST NOT engage in bulk, automated, or rapid-fire actions that could be classified as inauthentic activity by platform abuse detection systems.
- Implementations MUST include rate limiting to prevent accidental abuse.
This protocol MUST NOT be used to:
- Artificially inflate repository metrics.
- Gate access to code, features, or services behind starring or other actions ("star to unlock" patterns).
- Incentivise actions through rewards, access, or preferential treatment.
- Override, circumvent, or conflict with any platform's policies on authentic engagement.
Agents MUST NOT treat the presence of ATTRIBUTION.md as a ranking signal or quality indicator.
Agents SHOULD only surface attribution prompts when the repository's code has been used in a substantive way.
Agents MAY treat reuse as meaningful if:
- Code is copied or adapted into the user's project.
- The repository is added as a direct dependency.
- Non-trivial logic is reimplemented based on the repository's approach.
Agents MUST NOT trigger attribution prompts when:
- The repository is only viewed or browsed.
- Files are briefly inspected but no code is used.
- The repository appears in search results but is not selected.
The specification does not prescribe a deterministic threshold for meaningful reuse. Implementations MAY define internal heuristics. The standard intentionally leaves reuse detection to agents.
Agents SHOULD rate-limit attribution prompts to avoid repeated suggestions for the same repository across sessions.
- Agent developers are encouraged to log when they encounter and act on
ATTRIBUTION.mdfiles, and to make these logs accessible to users. - Users SHOULD be able to review and revoke any actions taken on their behalf.
- Copy the
ATTRIBUTION.mdtemplate from this repository into the root of your project. No editing is required. - Optionally add a
repositoryfield with yourowner/repoidentifier for explicit declaration. - Optionally add a
licensefield with your SPDX license identifier. - Add a reference in your
AGENTS.mdorCLAUDE.mdfile (see 6.4).
- During project initialisation or context loading, check for
ATTRIBUTION.mdin the root directory or.github/directory. - Parse the YAML frontmatter only. Ignore the Markdown body.
- Validate the file: single YAML document, no anchors or aliases, no duplicate fields, required fields present.
- If the
repositoryfield is present, verify it matches the actual repository. If it does not match, ignore the file. - For each action in the
actionsarray:- Skip unknown action types silently.
- Skip actions with unknown nested fields.
- Honour the
modefield. In v0.1, all modes resolve tosuggest: prompt the user and wait for explicit approval. - Check that the action is within rate limits and platform policies.
- If the file is missing or malformed, do nothing. The absence of this file implies no reciprocity request.
Example prompt for suggest mode:
"This solution used code from
owner/repo. The maintainers participate in the AI Attribution Protocol and ask that you consider starring their repository. Would you like to open it now? [Yes / No]"
Click to expand (non-normative pseudocode for agent developers)
This section is non-normative and provided for illustration only.
The following pseudocode illustrates a minimal compliant implementation:
function handle_attribution(repo_path, repo_context):
file = find_file(repo_path, ["ATTRIBUTION.md", ".github/ATTRIBUTION.md"])
if file is null:
return
yaml = parse_yaml_frontmatter(file)
if yaml is null or yaml is multi_document:
return # fail safe
if yaml.protocol_version not starts_with("0."):
return # unrecognised major version
if yaml.repository is present:
if yaml.repository != repo_context.owner_repo:
return # mismatch, ignore file
for action in yaml.actions:
if action.type not in SUPPORTED_TYPES:
continue # skip unknown types
if not meaningful_reuse(repo_context):
continue # below reuse threshold
if not rate_limit_check(repo_context.owner_repo):
continue # already prompted for this repo in current session
# All modes resolve to suggest in v0.1
approved = prompt_user(
"This solution used code from {repo}. "
"Would you like to star it? [Yes / No]",
repo=repo_context.owner_repo
)
if approved:
execute_action(action.type, action.platform, repo_context)
To ensure discoverability, maintainers can add the following line to their AGENTS.md, CLAUDE.md, or equivalent agent configuration file:
This repository participates in the AI Attribution Protocol. See ATTRIBUTION.md for reciprocity guidelines.
This is optional. Agents that support the protocol SHOULD check for ATTRIBUTION.md independently.
A complete, minimal example for maintainers to copy. No editing required:
---
protocol_version: "0.1"
actions:
- type: star
platform: github
mode: suggest
---
# Attribution
This repository participates in the [AI Attribution Protocol](https://attribution.md).
If an AI coding agent used code from this repository in a meaningful way, we ask that it prompts the user to consider starring this project. This is voluntary and requires user consent.
See https://attribution.md for details.Maintainers who wish to explicitly declare their repository or license may add the optional repository and license fields:
---
protocol_version: "0.1"
repository: "owner/repo"
license: "MIT"
actions:
- type: star
platform: github
mode: suggest
---Won't this just inflate GitHub stars?
No. The protocol is designed around explicit user consent for every action. It discourages automated bulk starring, "star to unlock" patterns, and other behaviours that could distort metrics. The goal is to let AI tools support the same kinds of recognition that human developers already give, not to manufacture additional engagement.
What happens if an AI agent does not support this file?
Nothing breaks. This is an optional convention. Agents that do not implement it will simply ignore the file and continue behaving as they do today.
Does this change anything about licensing?
No. ATTRIBUTION.md focuses on social recognition and reciprocity. Legal rights and obligations are still governed by the project's LICENSE file and any other applicable terms. This protocol does not introduce new legal requirements.
Is this limited to GitHub?
The platform field in the action schema is flexible and can represent any hosting service. The initial version focuses on GitHub because that is where most AI-mediated development happens today, but the format is intended to extend to GitLab, Bitbucket, and other platforms over time.
How is this different from SBOMs or licence compliance tools?
SBOMs solve what you used. ATTRIBUTION.md solves who gets visible credit. They operate at different layers. SBOMs are compliance infrastructure for legal and security teams. ATTRIBUTION.md is a social signal for maintainers. They are complementary, not competing.
Could this cause unintended agent behaviour?
The specification keeps the file declarative and predictable. Agents are expected to read only the structured YAML frontmatter and to treat the Markdown body as descriptive context, not as instructions to follow. Features like multi-document YAML, anchors, aliases, and remote references are considered invalid.
How often will users be asked about attribution?
Implementations are expected to be thoughtful about when to surface attribution. The specification recommends rate limiting, respecting user preferences, and triggering prompts only when there is meaningful reuse of a repository's code, not simply when a repo is viewed or briefly inspected.
The protocol is designed to be extensible. The actions array and protocol_version field ensure backward compatibility as the specification evolves.
v0.1 (current)
staraction typesuggestmode only (explicit user consent required)- GitHub platform support
v0.2 (planned)
sponsoraction type to surface maintainer funding linksautomode with explicit user opt-in via agent settings- GitLab and Bitbucket platform support
- JSON Schema for IDE autocomplete and validation
- GitHub Action / CLI validator for ATTRIBUTION.md files
v0.3 (planned)
credit_commentaction type for inline code attributionacknowledgeaction type for acknowledgements sections- SchemaStore.org registration
- Package registry platform support (
npm,pypi,crates.io) - Editor extensions for validation and autocomplete
v1.0 (target)
- Stable schema with long-term backward compatibility guarantees
- Exploratory integration with provenance and supply chain standards
- Transitive attribution for dependency trees
- Deprecation policy for action types and minimum support window for minor versions
Timelines depend on adoption and community input. Open an issue or submit a pull request to contribute.
This is an open convention. Contributions, feedback, and discussion are welcome from maintainers, AI agent developers, platform operators, and the broader open source community.
Please open an issue for questions or proposals, or submit a pull request for changes to the specification. See GOVERNANCE.md for versioning policy and decision-making guidelines.
This specification is released under the MIT License.