SoulSkill - AISP Skills and Plugins

SoulSkill packages native AISP skill packages as a local skill library plus Codex and Claude Code plugin adapters. It gives agents and developers a self-contained way to discover, inspect, validate, hash, and distribute AISP skills.

Native skill packages: each skill lives in <id>_aisp/ with aisp.aisop.json as the source of truth.
Plugin-ready skills: Codex and Claude Code receive the same AISP package shape with a thin same-folder SKILL.md discovery bridge.
Bundled examples: yijing, stock-analysis, and aisp-creator-evolution.
Local tooling: CLI commands and reference tools for listing, inspecting, validating, README projection checks, and local integrity hashes.
Runtime boundary: SoulSkill is not a runtime. Hard execution requires a conforming AISOP/AISP runtime; generic agents can read the packages best-effort.

Quick Install

Run from the repository root:

python -m soulskill info
python -m soulskill list --json
python -m soulskill validate
python -m soulskill readme

If installed as a Python package:

soulskill info
soulskill list --json
soulskill validate
soulskill inspect --skill-id yijing_aisp

Use python -B for validation and release checks if you want to avoid local __pycache__/ artifacts:

python -B -m soulskill validate

Bundled Skills

Skill	Plugin trigger	Native package	Use for
Yijing Divination	`yijing`	`soulskill/aisp/yijing_aisp/`	Cast and interpret an I Ching hexagram for a user question
Stock Analysis	`stock-analysis`	`soulskill/aisp/stock_analysis_aisp/`	Produce an informational stock analysis report, not investment advice
AISP Creator & Evolution	`aisp-creator-evolution`	`soulskill/aisp/aisp_creator_evolution_aisp/`	Create, evolve, or adapt skills into native AISP packages

Example prompts after installing a plugin adapter:

Use yijing for a Yijing reading.
Use stock-analysis to prepare an informational stock analysis.
Use aisp-creator-evolution to create an AISP skill.

Each skill folder contains SKILL.md for host discovery and aisp.aisop.json for the native AISP contract. The SKILL.md file is generated from the AISP contract and is not the source of truth.

Install as a Codex Plugin

SoulSkill ships a repo-local Codex plugin at codex_plugin/. The marketplace metadata is at .agents/plugins/marketplace.json.

From the SoulSkill repository root:

codex plugin marketplace add .

Current Codex CLI releases expose marketplace management commands (add, upgrade, remove). They do not expose separate codex plugin add, codex plugin list, or codex plugin validate commands, and they do not expose codex plugin marketplace list. For a local path marketplace, re-run codex plugin marketplace add . after repository changes.

The Codex plugin layout is:

codex_plugin/
├── .codex-plugin/plugin.json
└── skills/
    ├── yijing_aisp/
    │   ├── SKILL.md
    │   ├── aisp.aisop.json
    │   └── ...
    ├── stock_analysis_aisp/
    │   ├── SKILL.md
    │   ├── aisp.aisop.json
    │   └── ...
    └── aisp_creator_evolution_aisp/
        ├── SKILL.md
        ├── aisp.aisop.json
        └── ...

Codex plugin ingestion treats every direct child of skills/ as a skill, so plugin-exported AISP packages are self-contained. Root-level shared directories are not copied into codex_plugin/skills/.

Refresh and verify Codex plugin skill copies:

powershell -ExecutionPolicy Bypass -File scripts\sync_codex_plugin.ps1
powershell -ExecutionPolicy Bypass -File scripts\sync_codex_plugin.ps1 -Check

Install as a Claude Code Plugin

SoulSkill ships a Claude Code plugin at claude_code_plugin/. The repository root contains .claude-plugin/marketplace.json, and the plugin manifest lives at claude_code_plugin/.claude-plugin/plugin.json.

For local development, point Claude Code's skills directory at the plugin root:

New-Item -ItemType Junction `
  -Path   "$env:USERPROFILE\.claude\skills\soulskill" `
  -Target "<path-to>\SoulSkill\claude_code_plugin"

Restart Claude Code, then use the skill triggers shown above.

Marketplace-style install, when this repository is available as a marketplace source:

/plugin marketplace add AIXP-Labs/SoulSkill
/plugin install soulskill@aixp

Refresh and verify Claude plugin skill copies:

