feat: Add swift-git skill definition and comprehensive API reference documentation, including Chinese localization.

Author: linhay

.skills/swift-git/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: "swift-git"
+description: "Repository-focused skill for building, testing, and agent-safe operations in the SwiftGit repository. Use when performing build/test tasks, running single tests, or when an automated agent needs to follow repository agent rules and safe commands."
+---
+
+# swift-git skill
+
+Purpose
+- Provide concise, actionable instructions and examples for automated agents and humans working with this repository.
+- Expose the small set of repository-specific commands and agent rules an automated worker needs so the runtime can make safe decisions without loading large docs.
+
+When to use this skill (trigger examples)
+- "Build the package"
+- "Run tests"
+- "Run a single test"
+- "Where are the build/test commands"
+- "What agent rules should I follow for commits and CI"
+
+Quick commands (do not execute without user approval)
+- Build (debug):
+  - swift build
+- Build (release):
+  - swift build -c release
+- Run full tests:
+  - swift test
+- Run a single test (filter by name):
+  - swift test --filter ParseTests.testChangedEntryIndex_valid
+  - swift test --filter test_format_date
+
+Repository constraints (MUST follow)
+- Do NOT create commits or push to remote on behalf of a user unless explicitly authorized.
+- Do NOT modify the embedded git bundle at Sources/SwiftGit/Resource/git-instance.bundle.
+- Avoid adding or enforcing new lint/format rules without updating AGENTS.md and CI configuration.
+
+Agent safety rules (short)
+- Prefer array-based process invocations in code over shell-escaped string commands to avoid escaping bugs.
+- Prefer existing libraries and small focused changes vs large refactors.
+- When making multi-step changes, create an explicit TODO plan and surface it before editing.
+
+References
+- See references/AGENTS.md for a concise, agent-focused summary of AGENTS.md and repository tooling.
+
+Examples (do not auto-run)
+- "I want to run the test suite locally": use `swift test` from repository root.
+- "Run a single test": use `swift test --filter <TestName>` as shown above.
+- "Check package manifest": open Package.swift at repository root.
+
+Packaging the skill
+- To package this skill (manual step), follow your environment's packaging script. Example: `scripts/package_skill.py swift-git.skill` (if package exists in your environment).
+
+FAQ
+- Q: Should an agent commit changes it makes?
+  - A: No. Only stage files locally and present a diff; commit only if the user explicitly asks.

.skills/swift-git/references/AGENTS.md

@@ -0,0 +1,29 @@
+This file is a concise, agent-focused summary of the repository AGENTS.md tailored for automated workers.
+
+Core commands
+- Build (debug): swift build
+- Build (release): swift build -c release
+- Run all tests: swift test
+- Run a single test: swift test --filter <TestName>
+
+Agent working rules (must follow)
+- NEVER commit or push without explicit user permission.
+- NEVER modify the embedded git bundle under Sources/SwiftGit/Resource/git-instance.bundle.
+- When creating commits, follow repository commit message style: short 1-2 line message that explains the why.
+- If adding linters or formatters, update AGENTS.md and CI configs accordingly.
+
+Test & CI notes
+- CI uses GitHub Actions (.github/workflows/ci.yml). Prefer macos-latest runners.
+- Integration tests prefer the embedded git instance and fall back to system git.
+
+File locations
+- Package manifest: Package.swift
+- Main sources: Sources/SwiftGit/
+- Tests: Tests/SwiftGitTests/
+
+Helpful patterns
+- Use Shell utilities present in Sources/SwiftGit/Custom/Shell.swift for centralized process execution.
+- Prefer array-based arguments when invoking Shell helpers (avoid building a single shell string).
+
+Contact
+- Open an issue with commands and repository state when blocked.

.skills/swift-git/references/APIS.md

