install-agent-skill 1.0.0

package/specs/ADD_SKILL_SPEC.md

@@ -0,0 +1,333 @@
+# ADD_SKILL_SPEC.md  
+## Enterprise Agent Skill Specification
+
+**Status:** Stable  
+**Version:** 1.0  
+**Applies to:** `@dataguruin/add-skill >= 1.0`  
+**Audience:** Tool authors, skill publishers, platform engineers, AI agents
+
+---
+
+## 1. Purpose & Scope
+
+`@dataguruin/add-skill` defines a **deterministic, secure, and auditable system** for managing **Agent Skills**.
+
+A **Skill** is a **versioned, verifiable intelligence artifact** that extends an agent’s capabilities without executing code or mutating the host environment.
+
+This specification is **normative** and defines:
+
+- Skill format and lifecycle
+- Deterministic installation and locking
+- Security and trust guarantees
+- CLI behavior and invariants
+- Explicitly forbidden practices
+
+Any implementation that violates this specification is considered **non-compliant**.
+
+---
+
+## 2. Terminology
+
+| Term | Definition |
+|---|---|
+| Skill | A folder containing agent instructions and static resources |
+| Publisher | Entity that authors and optionally signs a skill |
+| Skill Source | Git repository + immutable ref |
+| Workspace Scope | `.agent/skills` |
+| Global Scope | `~/.gemini/antigravity/skills` |
+| Lock File | `skill-lock.json`, ensures deterministic environments |
+| Deterministic | Same inputs always produce the same skill environment |
+
+---
+
+## 3. Skill Format (MANDATORY)
+
+### 3.1 Required Files
+
+Every skill **MUST** contain the following files:
+
+```
+
+<skill-name>/
+├─ SKILL.md               # Human- and agent-readable instructions
+├─ .skill-source.json     # Auto-generated metadata (DO NOT EDIT)
+
+```
+
+If any required file is missing:
+
+- `add-skill install` → **FAIL**
+- `add-skill doctor` → **ERROR**
+
+---
+
+### 3.2 Optional Files
+
+```
+
+├─ README.md
+├─ assets/
+├─ examples/
+├─ docs/
+
+````
+
+Optional files **MUST NOT**:
+
+- Execute automatically
+- Mutate the system environment
+- Perform network calls
+- Contain secrets or credentials
+
+All optional content must be **inert by default**.
+
+---
+
+## 4. SKILL.md Rules (NON-NEGOTIABLE)
+
+`SKILL.md`:
+
+- MUST be plain Markdown
+- MUST contain instructions only
+- MUST NOT contain:
+  - secrets or credentials
+  - API keys
+  - executable code
+  - shell commands that mutate the system
+
+**Design Rule:**
+
+> A skill must be safe to read, safe to load, and safe to reason about.
+
+---
+
+## 5. Skill Metadata — `.skill-source.json`
+
+Generated automatically at install time by `add-skill`.
+
+### Schema (v1)
+
+```json
+{
+  "repo": "org/repo",
+  "skill": "skill-name",
+  "ref": "v1.2.3",
+  "checksum": "sha256:…",
+  "publisher": "org",
+  "installedAt": "ISO-8601"
+}
+````
+
+### Rules
+
+* MUST NOT be manually edited
+* `checksum` is a Merkle SHA-256 hash of the entire skill directory
+* Any checksum drift is an **integrity violation**
+
+---
+
+## 6. Skill Lifecycle
+
+### 6.1 Install
+
+```bash
+add-skill install org/repo#skill@ref
+```
+
+**Guarantees:**
+
+* Skill content matches the declared source
+* Checksum is computed and recorded
+* Scope resolution is deterministic
+
+---
+
+### 6.2 Verify
+
+```bash
+add-skill verify
+add-skill verify --strict
+```
+
+**Verification checks:**
+
+* Directory integrity
+* Checksum validity
+* Metadata presence
+
+In `--strict` mode, **any violation results in failure**.
+
+---
+
+### 6.3 Upgrade
+
+```bash
+add-skill upgrade-all
+```
+
+or
+
+```bash
+add-skill install org/repo#skill@new-ref --upgrade
+```
+
+**Rules:**
+
+* Upgrades must be explicit
+* Silent or implicit upgrades are forbidden
+* Lock file must be regenerated after upgrades
+
+---
+
+### 6.4 Lock (Deterministic Environments)
+
+```bash
+add-skill lock
+```
+
+Generates:
+
+```
+.agent/skill-lock.json
+```
+
+**Purpose:**
+
+> Ensure identical skill environments across machines, CI pipelines, and production agents.
+
+---
+
+### 6.5 Locked Install (CI / Production Mode)
+
+```bash
+add-skill install --locked
+```
+
+**Rules:**
+
+* Only skills listed in `skill-lock.json` are allowed
+* Ref overrides are forbidden
+* Any checksum mismatch results in immediate failure
+
+---
+
+## 7. Security Model
+
+### 7.1 Integrity
+
+* Merkle SHA-256 hashing
+* Directory-wide and order-independent
+* Any file modification invalidates the checksum
+
+---
+
+### 7.2 Trust Model
+
+* Skills are verified locally
+* Registries and publishers may provide signatures
+* Trust is **explicit**, never implicit
+
+---
+
+### 7.3 Execution Model
+
+* Skills MUST NOT execute code
+* No scripts are run during install
+* No network calls are allowed during install or verification
+
+---
+
+## 8. add-skill doctor (Audit & Repair)
+
+```bash
+add-skill doctor
+add-skill doctor --fix
+add-skill doctor --strict
+```
+
+**Doctor checks:**
+
+* Missing required files
+* Checksum drift
+* Lock mismatches
+* Orphaned cache entries
+
+**Guarantee:**
+
+> No mutation occurs unless `--fix` is explicitly provided.
+
+---
+
+## 9. CLI Contract (STABILITY GUARANTEE)
+
+The following flags have **guaranteed semantics**:
+
+| Flag        | Meaning                          |
+| ----------- | -------------------------------- |
+| `--verify`  | Read-only integrity verification |
+| `--strict`  | Fail on any violation            |
+| `--locked`  | Enforce deterministic lock       |
+| `--dry-run` | No filesystem changes            |
+| `--fix`     | Apply safe, explicit repairs     |
+
+Breaking changes require:
+
+* Major version bump
+* Specification update
+
+---
+
+## 10. CI/CD Integration (RECOMMENDED)
+
+```yaml
+- name: Install skills
+  run: add-skill install --locked
+
+- name: Verify skills
+  run: add-skill verify --strict
+
+- name: Audit environment
+  run: add-skill doctor --strict
+```
+
+---
+
+## 11. Forbidden Practices (HARD FAIL)
+
+The following practices are explicitly forbidden:
+
+* ❌ Auto-updating skills
+* ❌ Executable scripts inside skills
+* ❌ Mutable skills without checksum update
+* ❌ Network calls during install
+* ❌ Hidden side effects
+* ❌ Silent security bypass
+
+Violation results in failure by design.
+
+---
+
+## 12. Design Philosophy
+
+Skills are **intelligence artifacts**, not scripts.
+Trust must be explicit.
+Reproducibility is mandatory.
+Silence is a bug.
+
+`@dataguruin/add-skill` treats agent skills with the same rigor as binaries, containers, or infrastructure code.
+
+---
+
+## 13. Forward Compatibility
+
+This specification is designed to be compatible with:
+
+* Signed skill registries
+* Organization-level registries
+* Policy enforcement engines
+* Paid and licensed skills
+* Enterprise governance systems
+
+---
+
+**END OF SPEC**