powershell -ExecutionPolicy Bypass -File scripts\sync_claude_plugin.ps1
powershell -ExecutionPolicy Bypass -File scripts\sync_claude_plugin.ps1 -Check

Skill Package Shape

The canonical package root is soulskill/aisp/:

soulskill/aisp/
├── README.md
├── aisp_list.py
├── aisp_list.json
├── yijing_aisp/
│   ├── README.md
│   ├── SKILL.md
│   ├── aisp.aisop.json
│   └── data/
├── stock_analysis_aisp/
│   ├── README.md
│   ├── SKILL.md
│   ├── aisp.aisop.json
│   ├── data/
│   ├── evals/
│   └── scripts/
└── aisp_creator_evolution_aisp/
    ├── README.md
    ├── README_CN.md
    ├── SKILL.md
    ├── aisp.aisop.json
    ├── aisp_reference_tools/
    ├── aisp_specification/
    ├── aisop_specification/
    ├── schemas/
    ├── scripts/
    └── templates/

There is no generated wrapper inside each skill package. A skill package is the <id>_aisp/ directory itself. aisp_list.json uses protocol-compatible registry paths such as aisp/yijing_aisp/aisp.aisop.json; those paths are relative to the directory above the fixed aisp/ package root.

Skill Mode vs Plugin Mode

Mode	Path	What it provides	Best for
Native AISP package	`soulskill/aisp/<id>_aisp/`	`aisp.aisop.json`, resources, generated README/SKILL projections	Protocol-native packaging and validation
Codex plugin skill	`codex_plugin/skills/<id>_aisp/`	Same-folder `SKILL.md` bridge plus native AISP package	Codex discovery and local plugin workflows
Claude Code plugin skill	`claude_code_plugin/skills/<id>_aisp/`	Same-folder `SKILL.md` bridge plus native AISP package	Claude Code discovery and local plugin workflows
Python CLI library	`python -m soulskill ...`	Discovery, inspection, validation, README checks, hash manifests	Release checks and local package maintenance

In every mode, aisp.aisop.json remains the source of truth. SKILL.md exists to help host tools discover and load the package.

CLI Reference

Command	Purpose
`python -m soulskill info`	Show bundled paths and the trust/runtime boundary
`python -m soulskill list [path]`	Discover AISP skills from the bundled root, a package root, a skill folder, a plugin `skills/` folder, or `aisp.aisop.json`
`python -m soulskill index [path]`	Print `aisp_list.json` from a package root
`python -m soulskill inspect [path] --skill-id <id>`	Show one discovered skill record
`python -m soulskill validate [path]`	Run the bundled AISP reference validator
`python -m soulskill readme [path]`	Check generated per-skill README projection
`python -m soulskill readme [path] --write`	Regenerate generated per-skill README files
`python -m soulskill hash [path]`	Compute local AISP integrity hashes
`python -m soulskill run [path]`	Explain the execution boundary for a package

soulskill run intentionally exits non-zero after printing runtime handoff guidance. SoulSkill does not execute aisop.main by itself.

Useful examples:

python -B -m soulskill list codex_plugin\skills --json
python -B -m soulskill validate claude_code_plugin\skills
python -B -m soulskill readme soulskill\aisp
python -B -m soulskill hash soulskill\aisp\stock_analysis_aisp

Development and Release Checks

Run the full local release gate:

powershell -ExecutionPolicy Bypass -File scripts\release_check.ps1

That check covers:

root AISP registry projection
root and plugin AISP validation
root and plugin generated README.md checks
root and plugin generated SKILL.md checks
Codex plugin marketplace-add smoke test with isolated CODEX_HOME
Claude plugin manifest validation when claude is available
isolated Python package install smoke test
one-skill plugin collection regression test
Markdown links, JSON parsing, build/cache residue checks

After editing soulskill/aisp/, refresh plugin copies:

powershell -ExecutionPolicy Bypass -File scripts\sync_codex_plugin.ps1
powershell -ExecutionPolicy Bypass -File scripts\sync_claude_plugin.ps1

Then verify drift:

powershell -ExecutionPolicy Bypass -File scripts\sync_codex_plugin.ps1 -Check
powershell -ExecutionPolicy Bypass -File scripts\sync_claude_plugin.ps1 -Check

Trust Boundary

SoulSkill is a skill library, plugin bundle, and validation wrapper. It is not a trust root.

