Swift-API-Design-Guidelines-Agent-Skill
AGENTS.md29 starsChanged 9 months agoMITView on GitHub
We split this AGENTS.md into the rules it gives an agent
17 rules. About 0 are common, 12 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
Treat clarity as more important than brevity.
- Distinctive: line 6
Keep instructions factual, specific, and testable in code review.
- Distinctive: line 7
Prefer Swift-native idioms over personal style preferences.
- Distinctive: line 8
Keep the skill focused on API design, naming, labels, and documentation quality.
- Very specific: line 11
Keep SKILL.md procedural and concise.
- Very specific: line 12
Put detailed rule explanations and examples in references/.
- Distinctive: line 14
Use concrete "good vs bad" examples for naming and labels.
- Distinctive: line 15
Avoid duplicating the same rule in multiple files unless needed for quick-reference context.
- Distinctive: line 32
Use direct, technical language.
- Distinctive: line 33
Use imperative instructions for actionable rules.
- Distinctive: line 34
Prefer short paragraphs and bullet lists over prose-heavy explanations.
- Distinctive: line 35
Keep examples compact and realistic.
- Distinctive: line 36
Avoid motivational or opinionated language.
- Distinctive: line 44
Prefer examples that reveal point-of-use readability, not declaration-only quality.
- Very specific: line 47
Update SKILL.md first when workflow or review process changes.
- Very specific: line 48
Update only the affected references/*.md files when a rule changes.
- Very specific: line 50
Keep references/ filenames stable.
≈ “Common” is an estimate: at least 1 in 5 of the 36,368 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
API Design Guidelines Skill Authoring Guide
Core Principles
- Optimize for clarity at the point of use.
- Treat clarity as more important than brevity.
- Keep instructions factual, specific, and testable in code review.
- Prefer Swift-native idioms over personal style preferences.
- Keep the skill focused on API design, naming, labels, and documentation quality.
Content Guidelines
- Keep
SKILL.mdprocedural and concise. - Put detailed rule explanations and examples in
references/. - Organize content by decision points the agent can apply while reviewing or writing code.
- Use concrete "good vs bad" examples for naming and labels.
- Avoid duplicating the same rule in multiple files unless needed for quick-reference context.
What To Include
- Swift API naming rules and argument-label guidance.
- Documentation comment rules and symbol-markup usage.
- Mutating/nonmutating naming pairs and side-effect naming patterns.
- Conventions for terminology, casing, overload design, and default parameters.
- Review checklists and action-oriented guidance for code changes.
What To Exclude
- App architecture prescriptions (MVVM/VIPER/etc.).
- Style debates unrelated to API surface design.
- Language features not relevant to API clarity.
- Long historical commentary or rationale not needed for implementation decisions.
- Duplicate reference material across multiple files.
Language And Tone
- Use direct, technical language.
- Use imperative instructions for actionable rules.
- Prefer short paragraphs and bullet lists over prose-heavy explanations.
- Keep examples compact and realistic.
- Avoid motivational or opinionated language.
Examples
- Include paired examples where possible:
- Ambiguous vs clear API names.
- Redundant vs concise naming.
- Incorrect vs correct argument labels.
- Overload ambiguity vs explicit method naming.
- Prefer examples that reveal point-of-use readability, not declaration-only quality.
Updating The Skill
- Update
SKILL.mdfirst when workflow or review process changes. - Update only the affected
references/*.mdfiles when a rule changes. - Preserve section structure so other agents can find guidance predictably.
- Keep
references/filenames stable; add new files only for genuinely new topics. - Validate checklists against the references after each update.
Summary
This skill should help agents design and review Swift APIs that read clearly at call sites, follow established Swift naming and labeling conventions, and maintain high documentation quality with minimal ambiguity.
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 28,693 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 repository2 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- swift-api-design-guidelines-skillSkill
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.