---
name: open-source-skill-release
description: Audit, sanitize, package, document, test, publish, and verify an Agent Skill as open source on GitHub. Use when a user wants to open-source a local workflow, add a Skill to a public catalog, review publication rights, remove secrets or personal data, preserve unrelated dirty-worktree changes, create a release, verify the online tree and CI, or improve honest project discovery without fake Stars. Do not treat a passing scanner as proof of copyright ownership or complete privacy.
---

# Open Source Skill Release

Treat source rights, the exported folder, human documentation, Git state, GitHub metadata, CI, and the live URL as one release. Keep project-specific state in a private controller; publish only the reusable method.

Read [references/publication-boundary.md](references/publication-boundary.md) whenever authorship, collaborators, third-party material, fixtures, screenshots, or data provenance are involved. Read [references/repository-adapters.md](references/repository-adapters.md) before editing an unfamiliar or dirty repository.

## Workflow

### 1. Establish real sources and authority

Identify the canonical local Skill, target repository, public license, repository contract, and requested publication action. Inspect the real files, `git status --short`, latest commit, remote, visibility, and recent CI before changing anything.

Publishing a new commit, tag, release, repository setting, or promotional post requires user authorization for that scope. Never infer permission to rewrite history, change visibility, force-push, discard changes, or publish unrelated work.

### 2. Build an explicit publication boundary

Make an allowlist of files and an exclusion list with reasons. Include only original or redistributable material. Exclude unknown provenance, jointly owned work without independent rights, private data, credentials, production configuration, session state, generated output, caches, and dependencies that should be installed rather than redistributed.

If private implementation and reusable method are mixed, rewrite the generic method in a new Skill. Do not rely on search-and-replace to convert a private controller into a public artifact.

### 3. Audit the candidate locally

Run the deterministic audit against the exact folder that will be staged:

```bash
python3 scripts/audit_publication.py /path/to/skill --json
```

Interpret results precisely:

- `blocked`: do not publish;
- `needs-review`: decide each contact, binary asset, large file, license, or provenance question manually;
- `pass`: automated checks found no listed issue, but manual rights and history gates still remain.

Never print matched secret values in reports. Replace real examples with synthetic fixtures and rerun the audit.

### 4. Package for both people and Agents

Keep the installed Skill concise: `SKILL.md`, `agents/openai.yaml`, and only necessary scripts, references, tests, or assets. In the public repository, add a plain-language entry that states:

- who it is for;
- what concrete result it produces;
- one example request;
- prerequisites and external dependencies;
- how completion is verified;
- a copyable install command.

Update the repository manifest, catalog, generated docs, counts, changelog, description, and preview only through their true sources. Preserve existing layout and naming conventions.

### 5. Test the exact export

Test executable scripts, Skill structure, manifest-to-directory consistency, generated-doc freshness, caches and symlinks, secret and private-path patterns, links, and the documented install path. Run tests from the public copy, not only the private source.

State the exact checks and failures. Passing source tests does not audit Git history, platform scanners, image metadata, licenses, or remote settings.

### 6. Stage and publish narrowly

Stage explicit intended paths. Inspect:

```bash
git diff --cached --name-status
git diff --cached --check
```

Confirm that pre-existing dirty files are absent. Commit, push, create a release, or change repository metadata only within the authorized workflow. Never clean the worktree as a shortcut.

### 7. Verify the public result independently

After pushing and after CI finishes, verify the exact commit:

```bash
python3 scripts/verify_github_publication.py \
  --repo owner/repository \
  --skill-path skills/example-skill \
  --ref COMMIT_SHA
```

Require public visibility, an online `SKILL.md`, the resolved commit, and successful CI for that same commit. A successful local push or browser click alone is not proof of the public result.

### 8. Promote honestly

Lead with one painful problem and one concrete demonstration, not a long name list. Put the repository and install command early. Explain limitations, invite real failure reports, and ask for a Star only after the workflow helps. Never buy, exchange, automate, or fabricate Stars or metrics.

## Completion report

Report separately:

1. publication boundary and unresolved rights;
2. automated findings and manual review limits;
3. exact staged files, tests, commit, push, CI, and release;
4. verified public and install links;
5. unrelated local changes deliberately left untouched.

Use “published” only after the live tree is readable. Use “verified” only when the public commit and its CI evidence match.