[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79X7W0M3XJMF1BHWHVTBN82":3,"skill-same:01M79X7W0M3XJMF1BHWHVTBN82":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M79X7W0M3XJMF1BHWHVTBN82","deniz-dotnet-general.api-design",null,"Design stable, compatible public APIs using extend-only design principles. Manage API compatibility, wire compatibility, and versioning for NuGet packages and distributed systems. Edit-time compatibility checks: dotnet-breaking-changes.","Blind-Striker\u002Fagent-skills-and-plugins","Blind-Striker","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1965259?v=4","01M79WFXTE5PH0C1VB7B54ANMN","Deniz İrgin","01M79WFXV5KZ5GST1K8G035DM5",1,"MIT","https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fopencode\u002Fdeniz-dotnet-general\u002Fskills\u002Fdeniz-dotnet-general.api-design\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: deniz-dotnet-general.api-design\ndescription: \"Design stable, compatible public APIs using extend-only design\n  principles. Manage API compatibility, wire compatibility, and versioning for\n  NuGet packages and distributed systems. Edit-time compatibility checks:\n  dotnet-breaking-changes.\"\n---\n\n# Public API Design and Compatibility\n\n## When to Use This Skill\n\nUse this skill when:\n- Designing public APIs for NuGet packages or libraries\n- Making changes to existing public APIs\n- Planning wire format changes for distributed systems\n- Implementing versioning strategies\n- Reviewing pull requests for breaking changes\n\nEdit-time compatibility checks of a concrete change to an existing public API belong to\ndotnet-breaking-changes; this skill covers the design-time principles and wire compatibility.\n\n---\n\n## The Three Types of Compatibility\n\n| Type | Definition | Scope |\n|------|------------|-------|\n| **API\u002FSource** | Code compiles against newer version | Public method signatures, types |\n| **Binary** | Compiled code runs against newer version | Assembly layout, method tokens |\n| **Wire** | Serialized data readable by other versions | Network protocols, persistence formats |\n\nBreaking any of these creates upgrade friction for users.\n\n---\n\n## Extend-Only Design\n\nThe foundation of stable APIs: **never remove or modify, only extend**.\n\n### Three Pillars\n\n1. **Previous functionality is immutable** - Once released, behavior and signatures are locked\n2. **New functionality through new constructs** - Add overloads, new types, opt-in features\n3. **Removal only after deprecation period** - Years, not releases\n\n### Benefits\n\n- Old code continues working in new versions\n- New and old pathways coexist\n- Upgrades are non-breaking by default\n- Users upgrade on their schedule\n\n**Resources:**\n- [Extend-Only Design](https:\u002F\u002Faaronstannard.com\u002Fextend-only-design\u002F)\n- [OSS Compatibility Standards](https:\u002F\u002Faaronstannard.com\u002Foss-compatibility-standards\u002F)\n\n---\n\n## API Change Guidelines\n\n### Safe Changes (Any Release)\n\n```csharp\n\u002F\u002F SAFE: Add NEW overload methods that delegate to existing methods\n\u002F\u002F Existing method - do not modify its signature\npublic void Process(Order order) { ... }\n\u002F\u002F New overload - safe to add\npublic void Process(Order order, CancellationToken ct)\n{\n    \u002F\u002F implementation that handles cancellation\n}\n\n\u002F\u002F SAFE: Add NEW overloads for additional functionality\n\u002F\u002F Existing method - do not modify\npublic void Send(Message msg) { ... }\n\u002F\u002F New overload - safe to add\npublic void Send(Message msg, Priority priority)\n{\n    \u002F\u002F implementation that handles priority\n}\n\n\u002F\u002F ADD new types, interfaces, enums\npublic interface IOrderValidator { }\npublic enum OrderStatus { Pending, Complete, Cancelled }\n\n\u002F\u002F ADD new members to existing types\npublic class Order\n{\n    public DateTimeOffset? ShippedAt { get; init; }  \u002F\u002F NEW\n}\n```\n\n### Unsafe Changes (Never or Major Version Only)\n\n```csharp\n\u002F\u002F REMOVE or RENAME public members\npublic void ProcessOrder(Order order);  \u002F\u002F Was: Process()\n\n\u002F\u002F CHANGE parameter types or order\npublic void Process(int orderId);  \u002F\u002F Was: Process(Order order)\n\n\u002F\u002F CHANGE return types\npublic Order? GetOrder(string id);  \u002F\u002F Was: public Order GetOrder()\n\n\u002F\u002F CHANGE access modifiers\ninternal class OrderProcessor { }  \u002F\u002F Was: public\n\n\u002F\u002F ADD optional parameters to EXISTING methods (binary incompatible!)\n\u002F\u002F The compiled IL method signature changes - callers compiled against\n\u002F\u002F the old signature will get MissingMethodException at runtime.\n\u002F\u002F Optional parameter defaults are baked into the CALLER's assembly at compile time.\npublic void Process(Order order, CancellationToken ct = default);  \u002F\u002F Breaks binary compat!\npublic void Send(Message msg, Priority priority = Priority.Normal);  \u002F\u002F Breaks binary compat!\n\u002F\u002F Correct approach: add a NEW overload method instead (see Safe Changes above)\n\n\u002F\u002F ADD required parameters without defaults\npublic void Process(Order order, ILogger logger);  \u002F\u002F Breaks callers!\n```\n\n### Deprecation Pattern\n\n```csharp\n\u002F\u002F Step 1: Mark as obsolete with version (any release)\n[Obsolete(\"Obsolete since v1.5.0. Use ProcessAsync instead.\")]\npublic void Process(Order order) { }\n\n\u002F\u002F Step 2: Add new recommended API (same release)\npublic Task ProcessAsync(Order order, CancellationToken ct = default);\n\n\u002F\u002F Step 3: Remove in next major version (v2.0+)\n\u002F\u002F Only after users have had time to migrate\n```\n\n---\n\n## API Approval Testing\n\nPrevent accidental breaking changes with automated API surface testing.\n\n### Using ApiApprover + Verify\n\n```bash\ndotnet add package PublicApiGenerator\ndotnet add package Verify.Xunit\n```\n\n```csharp\n[Fact]\npublic Task ApprovePublicApi()\n{\n    var api = typeof(MyLibrary.PublicClass).Assembly.GeneratePublicApi();\n    return Verify(api);\n}\n```\n\nCreates `ApprovePublicApi.verified.txt`:\n\n```csharp\nnamespace MyLibrary\n{\n    public class OrderProcessor\n    {\n        public OrderProcessor() { }\n        public void Process(Order order) { }\n        public Task ProcessAsync(Order order, CancellationToken ct = default) { }\n    }\n}\n```\n\n**Any API change fails the test** - reviewer must explicitly approve changes.\n\n### PR Review Process\n\n1. PR includes changes to `*.verified.txt` files\n2. Reviewers see exact API surface changes in diff\n3. Breaking changes are immediately visible\n4. Conscious decision required to approve\n\n---\n\n## Wire Compatibility\n\nFor distributed systems, serialized data must be readable across versions.\n\n### Requirements\n\n| Direction | Requirement |\n|-----------|-------------|\n| **Backward** | Old writers → New readers (current version reads old data) |\n| **Forward** | New writers → Old readers (old version reads new data) |\n\nBoth are required for zero-downtime rolling upgrades.\n\n### Safely Evolving Wire Formats\n\n**Phase 1: Add read-side support (opt-in)**\n\n```csharp\n\u002F\u002F New message type - readers deployed first\npublic sealed record HeartbeatV2(\n    Address From,\n    long SequenceNr,\n    long CreationTimeMs);  \u002F\u002F NEW field\n\n\u002F\u002F Deserializer handles both old and new\npublic object Deserialize(byte[] data, string manifest) => manifest switch\n{\n    \"Heartbeat\" => DeserializeHeartbeatV1(data),   \u002F\u002F Old format\n    \"HeartbeatV2\" => DeserializeHeartbeatV2(data), \u002F\u002F New format\n    _ => throw new NotSupportedException()\n};\n```\n\n**Phase 2: Enable write-side (opt-out, next minor version)**\n\n```csharp\n\u002F\u002F Config to enable new format (off by default initially)\nakka.cluster.use-heartbeat-v2 = on\n```\n\n**Phase 3: Make default (future version)**\n\nAfter install base has absorbed read-side code.\n\n### Schema-Based Serialization\n\nPrefer schema-based formats over reflection-based:\n\n| Format | Type | Wire Compatibility |\n|--------|------|-------------------|\n| **Protocol Buffers** | Schema-based | Excellent - explicit field numbers |\n| **MessagePack** | Schema-based | Good - with contracts |\n| **System.Text.Json** | Schema-based (with source gen) | Good - explicit properties |\n| Newtonsoft.Json | Reflection-based | Poor - type names in payload |\n| BinaryFormatter | Reflection-based | Terrible - never use |\n\nSee `dotnet\u002Fserialization` skill for details.\n\n---\n\n## Encapsulation Patterns\n\n### Internal APIs\n\nMark non-public APIs explicitly:\n\n```csharp\n\u002F\u002F Attribute for documentation\n[InternalApi]\npublic class ActorSystemImpl { }\n\n\u002F\u002F Namespace convention\nnamespace MyLibrary.Internal\n{\n    public class InternalHelper { }  \u002F\u002F Public for extensibility, not for users\n}\n```\n\nDocument clearly:\n\n> Types in `.Internal` namespaces or marked with `[InternalApi]` may change between any releases without notice.\n\n### Sealing Classes\n\n```csharp\n\u002F\u002F DO: Seal classes not designed for inheritance\npublic sealed class OrderProcessor { }\n\n\u002F\u002F DON'T: Leave unsealed by accident\npublic class OrderProcessor { }  \u002F\u002F Users might inherit, blocking changes\n```\n\n### Interface Segregation\n\n```csharp\n\u002F\u002F DO: Small, focused interfaces\npublic interface IOrderReader\n{\n    Order? GetById(OrderId id);\n}\n\npublic interface IOrderWriter\n{\n    Task SaveAsync(Order order);\n}\n\n\u002F\u002F DON'T: Monolithic interfaces (can't add methods without breaking)\npublic interface IOrderRepository\n{\n    Order? GetById(OrderId id);\n    Task SaveAsync(Order order);\n    \u002F\u002F Adding new methods breaks all implementations!\n}\n```\n\n---\n\n## Versioning Strategy\n\n### Semantic Versioning (Practical)\n\n| Version | Changes Allowed |\n|---------|----------------|\n| **Patch** (1.0.x) | Bug fixes, security patches |\n| **Minor** (1.x.0) | New features, deprecations |\n| **Major** (x.0.0) | Breaking changes, old API removal, obsolete removal |\n\n### Key Principles\n\n1. **No surprise breaks** - Even major versions should be announced and planned\n2. **Extensions anytime** - New APIs can ship in any release\n3. **Deprecate before remove** - `[Obsolete]` for at least one minor version\n4. **Communicate timelines** - Users need to plan upgrades\n\n### Chesterton's Fence\n\n> Before removing or changing something, understand why it exists.\n\nAssume every public API is used by someone. If you want to change it:\n1. Socialize the proposal on GitHub\n2. Document migration path\n3. Provide deprecation period\n4. Ship in planned release\n\n---\n\n## Pull Request Checklist\n\nWhen reviewing PRs that touch public APIs:\n\n- [ ] **No removed public members** (use `[Obsolete]` instead)\n- [ ] **No changed signatures** (add overloads instead)\n- [ ] **No new required parameters** (use defaults)\n- [ ] **API approval test updated** (`.verified.txt` changes reviewed)\n- [ ] **Wire format changes are opt-in** (read-side first)\n- [ ] **Breaking changes documented** (release notes, migration guide)\n\n---\n\n## Anti-Patterns\n\n### Breaking Changes Disguised as Fixes\n\n```csharp\n\u002F\u002F \"Bug fix\" that breaks users\npublic async Task\u003COrder> GetOrderAsync(OrderId id)  \u002F\u002F Was sync!\n{\n    \u002F\u002F \"Fixed\" to be async - but breaks all callers\n}\n\n\u002F\u002F Correct: Add new method, deprecate old\n[Obsolete(\"Use GetOrderAsync instead\")]\npublic Order GetOrder(OrderId id) => GetOrderAsync(id).Result;\n\npublic async Task\u003COrder> GetOrderAsync(OrderId id) { }\n```\n\n### Silent Behavior Changes\n\n```csharp\n\u002F\u002F Changing defaults breaks users who relied on old behavior\npublic void Configure(bool enableCaching = true)  \u002F\u002F Was: false!\n\n\u002F\u002F Correct: keep the old method, add an overload for the new behavior\npublic void Configure(bool enableCaching = false)  \u002F\u002F Original signature and default preserved\n    => Configure(enableCaching, enableNewCaching: false);\n\npublic void Configure(bool enableCaching, bool enableNewCaching)  \u002F\u002F New behavior opt-in\n```\n\n### Polymorphic Serialization\n\n```csharp\n\u002F\u002F AVOID: Type names in wire format\n{ \"$type\": \"MyApp.Order, MyApp\", \"Id\": 123 }\n\n\u002F\u002F Renaming Order class = wire break!\n\n\u002F\u002F PREFER: Explicit discriminators\n{ \"type\": \"order\", \"id\": 123 }\n```\n\n---\n\n## Resources\n\n- [Making Public API Changes](https:\u002F\u002Fgetakka.net\u002Fcommunity\u002Fcontributing\u002Fapi-changes-compatibility.html)\n- [Wire Format Changes](https:\u002F\u002Fgetakka.net\u002Fcommunity\u002Fcontributing\u002Fwire-compatibility.html)\n- [Extend-Only Design](https:\u002F\u002Faaronstannard.com\u002Fextend-only-design\u002F)\n- [OSS Compatibility Standards](https:\u002F\u002Faaronstannard.com\u002Foss-compatibility-standards\u002F)\n- [Semantic Versioning](https:\u002F\u002Fsemver.org\u002F)\n- [PublicApiGenerator](https:\u002F\u002Fgithub.com\u002FPublicApiGenerator\u002FPublicApiGenerator)\n","# Public API Design and Compatibility\n\n## When to Use This Skill\n\nUse this skill when:\n- Designing public APIs for NuGet packages or libraries\n- Making changes to existing public APIs\n- Planning wire format changes for distributed systems\n- Implementing versioning strategies\n- Reviewing pull requests for breaking changes\n\nEdit-time compatibility checks of a concrete change to an existing public API belong to\ndotnet-breaking-changes; this skill covers the design-time principles and wire compatibility.\n\n---\n\n## The Three Types of Compatibility\n\n| Type | Definition | Scope |\n|------|------------|-------|\n| **API\u002FSource** | Code compiles against newer version | Public method signatures, types |\n| **Binary** | Compiled code runs against newer version | Assembly layout, method tokens |\n| **Wire** | Serialized data readable by other versions | Network protocols, persistence formats |\n\nBreaking any of these creates upgrade friction for users.\n\n---\n\n## Extend-Only Design\n\nThe foundation of stable APIs: **never remove or modify, only extend**.\n\n### Three Pillars\n\n1. **Previous functionality is immutable** - Once released, behavior and signatures are locked\n2. **New functionality through new constructs** - Add overloads, new types, opt-in features\n3. **Removal only after deprecation period** - Years, not releases\n\n### Benefits\n\n- Old code continues working in new versions\n- New and old pathways coexist\n- Upgrades are non-breaking by default\n- Users upgrade on their schedule\n\n**Resources:**\n- [Extend-Only Design](https:\u002F\u002Faaronstannard.com\u002Fextend-only-design\u002F)\n- [OSS Compatibility Standards](https:\u002F\u002Faaronstannard.com\u002Foss-compatibility-standards\u002F)\n\n---\n\n## API Change Guidelines\n\n### Safe Changes (Any Release)\n\n```csharp\n\u002F\u002F SAFE: Add NEW overload methods that delegate to existing methods\n\u002F\u002F Existing method - do not modify its signature\npublic void Process(Order order) { ... }\n\u002F\u002F New overload - safe to add\npublic void Process(Order order, CancellationToken ct)\n{\n    \u002F\u002F implementation that handles cancellation\n}\n\n\u002F\u002F SAFE: Add NEW overloads for additional functionality\n\u002F\u002F Existing method - do not modify\npublic void Send(Message msg) { ... }\n\u002F\u002F New overload - safe to add\npublic void Send(Message msg, Priority priority)\n{\n    \u002F\u002F implementation that handles priority\n}\n\n\u002F\u002F ADD new types, interfaces, enums\npublic interface IOrderValidator { }\npublic enum OrderStatus { Pending, Complete, Cancelled }\n\n\u002F\u002F ADD new members to existing types\npublic class Order\n{\n    public DateTimeOffset? ShippedAt { get; init; }  \u002F\u002F NEW\n}\n```\n\n### Unsafe Changes (Never or Major Version Only)\n\n```csharp\n\u002F\u002F REMOVE or RENAME public members\npublic void ProcessOrder(Order order);  \u002F\u002F Was: Process()\n\n\u002F\u002F CHANGE parameter types or order\npublic void Process(int orderId);  \u002F\u002F Was: Process(Order order)\n\n\u002F\u002F CHANGE return types\npublic Order? GetOrder(string id);  \u002F\u002F Was: public Order GetOrder()\n\n\u002F\u002F CHANGE access modifiers\ninternal class OrderProcessor { }  \u002F\u002F Was: public\n\n\u002F\u002F ADD optional parameters to EXISTING methods (binary incompatible!)\n\u002F\u002F The compiled IL method signature changes - callers compiled against\n\u002F\u002F the old signature will get MissingMethodException at runtime.\n\u002F\u002F Optional parameter defaults are baked into the CALLER's assembly at compile time.\npublic void Process(Order order, CancellationToken ct = default);  \u002F\u002F Breaks binary compat!\npublic void Send(Message msg, Priority priority = Priority.Normal);  \u002F\u002F Breaks binary compat!\n\u002F\u002F Correct approach: add a NEW overload method instead (see Safe Changes above)\n\n\u002F\u002F ADD required parameters without defaults\npublic void Process(Order order, ILogger logger);  \u002F\u002F Breaks callers!\n```\n\n### Deprecation Pattern\n\n```csharp\n\u002F\u002F Step 1: Mark as obsolete with version (any release)\n[Obsolete(\"Obsolete since v1.5.0. Use ProcessAsync instead.\")]\npublic void Process(Order order) { }\n\n\u002F\u002F Step 2: Add new recommended API (same release)\npublic Task ProcessAsync(Order order, CancellationToken ct = default);\n\n\u002F\u002F Step 3: Remove in next major version (v2.0+)\n\u002F\u002F Only after users have had time to migrate\n```\n\n---\n\n## API Approval Testing\n\nPrevent accidental breaking changes with automated API surface testing.\n\n### Using ApiApprover + Verify\n\n```bash\ndotnet add package PublicApiGenerator\ndotnet add package Verify.Xunit\n```\n\n```csharp\n[Fact]\npublic Task ApprovePublicApi()\n{\n    var api = typeof(MyLibrary.PublicClass).Assembly.GeneratePublicApi();\n    return Verify(api);\n}\n```\n\nCreates `ApprovePublicApi.verified.txt`:\n\n```csharp\nnamespace MyLibrary\n{\n    public class OrderProcessor\n    {\n        public OrderProcessor() { }\n        public void Process(Order order) { }\n        public Task ProcessAsync(Order order, CancellationToken ct = default) { }\n    }\n}\n```\n\n**Any API change fails the test** - reviewer must explicitly approve changes.\n\n### PR Review Process\n\n1. PR includes changes to `*.verified.txt` files\n2. Reviewers see exact API surface changes in diff\n3. Breaking changes are immediately visible\n4. Conscious decision required to approve\n\n---\n\n## Wire Compatibility\n\nFor distributed systems, serialized data must be readable across versions.\n\n### Requirements\n\n| Direction | Requirement |\n|-----------|-------------|\n| **Backward** | Old writers → New readers (current version reads old data) |\n| **Forward** | New writers → Old readers (old version reads new data) |\n\nBoth are required for zero-downtime rolling upgrades.\n\n### Safely Evolving Wire Formats\n\n**Phase 1: Add read-side support (opt-in)**\n\n```csharp\n\u002F\u002F New message type - readers deployed first\npublic sealed record HeartbeatV2(\n    Address From,\n    long SequenceNr,\n    long CreationTimeMs);  \u002F\u002F NEW field\n\n\u002F\u002F Deserializer handles both old and new\npublic object Deserialize(byte[] data, string manifest) => manifest switch\n{\n    \"Heartbeat\" => DeserializeHeartbeatV1(data),   \u002F\u002F Old format\n    \"HeartbeatV2\" => DeserializeHeartbeatV2(data), \u002F\u002F New format\n    _ => throw new NotSupportedException()\n};\n```\n\n**Phase 2: Enable write-side (opt-out, next minor version)**\n\n```csharp\n\u002F\u002F Config to enable new format (off by default initially)\nakka.cluster.use-heartbeat-v2 = on\n```\n\n**Phase 3: Make default (future version)**\n\nAfter install base has absorbed read-side code.\n\n### Schema-Based Serialization\n\nPrefer schema-based formats over reflection-based:\n\n| Format | Type | Wire Compatibility |\n|--------|------|-------------------|\n| **Protocol Buffers** | Schema-based | Excellent - explicit field numbers |\n| **MessagePack** | Schema-based | Good - with contracts |\n| **System.Text.Json** | Schema-based (with source gen) | Good - explicit properties |\n| Newtonsoft.Json | Reflection-based | Poor - type names in payload |\n| BinaryFormatter | Reflection-based | Terrible - never use |\n\nSee `dotnet\u002Fserialization` skill for details.\n\n---\n\n## Encapsulation Patterns\n\n### Internal APIs\n\nMark non-public APIs explicitly:\n\n```csharp\n\u002F\u002F Attribute for documentation\n[InternalApi]\npublic class ActorSystemImpl { }\n\n\u002F\u002F Namespace convention\nnamespace MyLibrary.Internal\n{\n    public class InternalHelper { }  \u002F\u002F Public for extensibility, not for users\n}\n```\n\nDocument clearly:\n\n> Types in `.Internal` namespaces or marked with `[InternalApi]` may change between any releases without notice.\n\n### Sealing Classes\n\n```csharp\n\u002F\u002F DO: Seal classes not designed for inheritance\npublic sealed class OrderProcessor { }\n\n\u002F\u002F DON'T: Leave unsealed by accident\npublic class OrderProcessor { }  \u002F\u002F Users might inherit, blocking changes\n```\n\n### Interface Segregation\n\n```csharp\n\u002F\u002F DO: Small, focused interfaces\npublic interface IOrderReader\n{\n    Order? GetById(OrderId id);\n}\n\npublic interface IOrderWriter\n{\n    Task SaveAsync(Order order);\n}\n\n\u002F\u002F DON'T: Monolithic interfaces (can't add methods without breaking)\npublic interface IOrderRepository\n{\n    Order? GetById(OrderId id);\n    Task SaveAsync(Order order);\n    \u002F\u002F Adding new methods breaks all implementations!\n}\n```\n\n---\n\n## Versioning Strategy\n\n### Semantic Versioning (Practical)\n\n| Version | Changes Allowed |\n|---------|----------------|\n| **Patch** (1.0.x) | Bug fixes, security patches |\n| **Minor** (1.x.0) | New features, deprecations |\n| **Major** (x.0.0) | Breaking changes, old API removal, obsolete removal |\n\n### Key Principles\n\n1. **No surprise breaks** - Even major versions should be announced and planned\n2. **Extensions anytime** - New APIs can ship in any release\n3. **Deprecate before remove** - `[Obsolete]` for at least one minor version\n4. **Communicate timelines** - Users need to plan upgrades\n\n### Chesterton's Fence\n\n> Before removing or changing something, understand why it exists.\n\nAssume every public API is used by someone. If you want to change it:\n1. Socialize the proposal on GitHub\n2. Document migration path\n3. Provide deprecation period\n4. Ship in planned release\n\n---\n\n## Pull Request Checklist\n\nWhen reviewing PRs that touch public APIs:\n\n- [ ] **No removed public members** (use `[Obsolete]` instead)\n- [ ] **No changed signatures** (add overloads instead)\n- [ ] **No new required parameters** (use defaults)\n- [ ] **API approval test updated** (`.verified.txt` changes reviewed)\n- [ ] **Wire format changes are opt-in** (read-side first)\n- [ ] **Breaking changes documented** (release notes, migration guide)\n\n---\n\n## Anti-Patterns\n\n### Breaking Changes Disguised as Fixes\n\n```csharp\n\u002F\u002F \"Bug fix\" that breaks users\npublic async Task\u003COrder> GetOrderAsync(OrderId id)  \u002F\u002F Was sync!\n{\n    \u002F\u002F \"Fixed\" to be async - but breaks all callers\n}\n\n\u002F\u002F Correct: Add new method, deprecate old\n[Obsolete(\"Use GetOrderAsync instead\")]\npublic Order GetOrder(OrderId id) => GetOrderAsync(id).Result;\n\npublic async Task\u003COrder> GetOrderAsync(OrderId id) { }\n```\n\n### Silent Behavior Changes\n\n```csharp\n\u002F\u002F Changing defaults breaks users who relied on old behavior\npublic void Configure(bool enableCaching = true)  \u002F\u002F Was: false!\n\n\u002F\u002F Correct: keep the old method, add an overload for the new behavior\npublic void Configure(bool enableCaching = false)  \u002F\u002F Original signature and default preserved\n    => Configure(enableCaching, enableNewCaching: false);\n\npublic void Configure(bool enableCaching, bool enableNewCaching)  \u002F\u002F New behavior opt-in\n```\n\n### Polymorphic Serialization\n\n```csharp\n\u002F\u002F AVOID: Type names in wire format\n{ \"$type\": \"MyApp.Order, MyApp\", \"Id\": 123 }\n\n\u002F\u002F Renaming Order class = wire break!\n\n\u002F\u002F PREFER: Explicit discriminators\n{ \"type\": \"order\", \"id\": 123 }\n```\n\n---\n\n## Resources\n\n- [Making Public API Changes](https:\u002F\u002Fgetakka.net\u002Fcommunity\u002Fcontributing\u002Fapi-changes-compatibility.html)\n- [Wire Format Changes](https:\u002F\u002Fgetakka.net\u002Fcommunity\u002Fcontributing\u002Fwire-compatibility.html)\n- [Extend-Only Design](https:\u002F\u002Faaronstannard.com\u002Fextend-only-design\u002F)\n- [OSS Compatibility Standards](https:\u002F\u002Faaronstannard.com\u002Foss-compatibility-standards\u002F)\n- [Semantic Versioning](https:\u002F\u002Fsemver.org\u002F)\n- [PublicApiGenerator](https:\u002F\u002Fgithub.com\u002FPublicApiGenerator\u002FPublicApiGenerator)\n",{"name":5,"description":7},"master","b30b1c1908dbc56a8184128f18803053d762ccb5","opencode\u002Fdeniz-dotnet-general\u002Fskills\u002Fdeniz-dotnet-general.api-design",0,"https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins","https:\u002F\u002Fgithub.com\u002FBlind-Striker","denizirgin.com","VP of Engineering - \r\n@armutcom @homeruntech @prontopro\r\n |  Speaker \r\n@CodeFiction\r\n, http:\u002F\u002Fcodefiction.tech | Developer, gamer, blogger, maiden iron fan","2026-11-13 00:23:18",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add Blind-Striker\u002Fagent-skills-and-plugins --skill deniz-dotnet-general.api-design",{"tool":39,"command":40},"bunx","bunx skills add Blind-Striker\u002Fagent-skills-and-plugins --skill deniz-dotnet-general.api-design",{"tool":42,"command":43},"pnpm","pnpm dlx skills add Blind-Striker\u002Fagent-skills-and-plugins --skill deniz-dotnet-general.api-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fopencode\u002Fdeniz-dotnet-general\u002Fskills\u002Fdeniz-dotnet-general.api-design\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M79YGWBJ52PHMSTKJ3RJ3AWR","writing-tunit-tests","Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.","https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fskills\u002Fdeniz-dotnet-general\u002Fwriting-tunit-tests\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M79YGR3Y9RCRS6TD71D0KKP8","dotnet-walls","Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.","https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fskills\u002Fdeniz-dotnet-general\u002Fdotnet-walls\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M79YGFNJBST7D803NQW3SBYM","csharp-15","Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`\u002F`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15\u002Fpreview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`\u002Fflag loop exits or capacity\u002Fcomparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121\u002FCS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.","https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fskills\u002Fdeniz-dotnet-general\u002Fcsharp-15\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M79YGAV031473HSX6FN87ENH","verified-waves","Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.","https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fskills\u002Fdeniz-coordination\u002Fverified-waves\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M79YG6QXNND4WRPP3GATSY8J","harness","The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.","https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fskills\u002Fdeniz-coordination\u002Fharness\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M79YG2P5S91SDTA5912XJ4FV","delegating-to-worker-models","Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.","https:\u002F\u002Fgithub.com\u002FBlind-Striker\u002Fagent-skills-and-plugins\u002Fblob\u002Fmaster\u002Fskills\u002Fdeniz-coordination\u002Fdelegating-to-worker-models\u002FSKILL.md",[],[]]