Keywords: SchoolFit HK, 啱校, 香港學校, 香港升中, 香港中學, 香港小學, 香港幼稚園, 國際學校, 專上教育, OpenClaw skill, ArkAgent skill, Claude Code skill, school selection, admissions, vacancies, Banding, Reach Match Safe, schoolfit.hk.
Use this skill to help families make conservative Hong Kong school decisions across the public SchoolFit HK API. The current service scope covers:
The skill must not read local Edu project databases, Prisma files, snapshots, cookies, .env files, or private API keys.
https://schoolfit.hk/api/... through scripts/schoolfit_api.py./api/agent/chat in v1. It can consume LLM resources and create persistent sessions; it is reserved for a future paid/API-gated version.https://schoolfit.hk/skill-code, generate an authorization code, copy it, and paste it back into the same chat window for the Agent. Do not ask the user to configure a terminal unless they explicitly want CLI usage.https://schoolfit.hk/skill-code. If a marketplace, chat app, or copied link adds query strings, hash fragments, tracking parameters, or any path suffix after /skill-code, strip them before asking the user to open the page.--skill-code or SCHOOLFIT_SKILL_CODE; the helper sends it as X-SchoolFit-Skill-Code.skillhub; use that name only when the user explicitly refers to an unrelated third-party catalog.SKILL.md discovery.Use SKILL.md.
After installation, if no authorization code has been provided yet, say this in the chat window before doing any search:
請先打開 https://schoolfit.hk/skill-code 取得 SchoolFit 授權碼，複製後直接發到這個聊天窗口。我收到後就可以幫你查中學、小學、幼稚園、國際學校和專上教育資料，做比較、推薦和申請計劃。
如果 URL 後面帶有 ?、#、tracking string 或其他路徑，先刪到 https://schoolfit.hk/skill-code 再打開。
When the user pastes a code such as sfhk_..., keep using it for subsequent SchoolFit calls in the current conversation. CLI examples below are for agents and testers, not instructions to give to ordinary users:
python3 <base_dir>/scripts/schoolfit_api.py quick-start --format markdown
python3 <base_dir>/scripts/schoolfit_api.py school-levels --format markdown
python3 <base_dir>/scripts/schoolfit_api.py activate "我的 SchoolFit 授權碼是 sfhk_xxxxxxxxxxxxxxxx" --format markdown
python3 <base_dir>/scripts/schoolfit_api.py metadata --skill-code "PASTE_CODE_FROM_CHAT"
Before calling the API, agents may parse a parent prompt locally:
python3 <base_dir>/scripts/schoolfit_api.py parse-parent-request --q "九龍城 Band 1 女校 英文環境 唔要直資 想穩陣" --format markdown
Resolve fuzzy school names or acronyms before detail/report calls:
python3 <base_dir>/scripts/schoolfit_api.py resolve-school --skill-code "PASTE_CODE" --name "SPCC" --format markdown
Build a parent-friendly shortlist:
python3 <base_dir>/scripts/schoolfit_api.py shortlist-builder --skill-code "PASTE_CODE" --q "沙田 Band 1 英文 男女校，想穩陣，近地鐵" --format markdown
Run local package checks before publishing:
python3 <base_dir>/scripts/schoolfit_api.py self-check --format markdown
Search schools:
python3 <base_dir>/scripts/schoolfit_api.py search-schools --skill-code "PASTE_CODE" --level secondary --q "沙田 Band 1 英文 男女校" --page-size 10 --format markdown
python3 <base_dir>/scripts/schoolfit_api.py search-schools --skill-code "PASTE_CODE" --level primary --q "九龍城 小學 英文環境" --page-size 10 --format markdown
python3 <base_dir>/scripts/schoolfit_api.py advisor-search --skill-code "PASTE_CODE" --level international --q "港島 國際學校 IB A-Level" --format markdown
python3 <base_dir>/scripts/schoolfit_api.py advisor-search --skill-code "PASTE_CODE" --level postsecondary --q "JUPAS HD 副學士 銜接" --format markdown
Smart advisor search for polished model answers:
python3 <base_dir>/scripts/schoolfit_api.py advisor-search \
--skill-code "PASTE_CODE" \
--q "沙田 Band 1 英文 男女校" \
--district "沙田區" \
--banding "Band 1" \
--gender "男女校" \
--medium "英文" \
--application-goal "升中自行分配" \
--priorities "校風" "英文環境" "學額" \
--intent recommend \
--format markdown
Deep compare and next-step planning:
python3 <base_dir>/scripts/schoolfit_api.py deep-compare sha-tin-methodist-college,ying-wa-girls-school --skill-code "PASTE_CODE" --include-detail --format markdown
python3 <base_dir>/scripts/schoolfit_api.py decision-brief st-paul-s-co-educational-college --skill-code "PASTE_CODE" --format markdown
python3 <base_dir>/scripts/schoolfit_api.py school-report st-paul-s-co-educational-college --skill-code "PASTE_CODE" --student-profile-json '{"banding":"Band 1B","district":"沙田區"}' --format markdown
Use application-plan for concrete deadlines and reminders:
python3 <base_dir>/scripts/schoolfit_api.py application-plan \
--school-slugs sha-tin-methodist-college,ying-wa-girls-school \
--student-profile-json '{"banding":"Band 1B","grade":"S1","supportNeeds":["EL"],"district":"沙田區"}' \
--deadline-window-days 45 \
--format markdown
python3 <base_dir>/scripts/schoolfit_api.py marketplace-demo --format markdown
Get one school detail:
python3 <base_dir>/scripts/schoolfit_api.py school-detail st-paul-s-co-educational-college
Compare up to four schools:
python3 <base_dir>/scripts/schoolfit_api.py compare st-paul-s-co-educational-college,ying-wa-girls-school
Recommend a shortlist:
python3 <base_dir>/scripts/schoolfit_api.py recommend \
--district "沙田區" \
--banding "Band 1" \
--gender "男女校" \
--medium "英文" \
--application-goal "升中自行分配" \
--priorities "校風" "英文環境" "學額"
Query EDB vacancy records:
python3 <base_dir>/scripts/schoolfit_api.py vacancies --district "沙田區" --grade S1 --has-vacancy true --format markdown
Query admission notices:
python3 <base_dir>/scripts/schoolfit_api.py admissions --grade S1 --is-active true --q "申請" --format markdown
When presenting results:
資料庫, 地區, Band 參考, 授課語言, 學費上限, and 重視因素; avoid exposing raw internal keys such as level, banding, hasVacancy unless the user is asking for CLI/API usage.advisor-search over raw search-schools. It returns both structured API results and an llmBrief for the calling model to polish.llmBrief.agentHandoff first. It is the stable contract for downstream AI models and contains the response plan, source policy, vacancy policy, hard rules, follow-up policy and formatting expectations.llmBrief as guidance, then write the final answer yourself in natural language. Do not paste raw JSON unless the user asks for raw data.llmBrief.factsOnly=true as binding: polish the wording, but never add school facts that are not present in API output.llmBrief.agentHandoff.officialSiteVerificationPolicy: the calling model may open or fetch only official school or notice URLs returned by the current SchoolFit payload, such as officialUrl, sourceUrl or noticeUrl. Never use search engines, guessed school domains, source-ledger shortcuts, social media, maps or broad web browsing to fill gaps.https://schoolfit.hk/ as the place to continue comparison, school-detail reading, admissions checks, and shortlist refinement.decision-brief or returned decisionBriefApiUrl; keep school-report only as a compatibility alias.--verbose only when the user explicitly needs raw vacancy/admission arrays, full source ledgers, or audit evidence.nameZh, nameEn, district, gender, fundingType, mediumOfInstruction, bandingReference, and annualTuitionHkd when present.sourceLedger and follow explicit source separation between official SchoolFit facts, non-official Band references, school-official admission facts, and vacancy/admissions evidence.Band 參考 or 非官方 Band 參考; never say 官方 Band.display object when present. If no vacancy summary is matched, say 學位狀況更新中; if a summary exists but no open/limited grades are present, say 暫無可跟進學額. Never turn missing data into 沒有學額.暫無可靠資料; do not invent facts.我只處理香港找學校、比較學校、學額、招生、申請計劃和升學路線問題。這個問題不屬於 SchoolFit HK 範圍，所以不會使用 SchoolFit Skill 或大模型 API。rankingRationale is returned, use it to explain why schools were placed higher; do not imply it is an official ranking.首選, 穩陣, or 備選; keep them in 暫不建議 with a clear preference warning.暫不建議 unless the user later relaxes the language preference.robustSearch to run a broad fallback and client-side district/filter merge if SchoolFit API full-text or district filters appear to under-return.Use search-schools when the user asks for schools by district, Band reference, gender, medium, funding type, tuition, religion, or vacancy status. Supported filters include:
--q--level (secondary, primary, kindergarten, international, postsecondary)--district--banding--gender--medium--funding-type--religion--max-tuition--vacancy-grade--vacancy-status--has-vacancyFor district-only or mixed natural-language searches such as 九龍城 Band 1 女校, the helper should parse the district and may run robust fallback search. If robustSearch appears in output, mention it as a data-quality safeguard rather than an extra source.
Use advisor-search when the user asks a broad question like "推薦沙田 Band 1 英文中學", "九龍城有哪些小學", "港島國際學校 IB", "JUPAS/副學士銜接", "幫我揀幾間", "邊幾間適合", or any search request where a polished recommendation-style answer is better than a raw list.
advisor-search first parses natural language conditions locally, then calls SchoolFit HK search and detects intent from user wording unless --intent is provided. The live API may also return parentQuestion plus llmBrief.answerBlueprint; preserve those fields because they encode the current parent-query understanding, evidence order, missing information and response shape.
When intent and signal strength match, it may call:
It returns:
search: compact search results with SchoolFit school URLsintent: detected intent labelcompare: optional compare data for top candidatesschoolDetail: optional single-school detailadmissionAndVacancy: optional vacancy/admissions contextrecommendation: Safe / Match / Reach buckets when availableparentQuestion: detected parent signals, answer strategy and confidencenextActions: concrete parent next stepsllmBrief: a model-facing brief for polishing the final answerllmBrief.agentHandoff: stable downstream-AI contract for response plan, source limits, privacy boundaries and final-answer formatsourceLedger: source hierarchy and caveat map for every responseThe final response should read like a human advisor answer: 3-6 prioritized schools, one reason each, SchoolFit HK links, caveats, and next steps.
Use shortlist-builder when the user asks for "首選/穩陣/備選", "幫我排一排", "shortlist", or wants a practical family list. It groups returned schools into 首選, 穩陣, 備選, and 暫不建議. It considers district/nearby district, English-environment preference, Band reference and DSS preference. These are decision-support buckets, not admissions predictions.
Use school-detail when the user names one school or provides a SchoolFit slug. If the user only gives a Chinese or English name, search first, then call detail on the best slug.
Use resolve-school when the user gives a fuzzy school name, acronym, English shorthand, or Chinese partial name. Common aliases such as SPCC, DGS, DBS, HYS, LSC, WYHK, WYK, SJC, MCS, SMCC, YWGS and YWC should be expanded before API search. Return candidates and ask for confirmation if the match is ambiguous.
Use compare when the user asks A vs B, 比較, 對比, or wants a shortlist decision. Compare at most four schools in one call.
Use deep-compare for two-to-four school in-depth comparisons. It includes SchoolFit comparison output and next action suggestions.
Prefer decision-brief for one-school deep checks. It uses the SchoolFit Skill decision-brief API and returns the current compact parent decision brief, admission/vacancy summaries, source ledger and caveats. Use school-report only as a backward-compatible alias for older agent prompts.
Use application-plan to generate a practical application timeline and checklist from selected schools.
Use quick-start when the user has just installed the Skill or asks how to begin. It does not call the SchoolFit API and should be safe before activation.
Use activate when the user pastes a message containing sfhk_.... After successful activation, keep the code only in the current chat context and pass it into future helper calls with --skill-code.
Use school-levels when the user asks what the Skill can cover, or before a broad advisory turn where the school stage is unclear. It does not require activation and returns the five supported databases, current counts, --level values, and example prompts.
Use parse-parent-request before API calls when the user writes a long mixed-language prompt. It extracts school level, region/district, Band reference where applicable, gender, medium, funding type, grade, vacancy/admission intent, DSS preference, risk preference, tuition and priorities without calling the API. It also returns missingInfoQuestions and conversationHints for follow-up turns.
Use self-check before release or marketplace submission. It runs local package checks and does not call the SchoolFit API.
Use recommend when the user gives a student's profile or asks for Safe / Match / Reach options. Include as many known inputs as possible:
district, banding, gender, mediumapplicationGoal, languagePrioritysupportNeeds, acceptsDss, maxTuition, commuteMinutespersonality, priorities, notesUse --no-dss when the parent rejects DSS/direct-subsidy schools. Use --include-decision-brief when the answer should carry current decisionBriefApiUrl pointers for top schools.
Use vacancies for school-place availability, transfer, 插班, S1-S6 vacancy, 學額, or 學位 questions. Always keep the answer conservative.
Use admissions for application forms, deadlines, S1 admission, transfer admission, school notices, or application links.
404: tell the user the school or endpoint was not found; search by name if appropriate.429 or 5xx: report the temporary service issue and retry later; do not expose headers or stack traces.Install examples after GitHub publication:
/skill install clawhub:schoolfit-hk
ark skill install clawhub:schoolfit-hk
/skill install djanngau/schoolfit-hk-skill#skills/schoolfit-hk
ark skill install djanngau/schoolfit-hk-skill#skills/schoolfit-hk
Marketplace summary:
SchoolFit HK helps agents search, compare, and recommend Hong Kong schools across secondary, primary, kindergarten, international, and postsecondary SchoolFit HK public APIs, with conservative source labeling for official facts, Band references where applicable, vacancy data, and admission notices.
共 1 个版本