system-design-primer-skill 0.0.0-stage → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/ATTRIBUTION.md +10 -0
  2. package/LICENSE +7 -0
  3. package/README.md +180 -2
  4. package/SKILL.md +447 -0
  5. package/VERSION +1 -0
  6. package/package.json +78 -4
  7. package/references/00-primer-map-and-attribution.md +29 -0
  8. package/references/01-requirements-and-capacity.md +107 -0
  9. package/references/02-architecture-and-networking.md +94 -0
  10. package/references/03-data-and-storage.md +88 -0
  11. package/references/04-caching.md +78 -0
  12. package/references/05-async-and-messaging.md +77 -0
  13. package/references/06-distributed-systems.md +59 -0
  14. package/references/07-reliability-and-resilience.md +71 -0
  15. package/references/08-api-security-observability.md +62 -0
  16. package/references/09-modern-engineering.md +58 -0
  17. package/references/10-workflows-and-checklists.md +97 -0
  18. package/references/11-case-studies.md +74 -0
  19. package/references/12-ai-systems-architecture.md +139 -0
  20. package/references/13-architecture-intelligence.md +91 -0
  21. package/references/14-api-and-data-contracts.md +80 -0
  22. package/references/15-failure-analysis.md +84 -0
  23. package/references/16-multi-agent-architecture.md +76 -0
  24. package/references/17-agent-harness-and-runtime.md +87 -0
  25. package/references/18-mcp-architecture.md +67 -0
  26. package/references/19-agent-security-and-permissions.md +74 -0
  27. package/references/20-agent-state-and-memory.md +72 -0
  28. package/references/21-agent-evaluation-and-observability.md +90 -0
  29. package/references/22-kubernetes-and-container-platforms.md +29 -0
  30. package/references/23-service-mesh-and-traffic-management.md +21 -0
  31. package/references/24-multi-region-and-disaster-recovery.md +24 -0
  32. package/references/25-platform-engineering-and-developer-experience.md +26 -0
  33. package/references/26-finops-and-cloud-cost.md +29 -0
  34. package/references/27-production-observability-and-slo.md +29 -0
  35. package/references/28-event-streaming-and-kafka-pulsar.md +27 -0
  36. package/references/29-event-sourcing-and-cqrs.md +23 -0
  37. package/references/30-change-data-capture-and-debezium.md +27 -0
  38. package/references/31-data-lakehouse-and-stream-batch.md +24 -0
  39. package/references/32-workflow-orchestration-and-temporal.md +24 -0
  40. package/references/33-schema-registry-and-event-governance.md +22 -0
  41. package/references/34-postgresql-internals-and-performance.md +43 -0
  42. package/references/35-mysql-innodb-and-performance.md +27 -0
  43. package/references/36-sharding-and-distributed-sql.md +22 -0
  44. package/references/37-consensus-and-distributed-transactions.md +25 -0
  45. package/references/38-search-architecture-elasticsearch-opensearch.md +24 -0
  46. package/references/39-vector-databases-and-hybrid-retrieval.md +31 -0
  47. package/references/40-zero-downtime-database-migrations.md +27 -0
  48. package/references/41-api-gateway-and-edge-architecture.md +23 -0
  49. package/references/42-rest-api-design-and-lifecycle.md +23 -0
  50. package/references/43-graphql-architecture-and-governance.md +16 -0
  51. package/references/44-grpc-and-service-contracts.md +16 -0
  52. package/references/45-websocket-sse-and-realtime-systems.md +16 -0
  53. package/references/46-realtime-collaboration-ot-crdt.md +16 -0
  54. package/references/47-api-security-rate-limiting-and-abuse.md +16 -0
  55. package/references/48-oauth-oidc-and-passkeys.md +20 -0
  56. package/references/49-iam-rbac-abac-rebac.md +16 -0
  57. package/references/50-zero-trust-and-workload-identity.md +16 -0
  58. package/references/51-secrets-kms-pki-and-key-management.md +16 -0
  59. package/references/52-supply-chain-security-sbom-slsa.md +16 -0
  60. package/references/53-threat-modeling-stride-and-attack-trees.md +16 -0
  61. package/references/54-privacy-engineering-and-data-governance.md +16 -0
  62. package/references/55-opentelemetry-and-instrumentation.md +50 -0
  63. package/references/56-distributed-tracing-and-context-propagation.md +43 -0
  64. package/references/57-continuous-profiling-and-performance-diagnostics.md +45 -0
  65. package/references/58-load-stress-soak-testing-and-workload-modeling.md +44 -0
  66. package/references/59-capacity-planning-and-performance-modeling.md +34 -0
  67. package/references/60-chaos-engineering-and-resilience-experiments.md +41 -0
  68. package/references/61-incident-management-and-postmortems.md +34 -0
  69. package/references/62-dns-and-service-discovery.md +35 -0
  70. package/references/63-load-balancing-and-global-traffic-management.md +31 -0
  71. package/references/64-cdn-and-edge-caching.md +34 -0
  72. package/references/65-cloud-networking-and-connectivity.md +34 -0
  73. package/references/66-edge-computing-architecture.md +33 -0
  74. package/references/67-storage-infrastructure-and-storage-systems.md +30 -0
  75. package/references/68-tcp-quic-and-network-performance.md +27 -0
  76. package/references/69-task-routing-and-evidence.md +58 -0
  77. package/scripts/install.ps1 +124 -0
  78. package/scripts/install.sh +105 -0
  79. package/scripts/validate.py +376 -0
  80. package/templates/adr-template.md +32 -0
  81. package/templates/agent-evaluation-plan-template.md +57 -0
  82. package/templates/agent-security-review-template.md +46 -0
  83. package/templates/agent-system-design-template.md +74 -0
  84. package/templates/api-architecture-design-template.md +33 -0
  85. package/templates/api-security-and-rate-limit-review-template.md +29 -0
  86. package/templates/architecture-decision-matrix-template.md +48 -0
  87. package/templates/architecture-design-template.md +95 -0
  88. package/templates/architecture-review-scorecard-template.md +36 -0
  89. package/templates/architecture-review-template.md +52 -0
  90. package/templates/cdc-data-pipeline-template.md +41 -0
  91. package/templates/cdn-and-edge-strategy-template.md +36 -0
  92. package/templates/chaos-experiment-template.md +39 -0
  93. package/templates/cloud-cost-model-template.md +37 -0
  94. package/templates/database-architecture-review-template.md +33 -0
  95. package/templates/edge-computing-readiness-template.md +36 -0
  96. package/templates/event-sourcing-cqrs-template.md +41 -0
  97. package/templates/event-streaming-design-template.md +47 -0
  98. package/templates/failure-analysis-template.md +36 -0
  99. package/templates/identity-and-access-architecture-template.md +29 -0
  100. package/templates/incident-postmortem-template.md +39 -0
  101. package/templates/multi-region-disaster-recovery-template.md +43 -0
  102. package/templates/network-architecture-design-template.md +38 -0
  103. package/templates/observability-architecture-template.md +52 -0
  104. package/templates/performance-test-plan-template.md +52 -0
  105. package/templates/privacy-data-governance-template.md +24 -0
  106. package/templates/production-readiness-checklist-template.md +52 -0
  107. package/templates/realtime-system-design-template.md +28 -0
  108. package/templates/security-threat-model-template.md +26 -0
  109. package/templates/sharding-distributed-sql-design-template.md +34 -0
  110. package/templates/storage-architecture-design-template.md +35 -0
  111. package/templates/supply-chain-security-review-template.md +20 -0
  112. package/templates/zero-downtime-database-migration-template.md +32 -0
