refresh-skills

Policy

npx skills

.agents/skills/

Updating skills in the home directory

DISABLE_TELEMETRY=1 npx skills list -g

DISABLE_TELEMETRY=1 npx skills update <skill-name> <skill-name> -g -y

• Specify the names so that skills installed by the user from other Sources are not modified.
• If a required skill is not installed, or its Source is not philtzjp/skills, reinstall it after obtaining the user's permission. Follow the procedure in skill-selection.
• If installation or updating is not possible, report the issue to the user instead of proceeding based on assumptions.

Migrating copies left in the target repository

.agents/skills/

.claude/skills/

DISABLE_TELEMETRY=1 npx skills add philtzjp/skills --list

1. Classify the copies

• A copy with the same content as upstream: It is safe to delete.
• An old skill that has been merged upstream: It is safe to delete. The merge destinations are as follows.

  Old skill	Merge destination
  commit-and-git、issue-branch-pr-flow	github
  japanese-writing	japanese
  typescript-monorepo	turborepo
  api-design	hono
  data-migration	db
  e2e-testing	e2etest
  google-analytics	analytics

• A copy whose content differs from upstream: It may have been modified locally. Show the user the differences before deleting it.
  sh

  curl -fsSL https://raw.githubusercontent.com/philtzjp/skills/main/.agents/skills/<skill-name>/SKILL.md | diff - .agents/skills/<skill-name>/SKILL.md

  Have the user determine whether the copy was merely modified from an older upstream version or whether the changes are specific to that repository. If the changes would also be useful in other repositories, propose them to philtzjp/skills in accordance with skill-escalation. If they are specific only to that repository, retain the skill as a repository-specific skill or write the convention in AGENTS.md.
• A skill that does not exist in philtzjp/skills: It is a repository-specific skill. Retain it.

2. Perform the migration

1. Check whether the skill being deleted or its merge destination is installed in the home directory. If it is not installed, obtain the user's permission and install it.
2. Delete

   .agents/skills/<skill-name>/

   and

   .claude/skills/<skill-name>

   for each skill being deleted.
3. Remove the rows for deleted skills from the skill tables in AGENTS.md and CLAUDE.md. If no repository-specific skills remain, remove the entire skill table.
4. Remove statements in AGENTS.md and CLAUDE.md that assume the deleted skills still exist, such as “imported from philtzjp/skills” or “synchronized with refresh-skills.”
5. Add an instruction to AGENTS.md to read the START.md file from philtzjp/startingpoint.
   markdown

   ## Development Rules
   
   Before starting work, use curl to retrieve the following URL, read the entire file, and follow the procedures it contains:
   https://raw.githubusercontent.com/philtzjp/startingpoint/main/START.md

6. If there are mechanisms derived from philtzjp/startingpoint, such as

   scripts/refresh-skills.sh

   or

   .cursor/environment.json

   , that assume copied skills are synchronized, propose replacing them with

   npx skills

   .

   • scripts/refresh-skills.sh

     : Stop checking differences with upstream using

     --upstream

     and stop synchronizing copies. Change the script to update skills in the home directory with

     npx skills update

     . If repository-specific skills remain, retain only the symlink and skill-table reconciliation. If none remain, delete the script entirely.
   • The

     start

     setting in

     .cursor/environment.json

     : Cursor Cloud Agent's home directory is empty every time it starts, so install the skills at startup instead of running

     ./scripts/refresh-skills.sh

     .
     json

     {
       "start": "DISABLE_TELEMETRY=1 npx skills add philtzjp/skills -g -a cursor -s github -s japanese -s turborepo -y"
     }

   • If other mechanisms, such as CI, lefthook, or setup scripts, copy or synchronize skills, replace them with

     npx skills

     in the same way.

Reconciling canonical sources and symlinks

• .agents/skills/<skill-name>/SKILL.md

  (the canonical source)

• .claude/skills/<skill-name>

  (a relative symlink to

  ../../.agents/skills/<skill-name>

  )
• The corresponding row in the skill table in AGENTS.md
• The

  name

  field in the SKILL.md frontmatter

• The canonical source is located under

  .agents/skills/

  . Do not place regular files under

  .claude/skills/

  .
• Symlinks use relative paths, not absolute paths.
• There are no broken symlinks or missing corresponding links.
• The set of skills in the skill table matches the set of skill directories.
• Skill names use kebab-case, and the frontmatter

  name

  matches the directory name.
• The skill does not contain sensitive information, tokens, or credentials.

• If a link is missing:

  ln -s ../../.agents/skills/<skill-name> .claude/skills/<skill-name>

• If a link is a regular file or points to a different location: delete it and recreate it.
• If the link target does not exist: delete the link.
• If the skill table and directories do not match: add or remove the corresponding table rows.
• If

  name

  differs from the directory name: correct the frontmatter.

Adding, deleting, or renaming skills

• Adding: Create

  .agents/skills/<skill-name>/SKILL.md

  , and add

  name

  and

  description

  to the frontmatter. Describe specifically when the skill should be used. Create the symlink and add a row to the skill table.
• Deleting: Delete the directory, symlink, and skill-table row. Search for and update references to the skill in other skills and AGENTS.md.
• Renaming: Change the directory name and the frontmatter

  name

  , recreate the symlink, and update the skill table and references.