Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (86 loc) · 3.01 KB

CONTRIBUTING.md

File metadata and controls

118 lines (86 loc) · 3.01 KB
Raw

Contributing to Codexkit

Thank you for your interest in improving Codexkit! This guide covers the process for contributing.

Getting Started

  1. Fork the repository
  2. Clone your fork locally
  3. Create a feature branch (git checkout -b feature/your-feature)
  4. Make your changes
  5. Test your changes
  6. Commit with a descriptive message
  7. Push to your fork
  8. Open a Pull Request

Development Setup

git clone https://github.com/QuangThai/codexkit.git
cd codexkit

No build step required — Codexkit is a configuration framework, not compiled software.

Conventions

File Naming

  • Kebab-case for files and directories: my-skill, my-prompt.md
  • Skill directories: .codex/skills/<skill-name>/SKILL.md
  • Prompt files: .codex/prompts/<name>.md
  • Agent definitions: .codex/agents/<role>.toml
  • Hook scripts: .codex/hooks/<event>.sh

Commit Messages

Use conventional commit format:

type(scope): description

- detail 1
- detail 2

Types: feat, fix, docs, test, refactor, chore

Code Style

  • Shell scripts: set -euo pipefail, POSIX-compatible where possible
  • Markdown: ATX headers (#), one sentence per line for diffs
  • TOML: Standard formatting, comments for non-obvious values
  • YAML frontmatter: Required for skills (name, description)

Testing

Run the full test suite before submitting:

# Smoke tests
bash tests/smoke/test_structure.sh
bash tests/smoke/test_scripts.sh

# Integration tests
bash tests/integration/test_profiles.sh
bash tests/integration/test_skills.sh
bash tests/integration/test_prompts.sh
bash tests/integration/test_hooks.sh
bash tests/integration/test_install.sh

# Validation
bash install/validate.sh

All tests must pass with zero failures.

Adding a New Skill

  1. Create directory: .codex/skills/your-skill/
  2. Create SKILL.md with YAML frontmatter: 
    ---
name: your-skill
description: When and how to use this skill
version: 1.0.0
tags: [relevant, tags]
dependencies: []
---
  3. Write skill content with sections: Purpose, When to Use, Workflow, Anti-Patterns
  4. Register in AGENTS.md skills table
  5. Run bash tests/integration/test_skills.sh to verify

Adding a New Prompt

  1. Create file: .codex/prompts/your-prompt.md
  2. Follow phase-based structure (Phase 1, Phase 2, etc.)
  3. Include ## Skills Used and ## Related Commands sections
  4. Reference skills with $skill-name syntax
  5. Run bash tests/integration/test_prompts.sh to verify

Pull Request Guidelines

  • One PR per concern — don't mix features with fixes
  • Run all tests before submitting
  • Follow AGENTS.md conventions for all changes
  • Update documentation if adding new features
  • Update CHANGELOG.md with your changes under [Unreleased]

Reporting Issues

  • Use GitHub Issues
  • Include: expected behavior, actual behavior, steps to reproduce
  • Attach test output if relevant

License

By contributing, you agree that your contributions will be licensed under the MIT License.