salesforce-agent-optimizer 1.0.0

Frictionless Salesforce Agent Skill for Codex, Claude Code, and GitHub Copilot.

Salesforce Agent Optimizer

Salesforce Agent Optimizer is a public, autonomous Salesforce Agent Skill packaged as the sfao Python CLI for Codex, Claude Code, and GitHub Copilot.

Current version: 1.0.0

It optimizes Salesforce delivery for AI agents through Salesforce-first solutioning, configuration-first planning, minimal reversible changes, compact local Knowledge, safe Salesforce CLI usage, least-privilege planning, destructive-operation guardrails, package.xml awareness, and token-efficient progressive disclosure.

Quick Start

uv tool install salesforce-agent-optimizer
sfao install --project --platform all
sfao knowledge init --project-root .
sfao doctor

Use uv tool install or pipx install for CLI isolation. Plain pip install works, but isolated tool installers reduce PATH and dependency friction.

Install From PyPI

uv tool install salesforce-agent-optimizer
sfao install --project --platform all
sfao knowledge init --project-root .
sfao doctor

Alternative:

pipx install salesforce-agent-optimizer
sfao install --project --platform all
sfao doctor

Install From Git Before PyPI

uv tool install git+https://github.com/<owner>/<repository>.git
sfao version
sfao install --project --platform all
sfao doctor

Alternative:

pip install git+https://github.com/<owner>/<repository>.git
sfao install --project --platform all
sfao doctor

Local Development Install

git clone https://github.com/lucabenedettini/salesforce-ai-agent-optimizer.git
cd salesforce-ai-agent-optimizer
python -m pip install -e ".[dev]"
sfao version
sfao validate
sfao doctor

What sfao Installs

For Codex:

.agents/skills/salesforce-agent-optimizer/SKILL.md
.agents/skills/salesforce-agent-optimizer/references/
.agents/skills/salesforce-agent-optimizer/scripts/
.agents/skills/salesforce-agent-optimizer/agents/openai.yaml

For Claude Code:

.claude/skills/salesforce-agent-optimizer/SKILL.md
.claude/skills/salesforce-agent-optimizer/references/
.claude/skills/salesforce-agent-optimizer/scripts/

For GitHub Copilot:

AGENTS.md
.github/copilot-instructions.md
.github/instructions/salesforce-agent-optimizer.instructions.md

Generated files contain:

<!-- Generated by salesforce-agent-optimizer. Managed by sfao. -->

sfao never overwrites or removes user-owned files silently.

Install

All agents:

sfao install --project --platform all

Only Codex:

sfao install --project --platform codex

Only Claude Code:

sfao install --project --platform claude

Only GitHub Copilot:

sfao install --project --platform copilot

Update

uv tool upgrade salesforce-agent-optimizer
sfao update --project --platform all
sfao doctor

Alternative:

pipx upgrade salesforce-agent-optimizer
sfao update --project --platform all
sfao doctor

sfao update updates only files generated by sfao. If a generated file was manually edited, it is skipped and reported.

Uninstall

sfao uninstall --project --platform all --yes
uv tool uninstall salesforce-agent-optimizer

Alternative:

sfao uninstall --project --platform all --yes
pipx uninstall salesforce-agent-optimizer

sfao uninstall removes only generated files. It keeps user-owned files and project folders such as .github, .agents, .claude, and .salesforce-agent-knowledge.

Knowledge Generation

Create or refresh compact local Salesforce project Knowledge:

sfao knowledge init --project-root .
sfao knowledge refresh --project-root .
sfao knowledge doctor --project-root .

Knowledge is written to .salesforce-agent-knowledge/ and stores summaries, indexes, hashes, source paths, wiki pages, and history. Source metadata remains the source of truth.

Optional org enrichment must use an explicit alias:

sfao knowledge refresh --project-root . --target-org my-sandbox

No org access is required by default.

Salesforce Version-Context Update

Create and validate version-context resources:

sfao version-context scaffold
sfao version-context validate

Refresh official-source context:

