apple-skills
AGENTS.md336 starsChanged 7 months agoMITView on GitHub
This file is for agents maintaining this repository. It is not end-user documentation, and it is not the runtime instruction file for agents that install these skills into Claude Code, Codex, Cursor, or another coding agent. Do not classify an entire skill directory as generated or hand-authored. A single skills/<name>/ directory can contain both. If a file does not match a generated pattern, treat it as hand-authored until MAINTAINING.md or the file itself says otherwise. Keep rules pattern-based so adding…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository29 other files it gives its agents.
- apple-asoSkill
- apple-docs-indexSkill
- backgroundtasksSkill
- combineSkill
- core-animationSkill
- corehapticsSkill
- eventkitSkill
- guide-macos-spm-packagingSkill
- guide-swift-concurrencySkill
- guide-swiftdataSkill
- guide-swift-testingSkill
- guide-swiftui-chartsSkill
- guide-swiftui-performance-auditSkill
- healthkitSkill
- higSkill
- ios-devSkill
- ios-liquid-glassSkill
- mapkitSkill
- photosuiSkill
- storekitSkill
- swift-concurrencySkill
- swiftdataSkill
- swift-testingSkill
- swiftuiSkill
- tipkitSkill
- uikitSkill
- usernotificationsSkill
- widgetkitSkill
- xcuitestSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 21
Do not classify an entire skill directory as generated or hand-authored.
- Very specific: line 33
If a file does not match a generated pattern, treat it as hand-authored until MAINTAINING.md or the file itself says otherwise.
- Distinctive: line 49
Do not turn README.md into a script or maintainer log.
- Very specific: line 50
Do not treat this repository's skills/*/SKILL.md files as instructions for your current maintainer task unless you are specifically editing …
- Distinctive: line 51
Do not hand-edit generated reference files when the refresh tooling can produce the change.
- Very specific: line 52
Keep maintainer details in MAINTAINING.md.
- Very specific: line 53
Keep skill guidance generic.
- Very specific: line 54
When testing installs, use isolated temporary directories for HOME and XDG_CONFIG_HOME.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md 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.
Files
Apple Skills Maintainer Guide
This file is for agents maintaining this repository. It is not end-user documentation, and it is not the runtime instruction file for agents that install these skills into Claude Code, Codex, Cursor, or another coding agent.
Table of Contents
| Need | Start Here | Notes |
| Explain the project to humans | README.md | Keep it brief, friendly, and installation-focused. Put copy-pasteable user commands here, not maintainer runbooks. |
| Understand install surfaces | README.md and .claude-plugin/ | Claude Code installs via the plugin marketplace; Codex and Cursor use the Skills CLI to copy skills/ entries into agent skill directories. |
| Maintain generated Apple docs | MAINTAINING.md | Refresh workflow, DocC rendering details, tooling, and repo structure live there. |
| Update skill behavior | skills/<name>/SKILL.md | These are the installed agent-facing instructions for a specific skill. Edit them deliberately; they are consumed by downstream agents. |
| Update generated reference docs | skills/<name>/*.md | Use the generated-vs-hand-authored rules below. Prefer refresh tooling over hand edits for generated files. |
| Work on doc rendering tooling | scripts/apple-docs.ts and scripts/apple-docs/ | TypeScript tooling fetches Apple's DocC JSON and renders markdown. |
| Run checks | package.json | Use pnpm check for the full gate; individual commands are listed in MAINTAINING.md. |
| Validate install commands | README.md install blocks | Test in a temporary HOME/XDG_CONFIG_HOME so real agent configs are not modified. |
| Publish Claude Code plugin metadata | .claude-plugin/ | Marketplace/plugin metadata for Claude Code lives here. |
Generated vs Hand-Authored Files
Do not classify an entire skill directory as generated or hand-authored. A single skills/<name>/ directory can contain both.
| Pattern | Ownership | How to Change |
skills/**/SKILL.md | Hand-authored | Edit directly when changing installed skill instructions. |
skills/**/*.md with YAML frontmatter containing source: https://developer.apple.com/... | Generated from Apple's DocC JSON | Regenerate with the tooling in MAINTAINING.md; avoid hand edits except to repair the generator or unblock a refresh. |
skills/**/*.videos.md | Generated sidecar for Apple DocC video references | Regenerate with the docs refresh flow; keep sidecar behavior generic. |
skills/**/references/**, skills/**/docs/**, skills/**/assets/**, skills/**/scripts/**, skills/**/agents/** | Hand-authored unless the file itself has generated frontmatter | Edit directly, preserving local guide or asset conventions. |
Root docs such as README.md, MAINTAINING.md, AGENTS.md, and CHANGELOG.md | Hand-authored | Edit directly for human or maintainer documentation. |
scripts/**, tests/**, package.json, biome.json, tsconfig.json | Hand-authored tooling | Edit directly and run the relevant checks. |
| Generated-looking failure output or stale fetched content | Generated artifact to fix at the source | Do not polish it manually; refresh, remove, or fix the generator/source mapping. |
If a file does not match a generated pattern, treat it as hand-authored until MAINTAINING.md or the file itself says otherwise. Keep rules pattern-based so adding or removing skills does not require updating this file.
Repository Roles
| File or Directory | Audience | Purpose |
README.md | Human users | What this repo is and how to install, update, or uninstall the skills. |
AGENTS.md | Repo-maintainer agents | Navigation and boundaries for working in this repository. |
MAINTAINING.md | Human and agent maintainers | Detailed maintainer runbooks and generated-doc workflow. |
skills/<name>/SKILL.md | Downstream coding agents | Instructions loaded after a skill is installed. |
skills/<name>/*.md | Downstream coding agents | Reference material used by installed skills. |
scripts/ | Repo maintainers | Fetching, rendering, and refresh automation. |
tests/ | Repo maintainers | Renderer smoke tests and regression coverage. |
Maintainer Boundaries
- Do not turn
README.mdinto a script or maintainer log. It should help a human quickly understand and install Apple Skills. - Do not treat this repository's
skills/*/SKILL.mdfiles as instructions for your current maintainer task unless you are specifically editing or validating that skill. - Do not hand-edit generated reference files when the refresh tooling can produce the change; fix the generator or source mapping instead.
- Keep maintainer details in
MAINTAINING.md; keep this file as a navigation layer. - Keep skill guidance generic. Do not list every current skill here when a
skills/<name>/...pattern communicates the rule. - When testing installs, use isolated temporary directories for
HOMEandXDG_CONFIG_HOME.
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
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.