feat: define skill placement and provenance policy (#748)

2026-03-30 13:43:26 +08:00 · 2026-03-23 04:09:48 +05:30
parent 09efd68228
commit 4df960c9d5
6 changed files with 148 additions and 6 deletions
--- a/docs/SKILL-PLACEMENT-POLICY.md
+++ b/docs/SKILL-PLACEMENT-POLICY.md
@@ -0,0 +1,104 @@
+# Skill Placement and Provenance Policy
+
+This document defines where generated, imported, and curated skills belong, how they are identified, and what gets shipped.
+
+## Skill Types and Placement
+
+| Type | Root Path | Shipped | Provenance |
+|------|-----------|---------|------------|
+| Curated | `skills/` (repo) | Yes | Not required |
+| Learned | `~/.claude/skills/learned/` | No | Required |
+| Imported | `~/.claude/skills/imported/` | No | Required |
+| Evolved | `~/.claude/homunculus/evolved/skills/` (global) or `projects/<hash>/evolved/skills/` (per-project) | No | Inherits from instinct source |
+
+Curated skills live in the repo under `skills/`. Install manifests reference only curated paths. Generated and imported skills live under the user home directory and are never shipped.
+
+## Curated Skills
+
+Location: `skills/<skill-name>/` with `SKILL.md` at root.
+
+- Included in `manifests/install-modules.json` paths.
+- Validated by `scripts/ci/validate-skills.js`.
+- No provenance file. Use `origin` in SKILL.md frontmatter (ECC, community) for attribution.
+
+## Learned Skills
+
+Location: `~/.claude/skills/learned/<skill-name>/`.
+
+Created by continuous-learning (evaluate-session hook, /learn command). Default path is configurable via `skills/continuous-learning/config.json` → `learned_skills_path`.
+
+- Not in repo. Not shipped.
+- Must have `.provenance.json` sibling to `SKILL.md`.
+- Loaded at runtime when directory exists.
+
+## Imported Skills
+
+Location: `~/.claude/skills/imported/<skill-name>/`.
+
+User-installed skills from external sources (URL, file copy, etc.). No automated importer exists yet; placement is by convention.
+
+- Not in repo. Not shipped.
+- Must have `.provenance.json` sibling to `SKILL.md`.
+
+## Evolved Skills (Continuous Learning v2)
+
+Location: `~/.claude/homunculus/evolved/skills/` (global) or `~/.claude/homunculus/projects/<hash>/evolved/skills/` (per-project).
+
+Generated by instinct-cli evolve from clustered instincts. Separate system from learned/imported.
+
+- Not in repo. Not shipped.
+- Provenance inherited from source instincts; no separate `.provenance.json` required.
+
+## Provenance Metadata
+
+Required for learned and imported skills. File: `.provenance.json` in the skill directory.
+
+Required fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| source | string | Origin (URL, path, or identifier) |
+| created_at | string | ISO 8601 timestamp |
+| confidence | number | 0–1 |
+| author | string | Who or what produced the skill |
+
+Schema: `schemas/provenance.schema.json`. Validation: `scripts/lib/skill-evolution/provenance.js` → `validateProvenance`.
+
+## Validator Behavior
+
+### validate-skills.js
+
+Scope: Curated skills only (`skills/` in repo).
+
+- If `skills/` does not exist: exit 0 (nothing to validate).
+- For each subdirectory: must contain `SKILL.md`, non-empty.
+- Does not touch learned/imported/evolved roots.
+
+### validate-install-manifests.js
+
+Scope: Curated paths only. All `paths` in modules must exist in the repo.
+
+- Generated/imported roots are out of scope. No manifest references them.
+- Missing path → error. No optional-path handling.
+
+### Scripts That Use Generated Roots
+
+`scripts/skills-health.js`, `scripts/lib/skill-evolution/health.js`, session hooks: they probe `~/.claude/skills/learned` and `~/.claude/skills/imported`. Missing directories are treated as empty; no errors.
+
+## Publishable vs Local-Only
+
+| Publishable | Local-Only |
+|-------------|------------|
+| `skills/*` (curated) | `~/.claude/skills/learned/*` |
+| | `~/.claude/skills/imported/*` |
+| | `~/.claude/homunculus/**/evolved/**` |
+
+Only curated skills appear in install manifests and get copied during install.
+
+## Implementation Roadmap
+
+1. Policy document and provenance schema (this change).
+2. Add provenance validation to learned-skill write paths (evaluate-session, /learn output) so new learned skills always get `.provenance.json`.
+3. Update instinct-cli evolve to write optional provenance when generating evolved skills.
+4. Add `scripts/validate-provenance.js` to CI for any repo paths that must not contain learned/imported content (if needed).
+5. Document learned/imported roots in CONTRIBUTING.md or user docs so contributors know not to commit them.