A generated README check proves projection consistency, not skill safety.
A local hash proves local integrity, not author identity or provenance.
Static validation proves only the rules implemented by the bundled validator.
Runtime enforcement, signatures, registry provenance, and publication trust require independent runtime or external evidence.
A generic agent can read an AISP package best-effort. Hard sys.* enforcement requires a conforming AISOP/AISP runtime.

Repository Layout

SoulSkill/
├── .agents/plugins/marketplace.json   # Codex marketplace metadata
├── .claude-plugin/                    # Claude marketplace metadata
├── codex_plugin/                      # self-contained Codex plugin
│   └── skills/                        # AISP-backed Codex skill sidecars
├── claude_code_plugin/                # self-contained Claude Code plugin
│   └── skills/                        # AISP-backed Claude skill sidecars
├── soulskill/
│   ├── __main__.py, cli.py, discovery.py, validation.py
│   ├── SKILL.md                       # host-neutral adapter note
│   ├── aisp/                          # native AISP package root
│   ├── aisp_reference_tools/          # bundled AISP reference tools
│   ├── schemas/                       # bundled AISP machine schemas
│   └── aisp_specification/            # bundled AISP specification snapshot
├── scripts/
│   ├── release_check.ps1
│   ├── sync_claude_plugin.ps1
│   └── sync_codex_plugin.ps1
├── README.md
├── README_CN.md
├── ARCHITECTURE.md
├── PRIVACY.md
├── pyproject.toml
├── LICENSE
└── NOTICE

AIXP Labs

SoulSkill is part of the AIXP protocol family and is aligned with Axiom 0: Human Sovereignty and Wellbeing.

Project	Description	Website
HSAW	Human Sovereignty and Wellbeing, the Axiom 0 foundation	hsaw.dev
AIZP	AI Zenith-Zero Protocol for runtime behavioral alignment	aizp.dev
AILP	AI List Protocol for agent discovery and capability advertising	ailp.dev
AIVP	AI Value Protocol for international commerce and crypto asset settlement	aivp.dev
AIRP	AI RMB Protocol for Mainland China commerce and RMB licensed settlement	airp.dev
AIBP	AI Bot Protocol for social communication and trust	aibp.dev
AISOP	AI Standard Operating Protocol for flow program definition	aisop.dev
AISP	AI Skill Protocol for portable AI skill package contracts	aisp.dev
SoulSkill	AISP-native skill package library and plugin distribution (this project)	soulskill.dev
SoulBot	AI agent runtime and orchestration framework	soulbot.dev
SoulACP	Adapter library bridging CLI tools and LLM providers	soulacp.dev

Disclaimer

This software is experimental and provided for research and educational purposes only. It is not a financial, legal, medical, security, or investment advisory system. The bundled stock-analysis skill is informational only and must not be used to place trades or make investment decisions. SoulSkill does not provide external provenance, registry trust, signature verification, or runtime enforcement by itself. Use at your own risk. The authors assume no liability for damages arising from the use of this software. See LICENSE for full Apache-2.0 terms.

License

Align Axiom 0: Human Sovereignty and Wellbeing. Version: SoulSkill V1.0.0. www.soulskill.dev

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

SoulSkill - AISP Skills and Plugins

Quick Install

Bundled Skills

Install as a Codex Plugin

Install as a Claude Code Plugin

Skill Package Shape

Skill Mode vs Plugin Mode

CLI Reference

Development and Release Checks

Trust Boundary

Repository Layout

AIXP Labs

Disclaimer

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
claude_code_plugin		claude_code_plugin
codex_plugin		codex_plugin
scripts		scripts
soulskill		soulskill
.gitattributes		.gitattributes
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
GUIDE_CN.md		GUIDE_CN.md
LICENSE		LICENSE
NOTICE		NOTICE
PRIVACY.md		PRIVACY.md
README.md		README.md
README_CN.md		README_CN.md
pyproject.toml		pyproject.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

SoulSkill - AISP Skills and Plugins

Quick Install

Bundled Skills

Install as a Codex Plugin

Install as a Claude Code Plugin

Skill Package Shape

Skill Mode vs Plugin Mode

CLI Reference

Development and Release Checks

Trust Boundary

Repository Layout

AIXP Labs

Disclaimer

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages