---
name: gisthubs-creator
description: Use when the user's existing Agent must direct a complete GistHubs project-creation workflow, combine selected writing, research, visual or video Skills, produce a gisthubs-agent-draft@1 Bundle, respond to Studio feedback, or publish only after human approval. Do not use as a substitute for the specialist Skills it coordinates.
---

# GistHubs Creator — Bring Your Own Agent workflow

You are the user's already-existing creative Agent. **This Skill does not create,
launch, configure or replace an Agent. GistHubs Studio is not an AI writer.** It
is a human editing, review and publication surface.

## What this package is — and is not

This package contains a universal Skill, open specifications, examples, schemas
and a mechanical handoff utility. It contains no Agent runtime, planner, memory,
model client, autonomous loop, tool executor or background worker.

Do not ask GistHubs to install an Agent for the user. The user decides which
Agent exists and how it is configured. Runtime-specific documentation may only
explain where to copy this same Skill.

## Responsibility boundary

### You, the user's Agent, own

- repository reading and product understanding;
- editorial strategy and narrative structure;
- every title, paragraph, caption and channel-specific draft;
- screenshots, recordings, diagrams, decorative graphics and their provenance;
- deciding whether one or several creative variants are useful;
- factual checking and creative self-critique;
- revising the work after human feedback.

Use only the models, tools, browser, terminal, image generators and video tools
that the user has already made available to this Agent. Do not route content
generation through GistHubs, and do not bootstrap another Agent to complete the task.

### The human owns

- selecting a variant;
- detailed wording edits;
- rearranging, hiding or removing blocks;
- choosing/replacing assets;
- writing change requests to you;
- approving the exact revision that may be published.

### GistHubs owns only mechanical infrastructure

- the handoff protocol;
- Studio preview and editing controls;
- schema/path/safety validation;
- revision and feedback records;
- deterministic serialization to `.gisthub/posts/`;
- atomic Git commit or Pull Request publication.

Never tell the human to click an “AI generate” button in Studio. There is none.

## Coordinate the user's selected Skill combination

The human may give you a numbered Skill combination copied from the GistHubs
official catalog. Read every selected Skill before creating content. Treat this
Skill as the director and the selected specialist Skills as the actual methods.

Plan dependencies before execution:

1. research and evidence Skills establish what is true;
2. writing Skills create the narrative, title or script from that evidence;
3. visual and video Skills produce authentic assets from the real project;
4. review Skills inspect the resulting work;
5. this Skill assembles the selected outputs into one Draft Bundle.

Do not pretend to use a Skill that was unavailable or whose required tools are
missing. State the gap, use a safe fallback when the specialist Skill permits
one, and keep unfinished artifacts out of the approved public revision.
Record every actually used specialist as `skill:<name>` in
`agent.capabilities`. Do not record Skills that you only considered or could not
load.

## Canonical handoff

Write one canonical local file:

```text
.gisthub/drafts/<draft-id>/bundle.json
```

Keep `.gisthub/drafts/` ignored by Git unless the user explicitly chooses a
private version-control policy. Draft Bundles contain collaboration state and
must not be committed to a public repository by accident.

It must follow `schemas/agent-draft.schema.json` and use:

```json
{
  "format": "gisthubs-agent-draft@1",
  "schemaVersion": 1,
  "draftId": "project-launch-2026-08",
  "repository": {},
  "agent": {},
  "project": {},
  "variants": [],
  "activeVariantId": "variant-a",
  "collaboration": {}
}
```

The Bundle is the shared state between you and the human. Do not keep important
creative decisions only in chat history. Read `specs/BYOA_CONTRACT.md` before
starting and treat `specs/PUBLICATION_SPEC.md` as the public/private boundary.

## Agent workflow

### 1. Understand the actual project

Read the repository, not only its README. Use relevant code, docs, tests,
releases, commits, issues, demo pages and runtime observations. When safe,
start the project and capture real states.

Record evidence in `project.evidence`. Record uncertainty in
`project.openQuestions`; do not convert uncertainty into confident marketing.

### 2. Decide the creative approach yourself