@@ -0,0 +1,99 @@
+# SwiftGit public API inventory
+
+This document catalogs the public API surface of the SwiftGit package and provides focused documentation and usage examples for automated agents and human readers. It is intended to be consumed by agents to generate actionable SKILL content for each API area.
+
+Structure
+- Classes & types: short descriptions and top-level public members
+- Models: commonly used value types and their important properties
+- Options: ExpressibleByStringLiteral option types used as argument helpers
+- Commands: repository/command helpers exposed as public extensions
+- Tests: reference to tests that target the public API
+
+Primary public types
+
+1) Git (class)
+- Location: Sources/SwiftGit/Custom/Git.swift
+- Summary: High-level entrypoint for running git commands via the package. Holds a GitEnvironment and a Shell.Instance for process execution.
+- Important public members (selection):
+  - public static var shared: Git { get throws }
+  - public init(environment: GitEnvironment)
+  - public func data(_ commands: [String], context: Shell.Context? = nil) async throws -> Data
+  - public func run(_ commands: [String], context: Shell.Context? = nil) async throws -> String
+  - public func run(_ cmd: String, context: Shell.Context? = nil) async throws -> String
+  - public func data(_ commands: [String], context: Shell.Context? = nil) throws -> Data
+  - public func run(_ commands: [String], context: Shell.Context? = nil) throws -> String
+  - public func repository(at url: URL) -> Repository
+  - public func repository(at path: String) -> Repository
+
+2) GitEnvironment (class & nested types)
+- Location: Sources/SwiftGit/Custom/GitEnvironment.swift
+- Summary: Represents a configured git runtime (embedded, system, or custom). Encapsulates resource (executable), environment variables, and triggers.
+- Important public members:
+  - public enum Style { case embed, system, custom(_ url: URL), auto }
+  - public struct Resource { public let executableURL: URL; public let envExecPath: String? }
+  - public struct Variable { factory helpers: execPath(_:), home(_:), prefix(_:), configNoSystem(_:), etc. }
+  - public init(resource: Resource, variables: [Variable], triggers: [GitTrigger])
+  - public static var shared: GitEnvironment { get }
+
+3) Repository (struct)
+- Location: Sources/SwiftGit/Custom/Repository.swift
+- Summary: Convenience repository-scoped helpers backed by a Git instance. Provides many sub-APIs for common git workflows.
+- Important public members (selection):
+  - public init(git: Git, url: URL)
+  - public init(git: Git, path: String)
+  - public extension Repository { many repository helpers live in extensions (clone, commit, push, status, tag, stash, etc.) }
+
+4) Shell (structs & Instance)
+- Location: Sources/SwiftGit/Custom/Shell.swift
+- Summary: Centralized process execution utilities (sync/async + Combine publishers). Prefer these helpers when invoking git.
+- Important public types & members:
+  - public struct Context { public var environment: [String: String]; public var currentDirectory: URL?; public let standardOutput: PassthroughSubject<Data, Never>? }
+  - public struct Arguments / ShellArguments
+  - public struct Instance { public var changedArgsBeforeRun: ((_ args: inout Arguments) -> Void)?; public func data(_ args: Shell.Arguments) async throws -> Data; public func string(_ args: Shell.Arguments) async throws -> String }
+  - convenience static helpers: Shell.zsh(...), Shell.data(...), Shell.string(...)
+
+5) GitTrigger (struct)
+- Location: Sources/SwiftGit/Custom/GitTrigger.swift
+- Summary: Small callback/event primitive used by GitEnvironment to trigger hooks on events.
+- Important public members:
+  - public enum Event: Int { case beforeRun, afterRun }
+  - public struct Content { public let commands: [String]; public let data: Data }
+  - public init(on event: Event, action: @escaping (_ result: Result<Content, Error>) -> Void)
+  - public static func failure(on:event, action: ...) and success(on:event, action: ...)
+
+Models (examples)
+- GitStatus (Sources/SwiftGit/Custom/models/GitStatus.swift): public struct GitStatus with properties branch, changed, renamedCopied, unmerged, untracked. Several nested types represent entries and styles.
+- Commit / Commit enums: Sources/SwiftGit/Custom/models/Commit.swift
+- Reference types: Sources/SwiftGit/Custom/models/Reference.swift (protocol ReferenceType, structs Branch, Tag)
+- Pathspec: ExpressibleByStringLiteral helper, value wrapper
+
+Options
+- Many option types are defined as small structs conforming to ExpressibleByStringLiteral for convenient API composition. Examples:
+  - AddOptions, ResetOptions, CloneOptions, CommitOptions, PushOptions, FetchOptions, StatusOptions, etc. (see Sources/SwiftGit/options/)
+
+Commands & repository extensions
+- Most git subcommands are exposed as public extensions on Git or Repository under Sources/SwiftGit/Custom/commands/*. Each file shapes a coherent sub-API (clone, commit, push, fetch, log, status, tag, stash, etc.).
+
+Tests that reference public APIs
+- Tests live under Tests/SwiftGitTests. Key files that exercise public APIs include:
+  - Tests/SwiftGitTests/IntegrationTests.swift
+  - Tests/SwiftGitTests/ParseTests.swift
+  - Tests/SwiftGitTests/CloneCommandTests.swift
+  - Tests/SwiftGitTests/ShowCommitResultTests.swift
+
+How this inventory will be used
+- The next step is to generate per-API skill documentation files that include:
+  - The declaration/signature
+  - Short description
+  - Examples of usage (non-executable snippets)
+  - Tests referencing the API
+
+Follow-up files to generate (I will create when you approve):
+- references/apis/Git.md
+- references/apis/GitEnvironment.md
+- references/apis/Repository.md
+- references/apis/Shell.md
+- references/apis/GitTrigger.md
+- references/apis/Models.md
+- references/apis/Options.md
+- references/apis/Commands.md

.skills/swift-git/references/apis/Commands.md

@@ -0,0 +1,16 @@
+# Commands
+
+This section maps the command helper files in Sources/SwiftGit/Custom/commands/ to high-level responsibilities. Each file typically exposes public extensions on Git or Repository and associated option types.
+
+Files & purpose (selection)
+- git-commands-clone.swift — clone helpers and CloneOptions
+- git-commands-commit.swift — commit helpers and CommitOptions
+- git-commands-status.swift — status helpers and StatusOptions
+- git-commands-log.swift — log helpers and LogOptions
+- git-commands-push.swift — push helpers and PushOptions
+- git-commands-fetch.swift — fetch helpers
+- git-commands-tag.swift — tag helpers
+- git-commands-stash.swift — stash helpers
+
+Notes for agents
+- For each command helper, open the corresponding file to extract exact function signatures and examples. When in doubt, prefer the explicit functions that accept typed option structs.

.skills/swift-git/references/apis/Git.md

@@ -0,0 +1,36 @@
+# Git
+
+Location: Sources/SwiftGit/Custom/Git.swift
+
+Public declaration highlights
+- public class Git
+- public static var shared: Git { get throws }
+- public init(environment: GitEnvironment)
+- public func data(_ commands: [String], context: Shell.Context? = nil) async throws -> Data
+- public func run(_ commands: [String], context: Shell.Context? = nil) async throws -> String
+- public func run(_ cmd: String, context: Shell.Context? = nil) async throws -> String
+- public func data(_ commands: [String], context: Shell.Context? = nil) throws -> Data
+- public func run(_ commands: [String], context: Shell.Context? = nil) throws -> String
+- public func run(_ cmd: String, context: Shell.Context? = nil) throws -> String
+- public func repository(at url: URL) -> Repository
+- public func repository(at path: String) -> Repository
+
+Summary
+The Git class is the high-level entrypoint for running Git commands. It wraps a GitEnvironment (which selects an embedded or system git) and a Shell.Instance that performs the actual process execution. Use Git for programmatic access to git operations in this package.
+
+Usage examples
+- Async run example:
+
+  let git = try Git(environment: .shared)
+  let output = try await git.run(["status", "--porcelain=v2"]) // String
+
+- Sync data example (throws):
+
+  let data = try git.data(["rev-parse", "HEAD"]) // Data
+
+Notes for agents
+- Prefer the array-based overloads ([String]) to avoid shell-escaping issues.
+- Do not modify Git.shared unless explicitly requested by the repository maintainer; creating a new Git(environment:) is preferred for test isolation.
+
+Tests that reference Git
+- Tests/SwiftGitTests/* includes integration tests that create Git/GitEnvironment instances and exercise repository workflows. See IntegrationTests.swift and RepositoryRunTests.swift.

.skills/swift-git/references/apis/GitEnvironment.md

@@ -0,0 +1,25 @@
+# GitEnvironment
+
+Location: Sources/SwiftGit/Custom/GitEnvironment.swift
+
+Public declaration highlights
+- public class GitEnvironment
+- public enum Style { case embed, system, custom(_ url: URL), auto }
+- public struct Resource { public let executableURL: URL; public let envExecPath: String? }
+- public struct Variable { factory helpers: execPath(_:), home(_:), prefix(_:), configNoSystem(_:), etc. }
+- public init(resource: Resource, variables: [Variable], triggers: [GitTrigger])
+- public static var shared: GitEnvironment { get }
+
+Summary
+Encapsulates how the library locates and configures a git binary, including an embedded git bundle or system git. Variables allow customizing environment variables such as GIT_EXEC_PATH and HOME.
+
+Usage
+
+  let env = try GitEnvironment(resource: .init(executableURL: url), variables: [], triggers: [])
+  let git = Git(environment: env)
+
+Notes for agents
+- When tests or integration code need predictable behavior, prefer explicitly constructed GitEnvironment instances over .shared.
+
+Tests referencing GitEnvironment
+- GitEnvironmentTests.swift and GitEnvironmentInitTests.swift

.skills/swift-git/references/apis/GitTrigger.md

@@ -0,0 +1,22 @@
+# GitTrigger
+
+Location: Sources/SwiftGit/Custom/GitTrigger.swift
+
+Public declaration highlights
+- public struct GitTrigger
+- public enum Event: Int { case beforeRun, afterRun }
+- public struct Content { public let commands: [String]; public let data: Data }
+- public init(on event: Event, action: @escaping (_ result: Result<Content, Error>) -> Void)
+- public static func failure(on:event, action: ...) and success(on:event, action: ...)
+
+Summary
+Small event/callback primitive used by GitEnvironment to invoke actions before or after certain events. Useful for logging, telemetry, or validation hooks.
+
+Usage example
+
+  let trigger = GitTrigger(on: .beforeRun) { result in
+     switch result { case .success(let content): print(content.commands) case .failure(let err): print(err) }
+  }
+
+Notes for agents
+- When constructing GitEnvironment for tests, pass triggers to observe command execution events.

.skills/swift-git/references/apis/Models.md

@@ -0,0 +1,20 @@
+# Models
+
+This page summarizes commonly used models exposed by the package.
+
+GitStatus
+- Location: Sources/SwiftGit/Custom/models/GitStatus.swift
+- public struct GitStatus: Equatable with properties branch, changed, renamedCopied, unmerged, untracked and nested entry types.
+
+Commit & User models
+- Sources/SwiftGit/Custom/models/Commit.swift
+- Sources/SwiftGit/Custom/results/LogResult.swift
+
+Reference types
+- Sources/SwiftGit/Custom/models/Reference.swift contains ReferenceType protocol and concrete Branch/Tag types for strongly-typed references.
+
+Pathspec
+- Sources/SwiftGit/Custom/models/Pathspec.swift — ExpressibleByStringLiteral helper for pathspecs.
+
+Notes for agents
+- Models are value types and safe to pass around. Prefer using them in examples rather than raw strings when demonstrating APIs.

.skills/swift-git/references/apis/Options.md

@@ -0,0 +1,13 @@
+# Options
+
+The repository defines many small option types used to compose git command arguments. All are in Sources/SwiftGit/options/ and most conform to ExpressibleByStringLiteral for convenient construction.
+
+Examples
+- CloneOptions, CommitOptions, PushOptions, FetchOptions, StatusOptions, ResetOptions, AddOptions, etc.
+
+Usage example
+
+  try await repo.log(options: .init("--oneline"))
+
+Notes for agents
+- These option types are lightweight wrappers. When generating examples, prefer to show both literal string usage and typed usage (e.g., .message("msg")).

.skills/swift-git/references/apis/Repository.md

@@ -0,0 +1,24 @@
+# Repository
+
+Location: Sources/SwiftGit/Custom/Repository.swift
+
+Public declaration highlights
+- public struct Repository
+- public init(git: Git, url: URL)
+- public init(git: Git, path: String)
+- Many repository-scoped command helpers are defined as public extensions across Sources/SwiftGit/Custom/commands/*. These include clone, commit, push, status, tag, stash, fetch, pull, merge, etc.
+
+Summary
+Repository is a lightweight wrapper that provides convenience methods executing git commands within a repository directory using an associated Git instance.
+
+Usage example
+
+  let git = try Git(environment: .shared)
+  let repo = git.repository(at: "/path/to/repo")
+  try await repo.commit("message", options: .init())
+
+Notes for agents
+- Look for specific helper files under Sources/SwiftGit/Custom/commands/ to find detailed signatures and option types for each command.
+
+Tests
+- CloneCommandTests, IntegrationTests, and RepositoryRunTests contain examples that exercise Repository helpers.