agentleFS
metyatechmetyatech/skill-human-ai-system-builder/SKILL.md

human-ai-system-builder

Skill0 starsChanged 4 months agoMITView on GitHub

Design and build systems that humans and AI agents can both manage. Use when a request says a system must be operated, edited, or maintained by both humans and AI, especially when the request is short and Codex must infer the canonical data store, human GUI, AI editing surface, synchronization flow, conflict policy, validation surfaces, diagnostics delivery, generated artifacts, and startup path.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Start from references/project-contract.md and assets/project-contract.template.yaml.

    line 9
  2. Distinctive:

    Ask only the irreducible questions that materially change architecture.

    line 50

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Human/AI system builder

The agent MUST build a project-contract before implementation. Start from references/project-contract.md and assets/project-contract.template.yaml.

The agent MUST make every decision below explicit:

  • Actors.
  • Canonical store.
  • Human surface.
  • AI surface.
  • Sync direction and trigger.
  • Conflict detection and resolution.
  • Validation timing and location.
  • Generated artifacts.
  • Human startup flow.

The agent MUST use references/gui-selection.md to choose one of these patterns:

  • references/pattern-native-gui-reuse.md
  • references/pattern-custom-gui.md
  • references/pattern-hybrid-gui.md

For core architecture choices, the agent MUST also use:

  • references/canonical-store-selection.md
  • references/sync-and-conflict.md
  • references/validation-and-launch.md
  • references/minimal-questions.md
  • references/deliverables.md

For document, form, spreadsheet, and layout-sensitive systems, the agent MUST also read references/domain-structured-docs.md.

Workflow

  1. Classify the domain and the primary constraints.
  2. Draft the project-contract.
  3. Choose the human GUI pattern.
  4. Decide the canonical store and AI editing surface.
  5. Specify sync, conflict, validation, artifacts, and launch flow.
  6. Ask only the irreducible questions that materially change architecture.
  7. Choose or adapt the nearest reusable template under assets/templates.
  8. Produce the architecture summary, chosen pattern, contract, scaffold plan, and implementation sequence.

Design rules

  • The agent MUST keep one canonical source of truth.
  • The agent MUST prefer machine-readable, diff-friendly canonical data for AI.
  • The agent MUST prefer the most natural human GUI for the job, even when it is an existing application.
  • The agent MUST reuse an existing GUI when that GUI is the truth for layout, wrapping, print, or visual constraints.
  • The agent MUST show validation in the human primary work surface whenever practical.
  • The agent MUST prefer diagnostics in the same active human GUI via inline markers, anchored panels, or in-surface sheets before introducing a separate diagnostics window.
  • The agent MUST separate generated artifacts from canonical data.
  • The agent MUST NOT rely on silent overwrites for human/AI conflicts.
  • The agent MUST make the human launch path low-friction. The agent MUST prefer launcher or double-click flows over CLI for routine human work.

Outputs

The agent MUST produce these outputs unless the user explicitly narrows scope:

  • Architecture summary.
  • project-contract.
  • Chosen GUI pattern and rationale.
  • Scaffold layout.
  • Implementation plan.
  • Acceptance criteria.

The agent MUST use assets/project-contract.schema.json when a machine-readable schema is needed. The agent SHOULD use the example contracts under assets/templates when the request is close to an existing pattern.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.