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.
- package/ATTRIBUTION.md +10 -0
- package/LICENSE +7 -0
- package/README.md +180 -2
- package/SKILL.md +447 -0
- package/VERSION +1 -0
- package/package.json +78 -4
- package/references/00-primer-map-and-attribution.md +29 -0
- package/references/01-requirements-and-capacity.md +107 -0
- package/references/02-architecture-and-networking.md +94 -0
- package/references/03-data-and-storage.md +88 -0
- package/references/04-caching.md +78 -0
- package/references/05-async-and-messaging.md +77 -0
- package/references/06-distributed-systems.md +59 -0
- package/references/07-reliability-and-resilience.md +71 -0
- package/references/08-api-security-observability.md +62 -0
- package/references/09-modern-engineering.md +58 -0
- package/references/10-workflows-and-checklists.md +97 -0
- package/references/11-case-studies.md +74 -0
- package/references/12-ai-systems-architecture.md +139 -0
- package/references/13-architecture-intelligence.md +91 -0
- package/references/14-api-and-data-contracts.md +80 -0
- package/references/15-failure-analysis.md +84 -0
- package/references/16-multi-agent-architecture.md +76 -0
- package/references/17-agent-harness-and-runtime.md +87 -0
- package/references/18-mcp-architecture.md +67 -0
- package/references/19-agent-security-and-permissions.md +74 -0
- package/references/20-agent-state-and-memory.md +72 -0
- package/references/21-agent-evaluation-and-observability.md +90 -0
- package/references/22-kubernetes-and-container-platforms.md +29 -0
- package/references/23-service-mesh-and-traffic-management.md +21 -0
- package/references/24-multi-region-and-disaster-recovery.md +24 -0
- package/references/25-platform-engineering-and-developer-experience.md +26 -0
- package/references/26-finops-and-cloud-cost.md +29 -0
- package/references/27-production-observability-and-slo.md +29 -0
- package/references/28-event-streaming-and-kafka-pulsar.md +27 -0
- package/references/29-event-sourcing-and-cqrs.md +23 -0
- package/references/30-change-data-capture-and-debezium.md +27 -0
- package/references/31-data-lakehouse-and-stream-batch.md +24 -0
- package/references/32-workflow-orchestration-and-temporal.md +24 -0
- package/references/33-schema-registry-and-event-governance.md +22 -0
- package/references/34-postgresql-internals-and-performance.md +43 -0
- package/references/35-mysql-innodb-and-performance.md +27 -0
- package/references/36-sharding-and-distributed-sql.md +22 -0
- package/references/37-consensus-and-distributed-transactions.md +25 -0
- package/references/38-search-architecture-elasticsearch-opensearch.md +24 -0
- package/references/39-vector-databases-and-hybrid-retrieval.md +31 -0
- package/references/40-zero-downtime-database-migrations.md +27 -0
- package/references/41-api-gateway-and-edge-architecture.md +23 -0
- package/references/42-rest-api-design-and-lifecycle.md +23 -0
- package/references/43-graphql-architecture-and-governance.md +16 -0
- package/references/44-grpc-and-service-contracts.md +16 -0
- package/references/45-websocket-sse-and-realtime-systems.md +16 -0
- package/references/46-realtime-collaboration-ot-crdt.md +16 -0
- package/references/47-api-security-rate-limiting-and-abuse.md +16 -0
- package/references/48-oauth-oidc-and-passkeys.md +20 -0
- package/references/49-iam-rbac-abac-rebac.md +16 -0
- package/references/50-zero-trust-and-workload-identity.md +16 -0
- package/references/51-secrets-kms-pki-and-key-management.md +16 -0
- package/references/52-supply-chain-security-sbom-slsa.md +16 -0
- package/references/53-threat-modeling-stride-and-attack-trees.md +16 -0
- package/references/54-privacy-engineering-and-data-governance.md +16 -0
- package/references/55-opentelemetry-and-instrumentation.md +50 -0
- package/references/56-distributed-tracing-and-context-propagation.md +43 -0
- package/references/57-continuous-profiling-and-performance-diagnostics.md +45 -0
- package/references/58-load-stress-soak-testing-and-workload-modeling.md +44 -0
- package/references/59-capacity-planning-and-performance-modeling.md +34 -0
- package/references/60-chaos-engineering-and-resilience-experiments.md +41 -0
- package/references/61-incident-management-and-postmortems.md +34 -0
- package/references/62-dns-and-service-discovery.md +35 -0
- package/references/63-load-balancing-and-global-traffic-management.md +31 -0
- package/references/64-cdn-and-edge-caching.md +34 -0
- package/references/65-cloud-networking-and-connectivity.md +34 -0
- package/references/66-edge-computing-architecture.md +33 -0
- package/references/67-storage-infrastructure-and-storage-systems.md +30 -0
- package/references/68-tcp-quic-and-network-performance.md +27 -0
- package/references/69-task-routing-and-evidence.md +58 -0
- package/scripts/install.ps1 +124 -0
- package/scripts/install.sh +105 -0
- package/scripts/validate.py +376 -0
- package/templates/adr-template.md +32 -0
- package/templates/agent-evaluation-plan-template.md +57 -0
- package/templates/agent-security-review-template.md +46 -0
- package/templates/agent-system-design-template.md +74 -0
- package/templates/api-architecture-design-template.md +33 -0
- package/templates/api-security-and-rate-limit-review-template.md +29 -0
- package/templates/architecture-decision-matrix-template.md +48 -0
- package/templates/architecture-design-template.md +95 -0
- package/templates/architecture-review-scorecard-template.md +36 -0
- package/templates/architecture-review-template.md +52 -0
- package/templates/cdc-data-pipeline-template.md +41 -0
- package/templates/cdn-and-edge-strategy-template.md +36 -0
- package/templates/chaos-experiment-template.md +39 -0
- package/templates/cloud-cost-model-template.md +37 -0
- package/templates/database-architecture-review-template.md +33 -0
- package/templates/edge-computing-readiness-template.md +36 -0
- package/templates/event-sourcing-cqrs-template.md +41 -0
- package/templates/event-streaming-design-template.md +47 -0
- package/templates/failure-analysis-template.md +36 -0
- package/templates/identity-and-access-architecture-template.md +29 -0
- package/templates/incident-postmortem-template.md +39 -0
- package/templates/multi-region-disaster-recovery-template.md +43 -0
- package/templates/network-architecture-design-template.md +38 -0
- package/templates/observability-architecture-template.md +52 -0
- package/templates/performance-test-plan-template.md +52 -0
- package/templates/privacy-data-governance-template.md +24 -0
- package/templates/production-readiness-checklist-template.md +52 -0
- package/templates/realtime-system-design-template.md +28 -0
- package/templates/security-threat-model-template.md +26 -0
- package/templates/sharding-distributed-sql-design-template.md +34 -0
- package/templates/storage-architecture-design-template.md +35 -0
- package/templates/supply-chain-security-review-template.md +20 -0
- 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'
|