Review Skills and Suites
This page covers pending-content inspection, decision submission and result verification for authorized reviewers. Authors can use the responsibility table to track submissions. A decision applies to a specific request and version; it does not replace Agent execution testing, compliance certification or global promotion approval.
Prerequisites and Responsibilities
| Operation | Identity and conditions | Entry |
|---|---|---|
| Review within a team namespace | Namespace Owner or Admin | Review entry in namespace details; opens the shared center with this scope selected |
| Review across namespaces | Platform Skill administrator (SKILL_ADMIN) or super administrator (SUPER_ADMIN) | /dashboard/reviews |
| Track an own submission | Submitter | My Review Progress; read access does not grant approval |
| Global promotion and revocation | Submitter and authorized platform reviewer | /dashboard/promotions, separate from ordinary version reviews |
Owners and Admins of a team namespace can review their own submissions; super administrators can self-review. Other own submissions cannot be self-reviewed solely through the platform Skill administrator role. Only a super administrator can review their own global promotion request. Ordinary review decisions also require an ACTIVE namespace. Source: review permission policy.
Ordinary public (PUBLIC) or namespace-member-visible (NAMESPACE_ONLY) uploads enter scanning and review. Private (PRIVATE) uploads are retained first and still require publication confirmation or a separate review submission. A previously published version may remain available while an update is pending.
Find Review Requests
The review center lists authorized Skill, Suite, avatar and visibility requests. Namespace entries open the same queue. The governance center retains reports, global promotions, activity and governance notifications without duplicating ordinary review tasks. User profile reviews remain a separate queue governed by user-management permissions.
The filter region includes keywords, status, scope, request type and source. Keywords match names, coordinates or submitters. Type and source are independent: a GitHub-synchronized request may be either an initial publication or an update. Platform reviewers can select authorized namespaces they have not joined; namespace Owners and Admins are limited to namespaces they manage.
Editing filters does not change results until Search is submitted, which returns to page one. Reset restores Pending, all scopes, all types, all sources and empty keywords. Applied filters, sorting and pagination remain in the URL and are restored when returning from details. Retry a failed scope request instead of interpreting it as an empty authorization scope.
Inspect Content and Submit a Decision
Figure: A decision requires a pending request and current permission. Reading the old version does not verify the current submission.
- Open a pending request and verify its submitter, subject, target version, visibility and namespace. GitHub-synchronized items also provide a content revision, source repository and fixed commit. The technical version used for installation appears in technical information.
- Inspect the effective display name, summary and overview bound to this request, then expand the original package to inspect its files. Neither the old published version nor the original SKILL.md substitutes for custom public-facing content. The page header groups request type, scope, version, submitter and evidence. Avatar and visibility requests show their own objects; visibility is not a content version number. An empty preview caused by an object-storage read failure is not evidence of acceptable content.
- Check license evidence, the scanning report and findings in Source & Security. Distinguish execution errors, risk findings and unconfigured analyzers. Ordinary version approval is unavailable while scanning is running. Unrecognized licenses or missing evidence require inspection of the specific status and supporting material; they do not confirm permission to use the content.
- For avatar or visibility changes, verify the candidate and requested target. For a Skill Suite, inspect the pending snapshot, Entry Skill and fixed member versions. Approval is unavailable before the snapshot loads. Member approval does not approve the Suite. A Suite definition and a Suite Bundle import operation are separate objects; see Skill Suites.
- Read previous decisions in Review History, then approve or reject after evidence checks. A rejection must identify the file, problem and correction conditions; approval comments are optional. Switching tabs preserves comments; switching requests clears comments and unconfirmed dialogs. This version has no conditional-approval state.
| Inspection result | Decision basis | Next action |
|---|---|---|
| Current content, target and evidence agree | The current request has been inspected and no unresolved issue remains | Approve, then re-read the task and target object |
| Files, evidence or declarations contain a specific issue | Record a traceable problem and correction conditions | Reject; the author revises the submission |
| Scan, snapshot or files are unavailable | Evidence required for a decision is missing | Diagnose or wait; do not treat missing results as acceptable evidence |
Online preview limits are listed together below. Exceeding a limit does not mean the file was deleted; obtain it through an authorized download before inspection.
| Item | Fixed limit | Exceeding the limit |
|---|---|---|
| Line-by-line comparison | File exceeds 64KiB or 1000 lines | Line comparison is skipped |
| Current content loaded online | File exceeds 256KiB | Content is not loaded online |
| Baseline download of a removed old file | File exceeds 1MiB | The old file cannot be downloaded from the review page |
These are frontend/API implementation limits, not review-page settings. Sources: review detail page and review API. GET /api/v1/reviews/{id}/skill-detail?includeDocumentation=false reads metadata, custom web/package presentation and the documentation path without fetching object-storage content; README or SKILL.md fallback content is loaded on demand; the default is true.
Switching tabs or opening evidence smoothly returns to the detail page top, including its heading; reduced motion uses direct positioning. Query completion and comment edits do not reset the reading position. The summary has a distinct section, with package download and file browsing available before the overview. All tabs share the same main width; comparison stacks on narrow screens. Content uses the main page scroll.
Understand Changes
The version context directly shows the published baseline, pending version and available package metadata. An absent changelog does not create an empty section. Missing displayable declarations do not create empty disclosures; an unavailable snapshot does not establish that no declaration was submitted.
Ordinary updates compare the actual published baseline on the left with the pending version on the right: effective display name, summary and overview, plus added, modified and removed files. Initial publication has no published baseline; the page states this instead of inventing an empty-version comparison. GitHub updates retain fixed source revisions and line-by-line file comparison. Avatar and visibility requests compare their own candidate or target rather than content versions.
Switching to history cannot bypass inspection: approval stays unavailable when required content, comparison or Suite snapshots cannot be read. Processed requests are read-only. A listed request does not itself grant decision permission. Search index maintenance is in system settings, outside review tasks.
Inspect Compliance Declarations
Versions containing x-astron-compliance display a compliance snapshot and added, removed or modified declarations. A changed complianceSnapshot.digest indicates a change in normalized declarations. Match declarations to actual capability, control items, evidence paths and external material rather than standard names alone. Inaccessible evidence, mismatched content or removals affecting downstream references require a documented issue and revision. The registry stores structured declarations and version snapshots; it does not certify the author's actual compliance. See compliance metadata.
State Object Reference
A task can be PENDING while its version is still SCANNING. Task and version states must not be substituted for each other. Read the following four objects separately.
Review Task States
| State | Meaning | Responsible party and next action |
|---|---|---|
PENDING | Awaiting a decision | Authorized reviewer reads the current request before acting |
APPROVED | Approved | Submitter verifies the version or metadata effect |
REJECTED | Rejected with comments retained | Submitter revises and resubmits |
SUPERSEDED | Replaced by a later request | Submitter and reviewer read the current request |
The task enum has no WITHDRAWN. Withdrawing an ordinary Skill version removes the pending task and changes its version state. It does not remove a previously published version or revoke an approved global promotion; see the withdrawal service.
Skill Version States
| State | Meaning | Responsible party and next action |
|---|---|---|
DRAFT | Version draft, not an authoring API draft object | Skill owner completes preparation |
SCANNING | Scan is running | Scanning service completes before continuation |
SCAN_FAILED | Scan execution failed | Operator and owner diagnose before retrying |
UPLOADED | Uploaded but not published | Owner confirms publication or submits for review |
PENDING_REVIEW | Awaiting a human decision | Authorized reviewer inspects this version |
PUBLISHED | Published | Users access under visibility rules; execution needs separate verification |
REJECTED | Not approved | Owner revises and resubmits |
YANKED | Withdrawn from distribution | Users select an installable alternative |
Source: version enum.
Suite Bundle Import Operation States
| State | Meaning | Responsible party and next action |
|---|---|---|
RUNNING | Executing | Importer tracks the original operation without duplicate confirmation |
WAITING_FOR_MEMBERS | Waiting for members | Import service and member reviewers handle members |
BLOCKED_RETRYABLE | Retryable block | Importer diagnoses and retries the original operation |
REPREVIEW_REQUIRED | Previous preview cannot continue | Importer previews again and checks differences |
SUITE_DRAFT_CREATED | Suite draft created, not approved | Suite owner continues publication |
CANCELLED | Cancelled; not a full rollback | Importer checks completed member actions |
Source: import states. Recovery instructions are in Suite Bundle Import.
Avatar Review Results
Avatars reuse Skill review requests, but their state dimensions remain separate. A machine block is not a human rejection.
| Field | Values and meanings | Responsible party and next action |
|---|---|---|
Candidate status | PENDING pending, ACTIVE in use, REJECTED rejected, SUPERSEDED replaced, REMOVED removed | Owner and reviewer compare the candidate with the active avatar; the response field is candidateStatus |
machineStatus | SKIPPED skipped, PENDING pending, PROCESSING running, PASSED allowed, BLOCKED blocked, ERROR execution error | Machine service processes it; deployment operator diagnoses ERROR |
reviewStatus | NOT_REQUIRED no human review, PENDING pending, APPROVED approved, REJECTED rejected, APPEAL_PENDING appeal pending | Authorized reviewer and owner act on current comments |
Source: avatar candidate model. Configuration and retry rules are in Skill Avatars.
Completion Criteria and Failure Handling
After ordinary version approval, the task is APPROVED and the target version is PUBLISHED; verify access with the intended identity. Metadata requests require checking the actual metadata effect, not only the version number. A rejected ordinary version is REJECTED with correction comments; the author revises and resubmits from the current-version entry. Approval does not prove Agent execution success or eliminate security risk.
| Symptom | Likely cause | Diagnosis | Resolution |
|---|---|---|---|
| Request is listed but cannot be approved | Self-review, namespace state or identity condition is not met | Compare submitter, roles and namespace state | Assign an eligible reviewer; do not alter requests to bypass restrictions |
| Approval button is disabled | Scan/avatar is pending or Suite snapshot failed to load | Read scan, candidate and snapshot errors | Complete dependencies or retry reads; do not treat absent results as acceptable evidence |
| File or documentation is empty | Object read failed or preview limit was exceeded | Check file size and preview error; download with permission | Obtain readable material before deciding; do not approve an empty preview |
| Decision reports a state conflict | Task was already processed or superseded | Refresh history and compare task ID and current state | Follow the new state; do not repeatedly approve or reject |
Global Revocation and Governance Boundaries
If deletion of a promoted Skill is blocked, request revocation from Promote to Global on its source Skill. A platform Skill administrator or super administrator handles it under Revocation Pending Review at /dashboard/promotions; own submissions follow the self-review restrictions above. After the revocation record is APPROVED, verify that the active relation is removed before deleting the source Skill with the required permission. Hiding, archiving or withdrawing ordinary review does not substitute for revocation.
When no revocation request is pending, an authorized platform operator can revoke directly from details with a retained record. An existing pending request must be handled in the queue. Approved revocation deletes the entire global Skill, its versions, reviews and statistics, while retaining the source Skill. Client files cannot be retrieved, and the old address can be reused. If deletion remains blocked after approval, check for another promotion and record object IDs, request ID, deployed version and failed response. Do not modify database relations directly. Source: revocation service.
Reports are handled at /dashboard/reports under existing governance permissions and the specific report evidence. Investigating a report does not automatically approve or reject a version. Withdrawal applies only to a pending review; historical comments and current request mutability must be evaluated separately.
Further Reading
- Publish and Update Skills: Preparation, submission and version management.
- Security Scanning: Interpret reports and diagnose execution failures.
- Manage Namespaces: Membership roles and namespace states.