site-knowledge

Athena Plugin Marketplace

Marketplace repository for:

1. Claude Code plugins (plugins/)
2. Athena workflows (workflows/)

Spec

Workflow and manifest contracts are defined in:

• RFC 0001: Long-Running Workflow Definition (Claude Plugin Compatible)
• RFC 0002: Cross-Runtime Workflow And Plugin Packaging

Use this RFC as the source of truth for workflow behavior, lifecycle, and cross-runtime plugin compatibility (skills, tools, and sub-agent/task patterns).

Repository Structure

.
├── .claude-plugin/
│   └── marketplace.json            # Plugin catalog
├── .athena-workflow/
│   └── marketplace.json            # Workflow catalog
├── workflows/
│   └── e2e-test-builder/
│       ├── workflow.json
│       └── system_prompt.md
└── plugins/
    ├── e2e-test-builder/
    ├── md-export/
    └── site-knowledge/

Runtime Artifacts

Each plugin package now generates versioned runtime artifacts during npm pack / npm publish:

• dist/<version>/release.json
• dist/<version>/claude/plugin/
• dist/<version>/codex/plugin/
• dist/<version>/codex/marketplace.json

The generated runtime plugin directories are packaged artifacts, not source mirrors:

• They keep the runtime-specific overlay for the target runtime plus the shared skill source.
• They exclude transient local install state such as node_modules/ and lockfiles.
• They do not retain repo-only build hooks that depend on this repository layout.

Build them locally for one plugin with:

cd plugins/<plugin-name>
npm run build:artifacts

Skill Compatibility And Validation

This repo uses a split skill metadata model so the same skills stay compatible with both Claude and Codex:

• Portable skill core lives in SKILL.md
• Claude-specific invocation metadata lives in agents/claude.yaml
• OpenAI/Codex UI metadata lives in agents/openai.yaml

For the full conventions, see docs/skills-compatibility.md.

Official Vendor Config vs Repo Overlays

Official vendor-aligned configuration lives outside this packaging layer:

• Claude Code officially documents project config in .claude/settings.json and .claude/settings.local.json
• Codex officially documents MCP/client configuration via codex mcp add ... and ~/.codex/config.toml

This repo also defines its own packaging overlays for distributing skills and plugins across runtimes:

• .claude-plugin/plugin.json
• .codex-plugin/plugin.json
• .agents/plugins/marketplace.json
• agents/openai.yaml
• agents/claude.yaml

These repo overlay files are conventions used by this repository. They are not presented here as official vendor-standard file formats.

Local Environment

The repo includes a local Python 3.12 virtualenv at .venv for running the official Agent Skills validator.

Activate it with:

source .venv/bin/activate

Validation Commands

Run the official portable validator across all plugin skills:

scripts/validate-skills-portable.sh

Run the repo-specific compatibility checks:

scripts/validate-skills-repo.sh

Run the lightweight local validator on a single skill:

scripts/quick-validate-skill.sh plugins/e2e-test-builder/skills/write-test-code

Authoring Commands

Create a new repo-compatible skill scaffold:

scripts/init-compatible-skill.py my-skill --path plugins/my-plugin/skills --interface display_name="My Skill" --interface short_description="Describe the skill in the UI" --interface default_prompt="Run my skill." --argument-hint "<arg>"

Generate or update Claude-only overlay metadata for an existing skill:

scripts/generate-claude-yaml.py plugins/my-plugin/skills/my-skill --frontmatter user-invocable=true --frontmatter argument-hint="<arg>"

Metadata Placement

Use these rules when editing or adding skills:

• Put only portable Agent Skills frontmatter in SKILL.md
• Put Claude-only fields like argument-hint and user-invocable in agents/claude.yaml
• Put menu copy like display_name, short_description, and default_prompt in agents/openai.yaml

Source Of Truth And Regeneration

• Treat SKILL.md as the hand-authored source of truth for the skill itself
• scripts/init-compatible-skill.py scaffolds SKILL.md, agents/openai.yaml, and agents/claude.yaml
• scripts/generate-claude-yaml.py regenerates agents/claude.yaml for an existing skill
• agents/claude.yaml should be treated as generated overlay metadata and may be overwritten when regenerated
• agents/openai.yaml is created during scaffolding and may also be replaced if you rerun scaffold or metadata-generation flows for that skill
• If you hand-edit generated metadata files, assume those edits can be lost on regeneration unless you also update the generator inputs or process

Install This Marketplace (Claude Plugin Consumers)