Your AI agent skills, finally organized. A macOS app to browse, edit, and manage skills across Claude Code, Cursor, Codex, Windsurf, and Amp.
import Foundation
@Observable
final class SkillRegistry {
/// One instance for the app so the trending and GitHub caches last the session,
/// not just a single sheet presentation.
static let shared = SkillRegistry()
var isSearching = false
var searchError: String?
// Cache repo metadata to avoid repeated GitHub API calls
private var treeCache: [String: [String]] = [:] // source@branch -> [SKILL.md paths]
private var branchCache: [String: String] = [:] // source -> default branch
// Popular/trending skills, scraped from skills.sh. Cached in memory for the session.
private var trendingCache: [RegistrySkill]?
// MARK: - Search
struct SearchResponse: Codable {
let skills: [RegistrySkill]
let count: Int
}
struct RegistrySkill: Identifiable, Codable {
let skillId: String
let name: String
let installs: Int
let source: String
let isOfficial: Bool?
// Derived rather than decoded: the search API sends an `id` field equal to
// "<source>/<skillId>", but the trending payload omits it. Computing it keeps
// both sources Identifiable without a fragile optional.
var id: String { "\(source)/\(skillId)" }
var formattedInstalls: String {
if installs >= 1_000_000 {
return "\(String(format: "%.1f", Double(installs) / 1_000_000).replacingOccurrences(of: ".0", with: ""))M"
} else if installs >= 1_000 {
return "\(String(format: "%.1f", Double(installs) / 1_000).replacingOccurrences(of: ".0", with: ""))K"
}
return "\(installs)"
}
}
func search(query: String) async throws -> [RegistrySkill] {
guard query.count >= 2 else { return [] }
let encoded = query.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? query
let url = URL(string: "https://skills.sh/api/search?q=\(encoded)&limit=30")!
let (data, response) = try await URLSession.shared.data(from: url)
guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
throw RegistryError.searchFailed
}
let decoded = try JSONDecoder().decode(SearchResponse.self, from: data)
return decoded.skills
}
// MARK: - Trending / Browse
/// Fetches the most-installed skills by scraping skills.sh's server-rendered
/// trending page (no public JSON API exists for this). The result — ~600 skills
/// ranked by install count — is cached for the session and powers instant local
/// browse + filtering, which is both faster and broader than the fuzzy search API.
func fetchTrending() async throws -> [RegistrySkill] {
if let cached = trendingCache { return cached }
var request = URLRequest(url: URL(string: "https://www.skills.sh/trending")!)
// Identify ourselves honestly since we're reading their HTML rather than a JSON API.
request.setValue(
"Chops/macOS (+https://github.com/Shpigford/chops)",
forHTTPHeaderField: "User-Agent"
)
let (data, response) = try await URLSession.shared.data(for: request)
guard let http = response as? HTTPURLResponse, http.statusCode == 200,
let html = String(data: data, encoding: .utf8) else {
throw RegistryError.trendingFailed
}
let skills = Self.parseTrending(html: html)
guard !skills.isEmpty else { throw RegistryError.trendingFailed }
trendingCache = skills
return skills
}
/// Extracts skill objects from the Next.js RSC payload embedded in the trending HTML.
/// The payload lives inside JS string literals, so JSON quotes arrive as `\"`; we
/// unescape, then pull out every flat `{…"skillId":…}` object and hand it to
/// JSONDecoder, which tolerates extra keys and any key order. Page order is
/// install-count descending, which we preserve.
static func parseTrending(html: String) -> [RegistrySkill] {
let unescaped = html.replacingOccurrences(of: "\\\"", with: "\"")
let pattern = #/\{[^{}]*"skillId":[^{}]*\}/#
let decoder = JSONDecoder()
var seen = Set<String>()
var result: [RegistrySkill] = []
for match in unescaped.matches(of: pattern) {
let json = String(match.output)
guard let skill = try? decoder.decode(RegistrySkill.self, from: Data(json.utf8)) else { continue }
if seen.insert(skill.id).inserted {
result.append(skill)
}
}
return result
}
/// Case-insensitive substring match across name, skillId, and source.
static func filter(_ skills: [RegistrySkill], query: String) -> [RegistrySkill] {
guard !query.isEmpty else { return skills }
return skills.filter {
$0.name.localizedCaseInsensitiveContains(query)
|| $0.skillId.localizedCaseInsensitiveContains(query)
|| $0.source.localizedCaseInsensitiveContains(query)
}
}
// MARK: - Content Resolution
func fetchContent(skill: RegistrySkill) async throws -> String {
let branch = try await getDefaultBranch(source: skill.source)
if let content = try await fetchContentAtConventionalPaths(skill: skill, branch: branch) {
return content
}
return try await fetchContentViaTreeAPI(skill: skill, branch: branch)
}
private func fetchContentAtConventionalPaths(skill: RegistrySkill, branch: String) async throws -> String? {
let pathPatterns = [
"skills/\(skill.skillId)/SKILL.md",
"skills/.curated/\(skill.skillId)/SKILL.md",
"skills/.experimental/\(skill.skillId)/SKILL.md",
"\(skill.skillId)/SKILL.md",
"SKILL.md",
]
for path in pathPatterns {
let rawURL = URL(string: "https://raw.githubusercontent.com/\(skill.source)/\(branch)/\(path)")!
guard let (data, response) = try? await URLSession.shared.data(from: rawURL),
let http = response as? HTTPURLResponse, http.statusCode == 200,
let content = String(data: data, encoding: .utf8) else {
continue
}
if path == "SKILL.md" {
let name = parseFrontmatterName(from: content)
if name != skill.skillId && name != skill.name { continue }
}
return content
}
return nil
}
private func fetchContentViaTreeAPI(skill: RegistrySkill, branch: String) async throws -> String {
let paths = try await getSkillPaths(source: skill.source, branch: branch)
for path in paths {
let rawURL = URL(string: "https://raw.githubusercontent.com/\(skill.source)/\(branch)/\(path)")!
guard let (data, response) = try? await URLSession.shared.data(from: rawURL),
let http = response as? HTTPURLResponse, http.statusCode == 200,
let content = String(data: data, encoding: .utf8) else {
continue
}
let frontmatterName = parseFrontmatterName(from: content)
if frontmatterName == skill.skillId || frontmatterName == skill.name {
return content
}
}
throw RegistryError.skillNotFound
}
private func getDefaultBranch(source: String) async throws -> String {
if let cached = branchCache[source] {
return cached
}
let url = URL(string: "https://api.github.com/repos/\(source)")!
let (data, response) = try await URLSession.shared.data(from: url)
guard let http = response as? HTTPURLResponse else {
throw RegistryError.treeFetchFailed
}
if http.statusCode == 403 {
throw RegistryError.rateLimited
}
guard http.statusCode == 200 else {
throw RegistryError.treeFetchFailed
}
struct RepoResponse: Codable {
let default_branch: String
}
let repo = try JSONDecoder().decode(RepoResponse.self, from: data)
branchCache[source] = repo.default_branch
return repo.default_branch
}
private func getSkillPaths(source: String, branch: String) async throws -> [String] {
let cacheKey = "\(source)@\(branch)"
if let cached = treeCache[cacheKey] {
return cached
}
let url = URL(string: "https://api.github.com/repos/\(source)/git/trees/\(branch)?recursive=1")!
let (data, response) = try await URLSession.shared.data(from: url)
guard let http = response as? HTTPURLResponse else {
throw RegistryError.treeFetchFailed
}
if http.statusCode == 403 {
throw RegistryError.rateLimited
}
guard http.statusCode == 200 else {
throw RegistryError.treeFetchFailed
}
struct TreeResponse: Codable {
struct TreeEntry: Codable {
let path: String
let type: String
}
let tree: [TreeEntry]
}
let tree = try JSONDecoder().decode(TreeResponse.self, from: data)
let skillPaths = tree.tree
.filter { $0.type == "blob" && ($0.path == "SKILL.md" || $0.path.hasSuffix("/SKILL.md")) }
.map(\.path)
treeCache[cacheKey] = skillPaths
return skillPaths
}
private func parseFrontmatterName(from content: String) -> String? {
let lines = content.components(separatedBy: .newlines)
guard lines.first?.trimmingCharacters(in: .whitespaces) == "---" else { return nil }
for line in lines.dropFirst() {
let trimmed = line.trimmingCharacters(in: .whitespaces)
if trimmed == "---" { break }
if trimmed.hasPrefix("name:") {
return trimmed
.dropFirst(5)
.trimmingCharacters(in: .whitespaces)
.trimmingCharacters(in: CharacterSet(charactersIn: "\"'"))
}
}
return nil
}
// MARK: - Install
func install(content: String, skillName: String, agents: [AgentTarget]) throws {
let sanitized = skillName
.lowercased()
.replacingOccurrences(of: " ", with: "-")
.filter { $0.isLetter || $0.isNumber || $0 == "-" || $0 == "." || $0 == "_" }
.trimmingCharacters(in: CharacterSet(charactersIn: ".-"))
guard !sanitized.isEmpty else {
throw RegistryError.invalidSkillName
}
let fm = FileManager.default
let home = fm.homeDirectoryForCurrentUser.path
// Canonical location — matches the official skills CLI behavior
let canonicalDir = "\(home)/.agents/skills/\(sanitized)"
let canonicalFile = "\(canonicalDir)/SKILL.md"
let canonicalAlreadyExisted = fm.fileExists(atPath: canonicalFile)
// Write real file to canonical location if not already there
if !canonicalAlreadyExisted {
try fm.createDirectory(atPath: canonicalDir, withIntermediateDirectories: true)
try content.write(toFile: canonicalFile, atomically: true, encoding: .utf8)
}
// Symlink from each agent's skills dir to the canonical location
var newLinks = 0
for agent in agents {
let agentDir = "\(agent.expandedSkillsDir)/\(sanitized)"
// Skip if already installed (real file or symlink)
if fm.fileExists(atPath: agentDir) { continue }
// Create parent dir if needed
try fm.createDirectory(atPath: agent.expandedSkillsDir, withIntermediateDirectories: true)
// Create symlink to canonical dir
try fm.createSymbolicLink(atPath: agentDir, withDestinationPath: canonicalDir)
newLinks += 1
}
if newLinks == 0 && canonicalAlreadyExisted {
throw RegistryError.skillAlreadyExists
}
}
// MARK: - Errors
enum RegistryError: LocalizedError {
case searchFailed
case trendingFailed
case treeFetchFailed
case rateLimited
case skillNotFound
case invalidSkillName
case skillAlreadyExists
var errorDescription: String? {
switch self {
case .searchFailed: "Search request failed"
case .trendingFailed: "Could not load trending skills from skills.sh"
case .treeFetchFailed: "Could not fetch repository contents"
case .rateLimited: "GitHub API rate limit reached — try again in a few minutes"
case .skillNotFound: "File not found in repository"
case .invalidSkillName: "Invalid name"
case .skillAlreadyExists: "Already installed for all selected targets"
}
}
}
}