Agent skill

kinemotion-development

Apply kinemotion development standards. Use when writing Python code, creating tests, modifying the kinemotion codebase, or reviewing code quality.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/kinemotion-development

SKILL.md

Kinemotion Development Standards

Pre-Commit Checklist

Always run before committing:

bash
uv run ruff check --fix   # Auto-fix linting
uv run ruff format        # Format code
uv run pyright            # Type check (strict)
uv run pytest             # Run all tests

Or combined:

bash
uv run ruff check --fix && uv run ruff format && uv run pyright && uv run pytest

Quality Targets

Metric Target Current
Test coverage ≥ 50% 80.86%
Code duplication < 3% 2.96%
Type errors 0 0
Lint errors 0 0

Check duplication: npx jscpd src/kinemotion

Type Hints

  • Use NDArray[np.float64] for numpy arrays
  • Use TypedDict for metric dictionaries
  • Use Literal for string unions
  • Pyright strict mode enforced
python
from numpy.typing import NDArray
from typing import TypedDict, Literal

QualityPreset = Literal["fast", "balanced", "accurate"]

class CMJMetrics(TypedDict):
    jump_height_cm: float
    flight_time_ms: float

Module Structure

src/kinemotion/
├── cli.py                  # Main CLI entry point
├── api.py                  # Public Python API
├── core/                   # Shared utilities
│   ├── validation.py       # Base validation classes
│   ├── pose.py             # MediaPipe wrapper
│   ├── filtering.py        # Signal processing
│   └── video_io.py         # Video I/O handling
├── cmj/                    # CMJ analysis module
│   ├── cli.py              # CMJ CLI subcommand
│   ├── analysis.py         # Core CMJ algorithm
│   ├── kinematics.py       # Velocity, position calc
│   └── validation_bounds.py # CMJ-specific bounds
└── dropjump/               # Drop jump module
    ├── cli.py              # Drop jump CLI subcommand
    ├── analysis.py         # Core drop jump algorithm
    └── validation_bounds.py # Drop jump bounds

Testing

Structure

Mirror source: tests/core/, tests/cmj/, tests/dropjump/, tests/cli/

Fixtures

Use centralized fixtures from tests/conftest.py:

  • cli_runner: Click test runner
  • minimal_video: Synthetic test video
  • sample_video_path: Path to test fixture

Edge Cases to Test

  • Empty arrays
  • Single frame videos
  • NaN values in landmarks
  • Missing landmarks (occlusion)
  • Zero velocity scenarios
python
@pytest.mark.parametrize("input_data,expected", [
    (np.array([]), None),  # Empty
    (np.array([1.0]), 1.0),  # Single value
    (np.array([np.nan, 1.0, 2.0]), None),  # NaN handling
])
def test_edge_cases(input_data, expected):
    ...

Key Algorithm Differences

Aspect CMJ Drop Jump
Search direction Backward (from peak) Forward
Velocity type Signed (direction matters) Absolute (magnitude)
Key phase Countermovement detection Ground contact
Starting position Floor level Elevated (box)

Common Gotchas

  1. CMJ velocity must be signed - backward search requires knowing direction
  2. Convert NumPy for JSON - use int(), float() before serialization
  3. Handle video rotation - mobile videos have rotation metadata
  4. Read first frame for dimensions - don't trust OpenCV properties

Commit Format

Use Conventional Commits:

<type>(<scope>): <description>

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

Examples:

feat(cmj): add triple extension tracking
fix(dropjump): correct ground contact detection
test(core): add filtering edge case tests

Code Style

  • 88 character line limit (ruff)
  • Use early returns to reduce nesting
  • Extract methods for complexity > 15
  • Prefer composition over inheritance
  • Single Responsibility for all functions

Adding New Analysis Type

  1. Create module directory: src/kinemotion/<type>/
  2. Implement: cli.py, analysis.py, kinematics.py
  3. Add validation bounds in validation_bounds.py
  4. Register CLI in main cli.py
  5. Export in api.py and __init__.py
  6. Add tests mirroring structure
  7. Update CLAUDE.md quick reference

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results