pqblocks-skills
AGENTS.md0 starsChanged 8 days agoApache-2.0View on GitHub
Copy this file into the root of a project (or merge it into an existing AGENTS.md) so coding agents follow these rules when they touch cryptography. 1. Use the documented API only. Before writing code with a PQBlocks package, read its page under https://pqblocks.github.io/packages/ (or call the get_snippet tool of the pqblocks-mcp server). Every quickstart there was executed against the package. Never guess function names. 2. Never hand-roll post-quantum cryptography. Use the packages; they wrap maintained implementations (liboqs, pyca/cryptography). 3.…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,542 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- .cursor/rules/pqblocks.mdcCursor rule
- llms.txtllms.txt
- pqblocksSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Use the documented API only: Before writing code with a PQBlocks package, read its page under https://pqblocks.github.io/packages/ (or call …
- Distinctive: line 11
Never hand-roll post-quantum cryptography: Use the packages; they wrap maintained implementations (liboqs, pyca/cryptography).
- Very specific: line 15
Randomness from the OS only: Never pass a seed argument when generating production keys.
- Distinctive: line 22
Install lines: use the exact install line listed for each package.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- GENERATED by scripts/gen_skills.py from data/catalog.json - do not edit by hand -->AGENTS.md: post-quantum rules for this project
Copy this file into the root of a project (or merge it into an existing AGENTS.md) so coding agents follow these rules when they touch cryptography.
Rules
- Use the documented API only. Before writing code with a PQBlocks package, read its page under https://pqblocks.github.io/packages/ (or call the
get_snippettool of thepqblocks-mcpserver). Every quickstart there was executed against the package. Never guess function names. - Never hand-roll post-quantum cryptography. Use the packages; they wrap maintained implementations (liboqs, pyca/cryptography).
- Hybrid by default during the transition: ML-KEM-768 + X25519 for key establishment, ML-DSA-65 + Ed25519 for signatures. Downgrade to classical-only must be explicit.
- Randomness from the OS only. Never pass a
seedargument when generating production keys; seeds exist for reproducible tests. - Never log or return secret keys or shared secrets (logs, exceptions, HTTP responses,
repr). - Say exactly what is true. PQBlocks packages implement FIPS 203/204/205 and test against official vectors where they exist. They are not FIPS 140-3 / CMVP validated, not externally audited, and pre-1.0. Never call them certified, validated, audited or quantum-proof.
- Quantum-inspired packages are optimisation, not cryptography. Never place them in a security path.
- Install lines: use the exact install line listed for each package; most install from GitHub until their PyPI release is published.
Which package for which task
| Task | Package | Install | Import |
| ML-KEM / ML-DSA / SLH-DSA primitives (keygen, encapsulate, sign) | pqblocks-primitives | pip install pqblocks-primitives | pqblocks_primitives |
| Hybrid ML-KEM-768 + X25519 key establishment, native speed | pqblocks-core | pip install git+https://github.com/PQBlocks/hybrid-sdk | pqblocks_core |
| Sign or verify JWTs / JWS with ML-DSA; encrypt JWE with ML-KEM | pqblocks-jose | pip install pqblocks-jose | pqblocks_jose |
| Encrypt files or byte strings to a post-quantum public key | pqblocks-files | pip install pqblocks-files | pqblocks_files |
| Find RSA / ECC / weak hashes in code or a TLS endpoint; CBOM + SARIF | pqblocks-scan | pip install pqblocks-scan | pqblocks_scan |
| Python crypto data-flow linting; CBOM + SARIF | pqblocks-lint | pip install pqblocks-lint | pqblocks_lint |
| Enrich a CycloneDX CBOM with quantum-safety and CNSA 2.0 tags | pqblocks-cbom | pip install pqblocks-cbom | pqblocks_cbom |
| Crypto-agility readiness score and CI regression gate | pqblocks-agility | pip install pqblocks-agility | pqblocks_agility |
| Policy-as-code: fail CI on forbidden algorithms | pqblocks-policy | pip install pqblocks-policy | pqblocks_policy |
| Audit which JWE / JOSE algorithms a gateway accepts | pqblocks-jwe-audit | pip install pqblocks-jwe-audit | pqblocks_jwe_audit |
| CNSA 2.0 compliance evidence pack | pqblocks-cnsa-evidence | pip install pqblocks-cnsa-evidence | pqblocks_cnsa_evidence |
| Probe a TLS 1.3 endpoint for X25519MLKEM768; hybrid key-schedule checks | pqblocks-tls-interop | pip install pqblocks-tls-interop | pqblocks_tls_interop |
| Binary container for ML-KEM ciphertexts and ML-DSA / SLH-DSA signatures | pqblocks-wire | pip install pqblocks-wire | pqblocks_wire |
| Five-part hybrid JWE wire layout (serialise / parse only, no encryption) | pqblocks-jwe | pip install pqblocks-jwe | pqblocks_jwe |
| ML-KEM certificate signing request with proof of possession | pqblocks-csr-pop | pip install pqblocks-csr-pop | pqblocks_csr_pop |
| Run NIST ACVP vectors against ML-KEM / ML-DSA implementations | pqblocks-acvp | pip install pqblocks-acvp | pqblocks_acvp |
| Reject malformed or wrong-length FIPS 203/204 inputs at a boundary | pqblocks-fips-check | pip install pqblocks-fips-check | pqblocks_fips_check |
| Verify post-quantum X.509 certificate chains in browser or Node.js | pqblocks-browser-pqc-verifier | npm install git+https://github.com/PQBlocks/browser-pqc-verifier | @pqblocks/browser-pqc-verifier |
| Build or convert QUBO / Ising models | pqblocks-qubo | pip install pqblocks-qubo | pqblocks_qubo |
| Solve QUBO / Ising / Max-Cut (Simulated Bifurcation) | pqblocks-bifurcation | pip install pqblocks-bifurcation | pqblocks_bifurcation |
| Simulated annealing / quantum annealing / population annealing / QIEA solvers | pqblocks-anneal-sa, pqblocks-anneal-sqa, pqblocks-population-anneal, pqblocks-qiea | pip install pqblocks-anneal-sa | pqblocks_anneal_sa |
| Benchmark QUBO / Ising solvers (time-to-solution) | pqblocks-qubo-bench | pip install pqblocks-qubo-bench | pqblocks_qubo_bench |
Full catalog for agents: https://pqblocks.github.io/llms.txt (index) and https://pqblocks.github.io/llms-full.txt (with every quickstart).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.