@@ -0,0 +1,27 @@
1
+ # TCP, QUIC, and Network Performance Engineering
2
+
3
+ ## Transport selection
4
+ Understand TCP connection setup, congestion control, retransmission, flow control, head-of-line blocking, keepalive, and connection reuse. Evaluate QUIC/HTTP/3 for connection migration, stream multiplexing, handshake behavior, and deployment compatibility; do not assume it improves every workload.
5
+
6
+ ## Latency budget
7
+ Decompose DNS lookup, connection establishment, TLS handshake, network RTT, congestion/window growth, server queueing, application processing, and response transfer. Separate cold and warm connections, client and server time, and network from application delay.
8
+
9
+ ## Throughput and congestion
10
+ - Estimate bandwidth-delay product (BDP = bandwidth × RTT) to understand in-flight data requirements.
11
+ - Investigate packet loss, retransmissions, congestion window, receive window, pacing, and path MTU.
12
+ - Avoid increasing socket buffers or concurrency without evidence; buffers can increase queueing and memory pressure.
13
+ - Account for NAT, firewalls, proxies, load balancers, and middleboxes that alter idle timeout, connection reuse, or protocol support.
14
+ - Test realistic RTT, loss, jitter, bandwidth constraints, and asymmetric paths.
15
+
16
+ ## Connection management
17
+ Define pool sizing, reuse, idle timeout, keepalive, maximum lifetime, DNS refresh, connection draining, and retry behavior. Avoid synchronized reconnect storms after deploys or network restoration. For streaming and long-lived connections, define heartbeat, backpressure, reconnect jitter, and resume semantics.
18
+
19
+ ## Diagnostics
20
+ Use packet captures, flow logs, socket metrics, retransmission counters, DNS/TLS timing, and distributed traces together. Packet captures can contain sensitive payloads and identifiers; restrict capture scope, access, and retention. eBPF tools can improve visibility but require kernel compatibility, privilege controls, and overhead evaluation.
21
+
22
+ ## Checklist
23
+ - [ ] Transport and protocol behavior are verified for clients and intermediaries.
24
+ - [ ] Cold/warm connection and end-to-end latency are measured separately.
25
+ - [ ] RTT, loss, MTU, retransmissions, and BDP inform tuning.
26
+ - [ ] Pools, keepalive, timeouts, draining, and reconnect jitter are bounded.
27
+ - [ ] Packet and kernel-level diagnostics follow privacy and privilege controls.
@@ -0,0 +1,58 @@
1
+ # Task routing and evidence discipline
2
+
3
+ ## Purpose
4
+
5
+ Use this guide as the first-pass index for selecting knowledge. Route by the user's decision or observed failure, not by attempting to load the entire reference library. Start with one primary reference and add only the adjacent material needed to answer the concrete question.
6
+
7
+ ## Task-to-reference routing
8
+
9
+ | Task signal | Start here | Add when relevant |
10
+ |---|---|---|
11
+ | Requirements, workload, sizing, latency or cost envelope | `01-requirements-and-capacity.md` | `59-capacity-planning-and-performance-modeling.md`, `26-finops-and-cloud-cost.md` |
12
+ | High-level architecture, boundaries, synchronous flows | `02-architecture-and-networking.md` | `13-architecture-intelligence.md`, `14-api-and-data-contracts.md` |
13
+ | Repository architecture review | `13-architecture-intelligence.md` | `15-failure-analysis.md`, then domain-specific references identified from code |
14
+ | Database schema, query, consistency or transaction issue | `03-data-and-storage.md` | Select the matching database, sharding, search, vector, or migration reference |
15
+ | Cache behavior or invalidation | `04-caching.md` | `07-reliability-and-resilience.md`, `64-cdn-and-edge-caching.md` |
16
+ | Queue, event, CDC or workflow issue | `05-async-and-messaging.md` | Select Kafka/Pulsar, CQRS, CDC, workflow orchestration, or schema governance |
17
+ | Reliability, incident, recovery or failover | `07-reliability-and-resilience.md` | `15-failure-analysis.md`, `24-multi-region-and-disaster-recovery.md`, `61-incident-management-and-postmortems.md` |
18
+ | API design, compatibility or real-time transport | `14-api-and-data-contracts.md` | REST, GraphQL, gRPC, WebSocket/SSE, gateway, and API security references |
19
+ | Identity, authorization, threat or privacy | `08-api-security-observability.md` | OAuth/OIDC, IAM, workload identity, secrets, STRIDE, supply chain, and privacy references |
20
+ | AI agents, harness, MCP, memory or evaluation | `12-ai-systems-architecture.md` | Select only the relevant agent, harness, MCP, security, state, or evaluation reference |
21
+ | Kubernetes, platform, network, CDN, storage or edge | `09-modern-engineering.md` | Select the matching infrastructure reference |
22
+ | Performance optimization | `57-continuous-profiling-and-performance-diagnostics.md` | `58-load-stress-soak-testing-and-workload-modeling.md`, `59-capacity-planning-and-performance-modeling.md` |
23
+ | Architecture choice or ADR | `13-architecture-intelligence.md` | Relevant domain reference plus `templates/architecture-decision-matrix-template.md` |
24
+ | Interview practice | `10-workflows-and-checklists.md` | `01-requirements-and-capacity.md`, `11-case-studies.md` |
25
+
26
+ ## Evidence protocol for repository reviews
27
+
28
+ 1. **Declare scope.** List inspected directories, entry points, configuration, tests, deployment files, and known exclusions. State whether the review is static-only.
29
+ 2. **Trace critical paths.** Follow at least one important request or event from entry point through authorization, domain logic, persistence/external calls, and response/event publication.
30
+ 3. **Map dependencies.** Record caller/callee, data ownership, sync/async boundaries, and trust boundaries. Draw only edges supported by inspected code or configuration.
31
+ 4. **Classify evidence.** Use Confirmed for directly observed code/configuration, Likely for a reasoned inference, and Unknown when runtime or repository visibility is insufficient.
32
+ 5. **Prioritize by impact.** Rank data loss/corruption, security exposure, unavailability, and uncontrolled cost above style or speculative scale concerns.
33
+ 6. **Make findings reproducible.** Include file path and symbol/config key, trigger conditions, impact, recommended change, and a validation method.
34
+ 7. **State limitations.** Static inspection does not establish production traffic, deployed topology, live configuration, incident history, or actual performance. Request runtime metrics or traces when those facts affect the conclusion.
35
+
36
+ ## Reference-loading rules
37
+
38
+ - Read the routing index first, then the smallest relevant reference set.
39
+ - Prefer the exact technology or failure-domain reference over loading all adjacent topics.
40
+ - Load templates only when producing that deliverable; do not force a template into a short answer.
41
+ - If a task spans domains, explain why each additional reference is needed.
42
+ - Verify fast-changing vendor and protocol details against current official documentation.
43
+ - Do not treat a reference's presence as evidence that a repository implements the described mechanism.
44
+
45
+ ## Confidence and estimate labels
46
+
47
+ Use these labels consistently:
48
+
49
+ - **Observed:** directly visible in source, configuration, tests, or supplied measurements.
50
+ - **Inferred:** plausible conclusion from observed evidence; state the reasoning and alternatives.
51
+ - **Assumed:** temporary input used to make progress; identify the owner or question that can confirm it.
52
+ - **Unknown:** unavailable from current inspection; name the evidence needed to resolve it.
53
+
54
+ For capacity and cost estimates, show the formula, units, input provenance, and sensitivity range. Never convert an assumed peak factor or average record size into a measured fact.
55
+
56
+ ## Regression cases
57
+
58
+ The machine-readable cases in `evals/system-design-cases.json` cover representative routing and output expectations. They are prompt fixtures for human or model-assisted evaluation, not deterministic proof of answer quality. Evaluate both the selected mode/references and whether the response respects evidence, safety, and scope guardrails.
@@ -0,0 +1,124 @@
1
+ [CmdletBinding()]
2
+ param(
3
+ [ValidateSet('all','dsh','codex','claude','cursor','copilot')]
4
+ [string]$Agent = 'all',
5
+ [ValidateSet('project','user')]
6
+ [string]$Scope = 'project',
7
+ [switch]$Force,
8
+ [switch]$WhatIf
9
+ )
10
+
11
+ $ErrorActionPreference = 'Stop'
12
+ $Name = 'system-design-primer'
13
+ $Source = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
14
+ if (-not (Test-Path -LiteralPath (Join-Path $Source 'SKILL.md') -PathType Leaf)) {
15
+ throw "SKILL.md not found at package root: $Source"
16
+ }
17
+ $Base = (Get-Location).Path
18
+ if ($Scope -eq 'user') { $Base = $HOME }
19
+ $DshRoot = Join-Path $Base '.dsh'
20
+ if ($Scope -eq 'user') {
21
+ if ([string]::IsNullOrWhiteSpace($env:DSH_HOME)) { $DshRoot = Join-Path $HOME '.dsh' }
22
+ else { $DshRoot = $env:DSH_HOME }
23
+ }
24
+
25
+ $Parents = @()
26
+ switch ($Agent + ':' + $Scope) {
27
+ 'all:project' {
28
+ $Parents += (Join-Path $Base '.dsh/skills')
29
+ $Parents += (Join-Path $Base '.agents/skills')
30
+ $Parents += (Join-Path $Base '.claude/skills')
31
+ $Parents += (Join-Path $Base '.github/skills')
32
+ }
33
+ 'all:user' {
34
+ $Parents += (Join-Path $DshRoot 'skills')
35
+ $Parents += (Join-Path $Base '.agents/skills')
36
+ $Parents += (Join-Path $Base '.claude/skills')
37
+ $Parents += (Join-Path $Base '.copilot/skills')
38
+ }
39
+ 'dsh:project' { $Parents += (Join-Path $DshRoot 'skills') }
40
+ 'dsh:user' { $Parents += (Join-Path $DshRoot 'skills') }
41
+ 'codex:project' { $Parents += (Join-Path $Base '.agents/skills') }
42
+ 'codex:user' { $Parents += (Join-Path $Base '.agents/skills') }
43
+ 'claude:project' { $Parents += (Join-Path $Base '.claude/skills') }
44
+ 'claude:user' { $Parents += (Join-Path $Base '.claude/skills') }
45
+ 'cursor:project' { $Parents += (Join-Path $Base '.cursor/skills') }
46
+ 'cursor:user' { $Parents += (Join-Path $Base '.cursor/skills') }
47
+ 'copilot:project' { $Parents += (Join-Path $Base '.github/skills') }
48
+ 'copilot:user' { $Parents += (Join-Path $Base '.copilot/skills') }
49
+ }
50
+
51
+ $Items = @('SKILL.md','references','templates','ATTRIBUTION.md','LICENSE','VERSION')
52
+ $ScriptItems = @('install.sh','install.ps1','validate.py')
53
+ foreach ($Item in $Items) {
54
+ if (-not (Test-Path -LiteralPath (Join-Path $Source $Item))) {
55
+ throw "Required package entry is missing: $Item"
56
+ }
57
+ }
58
+ foreach ($Item in $ScriptItems) {
59
+ if (-not (Test-Path -LiteralPath (Join-Path $Source "scripts/$Item") -PathType Leaf)) {
60
+ throw "Required script is missing: scripts/$Item"
61
+ }
62
+ }
63
+
64
+ # Preflight every destination before changing any of them.
65
+ foreach ($Parent in $Parents) {
66
+ $Destination = Join-Path $Parent $Name
67
+ if ((Test-Path -LiteralPath $Destination) -and -not $Force) {
68
+ throw "Target already exists: $Destination (use -Force to replace it)"
69
+ }
70
+ }
71
+
72
+ foreach ($Parent in $Parents) {
73
+ $Destination = Join-Path $Parent $Name
74
+ if ($WhatIf) {
75
+ Write-Host "Would install $Source -> $Destination"
76
+ continue
77
+ }
78
+
79
+ New-Item -ItemType Directory -Force -Path $Parent | Out-Null
80
+ $Staging = Join-Path $Parent (".$Name.tmp." + [guid]::NewGuid().ToString('N'))
81
+ $Backup = $null
82
+ try {
83
+ New-Item -ItemType Directory -Path $Staging | Out-Null
84
+ foreach ($Item in $Items) {
85
+ Copy-Item -LiteralPath (Join-Path $Source $Item) -Destination $Staging -Recurse -Force
86
+ }
87
+ $ScriptsDestination = Join-Path $Staging "scripts"
88
+ New-Item -ItemType Directory -Force -Path $ScriptsDestination | Out-Null
89
+ foreach ($Item in $ScriptItems) {
90
+ Copy-Item -LiteralPath (Join-Path $Source "scripts/$Item") -Destination $ScriptsDestination -Force
91
+ }
92
+
93
+ if (Test-Path -LiteralPath $Destination) {
94
+ $Backup = Join-Path $Parent (".$Name.backup." + [guid]::NewGuid().ToString('N'))
95
+ Move-Item -LiteralPath $Destination -Destination $Backup
96
+ }
97
+
98
+ try {
99
+ Move-Item -LiteralPath $Staging -Destination $Destination
100
+ $Staging = $null
101
+ }
102
+ catch {
103
+ if ($Backup -and (Test-Path -LiteralPath $Backup) -and -not (Test-Path -LiteralPath $Destination)) {
104
+ Move-Item -LiteralPath $Backup -Destination $Destination
105
+ $Backup = $null
106
+ }
107
+ throw
108
+ }
109
+
110
+ if ($Backup -and (Test-Path -LiteralPath $Backup)) {
111
+ Remove-Item -LiteralPath $Backup -Recurse -Force
112
+ $Backup = $null
113
+ }
114
+ Write-Host "Installed: $Destination"
115
+ }
116
+ finally {
117
+ if ($Staging -and (Test-Path -LiteralPath $Staging)) {
118
+ Remove-Item -LiteralPath $Staging -Recurse -Force
119
+ }
120
+ }
121
+ }
122
+
123
+ if ($WhatIf) { Write-Host 'Dry run complete; no files changed.' }
124
+ else { Write-Host 'Installation complete. Reload the agent if the Skill is not discovered.' }
@@ -0,0 +1,105 @@
1
+ #!/usr/bin/env bash
2
+ set -Eeuo pipefail
3
+ NAME="system-design-primer"
4
+ AGENT="all"
5
+ SCOPE="project"
6
+ DRY_RUN=0
7
+ FORCE=0
8
+ usage() {
9
+ cat <<'EOF'
10
+ Install the system-design-primer Agent Skill.
11
+ Usage: bash scripts/install.sh [--agent all|dsh|codex|claude|cursor|copilot] [--scope project|user] [--dry-run] [--force]
12
+ Targets: all -> .dsh/skills + .agents/skills + .claude/skills + .github/skills (project)
13
+ $DSH_HOME/skills + .agents/skills + .claude/skills + .copilot/skills (user)
14
+ Run from the target project's root for --scope project.
15
+ For user-level DSH installs, DSH_HOME overrides the default $HOME/.dsh root.
16
+ DeepSeek Harness discovers project Skills under .dsh/skills and user Skills under $DSH_HOME/skills.
17
+ Only distributable Skill files are copied; .git, CI, and tests are excluded.
18
+ Existing installs are never replaced unless --force is supplied.
19
+ EOF
20
+ }
21
+ fail() { printf 'ERROR: %s\n' "$*" >&2; exit 1; }
22
+ while (($#)); do
23
+ case "$1" in
24
+ --agent) (($# >= 2)) || fail "--agent requires a value"; AGENT="$2"; shift 2 ;;
25
+ --scope) (($# >= 2)) || fail "--scope requires a value"; SCOPE="$2"; shift 2 ;;
26
+ --dry-run) DRY_RUN=1; shift ;;
27
+ --force) FORCE=1; shift ;;
28
+ -h|--help) usage; exit 0 ;;
29
+ *) usage >&2; fail "unknown argument: $1" ;;
30
+ esac
31
+ done
32
+ case "$AGENT" in all|dsh|codex|claude|cursor|copilot) ;; *) fail "invalid agent: $AGENT" ;; esac
33
+ case "$SCOPE" in project|user) ;; *) fail "invalid scope: $SCOPE" ;; esac
34
+ SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd -P)"
35
+ SOURCE="$(cd -- "$SCRIPT_DIR/.." && pwd -P)"
36
+ [[ -f "$SOURCE/SKILL.md" ]] || fail "SKILL.md not found at package root"
37
+ BASE="$PWD"
38
+ [[ "$SCOPE" == "user" ]] && BASE="$HOME"
39
+ [[ -n "$BASE" && -d "$BASE" ]] || fail "target root does not exist: $BASE"
40
+ DSH_ROOT="$BASE/.dsh"
41
+ if [[ "$SCOPE" == "user" ]]; then
42
+ DSH_ROOT="${DSH_HOME:-$HOME/.dsh}"
43
+ fi
44
+ declare -a PARENTS=()
45
+ case "$AGENT:$SCOPE" in
46
+ all:project) PARENTS=("$BASE/.dsh/skills" "$BASE/.agents/skills" "$BASE/.claude/skills" "$BASE/.github/skills") ;;
47
+ all:user) PARENTS=("$DSH_ROOT/skills" "$BASE/.agents/skills" "$BASE/.claude/skills" "$BASE/.copilot/skills") ;;
48
+ dsh:*) PARENTS=("$DSH_ROOT/skills") ;;
49
+ codex:*) PARENTS=("$BASE/.agents/skills") ;;
50
+ claude:*) PARENTS=("$BASE/.claude/skills") ;;
51
+ cursor:*) PARENTS=("$BASE/.cursor/skills") ;;
52
+ copilot:project) PARENTS=("$BASE/.github/skills") ;;
53
+ copilot:user) PARENTS=("$BASE/.copilot/skills") ;;
54
+ esac
55
+ for parent in "${PARENTS[@]}"; do
56
+ dest="$parent/$NAME"
57
+ if [[ -e "$dest" || -L "$dest" ]] && ((FORCE == 0)); then
58
+ fail "target already exists: $dest (use --force to replace it)"
59
+ fi
60
+ done
61
+ PACKAGE_ITEMS=(SKILL.md references templates ATTRIBUTION.md LICENSE VERSION)
62
+ SCRIPT_ITEMS=(install.sh install.ps1 validate.py)
63
+ for item in "${PACKAGE_ITEMS[@]}"; do
64
+ [[ -e "$SOURCE/$item" ]] || fail "required package entry is missing: $item"
65
+ done
66
+ for item in "${SCRIPT_ITEMS[@]}"; do
67
+ [[ -f "$SOURCE/scripts/$item" ]] || fail "required script is missing: scripts/$item"
68
+ done
69
+ if ((DRY_RUN)); then
70
+ for parent in "${PARENTS[@]}"; do
71
+ printf 'Would install %s -> %s/%s\n' "$SOURCE" "$parent" "$NAME"
72
+ done
73
+ printf 'Dry run complete; no files changed.\n'
74
+ exit 0
75
+ fi
76
+ for parent in "${PARENTS[@]}"; do
77
+ mkdir -p "$parent"
78
+ dest="$parent/$NAME"
79
+ staging="$(mktemp -d "$parent/.$NAME.tmp.XXXXXX")"
80
+ backup=""
81
+ cleanup() {
82
+ [[ -n "${staging:-}" && -d "$staging" ]] && rm -rf -- "$staging"
83
+ if [[ -n "${backup:-}" && -e "$backup" && ! -e "$dest" ]]; then mv -- "$backup" "$dest"; fi
84
+ }
85
+ trap cleanup EXIT
86
+ for item in "${PACKAGE_ITEMS[@]}"; do cp -R -- "$SOURCE/$item" "$staging/"; done
87
+ mkdir -p "$staging/scripts"
88
+ for item in "${SCRIPT_ITEMS[@]}"; do cp -- "$SOURCE/scripts/$item" "$staging/scripts/"; done
89
+ chmod +x "$staging/scripts/"*.sh "$staging/scripts/"*.py 2>/dev/null || true
90
+ if [[ -e "$dest" || -L "$dest" ]]; then
91
+ backup="$parent/.$NAME.backup.$$"
92
+ [[ ! -e "$backup" ]] || fail "backup path already exists: $backup"
93
+ mv -- "$dest" "$backup"
94
+ fi
95
+ if ! mv -- "$staging" "$dest"; then
96
+ [[ -z "$backup" || ! -e "$backup" ]] || mv -- "$backup" "$dest"
97
+ fail "could not move staged Skill into place: $dest"
98
+ fi
99
+ [[ -z "$backup" || ! -e "$backup" ]] || rm -rf -- "$backup"
100
+ staging=""
101
+ backup=""
102
+ trap - EXIT
103
+ printf 'Installed: %s\n' "$dest"
104
+ done
105
+ printf 'Installation complete. Reload the agent if the Skill is not discovered.\n'