# cqlib-skill

**Repository Path**: NeoFantom/cqlib-skill

## Basic Information

- **Project Name**: cqlib-skill
- **Description**: Agent skill: a router + reference for cqlib, the QuantumCTek (国盾) quantum-cloud SDK — platform, pulse-level control, IRB, raw IQ, and credit accounting.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cqlib-skill

An agent **skill** that teaches a coding agent the full capability surface of
[`cqlib`](https://gitee.com/cq-lib/cqlib) — the open-source Python SDK for the QuantumCTek /
国盾 quantum cloud — together with the operational discipline for using it safely:
credit accounting, raw-IQ retrieval, and pulse-level programming.

It is built for [Claude Code](https://claude.com/claude-code) skills but is plain Markdown +
Python, so it works with any agent that can read a folder of reference docs.

> **Mirrors.** This repository is published in two places, kept in sync:
> - GitHub — <https://github.com/NeoFantom/cqlib-skill>
> - Gitee — <https://gitee.com/NeoFantom/cqlib-skill>
>
> Use whichever is closer to you. Issues/PRs are accepted on both.

## Why

`cqlib`'s own docs are an API reference; they don't tell an agent *which* capability to reach
for, *when* a call costs money, or *how* to get data the SDK doesn't expose by default. This
skill is a **router**: a short entry point ([`SKILL.md`](./SKILL.md)) that points to
capability-scoped references under [`reference/`](./reference), each grounded in real SDK
signatures cited as `file:line`. The agent reads accurate APIs on demand instead of guessing.

## Install

Drop the repo (as a folder named `cqlib`) into your agent's skills directory. For Claude Code:

```bash
git clone https://github.com/NeoFantom/cqlib-skill .claude/skills/cqlib
# or, on Gitee:
git clone https://gitee.com/NeoFantom/cqlib-skill .claude/skills/cqlib
```

Then provide your platform API token via the `QCTEK_KEY` environment variable. Keep a local
checkout of cqlib itself so the agent can verify signatures against the source.

## Layout

```
.
├── SKILL.md                 # router + hard rules + capability map
├── reference/
│   ├── platform.md          # connect, submit_job, query, download_config, machine list
│   ├── pulse.md             # GetPulse, calibration, custom waveforms, PXY/PZ/PZ0 QCIS
│   ├── circuits.md          # Circuit API, gate set, the QCIS language
│   ├── irb.md               # interleaved randomized benchmarking (1Q/2Q)
│   ├── simulator-viz-mapping.md
│   ├── readout-utils.md     # readout→prob, error correction, QASM↔QCIS
│   ├── iq-data.md           # raw IQ via data_type="EVENT_IQ"
│   └── credits.md           # 机时/积分 accounting — accumulate per task, never poll balance
└── helpers/
    ├── iq_patch.py          # edit-free runtime patch enabling EVENT_IQ + IQ parse/classify
    └── test_iq_patch.py     # offline tests for the parse/classify helpers
```

## Highlights

- **Pulse-level programming** ([`reference/pulse.md`](./reference/pulse.md)): the QCIS pulse
  instructions (`PXY`/`PZ`/`PZ0`), DRAG, the frequency↔Z-amplitude calibration mappers, and
  the waveform types — what you need to author a custom gate rather than reuse a platform
  composite.
- **Raw IQ** ([`reference/iq-data.md`](./reference/iq-data.md) +
  [`helpers/iq_patch.py`](./helpers/iq_patch.py)): an edit-free monkey-patch adding
  `submit_job(..., data_type="EVENT_IQ")` that survives SDK upgrades, plus parsing, centroid,
  and nearest-center classification with the official center-drift discipline.
- **Credit safety** ([`reference/credits.md`](./reference/credits.md)): the balance endpoint
  lags by hours; the only real-time truth is per-task charges keyed by `experimentTaskId`.
  The skill enforces accumulate-as-you-go accounting and confirm-before-spend.

## Tests

The IQ helpers have offline tests (no network, no cqlib needed):

```bash
python helpers/test_iq_patch.py
```

## License

Released under the [MIT License](./LICENSE) © Neo. `cqlib` itself is © China Telecom Quantum
Group / QuantumCTek and licensed under Apache-2.0; this repository is independent
documentation and helper code about that SDK and copies none of its source. No credentials
are included — supply your API token via the `QCTEK_KEY` environment variable.