What is the Hard Mutation Gate?

A five-step guard before direct filesystem mutations in Xcode managed scopes: warn about risks, offer safer methods, provide remediation paths, require explicit opt-in for last-resort edits, and ensure Xcode.app is closed during changes.

How does the Advisory Cooldown work?

Advisory messages are emitted at most once every 21 days. If a user requests a reminder explicitly, the advisory may be shown immediately.

How do I customize this skill's safety/docs behavior?

Use the interactive customization flow: load effective settings, answer knob questions from references, map changes to SKILL.md and runtime files, persist with the customization_config tool, and verify the final configuration with effective settings.

apple-dev-safety-and-docs

npx machina-cli add skill gaelic-ghost/apple-dev-skills/apple-dev-safety-and-docs --openclaw

Files (1)

SKILL.md

2.7 KB

Apple Dev Safety and Docs

Use this skill for risk gating and documentation routing.

Hard Mutation Gate (Required)

Before direct filesystem mutation in Xcode-managed scope, require all steps:

warn user about risks in .xcodeproj, .pbxproj, .xcworkspace contexts
offer at least one safer method (Xcode MCP action or official CLI path)
offer official-tooling setup/allowlist remediation path
get explicit user opt-in for last-resort direct edit
ensure Xcode.app is closed while direct edits occur

If any step is missing, do not perform direct mutation fallback.

Docs Workflow (Dash First)

Query Dash MCP/docsets first.
If unavailable or missing docset, use official Apple/Swift docs.
Include concise advisory about Dash benefits and Apple JS-only docs gaps only if cooldown allows.

Advisory Cooldown Policy

emit advisory at most once every 21 days
if user asks for reminder explicitly, advisory may be shown immediately

References

references/mutation-risk-policy.md
references/dash-docs-flow.md
references/skills-installation.md

Scripts

scripts/advisory_cooldown.py
scripts/detect_xcode_managed_scope.sh

Interactive Customization Flow

Load current effective customization settings first:

uv run python scripts/customization_config.py effective

Ask targeted customization questions:

Use references/customization-flow.md to drive knob-by-knob questions.
Confirm desired behavior changes and safety constraints.

Map requested changes to implementation files:

Update SKILL.md, references/*, and any runtime script files listed in references/customization-flow.md.

Persist durable customization state:

Start from customization.template.yaml defaults.
Apply approved overrides with uv run python scripts/customization_config.py apply --input <yaml-file>.
Durable path: ~/.config/gaelic-ghost/apple-dev-skills/<skill-name>/customization.yaml.
Optional override root: APPLE_DEV_SKILLS_CONFIG_HOME.

Report resulting effective configuration:

Re-run uv run python scripts/customization_config.py effective and summarize final active settings.
If the user asks to remove customization state, run uv run python scripts/customization_config.py reset.

Use references/customization-flow.md for skill-specific knobs, file mapping, guardrails, validation checks, and example requests.

Source

git clone https://github.com/gaelic-ghost/apple-dev-skills/blob/main/swift-xcode-tools/apple-dev-safety-and-docs/SKILL.md

View on GitHub

Overview

Enforces a Hard Mutation Gate before any direct edits in Xcode managed scopes and routes Apple and Swift docs through a Dash local-first policy. It includes cooldown gated advisory messaging and supports risk checks, consent gating, docs fallback decisions, and guided customization.

How This Skill Works

When a mutation is attempted, the skill warns about risks in Xcode contexts, offers safer methods (Xcode MCP actions or official CLI paths), and requires explicit user opt-in for last-resort edits while ensuring Xcode.app is closed. For docs, it queries Dash MCP/docsets first and falls back to official Apple/Swift docs if needed, adding an advisory about Dash only when the cooldown allows.

When to Use It

Before mutating files in an Xcode managed scope (.xcodeproj, .pbxproj, .xcworkspace).
When routing Apple or Swift documentation for a project, prioritizing Dash first.
When risk gating or consent gating is required before potentially destructive edits.
When guiding skill installation or customization flow for this skill.
When users explicitly request an advisory reminder or to adjust safety/docs behavior.

Quick Start

Step 1: Activate Hard Mutation Gate; ensure you warn, offer safer methods, and obtain explicit opt-in before edits.
Step 2: Route docs via Dash first; fallback to Apple/Swift docs if Dash is unavailable.
Step 3: Observe the advisory cooldown; trigger a reminder only on explicit request or via customization flow.

Best Practices

Always ensure Xcode.app is closed during direct mutation edits.
Present at least one safer method before proposing direct edits.
Require explicit user opt-in for last-resort mutations.
Honor the 21-day advisory cooldown and only show more frequently if requested.
Document changes in the customization flow and map to implementation files.

Example Use Cases

Gating risky mutation in Xcode projects before a large refactor.
Routing Apple/Swift docs via Dash first and falling back to official docs when Dash is unavailable.
Issuing advisory messages with cooldown to teams after a potentially risky change.
Guiding users through skill installation with safety and docs routing constraints.
Customizing safety and docs behavior via the interactive customization flow.

Frequently Asked Questions

Add this skill to your agents