package/specs/REGISTRY_V2_SPEC.md

@@ -0,0 +1,334 @@
+# REGISTRY_V2_SPEC.md  
+## Signed Remote Skill Registry Specification
+
+**Status:** Stable  
+**Version:** 2.0  
+**Applies to:** `@dataguruin/add-skill >= 1.0`  
+**Audience:** Registry operators, platform engineers, security engineers, AI agents
+
+---
+
+## 1. Purpose
+
+Registry v2 defines a **signed, remote, read-only index** for discovering and resolving **Agent Skills**.
+
+The registry provides **metadata only**.  
+It never distributes executables, never installs code, and never mutates environments.
+
+Registry v2 exists to enable:
+
+- Global skill discovery
+- Publisher attribution
+- Version resolution
+- Cryptographic integrity guarantees
+
+---
+
+## 2. Design Principles (NON-NEGOTIABLE)
+
+1. Registry data is **read-only**
+2. Registry index is **cryptographically signed**
+3. Registry is **advisory**, never authoritative
+4. Lock files always override registry data
+5. Registry never executes or distributes code
+6. Verification is mandatory, silence is forbidden
+
+---
+
+## 3. Threat Model
+
+Registry v2 explicitly defends against:
+
+- Registry tampering
+- CDN compromise
+- Man-in-the-middle attacks
+- Skill version substitution
+- Silent metadata modification
+
+Registry v2 does **not** attempt to:
+
+- Protect against compromised publishers
+- Enforce business logic or licensing
+- Execute or sandbox code
+
+---
+
+## 4. Architecture Overview
+
+```
+
+[ Registry Operator ]
+|
+|  (signed index.json)
+v
+[ Static Hosting / CDN ]
+|
+v
+[ add-skill Client ]
+
+````
+
+Characteristics:
+
+- Static file hosting only
+- HTTPS transport
+- Offline-cacheable
+- No authentication required for read access
+
+---
+
+## 5. Registry Index File
+
+### 5.1 File Name
+
+```txt
+index.json
+````
+
+---
+
+### 5.2 Canonical Schema
+
+```json
+{
+  "registryVersion": 2,
+  "generatedAt": "2026-01-23T14:00:00Z",
+  "registryPublisher": "dataguruin",
+  "signature": {
+    "algorithm": "ed25519",
+    "keyId": "dataguruin-registry-v1",
+    "value": "BASE64_SIGNATURE"
+  },
+  "skills": {
+    "coinpika-swipe-tabs": {
+      "repo": "dataguruin/coinpika-skills",
+      "publisher": "dataguruin",
+      "description": "Universal swipe-tab architecture for mobile PWA",
+      "latest": "1.2.3",
+      "versions": {
+        "1.2.3": {
+          "ref": "v1.2.3",
+          "checksum": "sha256:abcd...",
+          "engines": ["antigravity", "gemini"],
+          "tags": ["ui", "mobile", "swipe"]
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 6. Signature Model
+
+### 6.1 Signed Payload
+
+The registry signature covers **all fields except `signature` itself**, including:
+
+* `registryVersion`
+* `generatedAt`
+* `registryPublisher`
+* Entire `skills` object
+
+Any modification to these fields invalidates the signature.
+
+---
+
+### 6.2 Algorithm Requirements
+
+* **Required:** `ed25519`
+* **Encoding:** Base64
+* **Key identification:** `keyId` MUST be globally unique per registry
+
+---
+
+### 6.3 Public Key Trust Store
+
+Registry public keys are stored locally at:
+
+```txt
+~/.add-skill/trusted-registries.json
+```
+
+Example:
+
+```json
+{
+  "dataguruin": {
+    "keys": {
+      "dataguruin-registry-v1": "BASE64_PUBLIC_KEY"
+    }
+  }
+}
+```
+
+Rules:
+
+* Unknown registry → WARN (FAIL in `--strict`)
+* Invalid signature → FAIL (always)
+* Expired or rotated keys MUST be explicitly trusted
+
+---
+
+## 7. Client Resolution Flow
+
+### 7.1 Fetch & Cache
+
+1. Download `index.json`
+2. Verify signature
+3. Cache locally
+4. Use cached copy when offline
+
+Signature verification is mandatory even when using cached data.
+
+---
+
+### 7.2 Install Resolution Order
+
+When installing a skill, the client resolves metadata in the following order:
+
+```
+1. skill-lock.json (--locked mode)
+2. Local registry (registry.json)
+3. Remote registry v2 (signed index)
+4. Explicit org/repo reference
+```
+
+The first successful resolution wins.
+
+---
+
+## 8. Registry Semantics
+
+### 8.1 Registry vs Lock File
+
+| Aspect     | Registry  | Lock File   |
+| ---------- | --------- | ----------- |
+| Purpose    | Discovery | Determinism |
+| Mutability | Mutable   | Immutable   |
+| Authority  | Advisory  | Absolute    |
+| CI Usage   | Optional  | Mandatory   |
+
+Registry data must **never** override lock file constraints.
+
+---
+
+### 8.2 Version Semantics
+
+* Each version entry is immutable
+* Checksum MUST NOT change after publication
+* `latest` is a convenience pointer, not authoritative
+
+---
+
+## 9. Client Commands (Registry-Aware)
+
+### 9.1 Add Registry
+
+```bash
+add-skill registry add https://registry.example.com/index.json
+```
+
+---
+
+### 9.2 List Registries
+
+```bash
+add-skill registry list
+```
+
+---
+
+### 9.3 Search Skills
+
+```bash
+add-skill search <query>
+```
+
+Search includes:
+
+* Skill name
+* Description
+* Tags
+
+---
+
+### 9.4 Skill Information
+
+```bash
+add-skill info <skill-name>
+```
+
+Displays:
+
+* Publisher
+* Repository
+* Available versions
+* Registry source
+* Signature status
+
+---
+
+## 10. Security Guarantees
+
+Registry v2 guarantees:
+
+* Registry tampering is detectable
+* Skill substitution is prevented by checksum verification
+* CDN compromise does not bypass trust
+* Silent metadata modification is impossible
+
+---
+
+## 11. Failure Modes (EXPLICIT)
+
+| Condition           | Client Behavior          |
+| ------------------- | ------------------------ |
+| Invalid signature   | FAIL                     |
+| Unknown registry    | WARN / FAIL (`--strict`) |
+| Network unavailable | Use cached registry      |
+| Skill missing       | FAIL                     |
+| Checksum mismatch   | FAIL                     |
+
+---
+
+## 12. Governance Recommendations
+
+* One registry per publisher identity
+* Separate keys for:
+
+  * Registry signing
+  * Skill signing
+* Key rotation via `keyId`
+* Public audit of registry history
+
+---
+
+## 13. Forward Compatibility
+
+Registry v2 is designed to support future extensions, including:
+
+* Paid skills
+* License metadata
+* Organization namespaces
+* Policy enforcement
+* Audit logs
+* Marketplace integration
+
+Backward compatibility must be preserved.
+
+---
+
+## 14. Design Philosophy
+
+Registry metadata is **signed policy**, not documentation.
+
+Trust must be explicit.
+Verification must be mandatory.
+Distribution must be passive.
+Silence is a bug.
+
+---
+
+**END OF REGISTRY V2 SPEC**