Repository Guidelines

Project Structure & Module Organization

Use this repository as a conversion-focused toolchain with a small, testable core.

src/ contains the runnable implementation modules.
tests/ contains unit and integration tests for each converter path.
assets/ stores input/output fixtures used by tests and manual verification.
scripts/ contains one-off developer scripts (data migration, bootstrapping, local checks).
docs/ holds reference notes and usage examples.
tooling.toml / pyproject.toml / package.json (if present) are the source of truth for local tooling.

npm run lint (or pnpm lint / yarn lint): format/lint project files before changes.
npm test (or python -m pytest): run automated tests.
npm run build (or python -m build): compile/transpile and package outputs if configured.
npm run dev / local script: start the converter in development mode for manual smoke testing.

Run commands from repository root after installing dependencies.

Use 2-space indentation for JS/TS, 4-space for Python, and keep line length reasonable (100–120 chars).
Use kebab-case for file names (skill-schema-updater.py, convert-task.ts), snake_case for Python variables/functions, and camelCase for JS/TS variables.
Prefer clear action-oriented function names (convert_markdown_to_skill, normalize_skill_entry).
Apply formatter/linter hooks before committing: prettier, eslint, ruff, or equivalent tool configured by the project.

Primary frameworks: project defaults (pytest/vitest/jest as configured).
Tests should validate: normal conversion, edge cases, and failure handling.
Naming convention:
- Python: tests/test_<feature>.py
- JS/TS: *.test.ts or *.spec.ts
Aim for meaningful coverage of converter logic and I/O parsing paths; add regression fixtures when fixing a bug.

Follow the existing project history if present; otherwise use Conventional Commits:
feat:, fix:, refactor:, docs:, chore:.
Keep commits scoped and one logical change per commit.
PRs should include:
- Brief summary and testing evidence (npm test / pytest)
- Linked issue or rationale
- Before/after examples for behavior changes
- Screenshots only when output format/UI output changes.

Never commit credentials, API keys, or raw user artifacts.
Store secrets in local environment variables only.
Add new config defaults conservatively and document any environment variable in docs/.