Bricks Academy Preview Skill

A local-first Agent Skill repository for querying the Bricks Academy preview documentation.

This repository packages a maintained mirror of the preview docs published at academy-preview.bricksbuilder.io and exposes it as a skill under skills/bricks-academy-preview/.

What This Repository Contains

• A Bricks Academy preview corpus mirrored to local Markdown
• Downloaded local image assets referenced by the docs
• Search and lookup scripts for querying the corpus
• Sync scripts for refreshing the corpus when the preview site changes
• A skill definition compatible with the Agent Skills open specification

Repository Layout

skills/bricks-academy-preview/
├── SKILL.md
├── corpus/
├── index/
├── references/
└── scripts/

Key paths:

• Skill entry: skills/bricks-academy-preview/SKILL.md
• Local corpus: skills/bricks-academy-preview/corpus/bricks-academy-preview/
• Search index: skills/bricks-academy-preview/index/preview_corpus_manifest.csv

Current Corpus Snapshot

• 691 synced documentation pages
• 569 downloaded local images
• 34 external embeds preserved as links

These numbers reflect the current preview snapshot in this repository and may change as the upstream preview site evolves.

Installation

This repository is structured as a skill repository with a nested skills/ directory:

bricks-academy-preview-skill/
└── skills/
    └── bricks-academy-preview/
        └── SKILL.md

When installing manually, copy the inner skills/bricks-academy-preview/ folder to a location your agent scans for skills.

Common locations:

• Project-level: .agents/skills/
• User-level: ~/.agents/skills/

Option 1: Project-Level Installation

Install the skill only for one project:

git clone https://github.com/<your-account>/bricks-academy-preview-skill.git /tmp/bricks-academy-preview-skill
mkdir -p .agents/skills
cp -R /tmp/bricks-academy-preview-skill/skills/bricks-academy-preview .agents/skills/
rm -rf /tmp/bricks-academy-preview-skill

Result:

.agents/skills/
└── bricks-academy-preview/
    └── SKILL.md

Option 2: User-Level Installation

Install the skill globally for your user account:

git clone https://github.com/<your-account>/bricks-academy-preview-skill.git /tmp/bricks-academy-preview-skill
mkdir -p ~/.agents/skills
cp -R /tmp/bricks-academy-preview-skill/skills/bricks-academy-preview ~/.agents/skills/
rm -rf /tmp/bricks-academy-preview-skill

Result:

~/.agents/skills/
└── bricks-academy-preview/
    └── SKILL.md

Verify Installation

Confirm the installed skill folder contains:

• SKILL.md
• scripts/
• references/
• corpus/
• index/

Then ask your agent a Bricks Builder question such as:

• How does Bricks query loop work?
• Look up bricks/query/before_loop
• Find the docs for Theme Styles in Bricks

Triggering the Skill

This skill supports both explicit and implicit invocation.

Explicit Invocation

Use the skill name directly when you want to force the agent to use this skill:

$bricks-academy-preview Find the docs for bricks/query/before_loop and answer briefly.

This is useful when:

• You want deterministic local-doc lookup
• You are testing the skill
• You want to avoid ambiguity with broader web or framework knowledge

Implicit Invocation

Ask a clearly Bricks-specific question in natural language:

In Bricks, what does bricks/query/before_loop do?
Where are Theme Styles configured in Bricks?
What is the Container element used for in Bricks?

The skill is designed so that clearly Bricks-specific queries can trigger local corpus lookup automatically, while unrelated generic topics should not trigger the skill.

Examples:

Usage

Search the corpus:

python3 skills/bricks-academy-preview/scripts/search_corpus.py "query loop"
python3 skills/bricks-academy-preview/scripts/search_corpus.py "bricks/query/before_loop" --kind hook
python3 skills/bricks-academy-preview/scripts/search_corpus.py "theme styles" --section builder --subsection builder/styling --limit 5

Open a document:

python3 skills/bricks-academy-preview/scripts/show_doc.py "new:developer/hooks/actions/action-bricks-query-before_loop"

Refresh the preview corpus:

bash skills/bricks-academy-preview/scripts/run_preview_sync.sh

Notes

• This repository tracks the preview docs, not a final stable Bricks Academy release.
• Structural and content changes are expected upstream.
• The skill is designed to answer from the local corpus first and only fall back to live browsing when needed.

Documentation

• English: README.md
• Traditional Chinese: README.zh-TW.md

License

This repository is licensed under the MIT License. See LICENSE.