# 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.