How to Install Agent Skills Safely

Before you copy anything

Installing an Agent Skill usually means placing its directory where your client scans for skills. That simplicity is useful, but it also means you are adding instructions—and sometimes code—that can influence agent behavior.

Inspect the complete directory first. Confirm the exact SKILL.md, read every referenced file, and identify scripts, network access, credentials, and write operations. A repository homepage is not enough evidence when several skills live in the same project.

Validate the portable structure

At minimum, the directory needs a SKILL.md with valid name and description frontmatter. The Agent Skills specification requires the name to match the parent directory and documents optional scripts/, references/, and assets/ folders.

Use a layout like:

my-skill/
├── SKILL.md
├── references/
│   └── REFERENCE.md
└── scripts/
    └── validate.js

Do not flatten the directory or copy only the main file when its instructions depend on bundled resources.

Install for Codex

Current Codex clients discover repository-scoped skills from .agents/skills directories between the working directory and repository root. Personal skills can live in $HOME/.agents/skills.

For a repository-scoped install:

your-repository/
└── .agents/
    └── skills/
        └── my-skill/
            └── SKILL.md

Choose repository scope when the workflow belongs with the codebase and should be reviewed in version control. Choose user scope for a personal workflow that applies across repositories. Codex also provides $skill-installer for supported curated or repository installs. The official Codex skills guide documents current discovery locations, explicit invocation, and disable controls.

Codex detects most skill changes automatically. If a new or edited skill does not appear, restart the client before diagnosing the file.

Install for Claude Code

Claude Code uses:

• .claude/skills/<skill-name>/SKILL.md for project skills.
• ~/.claude/skills/<skill-name>/SKILL.md for personal skills.

A project skill can be committed with the repository. A personal skill remains local to the user. Claude Code can load a matching skill automatically or invoke it directly as /skill-name. Its skills documentation also describes product-specific frontmatter beyond the portable standard.

If portability matters, keep the core workflow valid against the open specification and isolate client-only behavior behind clearly labeled compatibility notes.

Verify discovery and behavior

Installation is not finished when the files exist. Run a small activation test:

1. Start a fresh client session.
2. Ask a direct request that should activate the skill.
3. Ask an indirect request expressing the same goal.
4. Ask a nearby request that should not activate it.
5. Confirm referenced files resolve from the skill root.
6. Run scripts only with test data and the minimum permissions required.
7. Compare the output with the workflow's stated success criteria.

If activation is inconsistent, improve the description before adding more body instructions. Discovery depends heavily on a precise explanation of what the skill does and when to use it.

Keep secrets out of the skill

Do not commit API keys, access tokens, passwords, private endpoints, or production credentials inside SKILL.md, scripts, examples, or copied configuration. Document the expected environment-variable name and let the client or runtime provide the value.

A skill that requires a live system should state:

• Which service it contacts.
• Which credential it expects.
• Whether access is read-only or write-capable.
• Which data leaves the local environment.
• Which actions need confirmation.

Update without losing provenance

Record the original source URL, exact path, and source commit when possible. Before updating:

1. Review upstream changes rather than replacing the directory blindly.
2. Recheck scripts and new dependencies.
3. Preserve intentional local changes in a separate commit or fork.
4. Repeat activation and negative-trigger tests.
5. Update the recorded source commit or content hash.

Pinning a reviewed revision provides reproducibility. Automatically following a moving branch trades that reproducibility for convenience.

Disable or remove cleanly

To remove a repository skill, delete its exact directory in a reviewed change. To pause a Codex skill without deleting it, current Codex configuration supports a disabled skill entry in ~/.codex/config.toml; restart after changing that file.

After removal, start a fresh session and verify that explicit and implicit activation no longer find the skill. Also remove any separate MCP server, environment variable, scheduled job, or external credential the workflow depended on—those are not removed merely because the skill directory is gone.