# Agent skills Skills are short instructions, with scripts where they help, that an AI app loads when a task needs them. The MCP skills teach it how to work inside your own Main Team account through an [AI connection](https://hub.main-team.org/api/mcp); the API skills teach a developer’s agent how to call the API directly. ## For an AI connection available at launch These ship with the MCP server, for students, teachers and partners. They are published with the kit when the server goes live. - ### connecting-to-main-team Starting a session: whose account this is, which olympiads it covers, whether the app may change anything, and when to stop and ask. - ### staying-safe-with-main-team The rules an agent follows: read before changing, preview then confirm, never repeat a code or a username, never help with an exam in progress. - ### managing-olympiad-exams-as-a-student Finding exams a student may enter, entering them, changing or withdrawing an entry, and answering a team invitation. - ### paying-olympiad-fees-as-a-student Reading what is owed, checking a discount code and handing over the panel link where the fee is paid. - ### reviewing-results-and-certificates-as-a-student Reading published results and certificates and opening them in the panel. - ### preparing-for-olympiads-as-a-student Study materials, the calendar, announcements and notifications. - ### managing-students-as-a-teacher Working through a class list, registering new students from a spreadsheet with their exams, entering students for exams in confirmed batches, and removing unpaid entries. - ### following-student-results-as-a-teacher Exam sessions, results and certificates for the students on a teacher’s list. - ### running-group-challenges-as-a-teacher Forming groups from a teacher’s own students for an online group challenge, and following their steps. - ### taking-part-in-group-challenges-as-a-student A student’s group challenge: the steps, the files, and the final submission. - ### handling-payments-and-invoices-as-a-teacher Preparing one payment link for several students’ fees, and reading invoices. - ### managing-country-students-as-a-partner Working inside a partner’s scope, full or limited, and following unpaid entries. - ### working-with-teachers-as-a-partner Reading the teachers in scope and the students behind them. ## For a developer using the API These are published with the API itself: signing tokens, reading errors, registering students one at a time or a whole spreadsheet at once, entering them for exams and collecting results. - ### downloading-results-and-certificates-via-api Collects Main Team olympiad results from a partner's own server with the REST API: listing a student's released certificates with listStudentCertificates (GET /v1/{organizationId}/certificate/{userId}) and their result reports with listStudentReports, downloading each as a PDF with downloadCertificate and downloadReport, taking the file name from Content-Disposition, refusing a truncated transfer, understanding why one 404 covers a document that is missing, unreleased, cancelled or somebody else's, and finding new documents after an exam session by polling at a sensible pace because there are no webhooks. Also covers storing and serving the files safely. Use when writing or fixing code that fetches Main Team certificates, reports or result PDFs, schedules a results check after a sitting, or keeps a local copy in step. Needs an API account's apiKey and apiSecret on the machine that makes the calls, never in the conversation, and roles granting certificate/read and report/read on the olympiad in the path. Downloads answer bytes, not JSON, and need somewhere to write files. 4 files, 15 KB - SKILL.md 5.8 KB - references/documents.md 4.2 KB - references/operations.md 1.7 KB - references/polling-results.md 2.9 KB - ### enrolling-students-in-olympiad-exams-via-api Enters Main Team students for olympiad exams from a partner's own server with the REST API: reading the per-student picker listAvailableExams (GET /v1/{organizationId}/exam/available/{studentId}) rather than guessing, creating an entry with createApplication, moving one to another exam or language with moveApplication, withdrawing one with deleteApplication, listing an organization's or a student's entries with their payment state, and the rule that a student must have signed in to an olympiad once before they can be entered there. Explains every 409 the three writes answer, which of them are safe to send twice, what a settled payment freezes, and what cannot be undone. Use when writing or fixing code that applies Main Team students to exams on stem, hilingua, neo, gmath or coding, changes or cancels an entry, or reconciles entries and fees. Needs an API account's apiKey and apiSecret on the machine that makes the calls, never in the conversation, and roles granting exam/read and application/create, application/update or application/delete on the olympiad in the path. Works against api.main-team.org or apisnd.main-team.org. 5 files, 24 KB - SKILL.md 7.3 KB - references/availability.md 4.1 KB - references/conflicts.md 4.3 KB - references/lifecycle.md 4.8 KB - references/operations.md 3.6 KB - ### following-group-challenges-via-api Follows a partner's own students through Main Team group challenges with the REST API: listing an olympiad's challenges with listGroupChallenges (GET /v1/{organizationId}/group-challenge), reading where each student stands with listGroupChallengeStudents and getGroupChallengeStudent, reading their groups, steps and files with listGroupChallengeGroups and getGroupChallengeGroup and the group's history with listGroupChallengeActivity, and submitting a step or a group's finished work for one of the partner's students with submitGroupChallengeStep and submitGroupChallengeWork. Explains that teachers form groups and members upload in the panel or the app, that only the partner's own students are named, which 409 reasons wait on the members, why a repeat answers changed false, and what a 503 busy means. Use when writing or fixing code that tracks group challenge progress, sends a student to a challenge page, or submits group challenge work for a student. Needs an API account's apiKey and apiSecret on the machine that makes the calls, never in the conversation, and roles granting group-challenge/read, and group-challenge/submit for the submits, on the olympiad in the path. Group challenges answer 404 on an olympiad where they are not switched on. 3 files, 14 KB - SKILL.md 6.2 KB - references/group-challenges.md 3.9 KB - references/operations.md 3.6 KB - ### integrating-main-team-api Builds and debugs server-side integrations with the Main Team API (api.main-team.org/v1): signing HS256 tokens from an apiKey and apiSecret and reusing them, the success and error envelopes, organization ids, pagination, rate limits, retries and idempotency, polling for changes because there are no webhooks, and what to do about 400, 401, 403, 404, 409, 413, 415, 422, 429 and 503. Includes a token signer, a setup doctor and minimal Node.js and PHP clients. Use when writing, reviewing or fixing any code that calls the Main Team API, when a call answers something unexpected, and as the ground floor under the task skills registering-a-main-team-student, registering-main-team-students-from-spreadsheets, enrolling-students-in-olympiad-exams-via-api, downloading-results-and-certificates-via-api and managing-api-access-and-tokens. The scripts need Node.js 18 or newer and no packages, and network access to api.main-team.org or apisnd.main-team.org. The API is called from servers only. 12 files, 68 KB - SKILL.md 7.6 KB - assets/AGENTS.snippet.md 1.6 KB - assets/MainTeamClient.php 5.6 KB - assets/minimal-client.mjs 4.2 KB - references/authentication.md 4.5 KB - references/errors.md 9.2 KB - references/operations.md 12 KB - references/polling.md 3.7 KB - references/rate-limits.md 4.2 KB - references/retries-and-idempotency.md 4.6 KB - scripts/doctor.mjs 6.2 KB - scripts/sign-token.mjs 4.7 KB - ### managing-api-access-and-tokens Manages how a partner's server gets into the Main Team API and how its students get into an olympiad panel: signing an HS256 token from an apiKey and apiSecret with the kid, sub, iat and exp rules, reusing one token per process, reading the account and its roles with getCurrentApiAccount (GET /v1/api-account/validate-me), ending a token early with revokeToken, keeping the secret out of code, chat and logs, what to do when it leaks (it cannot be rotated), and minting single-use 120-second sign-in links with createSigninLink (POST /v1/{organizationId}/auth/signin) that must be redirected to at once and never stored, logged, emailed or prefetched. Use when a call answers 401 or 403, when setting up or handing over credentials, when a token or secret may have leaked, or when building a go-to-my-olympiad button. Needs an API account's apiKey and apiSecret on the machine that signs tokens, never in the conversation. Sign-in links need auth/signin on the olympiad in the path; reading the account needs api/* on mto. Works against api.main-team.org or apisnd.main-team.org. 5 files, 19 KB - SKILL.md 6.2 KB - references/operations.md 1.5 KB - references/rotation.md 3.1 KB - references/signin-links.md 4.2 KB - references/token-rules.md 4.1 KB - ### registering-a-main-team-student Registers one Main Team student at a time with the REST API and keeps the record right: checking a registration with checkStudentRegistration (POST /v1/student/check) before writing, registerStudent (POST /v1/student) and what its 409 means, resolving country, grade, city and school by id or by name, finding an existing student with the email filter, giving a student access to olympiads such as stem, hilingua, neo, gmath or coding, updating a student with updateStudent, setting a password only when the account holds the sign-in permission, and linking a supervisor. Explains what to do when an email address is already held by one of your own students or by somebody else's. Use when writing or fixing code that creates or updates Main Team students one by one, or when a registration answers 400, 403, 409 or invalid_email. For 30 students or more at once, use registering-main-team-students-from-spreadsheets. Needs an API account's apiKey and apiSecret on the machine that makes the calls, never in the conversation, and a role granting student/create and student/update on mto. Works against api.main-team.org or apisnd.main-team.org. 6 files, 33 KB - SKILL.md 8.0 KB - references/duplicates.md 3.8 KB - references/fields.md 11 KB - references/operations.md 4.2 KB - references/passwords.md 2.8 KB - references/reference-data.md 3.8 KB - ### registering-main-team-students-from-spreadsheets Registers a class list, Excel or CSV roster of 30 to 1000 students with the Main Team API's bulk registration in one request: cleaning and checking the rows locally with a bundled Python script, building the body, sending it to createStudentImport (POST /v1/student/import), reading the 422 row list when the batch is refused and fixing exactly those rows, and polling getStudentImport (GET /v1/student/import/{importId}) until the batch has succeeded or failed. The batch is all or nothing: when any row has a problem, including an address already held by one of your students or by anybody else, nothing is registered and the answer names every row at fault. Also covers lists under 30 rows, lists over 1000, giving the new students access to olympiads, the welcome email every student in the file receives, and resuming after a timeout without registering anyone twice. Use when a developer or an integration has to register many Main Team students from a file. Needs an API account's apiKey and apiSecret on the machine that makes the calls, never in the conversation, and a role granting student/create on mto. The bundled script needs Python 3.8 or newer and no packages; it makes no network calls of its own. Works against api.main-team.org or apisnd.main-team.org. 10 files, 51 KB - SKILL.md 8.2 KB - agents/openai.yaml 277 bytes - assets/column-aliases.json 2.0 KB - assets/roster-template.csv 87 bytes - references/columns.md 5.1 KB - references/emails.md 2.7 KB - references/rejections.md 5.0 KB - references/task-status.md 5.7 KB - references/workflow.md 5.3 KB - scripts/roster.py 16 KB ## Add them to your app available at launch The kit is published in the repository [main-team-organisation/agent-kit](https://github.com/main-team-organisation/agent-kit), one release per version of the MCP server. It is private until the server goes live, so these commands work from launch on. - ### Any app that reads skills The skills installer finds the skills in the repository and asks which apps to add them to: Terminal ``` npx skills add main-team-organisation/agent-kit ``` - ### Claude Code Add the repository as a plugin marketplace, then install the plugin. It brings the skills and the MCP server in one step: In Claude Code ``` /plugin marketplace add main-team-organisation/agent-kit /plugin install main-team@main-team ``` - ### Codex Add the repository as a plugin marketplace: Terminal ``` codex plugin marketplace add main-team-organisation/agent-kit ``` - ### Gemini CLI Install the repository as an extension: Terminal ``` gemini extensions install https://github.com/main-team-organisation/agent-kit ``` - ### claude.ai and Claude Desktop Download a skill’s zip from the latest release at [github.com/main-team-organisation/agent-kit](https://github.com/main-team-organisation/agent-kit/releases) and upload it in Claude’s skills settings. - ### Keeping them current Skills installed with the skills installer update with: Terminal ``` npx skills update ```