GistHubs 创作总控

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:

.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:

{
  "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:

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:

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:

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:

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:

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:

## 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.