Contributing

This guide explains how to contribute to the Ontopix Claude Code setup — adding plugins, creating skills, and updating documentation.

How This Repository Works

This is a plugin marketplace repository. It contains:

• The ontopix plugin in plugins/ontopix/ — the thin plugin that connects Claude Code to Ontopix patterns via MCP.
• A marketplace manifest in .claude-plugin/marketplace.json — the registry that allows claude plugin install to find the ontopix plugin.
• Documentation in docs/ — the publishable documentation for the claude-setup collection on docs.ontopix.dev.

External plugins (superpowers, sanctum, pensive, etc.) are installed from their own marketplaces and are not part of this repository.

Proposing a New Plugin or Marketplace

If you find a useful Claude Code plugin that should be part of the recommended setup:

1. Open an issue describing the plugin, what it does, and why it is useful for Ontopix engineers.
2. Add the install command to README.md under the appropriate section (Marketplaces, Plugins, or MCP Servers).
3. Test the installation end-to-end:

   claude plugin marketplace add <marketplace>
   claude plugin install <plugin>@<marketplace>
   

4. Update the documentation in docs/ if the plugin adds significant new capabilities.
5. Submit a PR with a clear description of why this addition benefits the team.

Adding a Skill to the Ontopix Plugin

The ontopix plugin supports custom skills. To add one:

1. Scaffold the skill:

   task create:skill PLUGIN=ontopix SKILL=skill-name
   

2. Edit the skill file at plugins/ontopix/skills/<name>/SKILL.md. Write concise instructions that tell Claude what to do when the skill is invoked.
3. Register the skill in plugins/ontopix/.claude-plugin/plugin.json by adding its path to the skills array.
4. Keep skills thin. Skills should instruct Claude to query MCP for live patterns, not embed content. This follows the thin plugin philosophy described in the overview.
5. Test locally:

   task test:plugin PLUGIN=ontopix
   

6. Validate:

   task validate:plugin PLUGIN=ontopix
   

Updating Documentation

The docs/ folder contains publishable documentation for the claude-setup collection on docs.ontopix.dev.

To update documentation:

1. Edit files in docs/. All documentation uses Markdown.
2. Follow the existing structure — see the documentation index for how pages are organized.
3. Maintain cross-references. Use relative paths for links between docs (e.g., [Getting Started](getting-started.md), [superpowers](plugins/superpowers.md)).
4. Test that links resolve. Ensure every relative link points to a file that exists.
5. Submit a PR with a description of what changed and why.

Documentation Structure

docs/
├── index.md                    # Philosophy and overview
├── getting-started.md          # Installation walkthrough
├── available-tools.md          # Quick reference tables
├── contributing.md             # This file
├── plugins/
│   ├── index.md                # Plugin ecosystem overview
│   ├── superpowers.md          # Per-plugin guides
│   ├── sanctum.md
│   └── ...
└── use-cases/
    ├── index.md                # Workflow quick reference
    ├── brainstorming.md        # Per-use-case guides
    ├── specification.md
    └── ...

Testing Changes Locally

Use the Taskfile to validate your changes before submitting a PR:

PR Guidelines

• Keep PRs focused on a single logical change.
• Test locally before submitting.
• Update docs if adding or changing skills, plugins, or MCP servers.
• Follow conventional commits — the PR title becomes the squash commit message on master. Use the format type(scope): description (e.g., feat(plugin): add new skill, docs: update getting started guide). See Ontopix git conventions for details.
• Get approval before merging — at least one review is required.