comparison / P1
Fygment vs hand-edited agent configs
A practical comparison of hand-edited agent config files, scripts, snippets, and a governed Skills and MCP setup workflow.
Hand-edited agent config is fine for a small personal setup, but teams eventually need governed packages, reproducible installs, approvals, and visible setup health.
Short version
Direct answer
Hand-edited JSON, copied MCP snippets, and local shell scripts are enough when one person owns the setup, the tool is low-risk, and changing it does not need review. A governed registry and package-manager approach is better when multiple people need the same Skill or MCP setup, approved versions matter, and stale or unsafe installs need to be visible before an agent runs them.
Where manual config is still reasonable
A simple local config is often the right first move. If you are testing one MCP server, wiring a private one-off tool, or keeping a personal Skill folder for a project, editing the harness config directly keeps friction low.
The tradeoff is that the config file becomes the system of record. That is fine while the owner, target path, version, risk, and update rule all fit in one person's head.
Config approaches compared
These approaches can coexist. The question is which one should be the source of truth as the setup becomes shared.
| Approach | Best for | Team risk | Fygment fit |
|---|---|---|---|
| Hand-edited harness config | One-person experiments, temporary local tools, and low-risk private MCP setup. | Stale versions, inconsistent target paths, silent edits, no approvals, no audit trail, and no reproducible install state. | Use direct config when speed matters more than governance. Move shared Skills or team setup into Fygment once drift starts costing time. |
| Scripts and copied snippets | Repeatable bootstrap steps, documented examples, and quick setup for a known environment. | Snippets age quickly, scripts rarely prove what is already installed, and teammates may run different revisions without team visibility. | Keep scripts as helpers, but let the registry own package identity, approved versions, lifecycle state, and install or check/update decisions. |
| Fygment-managed Skills and MCP setup | Shared agent capabilities that need owners, review, version history, approved install state, and health checks across supported AI harnesses and MCP clients. | More process than a single config file, and some setup surfaces are still Alpha rather than full enterprise automation. | Use Fygment when the team needs a governed source of truth, reproducible Skill installs, setup health, approvals, and a clear Live now, Alpha, and Roadmap boundary. |
What usually fails first
Manual setup does not usually fail because JSON is bad. It fails because local files cannot answer team questions.
- 1
Stale versions
A teammate keeps an old Skill or MCP command because nothing compares local state with the approved package version.
- 2
No approval path
A risky prompt, script, or server change becomes active by editing a file instead of moving through review.
- 3
No audit trail
When behavior changes, the team cannot see who changed the setup, what version changed, or why the change was accepted.
- 4
Inconsistent target paths
Codex, Claude Code, Claude Desktop, Cursor, Gemini, and custom MCP clients each expect different local paths or config shapes, so setup drifts by harness.
- 5
No reproducibility
A new machine cannot recreate the intended setup from a portable lockfile and dry-run plan.
- 6
No team visibility
Owners cannot tell which installs are current, stale, blocked, revoked, or unsupported without inspecting someone else's machine.
The Fygment approach
Fygment keeps the local path fast while adding a governed package workflow around it.
- 1
`npx fygment` setup
The CLI is the guided entrypoint for supported local setup, including readiness checks before a user mutates a harness config.
- 2
Setup health
Readiness and doctor-style checks explain auth, workspace, install registry, target roots, and lockfile state without exposing tokens or raw local paths by default.
- 3
Install, check, and update
Fygment install/check/update flows compare local Skill state with approved versions and surface current, stale, required update, blocked, revoked, and unsupported states.
- 4
Lockfile and local inventory
`fygment.lock`, `fygment list`, and `fygment sync --lock=...` make Skills-only local setup reproducible across supported local harness targets while leaving unmanaged files alone.
- 5
Approvals and lifecycle states
Owners and admins can govern Skill versions through approval, rejection, deprecation, blocking, revocation, rollback, and audit-backed history.
Availability boundaries
This comparison is intentionally candid about what is live, what is alpha, and what remains roadmap work.
Live now
Governed Skills registry and lifecycle for controlled pilots
Fygment supports the core registry, package evidence, approvals, version lifecycle, audit history, install/check/update concepts, and public resource guidance for pilot workspaces.
Alpha
CLI, lockfile, local inventory, and MCP setup helpers
`npx fygment`, setup readiness, Skills-only lockfiles, local inventory, sync, and MCP setup guidance are available as early workflows with explicit supported targets and diagnostics.
Roadmap
Enterprise identity, secret vaulting, marketplace, and broad automation
Fygment is not yet a full enterprise identity product, a third-party secret vault, a public marketplace, or a complete MCP server lifecycle manager. SSO, self-hosting, curated marketplace workflows, policy rollouts, and deeper automation remain sequenced roadmap work.
Auth-aware next step
If you are evaluating Fygment publicly, start with the related resources on AI Skills registries, MCP setup for teams, and portable AI harness Skill management. If you already have a Fygment workspace, sign in and use the workspace setup and catalog surfaces to inspect readiness, approvals, installs, and update state.
Public pages should not expose workspace-only routes as anonymous destinations. The anonymous call to action is to understand the model; the authenticated call to action is to review your own workspace state after sign-in.
FAQ
Should I stop hand-editing agent config files?
No. Hand-edited config is still a good fit for personal experiments, temporary tools, and one-off local setup. Move to a governed workflow when the setup becomes shared, reviewable, or safety-sensitive.
Are scripts and snippets bad?
No. Scripts and snippets are useful helpers, but they should not be the only source of truth for approved Skills, lifecycle state, update policy, or reproducible team setup.
What does Fygment add over a copied JSON block?
Fygment adds registry metadata, package evidence, approved versions, lifecycle state, audit history, setup health, install/check/update workflows, and a Skills-only lockfile/local inventory path for supported targets.
Does Fygment manage every MCP server automatically today?
No. MCP setup is Alpha. Fygment provides guided setup, hosted-agent URL guidance, OAuth health, local editor setup, and diagnostics, but full MCP server lifecycle management remains outside the live claim.
Is Fygment an enterprise identity provider, marketplace, or secret vault?
No. Those are explicit limitations today. Fygment focuses first on governed Skills, package lifecycle, approvals, setup health, and reproducible local inventory while SSO, public marketplace workflows, and secret-vault features remain roadmap work.
Which related resource should I read next?
Read "How teams should manage MCP setup" for connector setup boundaries, "Managing portable Skills across AI harnesses" for Skill portability, and "What is an AI Skills registry?" for the broader registry model.
Related resources
- How teams should manage MCP setup
MCP setup should be managed as shared configuration with ownership, review, install instructions, and a clear boundary between local credentials and team policy.
- Managing portable Skills across AI harnesses
Portable Skills become manageable when a governed registry, the fygment CLI, local inventory, lockfiles, and check/update flows keep supported harness installs reviewable.
- What is an AI Skills registry?
An AI Skills registry is the shared inventory, review surface, and package lifecycle for reusable agent capabilities that need ownership, versioning, and install state.