agent-smith

name	agent-smith
description	Architect, create, review, migrate, validate, and maintain Agent Skills, agents, hooks, plugins, and marketplaces for Claude Code, Codex, and Cursor. Use when building or auditing an agent capability layer or keeping multiple harnesses in sync.

Agent Smith

Design and maintain agent capability layers without letting their Claude Code, Codex, and Cursor representations drift.

Treat skills as the portable core. Treat manifests, agents, hooks, MCP configuration, rules, and settings as harness adapters.

Resolve bundled resources

Determine the directory containing this SKILL.md and call it SKILL_ROOT. Resolve every bundled script, reference, and template relative to that directory. Do not depend on a harness-specific environment variable.

Use these resources only when relevant:

• Read references/principles.md before creating or reviewing components.
• Read references/format-reference.md for portable skill metadata.
• Read references/harness-reference.md before generating an adapter.
• Read references/repository-topologies.md for detection, symlinks, or migration.
• Read references/plugin-reference.md for plugins or marketplaces.
• Read references/index-schema.md before creating or updating the index.

1. Inspect before deciding

Find the repository that contains the working directory. Prefer the nearest Git root. If there is no Git root, use the requested directory as a new-repository candidate.

Run the deterministic inspector when Python is available:

python3 "<SKILL_ROOT>/scripts/inspect_repository.py" "<target>" --json

Otherwise perform the checks in references/repository-topologies.md manually.

The inspection establishes two independent properties:

• Topology: project, plugin, or marketplace.
• Targets: any combination of claude, codex, and cursor.

Also inspect the technology stack, repository instructions, naming conventions, existing components, index, symlinks, and working-tree state. Preserve unrelated user changes.

When to ask

Ask the user before choosing a topology or target set when:

• The directory is new or has no agent-layer evidence.
• Only .agents/skills exists, so Codex and Cursor cannot be distinguished.
• Marketplace manifests map the same plugin name to different local directories.
• The requested change would add a harness not already detected.
• Two plausible canonical sources contain different content.

Otherwise report the inferred topology and targets in the pre-write summary and continue.

Never infer a harness solely from a generic instruction file such as AGENTS.md or CLAUDE.md.

2. Classify the request

Map the request to one or more flows:

• Create: add a skill, agent, hook, script, plugin, or marketplace.
• Review: improve a named component.
• Audit: inspect the whole component graph for drift, gaps, or redundancy.
• Setup: initialize a project, plugin, or marketplace.
• Migrate: adopt canonical paths, convert legacy commands, or add harnesses.
• Validate: run structural and parity checks.
• Index: build or refresh .agent-smith/index.json.

If the target component is unclear and repository inspection cannot resolve it, ask a focused question.

3. Apply the architecture invariants

Project repositories

• Store each canonical skill once at .agents/skills/<skill-name>/.
• Let Codex and Cursor consume .agents/skills directly.
• For Claude, create .claude/skills/<skill-name> as a relative symlink to the canonical directory.
• If symlinks are unavailable, create a copy, record status: copied and sourceHash in the index, and validate drift.
• Do not create redundant .cursor/skills or .codex/skills copies.

Plugin repositories

• Store each skill once under skills/.
• Point .claude-plugin/plugin.json, .codex-plugin/plugin.json, and .cursor-plugin/plugin.json at the same skill tree according to their native schemas.
• Keep harness-specific manifests and adapters separate.
• Do not use symlinks for the shared plugin skill tree.

Marketplace repositories

• Parse each native marketplace independently.
• Match logical plugins by normalized local source directory, never by array position.
• Aggregate only local plugins managed by the repository.
• Report external sources as unverified and do not modify them.
• Stop when the same plugin name resolves to different local directories until the user chooses the intended mapping.

Compatibility states

Represent every target/component pair as one of:

• shared: one artifact is consumed unchanged by multiple harnesses.
• native: the canonical artifact already uses the target format.
• symlink: a harness path resolves to the canonical artifact.
• copied: a fallback copy is protected by a content hash.
• Gap unacknowledged, accepted, or resolved: no truthful equivalent currently exists.

Never claim parity because files merely have similar names. Compare behavior, trigger conditions, permissions, lifecycle, and referenced resources.

4. Prepare changes

Before writing, show the user:

• Detected repository root, topology, and targets.
• Canonical files to create or modify.
• Adapters and symlinks to create.
• Migrations, moves, replacements, or deletions.
• Compatibility gaps and their impact.
• Validation commands that will run.

