2026 OpenHands Skills or AGENTS.md? How Should an iOS Repository Choose

A repository keeps repeating its basic rules, while task-specific guidance makes the agent’s context noisy.

Put short, always-required rules in AGENTS.md, move conditional workflows into OpenHands Skills, and require an independent Mac gate for Xcode builds, signing, tests, and device validation.

This guide is for repository maintainers who need stable OpenHands conventions, iOS developers who need on-demand Apple-toolchain procedures, and platform or security teams governing Skills, scripts, tools, and permissions.

Last updated September 6, 2026. The current terminology and migration guidance were checked against the OpenHands Skills overview, the OpenHands SDK Skill guide, and Apple’s Xcode documentation.

OpenHands Skills and AGENTS.md roles

The useful distinction is not “old file versus new file.” It is always-loaded repository context versus task-triggered operational knowledge.

AGENTS.md should describe the smallest set of rules that every agent task must see. In an iOS repository, that normally includes:

• The purpose and scope of the repository.
• Important directories and package boundaries.
• The supported installation path.
• The default branch and contribution expectations.
• Baseline CI checks.
• Rules that prevent unsafe or misleading changes.
• The authoritative files where build, test, and dependency settings are defined.

Keep this file short enough to remain trustworthy. If it becomes a complete engineering handbook, agents must process too much context before doing ordinary work. More importantly, maintainers will stop checking whether every instruction still matches the repository.

Skills are better for procedures that only apply under a condition. Examples include a Swift concurrency migration, a specific feature module, a release branch, a UI test workflow, or an investigation of a particular failure class. The official OpenHands Skills documentation presents Skills as the current mechanism for packaging reusable, task-relevant knowledge.

A Skill should answer three operational questions:

• What kind of task should activate it?
• What should the agent inspect before acting?
• What evidence proves that the procedure was completed correctly?

A description such as “Use this for iOS work” is too broad. A description such as “Use this when changing the notification extension, modifying its entitlements, or updating its UI tests” gives the agent a usable trigger boundary.

The same rule should not be copied into both locations unless the duplication is intentional and tested. If AGENTS.md says the project uses one test command while a Skill recommends another, the agent has no reliable basis for choosing. Keep the invariant in AGENTS.md; keep the detailed procedure in the Skill.

Decision comparison

The ratings below are editorial fit scores for rule placement, not measured OpenHands performance. They use the criteria that matter when maintaining an iOS repository: visibility, context cost, task specificity, auditability, and operational risk.

The table shows why a single “master prompt” is a weak design. It makes permanent rules too large and task-specific rules too easy to miss.

iOS Skill design for Xcode work

An iOS Skill should guide the agent through the project’s real structure rather than inventing a generic Apple workflow. The Skill can explain how to locate the workspace, select a scheme, identify test targets, interpret common failures, and collect a handoff package. It should not claim that a build or test has passed merely because the instructions were followed.

Keep volatile facts close to their source of truth. The Xcode version, simulator availability, scheme name, signing mode, and build command should be checked against the repository or CI configuration before being written into a Skill. Apple’s documentation on customizing Xcode build schemes is useful background, but it does not replace inspection of your project’s actual schemes.

A good iOS Skill can use this sequence:

• Inspect the repository for an .xcodeproj, .xcworkspace, package manifest, and CI configuration.
• Identify the intended scheme and test plan from project files or the existing workflow.
• Confirm whether dependencies are resolved by Swift Package Manager, another package system, or a checked-in lock file.
• Run the narrowest relevant validation first.
• Expand to the repository’s required test and build gate.
• Record the exact command, environment, result, and unresolved failure.
• Stop before signing or device actions unless the task has explicit authorization.

That sequence separates guidance from execution. A Skill can tell OpenHands what to inspect and how to report results. It cannot grant access to a signing key, guarantee a simulator is booted, or prove that a physical device accepted the build.

Apple’s guide to running tests and interpreting results should be treated as a reference for result interpretation, not as evidence that your repository has passed. Your acceptance record should still include the project, scheme, test target, destination, and log location.

