Add Agent Plugins and Codex package adapters

docs/spec/SPEC-004-cli-contract.md

@@ -213,12 +213,14 @@ The JSON form uses `sourceId`, `manifestName`, `sourceFormat`, and `manifestForm
 
 Auto format selection uses this order:
 
-1. Root `plugin.json` with the recognized Agent Plugins 1.0.0 schema.
-2. `.codex-plugin/plugin.json` as a compatibility manifest.
+1. Root `plugin.json` when the file exists.
+2. `.codex-plugin/plugin.json` only when the root file is absent.
 
 An explicit format inspects only that format.
 Netclaw does not combine declarations from multiple manifests.
 A selected invalid manifest fails without a fallback to another manifest.
+For example, a valid portable root wins over a valid Codex manifest.
+A root with malformed JSON fails, even when the Codex manifest is valid.
 
 The portable adapter uses the standard root manifest and fixed `skills/` directory.
 An invalid portable skill is skipped without blocking valid sibling skills.

feeds/skills/.system/files/skill-authoring/SKILL.md

@@ -3,7 +3,7 @@ name: skill-authoring
 description: "How to create, edit, and manage Netclaw skills. Read this when you need to synthesize a new skill from a session, understand the skill file format, or use the skill_manage tool."
 metadata:
   author: netclaw
-  version: "1.9.0"
+  version: "1.11.0"
 ---
 
 # Skill Authoring
@@ -254,3 +254,40 @@ All skills — regardless of origin — are visible in the skill index and
 available to all sessions. The skill index is a compressed file listing
 injected into the system prompt that points the agent directly at SKILL.md
 files on disk for retrieval-led reasoning.
+
+## GitHub Plugin Sources
+
+Netclaw accepts public `github.com` repositories that use supported plugin formats.
+Private repositories need a later credential feature.
+
+Agent Plugins 1.0.0 is the primary format.
+Its root `plugin.json` must use this schema identifier:
+
+`https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`
+
+The portable manifest requires `name`.
+Its optional `version` can use any string.
+Netclaw discovers skills in direct child directories under `skills/`.
+Netclaw skips an invalid portable skill and keeps each valid sibling.
+
+The Codex compatibility format uses `.codex-plugin/plugin.json`.
+Netclaw reads only these Codex manifest fields:
+
+- `name` is required. It uses lowercase letters, numbers, and hyphens.
+- `version` is optional. A present value must use strict SemVer.
+- `skills` is optional. It must contain one relative directory path.
+
+Netclaw always checks `./skills/`. It also checks the `skills` directory from
+the manifest. Each selected skill is a direct child directory with an exact
+`SKILL.md` filename. Netclaw imports the selected skill files and their safe
+resources only.
+
+Netclaw ignores plugin components that can run code or add authority. These
+components include `agents`, `apps`, `commands`, `hooks`, `mcpServers`, and
+`scripts`. Netclaw reports a notice for each ignored component.
+
+Netclaw rejects the complete candidate after an unsafe path, unsafe link, special file, invalid manifest, or scanner rejection.
+The Codex adapter also rejects the candidate after an invalid skill.
+Netclaw keeps the prior accepted package.
+Netclaw records a rejected commit and skips it during normal sync.
+An explicit retry checks that commit again.

src/Netclaw.Configuration/NetclawPaths.cs

@@ -48,8 +48,11 @@ public sealed class NetclawPaths
     public string ManagedGitSkillDirectory(string sourceName)
         => Path.Combine(ManagedGitSkillsDirectory, sourceName);
 
-    public string ManagedGitSkillCommitDirectory(string sourceName, string commit)
-        => Path.Combine(ManagedGitSkillDirectory(sourceName), "commits", commit);
+    public string ManagedGitSkillCommitDirectory(
+        string sourceName,
+        string sourceFingerprint,
+        string commit)
+        => Path.Combine(ManagedGitSkillDirectory(sourceName), sourceFingerprint, "commits", commit);
 
     public string ServerFeedDirectory(string feedName)
         => Path.Combine(ServerFeedsDirectory, feedName);