For a new repository, include the selected topology and target set explicitly. For an existing repository, call out any expansion beyond its detected targets.

Wait for confirmation before structural writes. A confirmation that includes listed gaps changes those gaps from unacknowledged to accepted in the index.

5. Execute the selected flow

Create a skill

1. Check the index and filesystem for an overlapping capability.
2. Read references/principles.md, references/format-reference.md, and references/templates/skill.md.
3. Create the skill in the topology's canonical skill root.
4. Use only portable frontmatter for a shared skill. Put harness-only behavior in adapters or document a gap.
5. Keep SKILL.md under 500 lines and place detailed material in references/, repeated deterministic work in scripts/, and output resources in assets/.
6. Create project symlinks or fallback copies for required targets.
7. Update the index and validate.

Create an agent or hook

1. Define the logical behavior and required capabilities.
2. Read references/harness-reference.md and the matching templates under references/templates/.
3. Generate a native adapter for each supported target.
4. Preserve equivalent intent while translating model, tools, permissions, sandbox, and lifecycle fields.
5. Record unsupported fields as explicit gaps. Do not silently discard them.
6. Update the index and validate.

Set up a project

1. Confirm targets because a new directory has no reliable harness evidence.
2. Create .agents/skills and .agent-smith/index.json.
3. Create harness directories only when an adapter requires them.
4. If Claude is selected, create one relative symlink per skill rather than symlinking the whole .claude/skills directory.
5. Optionally create the first component only if the user requested it.

Set up a plugin

1. Read references/plugin-reference.md.
2. Create skills/ and one native plugin manifest per selected target.
3. Keep identity fields aligned across manifests.
4. Add adapter directories only for components the plugin actually contains.
5. Create .agent-smith/index.json and validate every manifest.

Set up or modify a marketplace

1. Read and normalize all existing marketplace manifests.
2. Confirm the mapping when native catalogs disagree.
3. Add each local plugin to the selected native catalogs using their required source shape.
4. Keep remote sources untouched.
5. Validate catalogs individually and then validate cross-catalog logical parity.

Review

1. Read the target and all referenced supporting files.
2. Evaluate focus, triggering, naming, permissions, size, portability, failure handling, and adapter parity.
3. Report critical issues, improvements, and optional suggestions.
4. If changes are authorized, update canonical content first, then adapters, index, and validation.

Audit

1. Rebuild the component view from the filesystem rather than trusting the index.
2. Detect duplicate sources, copied drift, broken or escaping symlinks, stale index entries, manifest conflicts, unsupported extensions, and unacknowledged gaps.
3. Compare behavior across adapters.
4. Separate fixable drift from legitimate accepted gaps.
5. Report health by plugin and harness for marketplaces.

Migrate

Read references/repository-topologies.md and preview every path change.

For Claude project skills moving to .agents/skills:

1. Copy the legacy directory to the canonical destination.
2. Compare the complete content hash.
3. Replace the legacy directory with a relative symlink only after equality is proven.
4. Validate discovery and references.
5. Restore the original layout if any step fails.

For an index v1, preview migration with:

python3 "<SKILL_ROOT>/scripts/migrate_index.py" "<target>"

After confirmation, add --write. Preserve the legacy file until the v2 index and repository validate successfully.

For legacy commands/, convert each command into a named skill directory, preserve its intent and arguments, update external references, then validate.

Validate

Run:

python3 "<SKILL_ROOT>/scripts/validate_repository.py" "<target>"

Use --json when another tool will consume the result. Fix errors before declaring success. Report warnings, especially accepted gaps and unverified external plugins.

Index

Read references/index-schema.md. Rebuild from the filesystem, retain accepted product decisions, and diff against the existing index. Never preserve a stale path merely because it exists in the old index.

6. Finish and report

After any change:

1. Validate canonical skills, adapters, manifests, symlinks, copies, and index.
2. Run harness-native smoke tests when the relevant CLI and authentication are available.
3. Mark an unavailable runtime as not run, never as passed.
4. Summarize canonical changes, adapters, accepted gaps, migrations, and verification results.

General rules

• Match the user's language.
• Follow repository instructions and user conventions over built-in defaults.
• Use the minimum permissions required.
• Keep skill content portable; isolate vendor extensions.
• Prefer composition over duplication.
• Do not mutate external marketplace sources.
• Do not overwrite divergent copies or canonical candidates without explicit direction.
• Confirm destructive actions and provide a recovery path.