Templates under `templates/` are optional creative references for you. They are
not executable recipes and Studio will not apply them automatically.

Choose or combine them based on the project, audience and user's intent. You may
create one excellent direction or several genuinely different variants. Do not
create arbitrary variants merely to satisfy a fixed count.

Each variant must state:

- why this direction exists;
- intended audience and reaction;
- art direction;
- the complete Story document;
- template references, when used.

### 3. Create all content and visuals

Write the complete Story AST, including an explicit `postType` (`photo`,
`update` or `note`). GistHubs will not infer the editorial type. Use authentic
assets first:

1. real product screenshots;
2. real interaction recordings;
3. terminal output and code;
4. diagrams derived from the implementation;
5. AI-generated decorative visuals.

Generated visuals must not impersonate product functionality that does not
exist. Record their tool/model/prompt summary in asset provenance.

For an asset that must be copied into the final post, set a safe
`publicationPath`. Use one of these sources:

- `localPath` while the Bundle is unpacked in the user Agent workspace;
- `contentBase64` in a portable Bundle sent to Studio;
- `repositoryPath` when GistHubs should copy an existing Git blob atomically.

`localPath` is never read by the browser or publisher. Run `handoff pack` before importing the Bundle into Studio.

### 4. Self-review as an Agent

You—not a fixed scoring function—must review:

- factual accuracy;
- narrative specificity;
- visual hierarchy;
- originality versus generic AI prose;
- whether the first screen communicates the project;
- whether every asset proves or enriches the story;
- mobile reading order;
- the quality of channel adaptations.

The system validator checks only structural integrity, traceability hints,
unsafe SVG, paths and publication readiness. A passing validator does not mean
the story is creatively good.

### 5. Validate and hand off

From the standalone Skill package, run the network-free utility directly:

```bash
node scripts/gisthubs-handoff.mjs validate \
  .gisthub/drafts/<draft-id>/bundle.json
```

Inside the full GistHubs source repository, the same command is available as
`npm run studio:handoff -- validate ...`.

To embed files referenced by `localPath` (or, for compatibility,
`publicationPath`) into a portable Bundle:

```bash
node scripts/gisthubs-handoff.mjs pack \
  .gisthub/drafts/<draft-id>/bundle.json \
  --asset-root .gisthub/drafts/<draft-id> \
  --out <draft-id>.gisthubs-agent-draft.json
```

Give that file to the human to open in `/studio`.

### 6. Process the returned human feedback

The human returns an updated Bundle. Read:

```text
collaboration.requests[]
collaboration.revision
collaboration.humanApproval
activeVariantId
```

Resolve every `open` or `accepted` request in the actual content. Add a short,
specific `agentResponse`, mark it `resolved`, increment the revision, and set
status to `ready-for-human`.

Do not merely mark a request resolved. The Story or assets must reflect the
change.

### 7. Publish only after approval

Publication is allowed only when:

```text
humanApproval.status == approved
humanApproval.approvedRevision == collaboration.revision
no request has status open or accepted
```

Prefer a Pull Request. The publication layer writes all files as one Git tree
and one commit, so a partially written story never becomes visible.

## Required handoff summary

Tell the human:

- what you understood about the project;
- what variants you created and why;
- what real/generated assets are included;
- what remains uncertain;
- where the Bundle was written;
- which human requests were resolved in the latest revision.

## Register the public repository after publication

After a direct publication or after the human confirms that the Pull Request was
merged, register a public repository with the selected GistHubs instance:

```bash
curl -X POST <GISTHUB_HOST>/api/submit \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"https://github.com/OWNER/REPO"}'
```

Registration is idempotent. Later content updates only require normal Git push.

## Persist the collaboration rule

With the user's permission, append this rule to the repository's `AGENTS.md`:

```markdown
## GistHubs Agent-native creation

GistHubs does not create this project's content. At a real publishable milestone,
the project Agent should create or update a `gisthubs-agent-draft@1` Bundle from
the current repository, runtime evidence and authentic assets, then ask the user
to review it in GistHubs Studio. The Agent owns all creative work and revisions;
the human owns selection, detail edits, feedback and approval. Never publish a
revision that the human has not approved.
```