si-coder-agent

README

SI-Coder (`sc`)

One plain-language goal in. A working, verified app out.

SC is a tool for AI agents — not another platform to learn.

@sc  ·  /sc   →   build · connect · publish · verify

Why everyone should use SC

Most agent stacks force you to juggle prompts, secrets, providers, deploy scripts, and ten tool calls per change. SC collapses that into one skill / one CLI / one MCP surface.

flowchart LR
  You["You: plain-language goal"] --> SC["sc"]
  SC --> App["Working app"]
  SC --> Live["Published URL"]
  SC --> OK["Verified result"]

Without SC	With SC
Pick stack, DNS, DB, CI yourself	SC chooses defaults; you decide product behavior
Paste API keys into chat	Named connections + local vault; secrets never in chat/tools
8–15 agent tool calls per deploy	One `/sc` or `sc flow run` with props
Different habits per agent host	Same `sc` / `@sc` / `/sc` contract everywhere
“Looks done” in the transcript	Live verify + evidence when it matters

Simple on purpose: one entry point (sc). Internals (skills, providers, MCP, flows, memory) stay progressive — use them when you need power, ignore them when you do not.

Why SC wins

flowchart TB
  subgraph Surface["Simple surface"]
    A["/sc · @sc · sc CLI"]
  end
  subgraph Engine["Does the hard work"]
    B["Skills router"]
    C["Providers + named connections"]
    D["sc flow DAG · parallel / recursive"]
    E["MCP machine tools"]
  end
  subgraph Safe["Stays safe"]
    F["Secrets out of chat"]
    G["Verify live result"]
  end
  A --> B --> C --> D --> E
  C --> F
  D --> G

Product-first — asks what the app should do, not which container strategy you prefer.
Secret-safe — credentials live in user/connection stores (0600); agents get status, not plaintext.
Multi-account — isolated users + labeled connections for clients/projects.
One vocabulary — build, frontend quality (sc-fe), providers, deploy, skills CRUD.
Efficient agents — sc flow turns multi-provider steps into one call with custom props (parallel DAG, recursive subflows).
Host-portable — Claude, ChatGPT, Codex, Hermes, OpenClaw, local CLI; same intent.

30-second start

ChatGPT:  @sc Create a booking app for my salon and publish it.
Claude:   /sc Fix checkout and verify login.
CLI:      sc doctor   ·   sc flow list   ·   sc flow run provider-health --dry-run

You do not need the skill tree, provider matrix, or MCP catalog before your first win.

What SC does

SC gives an AI coding agent a consistent way to:

build a new web app from a plain-language idea,
improve an existing app without erasing intentional design DNA,
raise frontend UI / UX / DX / AX quality,
connect only the services the product needs,
publish + attach a domain,
manage users, providers, connections, credentials, and skills as CRUD resources,
verify the important user flow,
keep secrets out of chat and tool payloads,
suggest one useful next step after a milestone.

flowchart TD
  G[Goal] --> U[Understand product]
  U --> B[Build / change]
  B --> C[Connect only what is needed]
  C --> P[Publish]
  P --> V[Verify real result]

Common use cases

Start from the outcome. The main /sc skill can route internally; specialized /sc-* skills remain available when you want explicit control.

Goal	Example	What SC handles
Build a new product	`/sc Build a booking app for a barbershop and publish it.`	product defaults, implementation, data/runtime routing, publish, verification
Improve an existing frontend	`/sc-fe --workbench --density compact audit and improve this desktop shell`	UI + UX + DX + AX audit, existing design-DNA preservation, rendered verification
Apply a design-principle preset	`/sc-fe --apple improve this settings experience`	Apple/HIG-inspired principles without cloning trade dress or replacing coherent project identity
Connect a provider safely	`/sc Connect transactional email for password reset.`	provider routing, required account access, safe credential flow, live verification
Publish and connect a domain	`/sc Publish this app on my existing stack and connect the domain.`	runtime selection, deploy, DNS/domain work, HTTPS and live checks
Work with multiple clients/accounts	`sc user add client-a` then create named connections	isolated user credential stores, project mapping, explicit connection selection
Create a project-specific workflow	`sc skill create release-check --description "Verify release readiness"`	creates `.si-coder/skills/release-check/SKILL.md`; compatible hosts can invoke `/release-check`
Share one skill vocabulary across tools	type `/skills`, then `/sc-fe ...` in any compatible agent host	discovery, direct slash invocation, exact-id ambiguity handling