Should iOS Xcode commands go into AGENTS.md?

Only the stable command policy belongs there. For example, AGENTS.md can state that contributors must use the repository’s documented CI command and must not replace a failed test with an unrelated local command. The exact scheme-specific procedure belongs in an iOS Skill when it applies only to certain tasks or targets.

If every contribution needs the same command, keep the command or its authoritative location in AGENTS.md. If only release work, UI tests, or a particular extension needs it, place the procedure in a Skill and link it to the repository’s source-of-truth configuration.

Team ownership and loading control

Different roles need different control points. Treating all rules as a developer-owned Markdown file leaves platform and security risks unaddressed.

Repository maintainers

Maintainers own the permanent contract. They should review every AGENTS.md change against repository files, CI workflows, package manifests, and contribution checks. A rule is not “stable” because it has been present for a long time. It is stable when a maintainer can verify it from the repository or its enforced workflow.

The maintainer should remove:

• Historical instructions that no longer match the build.
• Duplicated framework guidance.
• Commands that depend on an undocumented local machine.
• Claims that an agent completed a task without attached evidence.
• Broad permissions hidden behind convenience wording.

Mobile developers

Mobile developers own task-specific Skills. Their responsibility is to explain when the Skill applies, what inputs it requires, and what a useful output looks like. They should avoid copying the full repository contract into every Skill.

A Skill for a notification extension, for example, can define the relevant target, entitlement checks, test scope, and expected failure explanations. It should refer back to the shared repository rule for contribution and CI policy rather than restating it.

Platform engineers

Platform teams govern discovery, versioning, and reuse. The exact loading behavior and supported locations must be checked against the current OpenHands documentation during deployment; do not assume that a directory used by an older setup has the same priority today.

Use an explicit ownership record for shared Skills:

• Name and version.
• Owning team.
• Supported repositories.
• Review date.
• Change approval path.
• Compatibility notes.
• Rollback location.

During migration, keep the old path available as a fallback until the same task has been run under both arrangements. Compare the actual loaded instructions and resulting changes. Do not judge migration success by file presence alone.

Do OpenHands Microagents need to move to Skills?

Treat the move as a controlled migration, not a blind rename. As of September 6, 2026, OpenHands documentation uses Skills as the current name and marks some Microagents paths as old or deprecated formats. The official SDK Skill guide should be checked for the current SKILL.md structure and supported behavior before changing a production repository.

Inventory each old Microagent by purpose. Move task-specific knowledge into a Skill, retain permanent repository rules in AGENTS.md, and delete duplicated instructions only after a comparison task produces the expected result. If a legacy path is still required for compatibility in your environment, document the fallback and its removal condition.

Security boundaries around Skills

A Skill is not harmless documentation merely because its main file is Markdown. OpenHands documentation describes Skills as packages that can include supporting material, and the SDK Skill architecture reference should be used when reviewing how those materials are exposed.

Can an OpenHands Skill include scripts and reference material?

Yes, a Skill can be designed with supporting scripts, reference documents, or tool configuration, but every attached resource expands the review boundary. Security approval should cover the package, not just its prose.

Review at least these areas:

• Script permissions and executable paths.
• Shell commands that accept dynamic input.
• Network access and downloaded content.
• MCP tools and their available actions.
• Access to credentials, signing files, source archives, and build artifacts.
• Paths outside the repository.
• Generated instructions that could change the agent’s next action.
• Logs that might expose tokens, personal data, or internal URLs.

Use a restricted test repository for the first run. Test an allowed action, a denied action, an unexpected path, and a malformed input. Capture logs for each case. A statement such as “the Skill cannot access signing credentials” is not a security result unless a permission check or blocking test supports it.

OpenHands also provides a separate Hooks customization reference. Do not use Hooks, Skills, or AGENTS.md as interchangeable security controls. Prompt context can influence behavior, but it is not an authorization boundary. File permissions, tool policy, sandboxing, credential isolation, and Mac host controls must enforce the boundary.