sfao version-context update
sfao version-context validate

The command uses official Salesforce source links only and stores concise summaries, source links, API version context, SOAP login guardrails, LWC notes, and package-version cautions.

Token Optimization And Context Compaction

The skill is designed for low-token agent work:

• Start from SKILL.md.
• Read references/routing.md.
• Load only task-relevant references.
• Consult .salesforce-agent-knowledge/ before repeated metadata reads.
• Prefer compact JSON, summaries, path lists, diffs, and focused excerpts.
• Do not paste full metadata files unless strictly necessary.
• Use --json, --summary, --compact, --max-items, and --verbose intentionally.
• After meaningful steps, compact task state into goal, current state, files changed, commands executed, validation status, risks, and next action.

Token optimization never removes destructive-operation warnings, validation errors, permission impacts, package.xml scope, or deployment risks.

Doctor And Validation

sfao doctor
sfao doctor --verbose
sfao doctor --json
sfao validate
sfao validate --verbose
sfao validate --json

Default output is concise: status first, then warnings and errors. Full diagnostics are opt-in with --verbose.

Release And Publishing

Build locally:

python -m pip install -e ".[dev]"
sfao validate
python -m build
python -m twine check dist/*

Tag release:

git tag v1.0.0
git push origin v1.0.0

The release workflow builds wheel, sdist, a versioned skill ZIP, SHA256 checksums, and release-manifest.json.

PyPI publishing uses Trusted Publishing and runs only when repository variable PUBLISH_TO_PYPI=true is set.

See docs/publishing.md.

Troubleshooting

sfao: command not found

• Run uv tool update-shell, open a new terminal, or add the tool bin directory to PATH.
• On Windows, check the user Scripts directory printed by pip.

uv: command not found

• Install uv, or use pipx install salesforce-agent-optimizer.

PyPI package not found

• Use the Git install command before PyPI publication.

Salesforce CLI sf not found

• Install the official Salesforce CLI and verify sf --version.

Skill not visible in Codex or Claude Code

• Run sfao install --project --platform codex or sfao install --project --platform claude.
• Restart the agent surface if it caches skills.

Copilot instructions not loading

• Confirm .github/copilot-instructions.md and .github/instructions/salesforce-agent-optimizer.instructions.md exist.
• Confirm the instructions file has applyTo frontmatter.

Version mismatch or stale generated files

• Run sfao update --project --platform all.
• Run sfao validate.

Invalid YAML, TOML, or frontmatter

• Run sfao validate --verbose.
• Ensure generated files were not collapsed into one line and have final LF newlines.

Windows And PowerShell Notes

• Prefer uv tool install or pipx install for a stable sfao command.
• If PowerShell cannot find sfao, reopen the terminal after PATH changes.
• If script execution policy blocks local scripts, use Python module commands such as python -m build and python scripts/validate_skill.py.

Privacy And Safety

• Do not commit Salesforce credentials, .sf/, .sfdx/, auth files, tokens, private keys, or local secrets.
• Least privilege is required during planning: inspect current access before granting permissions and grant only the minimum access needed.
• The safe Salesforce CLI facade requires explicit org aliases before org operations.
• Production org operations default to read-only inspection through the skill guardrails.
• Destructive data or metadata operations require explicit approval for the exact scope.
• Destructive CLI operations require the exact approval phrase I explicitly approve this deletion.
• Knowledge stores compact summaries and hashes, not raw secrets.

Backward Compatibility

The canonical CLI is sfao. Existing slash-command guidance remains as wrappers:

• /sf-init-project-skill maps to sfao knowledge init --project-root ..
• /sf-version-update-skill maps to sfao version-context scaffold and sfao version-context update.

Contributing

Before opening a pull request:

python -m pip install -e ".[dev]"
sfao validate
sfao doctor
python scripts/sync_agent_instructions.py --check --json
python scripts/validate_skill.py --json
python scripts/self_test.py --json
python -m pytest
python -m ruff check .
python -m build
python -m twine check dist/*