SkillHub Workflow

This skill provides a complete operating guide for day-to-day work in the SkillHub repository.

Use it to:

• Add or modify local skills under skills/
• Manage external sources in sources.json
• Rebuild external-skills.json and registry.json
• Validate README and repository consistency
• Prepare safe merge requests
• Diagnose GitLab CI and runner failures

Operating Principles

1. Keep changes minimal and scoped to the user request.
2. Preserve existing repository conventions and file structure.
3. Validate after every meaningful edit.
4. Distinguish between user/code errors and infrastructure errors.
5. Never introduce secrets in committed files.

Repository Areas

Key files and responsibilities:

• skills/<skill-name>/SKILL.md: local skill definitions
• sources.json: remote source configuration and discovery catalogs
• external-skills.json: synced remote skill cache
• registry.json: merged local + remote skill index
• eng/sync-remote-skills.mjs: remote sync implementation
• eng/update-registry.mjs: registry merge implementation
• .gitlab-ci.yml: CI rules, schedule behavior, deploy flow
• README.md: user-facing usage and operations documentation

Standard Task Flows

A) Create a New Skill

Follow this order:

1. Create directory skills/<new-skill-name>/
2. Create SKILL.md with valid frontmatter:
   • name
   • description
   • metadata.version
   • metadata.author
   • metadata.tags
3. Add optional references/, scripts/, assets/ only when needed.
4. Run validation.
5. Update docs only if behavior or discoverability changed.

Command sequence:

npm run skill:validate
npm run registry:update

B) Add or Update Remote Skill Sources

Use this when user asks to include third-party skill repositories.

1. Edit sources.json:
   • sources[]: executable sources actually synced
   • catalogs: discovery metadata only
2. Do not blindly convert discovered repositories into sources[] until roots/path conventions are known.
3. Sync remote skills and regenerate registry.

Command sequence:

npm run registry:sync-remote
npm run registry:update

C) Full Build Before MR

Use this for final checks before opening or merging MR.

npm run skill:validate
npm run registry:build
npm run website:build

If any step fails, stop and fix root cause before proceeding.

CI and MR Governance

Target Model

Default governance target:

• Protected default branch (no direct push)
• Changes go through MR
• Pipeline runs on MR and/or default branch according to .gitlab-ci.yml
• Optional auto-approve/auto-merge for skills/**-only MRs

Rules Interpretation Checklist

When user asks "why did this pipeline run", inspect:

1. workflow.rules (pipeline creation gate)
2. Job-level rules (job execution gate)
3. CI_PIPELINE_SOURCE (push, merge_request_event, schedule, web)
4. Branch condition (CI_COMMIT_BRANCH, CI_DEFAULT_BRANCH)
5. changes filters

Always explain behavior with these variables explicitly.

CI Failure Triage

Category 1: Infrastructure Failure

Examples:

• Kubernetes executor pending forever
• etcdserver: request timed out
• prepare environment system failure

Action:

• Explain this is runner/cluster level, not repo code logic.
• Recommend retry + infra owner investigation.

Category 2: Auth/Permission Failure

Examples:

• curl ... 401 on GitLab API approve/merge
• push back to repo denied

Action:

• Verify token variable name used in CI matches configured variable.
• Verify token scope/permissions.
• Verify protected variable visibility for MR pipelines.

Category 3: Repository Logic Failure

Examples:

• JSON parse errors
• duplicate path collisions
• invalid SKILL frontmatter

Action:

• Reproduce locally with exact command.
• Patch smallest failing area.
• Re-run command to confirm.

Skill Authoring Quality Bar

Every new skill should include:

• Clear trigger language in description
• Boundaries: what it does and does not do
• Step-by-step process
• Explicit output expectations
• Error handling guidance
• At least 2 realistic usage examples

Avoid:

• Vague descriptions
• Tool-specific assumptions without checks
• Hidden side effects

Required Validation After Edits

After changing any of these files, run the matching checks:

• Changed skills/**:

npm run skill:validate
npm run registry:update

• Changed sources.json or sync scripts:

npm run registry:sync-remote
npm run registry:update

• Changed website build logic:

npm run website:build

• Changed CI config:
• Validate YAML syntax
• Verify expected workflow and rules behavior with concrete scenarios

Communication Template for MR Readiness

Use this response structure when asked for "can I submit now":

1. Findings first (ordered by severity)
2. Blocking vs non-blocking classification
3. Exact file references for each issue
4. What was validated locally
5. Residual risk (if any)

If no findings:

• State explicitly: "No blocking findings found."
• Mention what was validated and what was not validated.

Examples

Example 1: User asks to add a repository to sources

Expected behavior:

1. Add source entry only if repo root/path strategy is known.
2. Otherwise add to discovery catalog.
3. Run sync + update.
4. Report counts and changed outputs.

Example 2: User asks why auto-merge job failed with 401

Expected behavior:

1. Identify failing API call and status code.
2. Check token variable mapping in CI file.
3. Check token presence and scope.
4. Explain protected-variable behavior for MR pipelines.

Safety and Security

• Never hardcode API tokens into repository files.
• Use CI variables for credentials.
• Do not suggest destructive git commands unless explicitly requested.
• Preserve unrelated user changes in dirty working trees.

Definition of Done

A SkillHub task is complete only when:

1. Requested edits are implemented.
2. Relevant local validations pass.
3. Behavior is explained in plain language.
4. Any remaining risk is explicitly called out.