mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-03-30 13:43:26 +08:00
105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
# 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.
|