my_agent_skill

Personal agent skills packaged for Claude Code, Codex, and related agent clients.

Skills CLI

This repo can be published as a lowercase scoped npm package, for example ethan-agent-skills. npm package names cannot contain uppercase letters, so @Ethan_Zhang/skills is not valid.

One-Time Update

npx -y ethan-agent-skills@latest update

By default, update syncs package-managed skills to ~/.claude/skills. Other useful forms:

npx -y ethan-agent-skills@latest update --client codex
npx -y ethan-agent-skills@latest update --client all
npx -y ethan-agent-skills@latest update --dry-run
npx -y ethan-agent-skills@latest update --target /tmp/test-skills
npx -y ethan-agent-skills@latest list

Current common bundled skills include pdf-extract, skill-evolution, fix-my-life, smzdm-picks, and xhs-search, plus the client-specific OpenSpec OPSX skills.

The updater writes .skills-lock.json in each target skill root and only rewrites skills managed by this package. If a destination skill directory exists but is not recorded in the lock file, the updater reports a conflict and leaves that directory untouched.

Claude SessionStart Hook

Add this to user-level ~/.claude/settings.json to refresh before each Claude Code session:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y ethan-agent-skills@latest update --client claude >/dev/null 2>&1 || true",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Codex Refresh

Codex can use the same CLI:

npx -y ethan-agent-skills@latest update --client codex

For a guaranteed refresh before Codex starts, use a shell wrapper or alias:

alias codex='npx -y ethan-agent-skills@latest update --client codex >/dev/null 2>&1 || true; command codex'

Session-start hooks may update files after the current session has already loaded its skill list, so hook-based updates are safest when you only need the next session to see new skills.

Local Validation And Publish

npm install
npm run test:local
npm run pack:check
npm pack

To publish publicly:

npm login
npm publish --access public

Automated Release Workflow

This repo includes .github/workflows/publish.yml for automated publishing with npm Trusted Publishing. The package [email protected] has already been published manually, so do not create or push a v0.1.0 tag now. That tag would try to publish the same version again and fail.

One-time setup:

1. Push this repository to GitHub.
2. On npmjs.com, open the package settings for ethan-agent-skills.
3. Add a Trusted Publisher:
   • Provider: GitHub Actions
   • Organization or user: EthenZhang
   • Repository: my_agent_skill
   • Workflow filename: publish.yml Trusted Publishing uses GitHub OIDC, so no long-lived NPM_TOKEN secret is required.

Normal release flow:

npm run test:local
npm run pack:check
npm version patch
git push --follow-tags

npm version patch updates package.json and package-lock.json, creates a commit, and creates a tag like v0.1.1. Pushing the tag triggers the workflow, which runs validation and publishes the tagged version to npm.

Publishing Skill Updates

When you change a skill, a normal git push origin main only updates GitHub. It does not publish a new npm version. To make the change available through npx -y ethan-agent-skills@latest update, publish a new package version:

# Edit skill files first, then:
npm run test:local
npm run pack:check
git add .
git commit -m "Update <skill-name> skill"
npm version patch
git push --follow-tags

Use patch for routine skill edits and fixes. Use minor when adding a new skill or a meaningful new CLI capability. Use major only for breaking changes.

After the GitHub Actions publish job succeeds, users can refresh local skills:

npx -y ethan-agent-skills@latest update

For minor or major releases, use:

npm version minor
# or
npm version major
git push --follow-tags

If the workflow fails:

• Check the GitHub Actions run logs first.
• If npm says the version already exists, bump to a new version and push a new tag.
• If npm says trusted publishing is not configured, confirm the npm package settings still point to EthenZhang/my_agent_skill and publish.yml.

The workflow can also be started manually from the GitHub Actions tab, but tag pushes are the preferred release path because they tie npm versions to Git history.

Importing Existing Local Skills

Use this flow when a useful skill already exists under a local agent directory such as ~/.claude/skills/<skill-dir> and should become part of this package.

1. Choose the package destination:
   • Put cross-client skills in skills/<skill-dir>.
   • Put Claude-only skills in claude/skills/<skill-dir>.
   • Put Codex-only skills in codex/skills/<skill-dir>.
   • Put source-command or agent-only skills in agents/skills/<skill-dir>.
2. Inspect the source before copying:

SOURCE="$HOME/.claude/skills/<skill-dir>"
rg --files -uu "$SOURCE"
rg -n "(secret|password|token|api[_-]?key|PRIVATE|sk-[A-Za-z0-9])" "$SOURCE"

Do not copy real .env files, private keys, generated caches, or unrelated local state. Placeholder files such as .env.example are fine.

3. Copy the skill into the package:

DEST="skills/<skill-dir>"
rm -rf "$DEST"
cp -R "$SOURCE" "$DEST"
find "$DEST" -type d -name "__pycache__" -prune -exec rm -rf {} +
find "$DEST" -name "*.pyc" -delete

4. Add or update skill.json beside SKILL.md:

{
  "name": "<trigger-or-display-name>",
  "version": "0.1.0",
  "description": "Short description used by the package list command."
}

Keep the SKILL.md frontmatter name unchanged when the existing trigger name should remain stable. For example, a directory can be skill-evolution while the skill frontmatter name remains skill-dev.

5. Verify local discovery and install behavior:

node bin/skills.mjs list
node bin/skills.mjs update --dry-run --target /tmp/test-skills --client claude
npm run test:local
npm run pack:check

npm run pack:check should show the new SKILL.md, skill.json, references, and scripts in the tarball contents.

6. Commit and push the imported skill:

git status --short
git add README.md skills/<skill-dir>
git commit -m "Add <skill-dir> skill"

Adjust the git add path if the skill was copied into claude/, codex/, or agents/ instead of skills/.

7. Publish a new npm version:

npm version minor
git push --follow-tags

Use minor for adding a new skill. Use patch if the skill was already published and only its content changed.

8. Confirm the automated release:

npm view ethan-agent-skills version --json
npx -y ethan-agent-skills@latest list
npx -y ethan-agent-skills@latest update --dry-run --target /tmp/test-skills --client claude

After the new version appears on npm, users can refresh with:

npx -y ethan-agent-skills@latest update

OpenSpec OPSX Usage

Codex App can invoke the global custom prompts directly:

• /prompts:opsx-explore
• /prompts:opsx-propose
• /prompts:opsx-apply
• /prompts:opsx-archive

Codex CLI currently does not dispatch these custom prompt commands through the interactive slash-command parser. In CLI sessions, use the OpenSpec skills with plain text instead:

• opsx explore <topic>
• opsx propose <change or request>
• opsx apply <change>
• opsx archive <change>

If you specifically want to type the Claude-style alias in Codex CLI, prefix it with one leading space so the CLI sends it as normal text instead of trying to parse it as a built-in slash command:

• /opsx:explore <topic>
• /opsx:propose <change or request>
• /opsx:apply <change>
• /opsx:archive <change>

The leading space is intentional. Without it, Codex CLI treats /opsx:explore as an unknown slash command before the model or skill loader can see it.