From c8df9ef1e1a7a6bb1654d9eeb51556f1b8d16e6a Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 18 Nov 2026 17:09:14 +0100 Subject: [PATCH 1/2] feat(skills): Add support and terms research workflows --- Sources/CLI/skills/BundledAgentSkills.swift | 117 ++++++++++++++++-- .../skills/AgentSkillsCommandTests.swift | 13 +- .../skills/AgentSkillsInstallationTests.swift | 26 ++-- .../skills/BundledAgentSkillsTests.swift | 31 ++++- 4 files changed, 164 insertions(+), 23 deletions(-) diff --git a/Sources/CLI/skills/BundledAgentSkills.swift b/Sources/CLI/skills/BundledAgentSkills.swift index 7a7b27f..1828998 100644 --- a/Sources/CLI/skills/BundledAgentSkills.swift +++ b/Sources/CLI/skills/BundledAgentSkills.swift @@ -21,27 +21,43 @@ enum BundledAgentSkills { shortDescription: "Check platform availability, deprecations, and documented migration options.", content: checkAvailabilityContent ), + BundledAgentSkill( + name: "apple-docs-support", + shortDescription: "Find support articles, browse help guides, and look up development glossary terms.", + content: supportContent + ), + BundledAgentSkill( + name: "apple-docs-terms", + shortDescription: "Discover agreements, guidelines, document resources, translations, and notices.", + content: termsContent + ), ] static func skill(named name: String) -> BundledAgentSkill? { all.first { $0.name == name } } +} +extension BundledAgentSkills { private static let appleDocsContent = """ --- name: apple-docs description: >- - Use for Apple Developer research, Swift and Apple framework questions, API documentation, declarations, - behavior, members, code examples, and platform support. Start with the apple-docs CLI instead of web - searches, browser lookups, direct HTTP requests, or remembered API details. Report unsupported research - explicitly rather than silently switching sources. + Use for Apple Developer research, Swift and Apple framework APIs, developer program support, + App Store Connect help, glossary terms, agreements, and guidelines. Start with the apple-docs CLI + instead of web searches, browser lookups, direct HTTP requests, or remembered details. + Report unsupported research explicitly rather than silently switching sources. --- # Apple Developer Research Use `apple-docs` as the first source for all Apple Developer research. Ground API claims in retrieved Apple - documentation, not search snippets or memory. The CLI currently provides technology discovery and DocC API - documentation lookup, not comprehensive search across every Apple Developer resource. + documentation, not search snippets or memory. The CLI provides technology discovery, DocC API documentation, + support resource catalogs, and supported help and support HTML pages, not comprehensive Apple Developer search. + + Use `apple-docs-support` for membership, App Store Connect workflows, support articles, guides, and glossary + definitions. Use `apple-docs-terms` for agreements, guidelines, and document translations. The API research + workflow below applies to framework and symbol questions. ## Start with the question @@ -90,10 +106,13 @@ enum BundledAgentSkills { apple-docs types view URLSession --technology Foundation --agent --json ``` - Catalog JSON is arrays. Search JSON contains `technology`, `types`, and `coverage`. Check coverage before + Technology and type-list JSON is arrays. Type-search JSON contains `technology`, `types`, and `coverage`. + Check coverage before interpreting no matches: `isComplete` and `unavailableCollections`. Page JSON is semantic, not raw DocC. Inspect `title`, `declarations`, `availability`, `content`, `relationships`, `topics`, and `seeAlso`. Agent `navigation` commands and grouped references retain validated targets. A missing field is not a guarantee. + Support commands return tagged objects with `kind`, not the DocC shapes above. Follow the support and terms + skills for their catalog, document, resource, and translation fields. ## Availability and examples @@ -260,3 +279,87 @@ enum BundledAgentSkills { before using sources outside the CLI. Never invent version numbers to complete a compatibility table. """ } + +extension BundledAgentSkills { + private static let supportContent = """ + --- + name: apple-docs-support + description: Use for Apple Developer support, membership, App Store Connect guides, and glossary definitions. + --- + + # Research Apple Developer Support + + Follow `apple-docs` source rules. Support commands are stateless and do not take `--technology`. + + ## Discover resources + + ```bash + apple-docs support articles list --agent + apple-docs support articles list --category membership --agent + apple-docs support guides list --agent + apple-docs support guides contents --name app-store-connect --agent --json + ``` + + Articles list categorized links; guides list resources and topics; contents returns an embedded guide index. + Copy category IDs, guide identifiers, or follow-up commands. This is not full-text or exhaustive search. + + ## Read the relevant page or definition + + ```bash + apple-docs support view --path support/fee-waiver --agent + apple-docs support glossary list --query account --agent + apple-docs support glossary view --term "Account Holder" --agent --json + ``` + + Follow returned navigation commands using relative `help/` or `support/` paths, not full URLs or query strings. + Omit fragments from arguments but retain source anchors in citations. Glossary queries match names by substring, + not definitions. View requires the exact term, case-insensitively. Read the source before recommending steps. + + ## Preserve evidence and limits + + Use `--agent` for Markdown and validated follow-up commands; add `--json` independently for structured evidence. + Inspect `kind`, categories, topics or entries, and document `content`, `breadcrumbs`, and `notices`. + Cite canonical URLs and retain qualifications, nested steps, links, and notices. PDFs and unknown layouts + are unsupported. Report failed commands precisely; do not invent paths or crawl the site. Ask before using + another source rather than silently switching to web search, direct HTTP, or memory. + """ + + private static let termsContent = """ + --- + name: apple-docs-terms + description: Use to find Apple Developer agreements, guidelines, document resources, translations, and notices. + --- + + # Discover Agreements and Guidelines + + Identify the program, document, and language. Public catalog results do not establish account acceptance. + + ## Find the source entry + + ```bash + apple-docs support terms list --agent + apple-docs support terms list --category guidelines --agent --json + apple-docs support terms view --name apple-developer-program-license-agreement --agent --json + ``` + + Copy category and entry IDs from the catalog or navigation commands. `terms view` returns metadata, resources, + translations, notices, and update labels, not the linked legal document text. Keep each translation with its + resource. Do not merge notices, assume shared languages across documents, or infer missing update dates. + + ## Read supported HTML without overstating coverage + + ```bash + apple-docs support view --path support/terms/apple-developer-program-license-agreement --agent + ``` + + `support view` reads known `help/` and `support/` HTML, not necessarily the full agreement on a landing page. + PDFs, off-site documents, and unknown layouts are unsupported. Do not guess commands or fetch them elsewhere. + + ## Report the evidence boundary + + `--agent` selects the audience; `--json` independently selects structured output. Inspect `kind`, categories, + entries, and `resources` with their `translations`. Cite source URLs and retain language and precedence notices. + Metadata does not establish obligations, accepted versions, or legal equivalence of translations. If unread + document text or account evidence is needed, state the gap and ask before using another source. + """ +} diff --git a/Tests/CLITests/cmd/agent/skills/AgentSkillsCommandTests.swift b/Tests/CLITests/cmd/agent/skills/AgentSkillsCommandTests.swift index 8c98bc2..e24c7dd 100644 --- a/Tests/CLITests/cmd/agent/skills/AgentSkillsCommandTests.swift +++ b/Tests/CLITests/cmd/agent/skills/AgentSkillsCommandTests.swift @@ -19,17 +19,22 @@ struct AgentSkillsCommandTests { #expect(deps.telemetry.commands == ["agent.skills.list"]) } - @Test("get writes bundled skill content through the injected output") - func writesSkillContent() throws { + @Test( + "get writes bundled skill content through the injected output", + arguments: [ + "apple-docs", "apple-docs-discover-api", "apple-docs-check-availability", "apple-docs-support", + "apple-docs-terms", + ]) + func writesSkillContent(name: String) throws { // -- Arrange -- - let command = try AgentSkillsGetCommand.parse(["apple-docs"]) + let command = try AgentSkillsGetCommand.parse([name]) let deps = SkillListDependencies() // -- Act -- try command.run(deps: deps) // -- Assert -- - #expect(deps.output.lines == [BundledAgentSkills.skill(named: "apple-docs")?.content]) + #expect(deps.output.lines == [BundledAgentSkills.skill(named: name)?.content]) #expect(deps.telemetry.commands == ["agent.skills.get"]) } diff --git a/Tests/CLITests/cmd/agent/skills/AgentSkillsInstallationTests.swift b/Tests/CLITests/cmd/agent/skills/AgentSkillsInstallationTests.swift index 586049d..84bf531 100644 --- a/Tests/CLITests/cmd/agent/skills/AgentSkillsInstallationTests.swift +++ b/Tests/CLITests/cmd/agent/skills/AgentSkillsInstallationTests.swift @@ -5,22 +5,26 @@ import Testing @Suite("Agent skills installation") struct AgentSkillsInstallationTests { - @Test("installs selected skills and is idempotent") - func installsSelectedSkills() throws { + @Test( + "installs selected skills and is idempotent", + arguments: [ + "apple-docs", "apple-docs-support", "apple-docs-terms", + ]) + func installsSelectedSkills(name: String) throws { // -- Arrange -- let root = temporaryRoot() defer { try? FileManager.default.removeItem(at: root) } // -- Act -- - try run(["install", "apple-docs", "--dir", root.path]) - try run(["install", "apple-docs", "--dir", root.path]) + try run(["install", name, "--dir", root.path]) + try run(["install", name, "--dir", root.path]) // -- Assert -- - let installed = try String(contentsOf: skillFile(root), encoding: .utf8) - #expect(installed == BundledAgentSkills.skill(named: "apple-docs")?.content) + let installed = try String(contentsOf: skillFile(root, name: name), encoding: .utf8) + #expect(installed == BundledAgentSkills.skill(named: name)?.content) #expect( try FileManager.default.contentsOfDirectory(atPath: root.appendingPathComponent("skills").path) - == ["apple-docs"]) + == [name]) } @Test("installs and uninstalls the entire bundle") @@ -187,8 +191,8 @@ struct AgentSkillsInstallationTests { // -- Assert -- #expect( - try FileManager.default.contentsOfDirectory(atPath: root.appendingPathComponent("skills").path) - == ["apple-docs-check-availability"]) + try Set(FileManager.default.contentsOfDirectory(atPath: root.appendingPathComponent("skills").path)) + == ["apple-docs-check-availability", "apple-docs-support", "apple-docs-terms"]) } @Test("preflights all removals before deleting any skill") @@ -282,8 +286,8 @@ struct AgentSkillsInstallationTests { .appendingPathComponent(UUID().uuidString) } - private func skillFile(_ root: URL) -> URL { - root.appendingPathComponent("skills/apple-docs/SKILL.md") + private func skillFile(_ root: URL, name: String = "apple-docs") -> URL { + root.appendingPathComponent("skills/\(name)/SKILL.md") } private func write(_ content: String, to url: URL) throws { diff --git a/Tests/CLITests/skills/BundledAgentSkillsTests.swift b/Tests/CLITests/skills/BundledAgentSkillsTests.swift index ccd1feb..5746785 100644 --- a/Tests/CLITests/skills/BundledAgentSkillsTests.swift +++ b/Tests/CLITests/skills/BundledAgentSkillsTests.swift @@ -7,7 +7,10 @@ struct BundledAgentSkillsTests { @Test("makes the research workflows discoverable by name") func listsBundledSkills() { // -- Arrange -- - let names = ["apple-docs", "apple-docs-discover-api", "apple-docs-check-availability"] + let names = [ + "apple-docs", "apple-docs-discover-api", "apple-docs-check-availability", + "apple-docs-support", "apple-docs-terms", + ] // -- Act -- let skills = names.compactMap { BundledAgentSkills.skill(named: $0) } @@ -46,6 +49,32 @@ struct BundledAgentSkillsTests { #expect(skills.allSatisfy { !$0.content.contains("aliases `--json`") }) } + @Test( + "support research examples select executable commands with independent output flags", + arguments: [ + "apple-docs-support", "apple-docs-terms", + ]) + func parsesSupportExamples(name: String) throws { + // -- Arrange -- + let skill = try #require(BundledAgentSkills.skill(named: name)) + let examples = skill.content.split(separator: "\n").filter { $0.hasPrefix("apple-docs support ") } + + // -- Act -- + let commands = try examples.map { example in + let pieces = example.split(separator: "\"", omittingEmptySubsequences: false) + #expect(!pieces.count.isMultiple(of: 2), "Example has unbalanced double quotes") + let arguments = pieces.enumerated().flatMap { index, piece in + index.isMultiple(of: 2) ? piece.split(separator: " ").map(String.init) : [String(piece)] + } + return try #require(CLI.parseAsRoot(Array(arguments.dropFirst())) as? any SupportExecutableCommand) + } + + // -- Assert -- + #expect(!commands.isEmpty) + #expect(commands.allSatisfy { $0.output.agent }) + #expect(commands.contains { $0.output.json }) + } + @Test("returns no skill for an unknown name") func rejectsUnknownSkill() { // -- Arrange -- From cda0bb00ce95abfb936653572f26600d86a0e5f0 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 18 Nov 2026 17:20:55 +0100 Subject: [PATCH 2/2] docs(skills): Clarify shared source and JSON guidance --- Sources/CLI/skills/BundledAgentSkills.swift | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Sources/CLI/skills/BundledAgentSkills.swift b/Sources/CLI/skills/BundledAgentSkills.swift index 1828998..fe5f0eb 100644 --- a/Sources/CLI/skills/BundledAgentSkills.swift +++ b/Sources/CLI/skills/BundledAgentSkills.swift @@ -106,9 +106,9 @@ extension BundledAgentSkills { apple-docs types view URLSession --technology Foundation --agent --json ``` - Technology and type-list JSON is arrays. Type-search JSON contains `technology`, `types`, and `coverage`. - Check coverage before - interpreting no matches: `isComplete` and `unavailableCollections`. Page JSON is semantic, not raw DocC. + Technology and type lists return JSON arrays. Type-search JSON contains `technology`, `types`, and `coverage`. + Check coverage before interpreting no matches: `isComplete` and `unavailableCollections`. + Page JSON is semantic, not raw DocC. Inspect `title`, `declarations`, `availability`, `content`, `relationships`, `topics`, and `seeAlso`. Agent `navigation` commands and grouped references retain validated targets. A missing field is not a guarantee. Support commands return tagged objects with `kind`, not the DocC shapes above. Follow the support and terms @@ -332,7 +332,8 @@ extension BundledAgentSkills { # Discover Agreements and Guidelines - Identify the program, document, and language. Public catalog results do not establish account acceptance. + Follow `apple-docs` source rules. Identify the program, document, and language. + Public catalog results do not establish account acceptance. ## Find the source entry