01 / Consumer path
Use a workflow without skipping the review step.
The shortest safe path is find → inspect → dry-run → install → verify. The add command copies files into your project; it does not execute the workflow.
01
Find
Search the directory index by repository or workflow name. This command only reads search results.
Search the directoryshellnpx --yes smithers-directory find code-review02
Inspect
Open a result to review its workflow source, required env vars, capability signals, docs, and source ref. You can also ask the CLI to discover a repository and print its workflow names without installing anything.
List workflows in a sourceshellnpx --yes smithers-directory add owner/repo --list--listexits after discovery. It does not show an install chooser and does not write files.03
Choose and preview
With a TTY and multiple workflows, an add command without a selector opens the interactive chooser. Select one workflow, several named workflows, or every workflow explicitly before a non-interactive run.
Selection and dry-run formsshell# Human chooser, followed by a confirmation prompt npx smithers-directory add owner/repo # Preview one workflow without writing npx --yes smithers-directory add owner/repo@workflow-name --dry-run # Preview every discovered workflow explicitly npx --yes smithers-directory add owner/repo --all --dry-run--allis an explicit selection; it does not open the chooser.--dry-runprints the resolved workflow/file counts and requirements without writing files or updating the lock file. Review the exact source-to-destination mappings on a workflow detail page.04
Install
Use an exact selection for agents and CI. Notice the two different approvals:
npx --yesskips npm's package-download prompt, while the trailing--yesconfirms the Smithers install.Non-interactive installsshell# One workflow npx --yes smithers-directory add owner/repo@workflow-name --yes # A named set npx --yes smithers-directory add owner/repo --workflows code-review,lint --yes # Everything currently discovered in the source npx --yes smithers-directory add owner/repo --all --yes05
List, check, update
The lock file drives local inventory and updates. List reads the lock; check verifies that locked workflow entries and docs still exist; update re-installs every unique locked source using all workflows from that source.
Project upkeepshellnpx --yes smithers-directory list npx --yes smithers-directory check # Preview sources before replacing local files npx --yes smithers-directory update --dry-run # Re-install every unique lockfile source npx --yes smithers-directory updateUse
list --jsonandcheck --jsonfor machine-readable output. A JSON check exits with code 1 when a locked entry or doc is missing.
02 / Consumer reference
Know what selection and installation actually do.
Workflow selection and install confirmation are separate decisions. The resulting plan maps repository files into .smithers with deterministic destinations.
| Selection | Behavior | Confirmation |
|---|---|---|
| no selector | One workflow continues directly. Multiple workflows open a chooser only when a TTY is available. | Prompts in a TTY. |
| @name / --workflow(s) | Installs the exact named workflow or set. | Pass --yes or --dry-run without a TTY. |
| --all | Selects every workflow; no chooser is shown. | Pass --yes or --dry-run without a TTY. |
Destination mappings
The workflow name determines its entry destination. Declared support paths keep their repository-relative shape under.smithers; docs always move under .smithers/docs.
| Repository source | Consumer destination |
|---|---|
| workflows/audit.tsx | .smithers/workflows/audit.tsx |
| .smithers/lib/audit/index.ts | .smithers/lib/audit/index.ts |
| components/audit/index.ts | .smithers/components/audit/index.ts |
| docs/audit.md | .smithers/docs/audit.md |
| guides/audit.mdx | .smithers/docs/guides/audit.mdx |
Replace
Existing destinations are replaced deterministically during an install.
Roll back
If a copy fails, files written by that command are rolled back and the lock file is not updated.
Do not run
Add copies workflow files. Execution is a separate action in smithers-orchestrator.
03 / Publisher path
Publish the smallest honest contract.
A manifest is optional. Auto-discovery is enough for a simple repository; a manifest is recommended when consumers need explicit metadata, support files, or operator docs.
Option A / zero config
Use auto-discovery
Without a manifest, JavaScript and TypeScript workflow files are discovered under workflows/ and .smithers/workflows/. Names come from filenames and capability signals are inferred from source.
Option B / recommended
Add a manifest
Add smithers-directory.json at the repository root to declare exact entries, descriptions, tags, env vars, capabilities, support paths, and docs.
# Either directory works without a manifest
workflows/
code-review.tsx
.smithers/workflows/
incident-response.tsTest discovery before publishing
List what the CLI discovers, then build a dry-run plan for the exact workflow set consumers should receive.
npx --yes smithers-directory add owner/repo --list
npx --yes smithers-directory add owner/repo --all --dry-runFinal publishing step
Add the public GitHub repository
Directory discovery checks the workflow entries and declared docs. It does not validate imported modules or declared support files during submission.
04 / Publisher reference
Describe each workflow at the repository root.
The manifest makes the install boundary reviewable. Every workflow needs a name and entry; the remaining fields let consumers understand and install it deliberately.
{
"name": "code-review-workflows",
"description": "Smithers workflows for code review.",
"workflows": [
{
"name": "code-review",
"entry": "workflows/code-review.tsx",
"description": "Reviews a repo and waits for approval.",
"tags": ["code-review"],
"env": ["ANTHROPIC_API_KEY"],
"capabilities": ["agent", "shell", "approval"],
"files": ["components/code-review", "prompts/code-review.mdx"],
"docs": [
{
"title": "Operator guide",
"path": "docs/code-review.md",
"summary": "Inputs, approvals, and safe operating notes.",
"showOnInstall": true,
"exampleCommand": "bunx smithers-orchestrator workflow run code-review --input '{...}'"
}
]
}
]
}| Field | Required | Contract |
|---|---|---|
| name, entry | Yes | Consumer-facing workflow name and repository-relative source file. |
| description, tags | No | Discovery and review context. |
| env, capabilities | No | Declared operating requirements and capability signals; detected signals are added from entry source. |
| files | No | Exact support files or directories installed with the selected workflow. |
| docs | No | Markdown operator guides copied under .smithers/docs. |
05 / Publisher reference
Make the copied file boundary explicit.
The entry is always installed. The files field controls additional support-file discovery, while docs defines durable guidance for operators and agents.
Support files: absent is different from empty
files omitted
Compatibility discovery may include eligible workflow, component, and prompt files based on repository layout.
files: []
Explicitly disables legacy support-file discovery. The entry and any declared docs are still installed.
files: ["…"]
Installs only those declared support paths with the entry and docs for the selected workflow.
{
"name": "quality-check",
"entry": ".smithers/workflows/quality-check.tsx",
"files": [".smithers/lib/quality"]
}files entries are repo-root-relative files or directories. Paths already under .smithers/preserve that destination; other paths are prefixed with .smithers/. Directory expansion needs the repository file list, so exact file paths are more reliable for public, no-token installs.
Operator docs
Use docs for required inputs, run modes, approval behavior, and operational caveats that should survive terminal scrollback. A workflow can declare up to eight docs.
Required
title: non-empty display name, up to 120 characters.path: safe repo-relative.mdor.mdxfile, up to 260 characters.
Optional
summary: post-install context, up to 280 characters.showOnInstall: shown unless explicitly false.exampleCommand: quick-run command, up to 400 characters.
For each workflow, install output shows up to three visible guides plus one quick-run command. list, list --json, check, and check --json surface installed doc paths. Duplicate doc paths are accepted only when their metadata is identical.
{
"name": "code-review",
"entry": "workflows/code-review.tsx",
"operatorGuide": "docs/code-review.md"
}operatorGuide remains a compatibility alias for one doc. Do not define it together with docs.
Declared support and doc path safety rejects absolute paths, traversal segments, generated top-level directories, node_modules, .git, and Smithers runtime directories. Local installs also reject symlink resolutions that leave the source root.
06 / Automation and upkeep
Make every non-interactive choice explicit.
Without a TTY, the CLI never prompts. Missing selection or confirmation flags produce guidance and exit code 2; -n or --non-interactive gives the same fail-fast behavior in a terminal.
# Read the current command contract
npx --yes smithers-directory add --help
# Discover, select, then install without prompts
npx --yes smithers-directory add owner/repo --list
npx --yes smithers-directory add owner/repo --workflows code-review,lint --yes
# Pin a branch, tag, or preferably a full commit SHA
npx --yes smithers-directory add owner/repo --workflow code-review --ref <ref> --yesSource forms
- owner/repo
- owner/repo@workflow
- owner/repo#branch
- owner/repo#branch@workflow
- ./local-path
- github:owner/repo
Environment
- GITHUB_TOKEN
- Optional for higher API limits and CLI access to private repositories.
- SMITHERS_DIRECTORY_NO_INPUT=1
- Forces non-interactive behavior.
07 / Trust boundary
Treat repository contents as code, not catalog metadata.
The directory helps you discover and copy workflows. It is not a sandbox, a dependency verifier, or proof that a workflow is safe to run.
Mutable refs
owner/repo resolves the source again when the command runs. Branches and tags can also move; use a full commit SHA with --ref for an immutable Git object. Review the source at that exact ref.
Updates
The lock records workflow identity and installed paths, not the original ref. update re-resolves each unique source and installs all workflows currently found there. Preview it, and pass a specific --refwhen reproducibility matters. One update-level ref applies to every source processed by that command.
Signals, not proof
Declared env vars and capabilities help review; detected capabilities are source-pattern signals. Discovery reads workflow entries and declared docs, but it does not prove that imports, dependencies, support files, or runtime behavior are safe.
Independent
smithers.directory is an independent community directory and is not affiliated with smithers.sh. Review workflow source, required env vars, capabilities, and destinations before installing or running it in a production environment.
Ready to publish?
Test discovery, review the install plan, then add the public repository to the directory.