The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
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.jsonpaths. - Validated by
scripts/ci/validate-skills.js. - No provenance file. Use
originin 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.jsonsibling toSKILL.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.jsonsibling toSKILL.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.jsonrequired.
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
- Policy document and provenance schema (this change).
- Add provenance validation to learned-skill write paths (evaluate-session, /learn output) so new learned skills always get
.provenance.json. - Update instinct-cli evolve to write optional provenance when generating evolved skills.
- Add
scripts/validate-provenance.jsto CI for any repo paths that must not contain learned/imported content (if needed). - Document learned/imported roots in CONTRIBUTING.md or user docs so contributors know not to commit them.