Instructions for AI coding agents (Grok, Cursor, Claude Code, Codex, Copilot and others) working in this repo or using it as a building block. Humans: see README.md.
Org-wide defaults (issue/PR templates, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY) plus the building-block docs: BUILD-WITH-BLOCKS.md, BLOCKS-SCHEMA.md, blocks.schema.json and the workflow that validates every repo's blocks.json.
- Kind: docs, automation · stability:
stable· licence: NOASSERTION - Machine-readable manifest:
blocks.json(schema: BLOCKS-SCHEMA) - How it fits with the other Blockchains repos: Build with Blocks
pip install jsonschemapython3 scripts/validate_blocks.pyTests hit live public networks/APIs (the org rule is no mocks). A failure can be an upstream outage: re-run before changing code.
| Path | What |
|---|---|
docs/BUILD-WITH-BLOCKS.md |
assembly guide + recipes |
docs/BLOCKS-SCHEMA.md |
schema documentation |
docs/blocks.schema.json |
JSON Schema |
docs/STATUS.md |
repo audit |
scripts/validate_blocks.py |
validator |
.github/workflows/validate-blocks.yml |
CI |
ISSUE_TEMPLATE/, *.md |
community health defaults |
- Community files here apply to every repo that does not define its own.
- New schema field: add it to blocks.schema.json + BLOCKS-SCHEMA.md as optional first.
- Validate locally before pushing a blocks.json.
- Make optional schema fields required without updating every repo.
- Commit secrets, keys or
.envfiles. Rungitleaksbefore pushing; CI and the org policy reject leaks.
- docs/blocks.schema.json (file):
https://raw.githubusercontent.com/Blockchains/.github/main/docs/blocks.schema.json - docs/BUILD-WITH-BLOCKS.md (file):
how to assemble projects from Blockchains repos, with 3 verified recipes - scripts/validate_blocks.py (cli):
python3 scripts/validate_blocks.py [--local DIR ...] # validates every repo's blocks.json - validate blocks (github-action):
push, daily, workflow_dispatch
See the README section Use as a building block for a copy-paste example.
- Blockchains/blockchains.github.io: hub aggregates every blocks.json into /blocks.json
- Blockchains/blockchainlab-sdk: example block
- Blockchains/blockchainlab-mcp: example block