Frontend presets can be composed rather than treated as themes:

/sc-fe --apple --density compact --motion subtle improve settings
/sc-fe --workbench --platform desktop --strict audit this project shell

When the project already has a coherent UI, SC preserves its design DNA by default. A preset changes principles and constraints; it is not permission to replace the product with a generic generated aesthetic.

CRUD model

Operator-owned resources should be manageable as normal resources instead of one-off setup state.

Resource	Create	Read	Update	Delete
Users	`sc user add <name>`	`sc user`, `sc user show <name>`, `sc user which`	`sc user rename <old> <new>`, `sc user use <name>`, mapping/owner commands	`sc user rm <name>`
Provider definitions	`sc providers create <id> ...`	`sc providers`, `sc providers show <id>`	`sc providers update <id> ...`, `key-add`, `key-rm`	`sc providers delete <id> --yes`
Named connections	`sc user connection-add <user> <provider> <label> ...`	`sc user connections <user> [provider]`, connection guide/status	label, default, authorize, sync, and migration commands	`sc user connection-rm <user> <provider> <connection> ...`
Credentials	`sc user credential-set <user> <provider> <KEY> --connection <id>`	`credential-status`; plaintext reads are intentionally disabled	run `credential-set` again to rotate	`sc user credential-rm <user> <provider> <KEY> --connection <id>`
Skills	`sc skill create <name> ...`	`sc skills`, `sc skill show <name	exact-id>`	`sc skill update <name

Skill CRUD

Create a project skill:

sc skill create release-check \
  --description "Verify release, security, rollback, and live health before handoff"

It becomes:

.si-coder/skills/release-check/SKILL.md

and is discoverable as:

/release-check

Create a global operator skill instead:

sc skill create release-check \
  --scope global \
  --description "Shared release readiness workflow"

Global managed skills live in:

~/.si-coder/skills/<name>/SKILL.md

Read, replace, update, and delete:

sc skills
sc skills --json
sc skill show release-check
sc skill show release-check --raw
sc skill update release-check --description "Verify release plus rollback readiness"
sc skill update release-check --from-file ./SKILL.md
sc skill delete release-check --yes

For long instructions, prefer --from-file SKILL.md instead of putting the full skill body in argv or shell history.

Bundled SI-Coder skills under skills/* are package source and read-only at runtime. Project skills live in .si-coder/skills; global operator skills live in ~/.si-coder/skills. Project scope wins normal same-name resolution, while /skill <exact-id> remains the explicit ambiguity escape hatch.

The shared invocation contract is:

/skills                         discover available skills
/<skill> [prompt]               invoke the normal resolved skill
/skill <exact-id> [prompt]      choose an exact project/global skill when needed

Find skills by keyword

Skill discovery is not tag-only. SC ranks the canonical name/slash invocation, Agent Skills description, derived/declared tags, aliases, and scope/source context. Existing skills remain searchable without a metadata migration because missing search metadata is derived at index time.

sc skills ui
sc skills "accessibility mobile"
sc-skill ui
sc-skill "deploy production"

The Finder/TUI uses the same fuzzy, multi-token matcher, so typing interfce in Skills can still surface interface/UI skills.

For new skills, do not maintain a taxonomy by hand. Use:

sc-skill --new

In a non-interactive agent shell, that returns the machine-readable creation/install contract: what is required, what SC derives automatically, and how to verify the new skill. A concise new skill can be created with:

sc-skill --new ui-audit \
  --description "Audit visual hierarchy, spacing, typography, responsive states, accessibility, and design-system consistency."

SC derives metadata.sc.tags and metadata.sc.aliases from the skill's name, description, and use_when. Manual --tags / --aliases are correction tools only. A precise description remains the primary discovery/activation metadata.

To install an existing Agent Skill that contains scripts, references, assets, or templates, preserve the whole bundle:

sc-skill --new --from-dir ./downloaded-skill

The bundle is inspected/copied without following symlinks, bounded by file/byte limits, validated as a skill, and rolled back on failure. Use --from-file SKILL.md only for a truly single-file skill.

The normal workflow

Same path as the diagram above — goal → understand → build → connect → publish → verify.

For a vague new idea, SC may ask a small number of product questions. If it can infer a reasonable default, it should continue instead of turning the request into a requirements workshop.

For an existing project, just describe the change you want:

/sc Make the dashboard responsive and fix the broken mobile navigation.

For deployment:

/sc Publish this app and verify the login flow.

For a provider integration:

/sc Connect transactional email for password reset.

The main sc skill routes internally to the appropriate workflow. Normal users should not need to choose a sub-skill themselves.

Move users and connections between projects

sc data export --out users.integration-bundle.json
sc data export --include-secrets --out users.integration-bundle.enc.json
sc data import --file users.integration-bundle.json

Plain JSON contains metadata only. Encrypted transfers prompt locally for a passphrase. Import previews conflicts before an explicitly confirmed create-only apply; no default, folder mapping, or active OAuth session is copied. The browser manager also has Import / export JSON. Receiving projects use the documented versioned bundle and their own import adapter; no other application is required to run SI-Coder.

Data portability and schema.

Set credentials without pasting into chat

sc setup --web

The temporary browser hub automatically uses a private Tailscale Serve URL when the VPS is already on a tailnet, with a localhost/SSH fallback. It includes every registered provider, user selection, named connections, source/auth methods, official links, expandable instructions, masked inputs, and verification before saving. Run it in an interactive terminal.

For VPS access, use SSH port forwarding rather than exposing the local port. See Secure credential setup.

Installation

Already have SC installed in your agent? Skip this section and just use sc.

The canonical source is the skills/sc/ directory containing SKILL.md. Different AI clients use different installation transports, so the exact install step varies by surface.

Installation by client

Installation format matrix

Generated from docs/install/README.md. Do not edit this matrix here.

Surface	What it installs/reads	Recommended SI-Coder link	Invocation
Claude Code	Plugin marketplace, or a skill directory containing `SKILL.md`	GitHub repo / sc skill directory	`/sc`
Claude Web / claude.ai	ZIP containing the skill folder	Download `sc.zip`	Automatic when relevant
Codex CLI / app	GitHub skill directory containing `SKILL.md`	sc skill directory plus core sibling skills	Client-specific / automatic
ChatGPT uploaded Skills (eligible workspaces)	Uploaded skill package; canonical content is a folder with `SKILL.md`	Download `sc.zip`	Automatic or `@sc`
ChatGPT managed workspace	GitHub plugin marketplace	GitHub repo	`@SI-Coder` / plugin picker / automatic
Hermes / OpenClaw / generic Agent Skills	Skill directory containing `SKILL.md`	sc skill directory or `install.sh`	Runtime-specific
Client that explicitly supports `.skill` archives	`.skill` archive containing a normal skill directory	Download optional `sc.skill`	Client-specific

Detailed guides:

If an AI agent is given only this repository URL and asked to install SC, it should read AI_INSTALL.md and choose the appropriate path automatically.

Claude Code

/plugin marketplace add rahmanef63/si-coder-agent
/plugin install si-coder@si-coder-marketplace

Then:

/sc Create a booking app for my salon.

Local Agent Skills runtimes

Requires Node.js 22, 24, or 26. The installer reads skills/catalog.json and installs active/default skills only; unfinished/legacy skills are kept out of normal routing.

bash install.sh --agent claude
bash install.sh --agent codex
bash install.sh --agent hermes
bash install.sh --agent openclaw
See [optional host adapters](docs/integrations/plugins/README.md) for host-specific integrations.
bash install.sh --agent all

Use --with-mcp only when the local runtime should also register SC's bundled MCP server.

Accounts and credentials

SC should never ask you to paste a password, API key, or access token into chat or machine-tool JSON.

When account access is required, SC should tell you:

which service/account is needed,
why it is needed,
the safest supported way to connect it,
how SC will verify the connection.

Hosted agents should prefer secure connected-account authorization. On a fresh local install, sc setup creates/selects a user and named provider connection first; direct credentials are stored only in that connection's 0600 file. Fresh setup does not write provider secrets to ~/.bashrc.

See first-run account onboarding for the detailed model.

One recommendation, not a backlog dump

After a meaningful milestone, SC may return one next step:

[rekomendasi]
Next : Add transactional email
Why  : Password reset needs reliable delivery.

The point is to keep the workflow moving without overwhelming the user with an internal engineering backlog.

Advanced usage

Everything below is optional for normal SC users.

Local CLI and provider connections

Running sc on a TTY opens the local interactive CLI. It is useful for operators who want to inspect users, provider connections, deployment plans, skills, or diagnostics directly. The Finder root also includes Import / export JSON, so portability is discoverable without memorizing sc data ... commands. Esc goes back one level; inside a credential/metadata input it cancels that input without saving or exiting SC. The lower INFO/PREVIEW/RESULT area expands on taller terminals so setup guidance is easier to read.

sc doctor
sc deploy plan
sc deploy plan --technical
sc user connections <user>
sc skills

Direct local connections are user/account scoped. External OAuth or connected-account backends keep their provider tokens outside SC and store only safe routing metadata locally.

See CLI navigation and account ownership.

MCP and machine tools

SC exposes a machine-readable tool surface for compatible agents through the bundled MCP server.

Machine-function SSOT: machine/functions.json
MCP server: scripts/sc-mcp.js
Tool documentation: docs/tool-calling.md

This is an integration surface for agents. A normal user does not need to call these functions manually.

Agent memory, evidence, recipes, and verification

SC also contains repo-local engineering safeguards used while maintaining SC itself:

sc task prepare "change provider auth routing" --json
sc memory query "provider auth" --json
sc skill verify --strict
sc verify
npm run verify:release

These features help an engineering agent reuse relevant past debugging/test knowledge, classify risky maintenance work, keep compact verification evidence, and promote repeated maintenance work into verified recipes/scripts.

They are maintenance infrastructure, not concepts a normal SC user needs to learn before using the tool.

See agent workflow and repo-local memory.

Design principles

SC should remain:

Simple at the surface — one main tool/skill for normal use.
Product-first — ask about desired behavior before infrastructure choices.
Agent-friendly — technical capabilities are machine-readable when an agent needs them.
CRUD-capable for operator-owned resources — users, provider definitions, connections, credentials, and managed skills can be inspected and changed explicitly.
Safe with credentials — secrets do not travel through chat/tool payloads; fresh local setup is named-connection-scoped rather than shell-global.
Verifiable — completion means the important result was actually checked.
Standalone — this repository owns its runtime contracts and does not require another local project or orchestrator to function.
Progressively disclosed — advanced internals stay available without dominating the main user experience.

Repository map

Only the major surfaces are shown here:

skills/sc/               main user-facing bundled skill
skills/sc-*/             bundled specialized workflows
.si-coder/skills/             project-managed slash skills
~/.si-coder/skills/          global operator-managed slash skills
bin/sc-entry.js          installed CLI entry + portable skill registry/CRUD
bin/sc.js                mature local control plane + Finder TUI
machine/functions.json   machine-tool contract
scripts/sc-mcp.js        MCP server
docs/                    detailed documentation
.agent/                  repo-maintenance memory/evidence/recipes

Development

For contributors and maintainers:

npm test
npm run docs:check
node bin/sc.js skill verify --strict
npm run verify:release
npm pack --dry-run

Release checks cover regression tests, lifecycle catalog validation, repository-wide secret scanning, skill validation, portable package contents, documentation consistency, and deterministic generated artifacts. Tagged releases rerun the full gate and verify public reachability before GitHub Release publication.

Documentation

If you only want to use SC, you can ignore those internals and start with:

@sc Build or change the app I describe, publish it when needed, and verify the result.