diff --git a/AGENTS.md b/AGENTS.md index 8b89a39..1468911 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,7 @@ Work in this repository should focus on: - keeping a lightweight registry of available Skills Do not migrate existing CCPE System content into this repository. +Do not pre-register speculative Skill candidates. Skills should come from real business-system needs or recurring local workflow automation. ## Boundary With CCPE @@ -37,6 +38,7 @@ If an automation Skill becomes a dependency of a CCPE runtime, agent, or committ - Preserve behavior during first migration; refactor only after baseline behavior is captured. - Add tests for transformations, file rewrites, parsing behavior, and safety checks when practical. - Do not write secrets, tokens, machine-specific credentials, or generated cache files into the repository. +- Do not treat business systems such as `video-workbench` as direct consumers of this repository. They should use installed Skills from `.agents/skills`; this repository owns source copies. ## Expected Skill Directory diff --git a/PROJECTS.md b/PROJECTS.md new file mode 100644 index 0000000..c9bb06a --- /dev/null +++ b/PROJECTS.md @@ -0,0 +1,122 @@ +# skills-vault Project Overview + +`skills-vault` is the source vault for automation-oriented Skills in the five-repository working system. + +It owns implementation source for reusable, installable, testable automation Skills. It does not own business workflows, expert agents, CCPE runtimes, or project-specific production records. + +## Position In The Five Repositories + +```text +knowledge-vault = long-term knowledge, discussions, rule discovery +writing-workbench = article projects after a writing project is already established +ccpe-system = agents, runtimes, model cards, protocols, architecture registration +video-workbench = video and multimodal production projects +skills-vault = automation Skill implementation source +``` + +The core boundary is: + +```text +Business systems raise real automation needs. +skills-vault stores reusable automation Skill source. +.agents/skills is the local runtime installation surface. +ccpe-system records architecture dependencies only when needed. +``` + +## Demand Sources + +New Skills should come from real work, not speculative candidate lists. + +There are two valid demand sources. + +### Business System Support + +A business system may reveal a repeated automation need while running a real workflow. + +Examples of business systems: + +- `video-workbench` +- `writing-workbench` +- `knowledge-vault` +- `ccpe-system` + +The business system owns its project workflow, decision records, source materials, and outputs. `skills-vault` only owns a reusable automation Skill if the need becomes stable enough to implement, test, install, and reuse. + +For example, `video-workbench` may need voice generation during production. The installed Skill used by that workflow lives under: + +```text +C:\Users\wangq\.agents\skills +``` + +The source copy, if maintained here, lives under: + +```text +skills-vault\skills\ +``` + +`video-workbench` is a demand source, not a direct submodule or runtime consumer of the development repository. + +### Local Workflow Automation + +A Skill may also come from a recurring local friction point discovered during daily work. + +Example: + +```text +fix-title +``` + +This class of Skill should still satisfy the same gate: clear input, clear output, bounded side effects, and practical verification. + +## What Belongs Here + +Use `skills-vault` for automation Skills that are: + +- repeatable +- bounded +- installable +- testable or manually verifiable +- useful across more than one session or workflow +- focused on execution rather than business judgment + +Typical examples include file transformations, format repair, batch generation, export helpers, validation helpers, and local CLI wrappers. + +## What Does Not Belong Here + +Do not put these in `skills-vault`: + +- deep writing workflows +- article premise or outline judgment +- expert reviewer personas +- CCPE agents, committees, or runtimes +- model cards or model indexes +- speculative Skill candidates without a real workflow source +- project-specific production artifacts + +## Registry Policy + +`registry/skills-index.md` tracks real Skills already managed by this repository. + +Do not use the registry as a speculative backlog. A Skill should be registered only after a real demand has produced concrete Skill source maintained by this repository. + +## Installation Boundary + +This repository is not the runtime install surface. + +```text +Source of truth: C:\Users\wangq\Documents\Codex\skills-vault\skills +Installed runtime: C:\Users\wangq\.agents\skills +Architecture records: C:\Users\wangq\Documents\Codex\ccpe-system +``` + +Business systems should normally use installed Skills from `.agents/skills`, not import directly from this development repository. + +## Working Rule + +When a new automation need appears, first ask: + +```text +Is this a real repeated action from a workflow, or just a possible future idea? +``` + +Only real repeated actions should become Skill work in this repository. diff --git a/README.md b/README.md index c131302..1d74892 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ This repository owns the implementation source for automation Skills: It does not own CCPE agents, committees, runtimes, model cards, or existing CCPE System assets. +See [PROJECTS.md](PROJECTS.md) for the project overview and cross-repository boundaries. + ## Relationship To CCPE System `C:\Users\wangq\Documents\Codex\ccpe-system` remains the system architecture workspace for: @@ -85,6 +87,17 @@ citation-checker report-exporter ``` +## Demand Sources + +New Skills should come from real workflow needs, not speculative candidate lists. + +Valid sources are: + +- business systems such as `video-workbench`, `writing-workbench`, `knowledge-vault`, or `ccpe-system` +- local workflow automation discovered during day-to-day work, such as `fix-title` + +Business systems use installed Skills from `C:\Users\wangq\.agents\skills`. This repository owns the source copy only when the automation has become stable enough to maintain as a reusable Skill. + ## Remote Canonical remote: diff --git a/docs/architecture.md b/docs/architecture.md index 9fb63e9..f7c49a7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,6 +6,13 @@ The repository is intentionally lightweight. It should make Skills easy to find, inspect, test, migrate, and install without turning the repository into an agent framework. +New Skill work should originate from real workflow demand: + +- a business system such as `video-workbench`, `writing-workbench`, `knowledge-vault`, or `ccpe-system` +- recurring local workflow automation discovered during day-to-day work + +Do not use this repository as a speculative backlog of possible Skills. + ## Primary Units ### Skill Source @@ -31,6 +38,8 @@ It should answer: - Are they installed locally? - Do they have any CCPE registration? +The registry tracks real Skills managed by this repository. It should not be used to pre-register candidate Skills that do not yet come from a real workflow. + ### Templates `templates/skill/` contains a baseline structure for migrated or newly created Skills. @@ -65,6 +74,8 @@ C:\Users\wangq\.agents\skills Future sync scripts may copy selected Skill directories from `skills-vault/skills/` into that install directory. +Business systems should normally use installed Skills from `.agents/skills`, not import directly from this development repository. For example, `video-workbench` may raise a need that leads to a Skill source here, but its workflow should call the installed Skill. + ## Design Principle Keep source ownership simple: diff --git a/docs/ccpe-relationship.md b/docs/ccpe-relationship.md index a0807ac..c31f379 100644 --- a/docs/ccpe-relationship.md +++ b/docs/ccpe-relationship.md @@ -49,6 +49,8 @@ Use `ccpe-system` for: CCPE may reference a Skill from this repository, but should not duplicate the Skill source. +Business projects may also create demand for a Skill, but they should not become owners of the Skill source. If a workflow in `video-workbench`, `writing-workbench`, or another project needs a stable automation action, the reusable implementation can live in `skills-vault` and the business project can use the installed copy from `.agents/skills`. + ## When To Register A Skill In CCPE Do not register every small utility. diff --git a/docs/installation.md b/docs/installation.md index 78b8d5c..d0d4112 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -82,7 +82,7 @@ Status: tested, installable, or installed Install Policy: default ``` -Conditional, optional, disabled, candidate, deprecated, and archived Skills are skipped during full installation. +Conditional, optional, disabled, deprecated, and archived Skills are skipped during full installation. ## Updating An Existing Installed Skill diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 8c6b3fa..9b24ec0 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -50,6 +50,8 @@ If the source is CCPE content, do not migrate it. registry/skills-index.md ``` + Register only real migrated or maintained Skill source. Do not use the registry as a backlog for speculative candidates. + 7. If needed, install or sync the Skill into: ```text @@ -63,7 +65,6 @@ If the source is CCPE content, do not migrate it. Use these status values in the registry: ```text -candidate migrated tested installed