Thank you for contributing to Codebase Knowledge Builder. This repository ships
one canonical, content-only Agent Skill plus package and plugin metadata. Keep
behavior in skills/codebase-knowledge-builder/; do not create
platform-specific copies of the skill.
By participating, you agree to follow the Code of Conduct.
Open an issue using the Bug report template. Include:
- What you expected to happen
- What actually happened
- The agent or host you are using
- The installation method and skill revision or package version
- Any error messages or unexpected output
Issues are public. Never post secrets, tokens, private repository URLs, proprietary code, personal data, or unredacted knowledge artifacts. Use a minimal synthetic reproduction or redact sensitive details. Report security vulnerabilities through the private process in SECURITY.md.
Open an issue using the Feature request template. Describe the problem you're solving, not just the solution you want. Context helps.
- Fork the repository and create a branch from
master. - Make one focused change.
- Update the canonical skill, its bundled resources, and affected metadata together when their contract changes.
- Run the validation below.
- Open a pull request and describe the change, evidence, and any validation you could not run.
skills/codebase-knowledge-builder/SKILL.md: canonical skill instructionsskills/codebase-knowledge-builder/references/: material loaded when neededskills/codebase-knowledge-builder/templates/: reusable artifact templates.codex-plugin/,.claude-plugin/, and.agents/plugins/: distribution metadatapackage.json: npm package metadata and the package file allowlist
Do not duplicate the canonical skill for individual agents. Compatibility changes should improve the shared instructions or metadata unless a platform requires a narrowly scoped manifest.
Run these commands from the repository root. They work in PowerShell, Command Prompt, and POSIX-compatible shells when Git, Node.js, and npm are available.
npx --yes markdownlint-cli2@0.23.2 "**/*.md" "!**/.planning/**" "llms.txt"
npx --yes skills@1.5.23 add "." --list
npm pack --dry-run --json --ignore-scripts
git diff --check
The discovery command must find codebase-knowledge-builder. Inspect the npm
dry-run file list and confirm it contains the canonical skill and intended
metadata, but excludes planning files, caches, dependencies, and generated
ClawHub staging files.
When behavior changes, also run the skill against a public or synthetic fixture. Check that the output is source-cited, bounded to the requested scope, and free of secrets or unsupported claims. Do not use a private codebase as public test evidence.
- One concern per PR. Don't bundle unrelated changes.
- Keep
SKILL.mdfocused. Move detailed, selectively loaded guidance toreferences/and link it from the canonical skill. - Preserve the read-only default, scope boundaries, redaction rules, and evidence labels when changing behavior.
- Keep package manifests and their version fields consistent when they change.
- Test behavior changes with at least one public or synthetic codebase before submitting.
- Use direct, platform-neutral instructions.
- Make claims proportional to the available evidence.
- Write human-facing documentation in plain language.
See CODE_OF_CONDUCT.md.