yao-open-skills-sync

Files (3)

• SKILL.md
• operating-rules.md · references/
• registry-schema.md · references/

SKILL.md (first lines)

# Yao Open Skills Sync

Use this skill to manage the public `yao-open-skills` collection in the current repo root.

This skill is not for creating arbitrary new skills from scratch. It is for intake, governance, sync tracking, and collection maintenance.

## Read First

Before changing the collection, read:

- `references/operating-rules.md`
- `references/registry-schema.md`

Only read repo-wide docs under `../../docs/` if you need more human-facing detail after reviewing the references.

## Primary Responsibilities

- Evaluate whether a local skill is suitable for public release
- Create a clean public copy under `skills/<slug>/`
- Register or update the skill in `registry/skills.json`
- Add or update a human-facing usage guide under `docs/skills/<slug>.md`
- Regenerate the README catalog and HTML navigation page so the collection homepage stays in sync
- Record whether the skill is only local, staged, published, or needs an update
- Push collection changes to GitHub when the user wants the public repo updated

## Workflow

### 1. Inspect the source skill

Given a local path from the user:

- Confirm the path exists
- Inspect `SKILL.md`
- Identify what should be kept, removed, or rewritten for public release

Watch for:

- `output/`, `downloads/`, `.venv/`, `node_modules/`, caches, logs
- generated reports, exported results, `.command` helpers, and local scan artifacts
- private APIs, tokens, cookies, internal references, customer data
- assets or references that may not be redistributable

### 2. Decide whether it can be public

Use the publishing rules:

- If the skill can be cleaned into a self-contained public version, proceed
- If it mixes public logic with sensitive material, split the public part from the private part
- If it cannot be safely cleaned, stop and explain why it should not be published

### 3. Import the public copy

When approved:

- Copy the public version into `skills/<slug>/` under the repo root
- Keep only the files needed for the public skill
- Make the structure self-contained and understandable
- Exclude local output artifacts by default unless the user explicitly wants a safe sample included

### 4. Register the skill

Upsert the registry entry using:

```bash
python3 scripts/register_skill.py \
  --slug <slug> \
  --title "<title>" \
  --summary "<summary>" \
  --source-local-path "<absolute-source-path>" \
  --collection-path "skills/<slug>" \
  --lifecycle active \
  --sync-status <local-only|staged|published|needs-update> \
  --github-repo yao-open-skills \
  --github-url "<url-if-known>" \
  --license "<license>" \
  --tags "tag1,tag2"
```

Use `--last-synced-at YYYY-MM-DD` only when the skill has actually been pushed to GitHub.

### 5. Update the README catalog

After every registry change, run:

```bash
python3 scripts/render_collection_pages.py
```

README and `index.html` are rendered views. Do not maintain the catalog table or HTML Skill cards manually.

### 5.5 Write the usage guide

For every published skill, add or update:

```text
docs/skills/<slug>.md
```

The guide should explain:

- what the skill does
- when to use it
- the main workflow
- important inputs and outputs
- any local-only outputs that should not be committed back into the repo

### 6. Publish to GitHub when requested

If the user wants the collection pushed:

- ensure the public files, registry, and README are already consistent
- ensure `index.html` is regenerated from the registry
- commit the current repo changes with a clear message
- push to the configured `yao-open-skills` GitHub repository
- only after a successful push, mark relevant skills as `published` and set `last_synced_at`

If the public repo exists but the local collection has new unpublished changes, use `needs-update` until the push is complete.

### 7. Report the result

From yaojingang/yao-open-skills, MIT.

More from yaojingang/yao-open-skills