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
import SwiftData
import os
/// Data collected from the filesystem for a single skill, before SwiftData persistence.
struct ScannedSkillData: Sendable {
let fileURL: URL
let resolvedPath: String
let toolSource: ToolSource
let isDirectory: Bool
let isGlobal: Bool
let name: String
let skillDescription: String
let content: String
let frontmatter: [String: String]
let modDate: Date
let fileSize: Int
let kind: ItemKind
}
@Observable
final class SkillScanner {
private let modelContext: ModelContext
private var scanTask: Task<Void, Never>?
private var scanGeneration = 0
/// Filenames that are tool config/meta files, not skills.
private static let ignoredFileNames: Set<String> = [
"README.md",
"README",
"CLAUDE.md",
"AGENTS.md",
"AGENTS.override.md",
"global_rules.md",
"SYSTEM.md",
"APPEND_SYSTEM.md",
"LICENSE.md",
"LICENSE",
"CHANGELOG.md",
]
private static func shouldIgnoreLooseMarkdownFile(named fileName: String) -> Bool {
return ignoredFileNames.contains(fileName)
}
init(modelContext: ModelContext) {
self.modelContext = modelContext
}
/// Project-level paths to probe inside each project directory
private static let projectProbes: [(subpath: String, tool: ToolSource, kind: ItemKind)] = [
(".claude/skills", .claude, .skill),
(".claude/agents", .claude, .agent),
(".cursor/skills", .cursor, .skill),
(".cursor/rules", .cursor, .rule),
(".cursor/agents", .cursor, .agent),
(".codex/skills", .codex, .skill),
(".codex/agents", .codex, .agent),
(".windsurf/rules", .windsurf, .rule),
(".github", .copilot, .skill),
(".github/agents", .copilot, .agent),
(".config/amp/skills", .amp, .skill),
(".opencode/skills", .opencode, .skill),
(".hermes/skills", .hermes, .skill),
]
func scanAll() {
let start = CFAbsoluteTimeGetCurrent()
AppLogger.scanning.notice("Scan started")
scanTask?.cancel()
scanGeneration += 1
let generation = scanGeneration
let customPaths = UserDefaults.standard.stringArray(forKey: "customScanPaths") ?? []
let includePlugins = ChopsSettings.includePluginSkills
scanTask = Task.detached { [weak self] in
let results = Self.collectAllSkills(customPaths: customPaths, includePlugins: includePlugins)
guard !Task.isCancelled else { return }
let elapsed = CFAbsoluteTimeGetCurrent() - start
AppLogger.scanning.notice("File collection done: \(results.count) skills in \(String(format: "%.2f", elapsed))s")
await MainActor.run {
guard let self, self.scanGeneration == generation else { return }
self.applyResults(results)
let total = CFAbsoluteTimeGetCurrent() - start
AppLogger.scanning.notice("Scan complete: \(results.count) skills applied in \(String(format: "%.2f", total))s")
}
}
}
/// Pure filesystem I/O — safe to run off main thread.
private static func collectAllSkills(customPaths: [String], includePlugins: Bool) -> [ScannedSkillData] {
var results: [ScannedSkillData] = []
for tool in ToolSource.allCases where tool != .custom {
guard !Task.isCancelled else { return results }
guard tool.isInstalled else {
continue
}
for path in tool.globalPaths {
let url = URL(fileURLWithPath: path)
collectFromDirectory(url, toolSource: tool, isGlobal: true, kind: .skill, into: &results)
}
for path in tool.globalAgentPaths {
let url = URL(fileURLWithPath: path)
collectFromDirectory(url, toolSource: tool, isGlobal: true, kind: .agent, into: &results)
}
for path in tool.globalRulePaths {
let url = URL(fileURLWithPath: path)
collectFromDirectory(url, toolSource: tool, isGlobal: true, kind: .rule, into: &results)
}
}
if includePlugins {
// CLI plugins (installed_plugins.json)
if ToolSource.claude.isInstalled {
collectFromCLIPlugins(into: &results)
}
// Claude Desktop/Cowork plugin skills
if ToolSource.claudeDesktop.isInstalled {
collectClaudeDesktopSkills(into: &results)
}
}
for path in customPaths {
guard !Task.isCancelled else { return results }
collectFromCustomDirectory(URL(fileURLWithPath: path), into: &results)
}
return results
}
private static func collectFromCustomDirectory(_ directory: URL, into results: inout [ScannedSkillData]) {
let fm = FileManager.default
collectDirectSkillsFromCustomDirectory(directory, into: &results)
guard let projects = try? fm.contentsOfDirectory(
at: directory,
includingPropertiesForKeys: [.isDirectoryKey],
options: [.skipsHiddenFiles]
) else { return }
for project in projects {
guard !Task.isCancelled else { return }
var isDir: ObjCBool = false
fm.fileExists(atPath: project.path, isDirectory: &isDir)
guard isDir.boolValue else { continue }
for probe in projectProbes {
let probePath = project.appendingPathComponent(probe.subpath)
guard fm.fileExists(atPath: probePath.path) else { continue }
if probe.tool == .copilot && probe.kind == .skill {
let file = probePath.appendingPathComponent("copilot-instructions.md")
if fm.fileExists(atPath: file.path) {
if let data = collectSkillData(at: file, toolSource: .copilot, isDirectory: false, isGlobal: false, kind: probe.kind) {
results.append(data)
}
}
} else {
collectFromDirectory(probePath, toolSource: probe.tool, isGlobal: false, kind: probe.kind, into: &results)
}
}
}
}
/// Custom scan paths serve two different jobs:
/// - parent dirs like ~/Development that contain projects with tool-specific folders
/// - library dirs that contain skills directly as child folders/files
///
/// Only scan direct skill-style entries here so repo-level AGENTS.md files do not become
/// bogus custom skills when the user adds a generic project parent directory.
private static func collectDirectSkillsFromCustomDirectory(_ directory: URL, into results: inout [ScannedSkillData]) {
let fm = FileManager.default
guard let contents = try? fm.contentsOfDirectory(
at: directory,
includingPropertiesForKeys: [.isDirectoryKey],
options: [.skipsHiddenFiles]
) else { return }
for item in contents {
guard !Task.isCancelled else { return }
var isDirectory: ObjCBool = false
fm.fileExists(atPath: item.path, isDirectory: &isDirectory)
if isDirectory.boolValue {
let skillFile = item.appendingPathComponent("SKILL.md")
guard fm.fileExists(atPath: skillFile.path) else { continue }
if let data = collectSkillData(
at: skillFile,
toolSource: .custom,
isDirectory: true,
isGlobal: false,
kind: .skill
) {
results.append(data)
}
} else {
guard ["md", "mdc", "toml"].contains(item.pathExtension) else { continue }
guard !shouldIgnoreLooseMarkdownFile(named: item.lastPathComponent) else { continue }
if let data = collectSkillData(
at: item,
toolSource: .custom,
isDirectory: false,
isGlobal: false,
kind: .skill
) {
results.append(data)
}
}
}
}
private static func collectFromDirectory(_ directory: URL, toolSource: ToolSource, isGlobal: Bool, kind: ItemKind = .skill, into results: inout [ScannedSkillData]) {
let fm = FileManager.default
var isDir: ObjCBool = false
guard fm.fileExists(atPath: directory.path, isDirectory: &isDir) else { return }
guard isDir.boolValue else { return }
// Enumerate through the resolved directory so symlinked directories are traversed.
let resolvedDirectory = directory.resolvingSymlinksInPath()
guard let contents = try? fm.contentsOfDirectory(
at: resolvedDirectory,
includingPropertiesForKeys: [.isDirectoryKey, .isSymbolicLinkKey, .contentModificationDateKey, .fileSizeKey],
options: [.skipsHiddenFiles]
) else { return }
// Track both bases so each entry can be remapped back to the canonical path for storage.
let originalBase = directory.path
let resolvedBase = resolvedDirectory.path
for rawItem in contents {
guard !Task.isCancelled else { return }
// Remap to canonical path for storage; use rawItem for filesystem operations.
let item: URL
if originalBase != resolvedBase, rawItem.path.hasPrefix(resolvedBase + "/") {
let suffix = String(rawItem.path.dropFirst(resolvedBase.count))
item = URL(fileURLWithPath: originalBase + suffix)
} else {
item = rawItem
}
var itemIsDir: ObjCBool = false
fm.fileExists(atPath: rawItem.path, isDirectory: &itemIsDir)
if itemIsDir.boolValue {
let skillFile = item.appendingPathComponent("SKILL.md")
let agentsFile = item.appendingPathComponent("AGENTS.md")
let rawSkillFile = rawItem.appendingPathComponent("SKILL.md")
let rawAgentsFile = rawItem.appendingPathComponent("AGENTS.md")
if fm.fileExists(atPath: rawSkillFile.path) {
if let data = collectSkillData(at: skillFile, toolSource: toolSource, isDirectory: true, isGlobal: isGlobal, kind: kind) {
results.append(data)
}
} else if fm.fileExists(atPath: rawAgentsFile.path) {
if let data = collectSkillData(at: agentsFile, toolSource: toolSource, isDirectory: true, isGlobal: isGlobal, kind: kind) {
results.append(data)
}
} else if kind == .agent, let agentFile = preferredAgentFile(in: rawItem) {
let remappedAgentFile = item.appendingPathComponent(agentFile.lastPathComponent)
if let data = collectSkillData(at: remappedAgentFile, toolSource: toolSource, isDirectory: true, isGlobal: isGlobal, kind: kind) {
results.append(data)
}
} else if toolSource == .hermes, kind == .skill {
// Hermes nests skills as ~/.hermes/skills/<category>/<skill>/SKILL.md (agentskills.io layout).
collectFromDirectory(item, toolSource: toolSource, isGlobal: isGlobal, kind: kind, into: &results)
}
} else if item.pathExtension == "md" || item.pathExtension == "mdc" || item.pathExtension == "toml" {
guard !shouldIgnoreLooseMarkdownFile(named: item.lastPathComponent) else { continue }
if let data = collectSkillData(at: item, toolSource: toolSource, isDirectory: false, isGlobal: isGlobal, kind: kind) {
results.append(data)
}
}
}
}
private static func preferredAgentFile(in directory: URL) -> URL? {
let fm = FileManager.default
guard let contents = try? fm.contentsOfDirectory(
at: directory,
includingPropertiesForKeys: [.isDirectoryKey],
options: [.skipsHiddenFiles]
) else { return nil }
let candidates = contents.filter { item in
var isDir: ObjCBool = false
fm.fileExists(atPath: item.path, isDirectory: &isDir)
guard !isDir.boolValue else { return false }
guard ["md", "mdc", "toml"].contains(item.pathExtension) else { return false }
return !shouldIgnoreLooseMarkdownFile(named: item.lastPathComponent)
}
let directoryName = directory.lastPathComponent.lowercased()
if let matchingFile = candidates.first(where: { $0.deletingPathExtension().lastPathComponent.lowercased() == directoryName }) {
return matchingFile
}
if candidates.count == 1 {
return candidates[0]
}
return nil
}
/// For Claude Desktop plugin paths, produce a canonical identity that strips volatile
/// components (session IDs, version numbers). For all other tools, returns the normal
/// symlink-resolved path. Same pattern as remote skills using `remote://` prefixes.
private static func canonicalResolvedPath(for fileURL: URL, toolSource: ToolSource) -> String {
let resolved = fileURL.resolvingSymlinksInPath().path
let path = fileURL.path
// CLI plugins: .../.claude/plugins/cache/<publisher>/<plugin>/<version>/skills/<skill>/SKILL.md
if toolSource == .claude, let range = path.range(of: ".claude/plugins/cache/") {
let after = String(path[range.upperBound...])
let parts = after.components(separatedBy: "/")
// parts: [publisher, plugin, version, "skills", skill, "SKILL.md"]
guard parts.count >= 6, parts[3] == "skills" else { return resolved }
return "claude-plugin:\(parts[0])/\(parts[1])/\(parts[4])"
}
guard toolSource == .claudeDesktop else { return resolved }
// Local plugins: .../cowork_plugins/cache/<marketplace>/<plugin>/<version>/skills/<skill>/SKILL.md
if let range = path.range(of: "cowork_plugins/cache/") {
let after = String(path[range.upperBound...])
let parts = after.components(separatedBy: "/")
// parts: [marketplace, plugin, version, "skills", skill, "SKILL.md"]
guard parts.count >= 6, parts[3] == "skills" else { return resolved }
return "claude-desktop:cowork_plugins/\(parts[0])/\(parts[1])/\(parts[4])"
}
// Remote plugins: .../remote_cowork_plugins/<plugin-id>/skills/<skill>/SKILL.md
if let range = path.range(of: "remote_cowork_plugins/") {
let after = String(path[range.upperBound...])
let parts = after.components(separatedBy: "/")
// parts: [plugin-id, "skills", skill, "SKILL.md"]
guard parts.count >= 4, parts[1] == "skills" else { return resolved }
return "claude-desktop:remote_cowork_plugins/\(parts[0])/\(parts[2])"
}
return resolved
}
private static func isSyntheticLocalResolvedPath(_ resolvedPath: String) -> Bool {
resolvedPath.hasPrefix("claude-plugin:") || resolvedPath.hasPrefix("claude-desktop:")
}
/// Read and parse a single skill file. Pure I/O, no SwiftData.
private static func collectSkillData(at fileURL: URL, toolSource: ToolSource, isDirectory: Bool, isGlobal: Bool, kind: ItemKind = .skill) -> ScannedSkillData? {
let fm = FileManager.default
let resolved = canonicalResolvedPath(for: fileURL, toolSource: toolSource)
// Resolve symlinks for the actual read — fileURL may be a remapped canonical path
// that does not physically exist when a parent directory is a symlink.
let physicalURL = fileURL.resolvingSymlinksInPath()
guard let parsed = SkillParser.parse(fileURL: physicalURL, toolSource: toolSource) else {
AppLogger.scanning.warning("Failed to parse: \(fileURL.path)")
return nil
}
let attrs = try? fm.attributesOfItem(atPath: physicalURL.path)
let modDate = (attrs?[.modificationDate] as? Date) ?? .now
let fileSize = (attrs?[.size] as? Int) ?? 0
let name: String
if !parsed.name.isEmpty {
name = parsed.name
} else if isDirectory {
name = fileURL.deletingLastPathComponent().lastPathComponent
} else {
name = fileURL.deletingPathExtension().lastPathComponent
}
return ScannedSkillData(
fileURL: fileURL,
resolvedPath: resolved,
toolSource: toolSource,
isDirectory: isDirectory,
isGlobal: isGlobal,
name: name,
skillDescription: parsed.description,
content: parsed.content,
frontmatter: parsed.frontmatter,
modDate: modDate,
fileSize: fileSize,
kind: kind
)
}
// MARK: - Claude Plugin Scanning
/// Scan CLI plugins from ~/.claude/plugins/installed_plugins.json
private static func collectFromCLIPlugins(into results: inout [ScannedSkillData]) {
let fm = FileManager.default
let home = fm.homeDirectoryForCurrentUser.path
let jsonPath = "\(home)/.claude/plugins/installed_plugins.json"
guard let data = fm.contents(atPath: jsonPath),
let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
let plugins = json["plugins"] as? [String: [[String: Any]]] else { return }
for (_, installations) in plugins {
guard !Task.isCancelled else { return }
for installation in installations {
guard let installPath = installation["installPath"] as? String else { continue }
let skillsDir = URL(fileURLWithPath: installPath).appendingPathComponent("skills")
collectFromDirectory(skillsDir, toolSource: .claude, isGlobal: true, into: &results)
}
}
}
/// Scan Claude Desktop/Cowork plugin skills using manifests as source of truth.
/// Only scans explicitly installed plugins — skips built-in Anthropic skills (skills-plugin/).
private static func collectClaudeDesktopSkills(into results: inout [ScannedSkillData]) {
let fm = FileManager.default
let home = fm.homeDirectoryForCurrentUser.path
let sessionsRoot = "\(home)/Library/Application Support/Claude/local-agent-mode-sessions"
guard fm.fileExists(atPath: sessionsRoot) else { return }
guard let sessionDirs = try? fm.contentsOfDirectory(atPath: sessionsRoot) else { return }
for sessionDir in sessionDirs {
guard !Task.isCancelled else { return }
// Skip skills-plugin (Anthropic built-in skills, not user-installed)
if sessionDir == "skills-plugin" { continue }
let sessionPath = "\(sessionsRoot)/\(sessionDir)"
guard let subDirs = try? fm.contentsOfDirectory(atPath: sessionPath) else { continue }
for subDir in subDirs {
guard !Task.isCancelled else { return }
let subPath = "\(sessionPath)/\(subDir)"
// Local cowork plugins: use installed_plugins.json as source of truth
let installedJson = "\(subPath)/cowork_plugins/installed_plugins.json"
if let data = fm.contents(atPath: installedJson),
let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
let plugins = json["plugins"] as? [String: [[String: Any]]] {
for (_, installations) in plugins {
guard !Task.isCancelled else { return }
for installation in installations {
guard let installPath = installation["installPath"] as? String else { continue }
let skillsDir = URL(fileURLWithPath: installPath).appendingPathComponent("skills")
collectFromDirectory(skillsDir, toolSource: .claudeDesktop, isGlobal: true, into: &results)
}
}
}
// Remote cowork plugins: use manifest.json as source of truth
let remoteDir = "\(subPath)/remote_cowork_plugins"
let manifestPath = "\(remoteDir)/manifest.json"
if let data = fm.contents(atPath: manifestPath),
let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
let plugins = json["plugins"] as? [[String: Any]] {
for plugin in plugins {
guard !Task.isCancelled else { return }
guard let pluginId = plugin["id"] as? String else { continue }
let skillsDir = "\(remoteDir)/\(pluginId)/skills"
guard fm.fileExists(atPath: skillsDir) else { continue }
collectFromDirectory(
URL(fileURLWithPath: skillsDir),
toolSource: .claudeDesktop,
isGlobal: true,
into: &results
)
}
}
}
}
}
/// Apply collected results to SwiftData. Must be called on main thread.
@MainActor
private func applyResults(_ results: [ScannedSkillData]) {
let groupedResults = Dictionary(grouping: results, by: \.resolvedPath)
let descriptor = FetchDescriptor<Skill>()
let allSkills = (try? modelContext.fetch(descriptor)) ?? []
let localSkills = allSkills.filter { !$0.isRemote }
let existingByResolved = Dictionary(uniqueKeysWithValues: localSkills.map { ($0.resolvedPath, $0) })
let scannedResolvedPaths = Set(groupedResults.keys)
for (resolvedPath, installations) in groupedResults {
guard let primary = installations.first else { continue }
let installedPaths = Array(Set(installations.map(\.fileURL.path))).sorted()
let toolSources = ToolSource.allCases.filter { tool in
installations.contains { $0.toolSource == tool }
}
if let existing = existingByResolved[resolvedPath] {
let preferredPath = installedPaths.contains(existing.filePath) ? existing.filePath : primary.fileURL.path
let preferredData = installations.first(where: { $0.fileURL.path == preferredPath }) ?? primary
existing.filePath = preferredPath
existing.isDirectory = preferredData.isDirectory
existing.name = preferredData.name
existing.skillDescription = preferredData.skillDescription
existing.content = preferredData.content
existing.frontmatter = preferredData.frontmatter
existing.fileModifiedDate = preferredData.modDate
existing.fileSize = preferredData.fileSize
existing.isGlobal = preferredData.isGlobal
existing.installedPaths = installedPaths
existing.toolSources = toolSources
existing.itemKind = preferredData.kind
} else {
let skill = Skill(
filePath: primary.fileURL.path,
toolSource: primary.toolSource,
isDirectory: primary.isDirectory,
name: primary.name,
skillDescription: primary.skillDescription,
content: primary.content,
frontmatter: primary.frontmatter,
fileModifiedDate: primary.modDate,
fileSize: primary.fileSize,
isGlobal: primary.isGlobal,
resolvedPath: primary.resolvedPath,
kind: primary.kind
)
skill.installedPaths = installedPaths
skill.toolSources = toolSources
modelContext.insert(skill)
}
}
for skill in localSkills where !scannedResolvedPaths.contains(skill.resolvedPath) {
modelContext.delete(skill)
}
do { try modelContext.save() } catch {
AppLogger.scanning.error("SwiftData save failed: \(error.localizedDescription)")
}
}
// MARK: - Remote Server Scanning
@MainActor
func syncAllRemoteServers() async {
let descriptor = FetchDescriptor<RemoteServer>()
guard let servers = try? modelContext.fetch(descriptor) else { return }
for server in servers {
await scanRemoteServer(server)
}
}
/// Scans a remote server for skills. Sets lastSyncError on failure.
@MainActor
func scanRemoteServer(_ server: RemoteServer) async {
do {
let remoteSkills = try await SSHService.findSkills(server)
var foundPaths = Set<String>()
for (path, content) in remoteSkills {
let resolvedPath = "remote://\(server.id)/\(path)"
foundPaths.insert(resolvedPath)
let parsed = FrontmatterParser.parse(content)
let name: String
if !parsed.name.isEmpty {
name = parsed.name
} else {
// Derive name from parent directory
let components = path.components(separatedBy: "/")
if let fileIndex = components.lastIndex(of: "SKILL.md"), fileIndex > 0 {
name = components[fileIndex - 1]
} else {
name = "Unknown"
}
}
let predicate = #Predicate<Skill> { $0.resolvedPath == resolvedPath }
let fetchDescriptor = FetchDescriptor<Skill>(predicate: predicate)
if let existing = try? modelContext.fetch(fetchDescriptor).first {
existing.content = parsed.content
existing.name = name
existing.skillDescription = parsed.description
existing.frontmatter = parsed.frontmatter
} else {
let skill = Skill(
filePath: resolvedPath,
toolSource: server.inferredRemoteToolSource,
isDirectory: true,
name: name,
skillDescription: parsed.description,
content: parsed.content,
frontmatter: parsed.frontmatter,
isGlobal: true,
resolvedPath: resolvedPath
)
skill.remoteServer = server
skill.remotePath = path
modelContext.insert(skill)
}
}
// Remove skills that no longer exist on the server
let serverID = server.id
let remotePredicate = #Predicate<Skill> { $0.resolvedPath.starts(with: "remote://") }
if let existingRemoteSkills = try? modelContext.fetch(FetchDescriptor<Skill>(predicate: remotePredicate)) {
for skill in existingRemoteSkills {
guard skill.remoteServer?.id == serverID else { continue }
if !foundPaths.contains(skill.resolvedPath) {
modelContext.delete(skill)
}
}
}
server.lastSyncDate = .now
server.lastSyncError = nil
do { try modelContext.save() } catch {
AppLogger.scanning.error("SwiftData save failed after sync: \(error.localizedDescription)")
}
} catch {
server.lastSyncError = error.localizedDescription
do { try modelContext.save() } catch {
AppLogger.scanning.error("SwiftData save failed after sync error: \(error.localizedDescription)")
}
}
}
@MainActor
func removeDeletedSkills() {
let descriptor = FetchDescriptor<Skill>()
guard let skills = try? modelContext.fetch(descriptor) else { return }
let fm = FileManager.default
for skill in skills {
// Remove orphaned remote skills (server was deleted)
if skill.resolvedPath.hasPrefix("remote://") && skill.remoteServer == nil {
modelContext.delete(skill)
continue
}
// Remote skills are managed by scanRemoteServer(), skip here
if skill.isRemote { continue }
// Plugin skills use canonical IDs, not filesystem paths. Let applyResults()
// handle their lifecycle so updates don't delete and recreate user metadata.
if Self.isSyntheticLocalResolvedPath(skill.resolvedPath) { continue }
// Remove previously-scanned loose markdown files that are now filtered out.
let fileName = URL(fileURLWithPath: skill.filePath).lastPathComponent
if !skill.isDirectory, Self.shouldIgnoreLooseMarkdownFile(named: fileName) {
modelContext.delete(skill)
continue
}
let validPaths = skill.installedPaths.filter { fm.fileExists(atPath: $0) }
if validPaths.isEmpty {
modelContext.delete(skill)
} else {
skill.installedPaths = validPaths
if !fm.fileExists(atPath: skill.filePath), let first = validPaths.first {
skill.filePath = first
}
}
}
do { try modelContext.save() } catch {
AppLogger.scanning.error("SwiftData save failed: \(error.localizedDescription)")
}
}
deinit {
scanTask?.cancel()
}
}