[andreyvelich]

I added initial contributing guide, AGENTS.md, and skill for PR reviews.

Motivation and Context

This should enhance how AI agents interact with our code base. Please review the contributing and agents guide for correctness.

/assign @varun06 @jeanmatthieu @akhilcb

How Has This Been Tested?

Breaking Changes

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

This PR was assisted with AI tools.

[andreyvelich]

/hold for review

[andreyvelich]

@modelcontextprotocol/swift-sdk Please review this and let me know if you think it would be better to shorten it.

[akhilcb]

Thanks for putting this together, @andreyvelich. Having AGENTS.md and CONTRIBUTING.md will help a lot and I checked most of the paths, commands and conventions against main. They're accurate. A few suggestions:

AGENTS.md / CONTRIBUTING.md

• The Agent Behavior Policy links the 2026-07-28 spec, while Principle 2 says the SDK implements up to 2025-11-25. Since 2026-07-28 support is still in progress, a short note on which revision to follow (current behavior vs. new-spec work) would help agents avoid mixing the two.
• .vscode/settings.json has formatOnSave turned on, so the "no formatter configuration" line could say something like "don't commit unrelated formatting changes" instead.
• NetworkTransport uses [weak self] in a few NWConnection callbacks. Narrowing that rule to actor-owned Tasks might stop agents from "fixing" working code.
• The Base/ imports rule could be "match the file you're editing", since some Base/ files use import Foundation.
• A one-line CLAUDE.md with @AGENTS.md would let Claude Code pick this up automatically.

review-pr skill

• For /review-pr <PR_LINK>, it might help to fetch the PR diff (gh pr diff) explicitly. Right now the agents default to the local git diff.
• Could code-simplifier be advisory-only in this flow, so it doesn't edit the local checkout during a review?
• Some of the agent prompts still have references from other languages and projects (Go/Rust/Python, errorIds.ts/Sentry, pkg/foo/bar.go). Swapping those for our MCPError and swift-log conventions would make the prompts sharper.
• The publish-guard hook could also catch gh api with -f/-F/--input, since those default to POST. If the hook is meant as a personal opt-in, .claude/settings.local.json might be a better place to register it than the shared settings file.

Really like the pending-review and suggestion-block approach. Thanks again!

[andreyvelich]

Thanks for review @akhilcb, I addressed the comments.

A one-line CLAUDE.md with @AGENTS.md would let Claude Code pick this up automatically.

I think, this is not needed since Claude can read AGENTS.md now:
https://code.claude.com/docs/en/memory#agents-md

[akhilcb]

Thanks for review @akhilcb, I addressed the comments.

A one-line CLAUDE.md with @AGENTS.md would let Claude Code pick this up automatically.

I think, this is not needed since Claude can read AGENTS.md now: https://code.claude.com/docs/en/memory#agents-md

Agreed. My bad. That’s a valid point. I missed it.

[EhsanAzish80]

Looks like the same Ubuntu setup failure we hit across our PRs: the Swift 6.1 job stops at Setup Swift on Linux, before build or tests. We fixed it by pinning that test leg to ubuntu-24.04 and updating the Linux step if: checks to match. The static SDK job can stay on ubuntu-latest.

[andreyvelich]

We fixed it by pinning that test leg to ubuntu-24.04 and updating the Linux step if: checks to match. The static SDK job can stay on ubuntu-latest.

Yeah, that makes sense. Could you help us to open PR to fix the CI @EhsanAzish80 ?

[andreyvelich]

Will go ahead with this PR, feel free to enhance contributing guides in the followup PRs!

[EhsanAzish80]

Thanks Andrey. I opened #320 for the Ubuntu CI fix. It pins the Swift 6.1 test job to ubuntu-24.04; the local build and 579 tests pass. I’ll watch the Linux CI result.