commit ef50a19d897f24b46a4f7cfdfa86f318528dbefd Author: wantsong Date: Sat Jun 13 22:57:33 2026 +0800 chore: initialize skills vault diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0e85895 --- /dev/null +++ b/.gitignore @@ -0,0 +1,36 @@ +# OS/editor +.DS_Store +Thumbs.db +*.swp +*.swo +.vscode/ +.idea/ + +# Python +__pycache__/ +*.py[cod] +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +.venv/ +venv/ + +# Node +node_modules/ +npm-debug.log* +pnpm-debug.log* +yarn-debug.log* + +# Build/cache/output +dist/ +build/ +coverage/ +tmp/ +temp/ +*.log + +# Secrets +.env +.env.* +*.key +*.pem diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8b89a39 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,52 @@ +# Agent Instructions + +This repository is the source vault for automation-oriented Skills. + +## Scope + +Work in this repository should focus on: + +- collecting automation Skill source code +- maintaining `SKILL.md` files +- maintaining scripts, tests, fixtures, and examples +- documenting migration and installation workflows +- keeping a lightweight registry of available Skills + +Do not migrate existing CCPE System content into this repository. + +## Boundary With CCPE + +`skills-vault` owns automation Skill implementation source. + +`ccpe-system` owns: + +- expert agents +- committees +- runtimes +- model cards +- model indexes +- architectural registrations for important Skills + +If an automation Skill becomes a dependency of a CCPE runtime, agent, or committee, create only a lightweight CCPE registration in `ccpe-system`. Do not duplicate this repository's implementation source there. + +## Editing Rules + +- Prefer small, focused changes. +- Keep Skill directories self-contained. +- Use lowercase kebab-case for Skill names and file names. +- 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. + +## Expected Skill Directory + +```text +skills// + SKILL.md + README.md + scripts/ + tests/ + fixtures/ +``` + +Use [templates/skill](templates/skill) for new migrations. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c131302 --- /dev/null +++ b/README.md @@ -0,0 +1,94 @@ +# skills-vault + +`skills-vault` is the source repository for automation-oriented Skills. + +It is used to collect, maintain, test, version, and publish reusable Skill source code that can be installed into local agent runtimes such as: + +```text +C:\Users\wangq\.agents\skills +``` + +## Repository Role + +This repository owns the implementation source for automation Skills: + +- `SKILL.md` +- scripts +- tests +- fixtures +- examples +- install notes +- migration records + +It does not own CCPE agents, committees, runtimes, model cards, or existing CCPE System assets. + +## Relationship To CCPE System + +`C:\Users\wangq\Documents\Codex\ccpe-system` remains the system architecture workspace for: + +- expert agents +- committees +- runtimes +- model cards +- model indexes +- CCPE Skill specifications and architecture registrations + +`skills-vault` is separate. It stores automation Skill source code. + +The current and future migration scope is: + +```text +Only automation Skills outside CCPE System are migrated into this repository. +Existing CCPE content is not migrated into this repository. +``` + +See [docs/ccpe-relationship.md](docs/ccpe-relationship.md) for the boundary. + +## Layout + +```text +skills-vault/ + skills/ + / + SKILL.md + README.md + scripts/ + tests/ + fixtures/ + templates/ + skill/ + docs/ + registry/ + scripts/ +``` + +## Skill Migration Workflow + +1. Identify an automation Skill outside CCPE System. +2. Copy or reconstruct its source under `skills//`. +3. Preserve original behavior first. +4. Add or repair tests where practical. +5. Register it in `registry/skills-index.md`. +6. Optionally install or sync it into `C:\Users\wangq\.agents\skills`. +7. Only create a CCPE registration later if a CCPE agent, runtime, or committee explicitly depends on it. + +See [docs/migration-guide.md](docs/migration-guide.md). + +## Naming + +Use lowercase kebab-case: + +```text +fix-title +markdown-normalizer +citation-checker +report-exporter +``` + +## Remote + +Canonical remote: + +```text +https://git.wantsong.life/wantsong/skills-vault.git +``` diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..9fb63e9 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,76 @@ +# skills-vault Architecture + +## Purpose + +`skills-vault` is a monorepo for automation Skill source code. + +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. + +## Primary Units + +### Skill Source + +Each Skill lives under: + +```text +skills// +``` + +A Skill directory should contain the runnable or installable source for one capability. + +### Registry + +`registry/skills-index.md` is the human-readable index of Skills in this repository. + +It should answer: + +- What Skills exist? +- What do they do? +- Where did they come from? +- What is their migration status? +- Are they installed locally? +- Do they have any CCPE registration? + +### Templates + +`templates/skill/` contains a baseline structure for migrated or newly created Skills. + +Use templates as starting points, not as strict bureaucracy. Small Skills may omit directories they do not need. + +### Scripts + +Top-level `scripts/` is for repository-level helper scripts only, such as future install, sync, validation, or registry tools. + +Skill-specific scripts should stay inside each Skill directory. + +## Non-Goals + +This repository does not: + +- store CCPE agents +- store CCPE committees +- store CCPE runtimes +- store CCPE model cards +- replace `ccpe-system` +- replace `knowledge-vault` +- act as the local installed runtime directory + +## Installation Surface + +The local runtime install surface is separate: + +```text +C:\Users\wangq\.agents\skills +``` + +Future sync scripts may copy selected Skill directories from `skills-vault/skills/` into that install directory. + +## Design Principle + +Keep source ownership simple: + +```text +Implementation source: skills-vault +Runtime install copy: .agents/skills +Architecture registration: ccpe-system, only when needed +``` diff --git a/docs/ccpe-relationship.md b/docs/ccpe-relationship.md new file mode 100644 index 0000000..a0807ac --- /dev/null +++ b/docs/ccpe-relationship.md @@ -0,0 +1,104 @@ +# Relationship Between skills-vault And CCPE System + +## Short Version + +`skills-vault` and `ccpe-system` are complementary, not competing. + +```text +skills-vault = automation Skill implementation source +ccpe-system = agentic system architecture and high-level artifacts +``` + +Existing CCPE content should not be migrated into `skills-vault`. + +Future migrations into `skills-vault` are limited to automation Skills that live outside CCPE System. + +## What Belongs In skills-vault + +Use `skills-vault` for automation-oriented Skills such as: + +- Markdown transformers +- file cleanup tools +- citation checkers +- report exporters +- batch processors +- source splitters +- installable Codex or Claude Code Skills +- scripts and tests that implement repeatable Skill behavior + +These Skills usually have: + +- a `SKILL.md` +- deterministic procedures +- scripts +- tests or fixtures +- clear file-operation boundaries + +## What Belongs In CCPE System + +Use `ccpe-system` for: + +- CCPE-Lite prompt cards +- durable agent specs +- committees +- runtimes +- model cards +- model indexes +- cognitive model assets +- architecture registrations for important Skills + +CCPE may reference a Skill from this repository, but should not duplicate the Skill source. + +## When To Register A Skill In CCPE + +Do not register every small utility. + +Create a lightweight CCPE registration only when a Skill becomes part of a larger agentic system, for example: + +- a CCPE runtime calls the Skill +- a committee depends on the Skill +- an agent spec lists the Skill as a required capability +- the Skill has meaningful authority, safety, or evaluation rules +- the Skill becomes part of a repeatable workflow + +## Example Registration Relationship + +If `fix-title` is migrated into this repository: + +```text +skills-vault/ + skills/ + fix-title/ + SKILL.md + scripts/ + tests/ +``` + +If later needed by CCPE, CCPE may add: + +```text +ccpe-system/ + skills/ + tool/ + fix-title.skill.md +``` + +That CCPE file should record only architecture metadata: + +```text +canonical implementation: skills-vault/skills/fix-title +installed path: C:\Users\wangq\.agents\skills\fix-title +skill type: tool-skill / transformation-skill +used by: ... +authority: ... +validation: ... +``` + +It should not copy implementation source from `skills-vault`. + +## Current Policy + +```text +Do not migrate any existing CCPE content into skills-vault. +Only migrate automation Skills outside CCPE System. +``` diff --git a/docs/install-sync.md b/docs/install-sync.md new file mode 100644 index 0000000..53dab9e --- /dev/null +++ b/docs/install-sync.md @@ -0,0 +1,31 @@ +# Install And Sync Notes + +The source repository and runtime install directory are separate. + +## Source + +```text +C:\Users\wangq\Documents\Codex\skills-vault\skills\ +``` + +## Local Runtime Install Surface + +```text +C:\Users\wangq\.agents\skills\ +``` + +## Current State + +This repository does not yet include an automated sync script. + +For early migrations, install manually or with a narrowly scoped copy command after reviewing the Skill directory. + +Future repository-level scripts may support: + +- listing Skills +- validating Skill structure +- installing selected Skills +- syncing selected Skills to `.agents/skills` +- checking registry consistency + +Do not sync CCPE content into `.agents/skills` through this repository. diff --git a/docs/migration-guide.md b/docs/migration-guide.md new file mode 100644 index 0000000..8c6b3fa --- /dev/null +++ b/docs/migration-guide.md @@ -0,0 +1,89 @@ +# Migration Guide + +This guide is for migrating automation Skills from scattered non-CCPE folders into `skills-vault`. + +## Scope Gate + +Before migrating, confirm: + +- The source is outside `C:\Users\wangq\Documents\Codex\ccpe-system`. +- The artifact is an automation Skill or tool-like Skill. +- The artifact is not a CCPE agent, committee, runtime, model card, or existing CCPE Skill specification. + +If the source is CCPE content, do not migrate it. + +## Migration Steps + +1. Create a target directory: + + ```text + skills// + ``` + +2. Copy or reconstruct the Skill source: + + ```text + SKILL.md + scripts/ + tests/ + fixtures/ + README.md + ``` + +3. Preserve the original behavior first. + +4. Add a short migration note to the Skill README: + + ```text + Original source: + Migration date: + Migration status: + Behavior preserved: + Known gaps: + ``` + +5. Add or repair tests when practical. + +6. Register the Skill in: + + ```text + registry/skills-index.md + ``` + +7. If needed, install or sync the Skill into: + + ```text + C:\Users\wangq\.agents\skills\ + ``` + +8. Commit the migration. + +## Migration Status Values + +Use these status values in the registry: + +```text +candidate +migrated +tested +installed +deprecated +archived +``` + +## First-Pass Rule + +The first migration pass should be conservative: + +- keep the original behavior +- avoid style rewrites +- avoid unnecessary abstraction +- capture tests before refactoring + +Refactor in a later commit after the Skill is stable in the vault. + +## CCPE Registration Rule + +Do not create CCPE registrations during ordinary migration. + +Only register a Skill in CCPE when a CCPE agent, runtime, or committee explicitly depends on it. diff --git a/registry/skills-index.md b/registry/skills-index.md new file mode 100644 index 0000000..0dd57e7 --- /dev/null +++ b/registry/skills-index.md @@ -0,0 +1,27 @@ +# Skills Index + +This registry tracks automation Skills managed by `skills-vault`. + +Current migration policy: + +```text +Only automation Skills outside CCPE System are migrated here. +Existing CCPE content is not migrated here. +``` + +## Skills + +| Skill | Purpose | Source | Status | Installed Path | CCPE Registration | +| --- | --- | --- | --- | --- | --- | +| _none yet_ | | | | | | + +## Status Values + +```text +candidate +migrated +tested +installed +deprecated +archived +``` diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..d8f42c6 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,17 @@ +# Repository Scripts + +This directory is reserved for repository-level helper scripts. + +Examples of future scripts: + +- validate Skill directory structure +- list registered Skills +- install selected Skills to `C:\Users\wangq\.agents\skills` +- sync selected Skills +- check registry consistency + +Skill-specific scripts should live under: + +```text +skills//scripts/ +``` diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..69adfd1 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,16 @@ +# Skills + +Automation Skill source directories live here. + +Expected layout: + +```text +skills// + SKILL.md + README.md + scripts/ + tests/ + fixtures/ +``` + +No CCPE System content should be migrated into this directory. diff --git a/templates/skill/README.md b/templates/skill/README.md new file mode 100644 index 0000000..b1e51ec --- /dev/null +++ b/templates/skill/README.md @@ -0,0 +1,33 @@ +# Skill Name + +## Purpose + +Short description of what this Skill automates. + +## Original Source + +```text +Original source: +Migration date: +Migration status: +Behavior preserved: +Known gaps: +``` + +## Layout + +```text +SKILL.md +README.md +scripts/ +tests/ +fixtures/ +``` + +## Usage + +Describe how to invoke or install this Skill. + +## Tests + +Describe the validation command. diff --git a/templates/skill/SKILL.md b/templates/skill/SKILL.md new file mode 100644 index 0000000..477e004 --- /dev/null +++ b/templates/skill/SKILL.md @@ -0,0 +1,42 @@ +--- +name: skill-name +description: Short trigger-oriented description of when this Skill should be used. +--- + +# Skill Name + +## Purpose + +Describe the automation capability this Skill provides. + +## When To Use + +Use this Skill when: + +- condition one +- condition two + +## Inputs + +Describe expected inputs. + +## Outputs + +Describe expected outputs or file changes. + +## Procedure + +1. Inspect the input. +2. Run the required script or transformation. +3. Verify the output. +4. Report changed files and validation results. + +## Safety + +- State what files the Skill may read or write. +- State what it must not modify. +- State when user approval is required. + +## Validation + +Describe the tests or checks that prove the Skill worked. diff --git a/templates/skill/fixtures/README.md b/templates/skill/fixtures/README.md new file mode 100644 index 0000000..e3583fc --- /dev/null +++ b/templates/skill/fixtures/README.md @@ -0,0 +1,3 @@ +# Fixtures + +Place small test fixtures here. diff --git a/templates/skill/scripts/README.md b/templates/skill/scripts/README.md new file mode 100644 index 0000000..9c05ae9 --- /dev/null +++ b/templates/skill/scripts/README.md @@ -0,0 +1,5 @@ +# Scripts + +Place Skill-specific helper scripts here. + +Keep repository-level scripts in the top-level `scripts/` directory. diff --git a/templates/skill/tests/README.md b/templates/skill/tests/README.md new file mode 100644 index 0000000..333ecbe --- /dev/null +++ b/templates/skill/tests/README.md @@ -0,0 +1,5 @@ +# Tests + +Place tests for this Skill here. + +Prefer small fixtures that capture real migration behavior.