Mac acceptance handoff

The final handoff should make it possible for another person to reproduce or reject the result. Give the Mac gate a defined input package:

• The patch or commit identifier.
• A summary of changed files.
• Dependency and lock-file changes.
• The intended scheme and test scope.
• Commands already attempted.
• Raw logs or links to retained logs.
• Known failures and their likely causes.
• Any requested signing or device action.
• The remaining approval owner.

Separate the risk levels. A source-only change may need build and unit-test evidence. A change to entitlements, signing settings, provisioning, release configuration, or device behavior needs stricter review. Do not let OpenHands self-certify those outcomes.

On the Mac, verify the project and scheme from the checked-out repository. Run the required build, run the relevant tests, inspect failures in Xcode or the CI-equivalent command, and record the destination. If signing is involved, confirm that the action used the approved identity and profile without exposing secrets in logs. For device validation, record the device class and result separately from simulator testing.

This arrangement prevents a common failure: a well-written Skill produces a plausible report, but the actual Mac environment lacks the required Xcode version, simulator runtime, signing access, or device connection. Guidance can reduce ambiguity; only the acceptance environment can establish the result.

Migration and verification checklist

Use this checklist for a low-risk pilot before changing every repository:

• [ ] List the current AGENTS.md, Skill, Microagent, Hook, and supporting-resource locations.
• [ ] Mark each rule as permanent, task-specific, security-sensitive, or release-specific.
• [ ] Move only permanent, verifiable repository rules into AGENTS.md.
• [ ] Give each Skill a precise activation description and a defined completion record.
• [ ] Remove conflicting copies of commands, scheme names, and test expectations.
• [ ] Record the owner, version, review path, and rollback location for shared Skills.
• [ ] Review scripts, reference files, MCP tools, dynamic content, and filesystem access.
• [ ] Run one low-risk iOS task with the old arrangement and once with the proposed arrangement.
• [ ] Compare the loaded guidance, changed files, commands, and reported evidence.
• [ ] Send the resulting patch and logs to a Mac acceptance environment.
• [ ] Verify build, tests, signing, and device actions as separate gates.
• [ ] Keep the fallback path until the new arrangement has passed review.

Do not optimize for the fewest files. Optimize for clear ownership and observable behavior. A short AGENTS.md plus several narrow Skills is easier to review than one large file that mixes repository policy, release instructions, security exceptions, and framework tutorials.

Choosing the right Mac operating model

If your current setup relies on a developer laptop, it has several practical weaknesses: availability depends on one person, Xcode and simulator state can drift, signing access may be mixed with daily development, and long-running agent work competes with interactive use. A general-purpose remote environment can add another weakness when it cannot provide the Mac-specific tooling needed for Xcode builds, simulator tests, or device-oriented checks.

A dedicated Mac workspace is not automatically the right answer. Long-running, predictable workloads may justify owning and managing a stable machine. A team that needs temporary validation, isolated experiments, or an occasional release check may prefer a remotely accessible Mac workspace instead. Physical device access, compliance requirements, sustained workload, and credential policy should decide the boundary.

If your team needs to compare a temporary remote Mac with local ownership, review the SSHMac workspace options after defining the acceptance commands and access controls. For setup and operational questions, the SSHMac help center is a more appropriate starting point than embedding infrastructure assumptions inside a Skill. You can also review the service scope through the SSHMac company information page before assigning a team-wide workflow.

The current “agent on a developer Mac” approach is often weaker because it combines personal availability, mutable Xcode state, shared credentials, and unrecorded simulator conditions. Renting a Mac workspace through SSHMac can provide a cleaner temporary validation environment when you need remote access without making every developer laptop a release gate. It still does not remove the need for permission review, reproducible commands, or independent evidence.

The practical sequence is simple: establish the AGENTS.md and Skill split, test it with one low-risk iOS task, and then decide whether your local Mac can sustain the required Xcode acceptance work. If it cannot, evaluate a separate remote Mac workspace rather than asking prompt rules to compensate for missing hardware, tooling, or access controls.