refactor: convert slash commands to skills, multi-agent layout#36
Merged
heyitsnoah merged 5 commits intomainfrom Apr 11, 2026
Merged
refactor: convert slash commands to skills, multi-agent layout#36heyitsnoah merged 5 commits intomainfrom
heyitsnoah merged 5 commits intomainfrom
Conversation
Convert all 14 slash commands from .claude/commands/ into agent skills, with
the canonical at .agents/skills/<name>/SKILL.md. The .agents/skills/ path is
read natively by OpenCode, Codex, and Cursor; symlinks at .claude/skills/ and
.pi/skills/ make Claude Code and Pi find them too. Edit canonical, all five
agents follow.
Skills converted (body preserved verbatim, name+description frontmatter added):
add-frontmatter, daily-review, de-ai-ify, download-attachment, inbox-processor,
install-claudesidian-command, pragmatic-review, pull-request, research-assistant,
thinking-partner, weekly-synthesis. Plus init-bootstrap and release with their
existing frontmatter cleaned up.
Pre-existing skills (git-worktrees, json-canvas, obsidian-bases,
obsidian-markdown, skill-creator, systematic-debugging) moved from
.claude/skills/ to the new canonical location.
Frontmatter cleanup so all 20 skills pass strict validation:
- Convert multi-line YAML descriptions to single-line so the discovery hook
parses them correctly (init-bootstrap, release, upgrade)
- Drop the command-only `argument-hint` field (init-bootstrap, release, upgrade)
- Drop the `version` field (systematic-debugging) — not in skill schema
Content fixes:
- init-bootstrap: replace dead /setup-gemini and /setup-firecrawl references
with concrete setup instructions; rewrite the "available commands" section
to point at skills with natural-language triggers
- upgrade: full rewrite for the new layout (642 → 276 lines). Adds layout
detection (skips legacy .claude/commands/ vaults), symlink hygiene step,
and a documented migration path for legacy users. Keeps all original safety
machinery: backups, mandatory diffs before any change, no auto-pick, never
cp -f, the "files we never touch" list, and rollback instructions.
- install-claudesidian-command: fix two pre-existing data-loss bugs caught by
guillaumeify review:
1. The sed range `/alias|function/,/^end$/d` would delete from a bash alias
(which has no `end`) all the way to the next `^end$` keyword anywhere in
the file, potentially nuking unrelated shell config. Split into a
single-line delete for the alias case and a range delete for the fish
function case.
2. Path-escaping order was reversed (escaped quotes before backslashes,
double-escaping the new backslashes). Escape backslashes first.
- README.md: rewrite the "Claude Code Commands" section to describe skills,
drop the dead create-command bullet, drop the "/[command-name]" invocation
hint that no longer applies.
Removed:
- .claude/claude_config.json — dead config file, no code references
- .claude/commands/README.md — stale docs for an empty directory
- .claude/commands/create-command.md — explicitly removed, no longer needed
Note: avoided `npx skills add` from vercel-labs/skills because its installer
rm -rf's the canonical when source path == canonical path (verified by reading
src/installer.ts). Did the move + symlink layout manually instead.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b301c6a608
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+157
to
+159
| if [ ! -e "$link" ]; then | ||
| mkdir -p ".${agent}/skills" | ||
| ln -s "../../.agents/skills/${name}" "$link" |
There was a problem hiding this comment.
The symlink repair logic only checks -e, which misses a key failure mode: a broken or wrong symlink path already exists at .claude/skills/<name>/.pi/skills/<name>. In that case the condition still enters (for broken links) but ln -s fails with “File exists,” leaving the bad link untouched, and for wrong-but-existing links the condition never runs at all. This can leave agents reading stale or missing skills after upgrade/migration even though step 6 reports hygiene complete.
Useful? React with 👍 / 👎.
| 4. **Add `name`/`description` frontmatter** to any file that lacks it. Use the | ||
| `add-frontmatter` skill. | ||
| 5. **Create symlinks** for `.claude/skills/` and `.pi/skills/` (see step 6). | ||
| 6. **Validate** with `skill-creator`'s `quick_validate.py`. |
There was a problem hiding this comment.
Step 6 of the legacy migration instructs running skill-creator's quick_validate.py, but there is no such script in this repository (repo-wide file search returns no quick_validate.py). Following the documented migration flow therefore hits a dead step and blocks completion unless users manually guess an alternative validator.
Useful? React with 👍 / 👎.
Closed
Two bugs caught by codex review on PR #36: 1. Symlink hygiene loop checked only `[ ! -e "$link" ]`, which has two failure modes: - Broken symlink (target missing): `-e` returns false → enters branch → `ln -s` fails with "File exists" because the broken symlink itself occupies the path. Bad link stays bad. - Symlink pointing the wrong way (target exists elsewhere): `-e` returns true → never enters branch. Wrong link silently stays wrong. Fix: check `-L` first (symlink existence), then verify target with `readlink` and repair if mismatched. Fall through to `-e` for real files/dirs (skip with warning, don't trample user data). Create only if nothing exists at the path. 2. Legacy migration step 6 referenced `skill-creator`'s `quick_validate.py`, which lives in the user's local skill-creator install — not in this repo. Migrating users without skill-creator hit a dead reference. Fix: replace with an inline awk loop that checks every `SKILL.md` has `name` and `description` in its frontmatter. Note that `quick_validate.py` is available to users who have skill-creator installed but is no longer part of the documented migration path. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
… upstream The previous skill-creator was a 275-line internal claudesidian write-up. Replace it with the official upstream skill from anthropics/skills, which ships with: - The full SKILL.md (more comprehensive than the internal version) - agents/ — analyzer, comparator, grader subagent prompts - scripts/ — quick_validate.py, run_eval.py, package_skill.py, improve_description.py, aggregate_benchmark.py, generate_report.py, run_loop.py, plus utils - references/schemas.md — full skill schema documentation - assets/eval_review.html — eval review template - eval-viewer/ — local eval viewer - LICENSE.txt — Apache 2.0 (upstream license) Adds NOTICE.md to .agents/skills/skill-creator/ documenting: - Source: https://github.com/anthropics/skills/tree/main/skills/skill-creator - Upstream third-party notices: https://github.com/anthropics/skills/blob/main/THIRD_PARTY_NOTICES.md - License: Apache 2.0 (LICENSE.txt in this dir) - Local modifications: none (verbatim copy) Symlinks at .claude/skills/skill-creator and .pi/skills/skill-creator already point at .agents/skills/skill-creator, so no symlink changes needed — all five agents (Claude Code, OpenCode, Codex, Cursor, Pi) automatically pick up the new directory contents. Bonus: the upstream skill bundles `quick_validate.py` directly, so the upgrade skill's legacy migration step no longer relies on the user having skill-creator installed globally — they can run it via this skill's bundled copy at .agents/skills/skill-creator/scripts/quick_validate.py. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two related fixups after pulling in the upstream anthropics/skills version of skill-creator (commit 7fdc60d): 1. upgrade skill, legacy migration step 6: prefer the now-bundled `.agents/skills/skill-creator/scripts/quick_validate.py` for frontmatter validation. Falls back to the inline awk check if uv is missing. 2. .prettierignore: skip `.agents/`, `.claude/skills/`, and `.pi/` so prettier does not try to reformat upstream skill copies. Two HTML files in the upstream skill-creator (assets/eval_review.html and eval-viewer/viewer.html) were tripping CI lint. Ignoring them keeps the upstream copies verbatim, which preserves the attribution. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Runs quick_validate.py from the bundled skill-creator across every skill in .agents/skills/. Useful as a pre-commit/pre-push check or in CI to catch malformed frontmatter, extra keys, missing name/description, etc. Usage: pnpm skills:validate
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Convert all 14 slash commands from .claude/commands/ into agent skills, with the canonical at .agents/skills//SKILL.md. The .agents/skills/ path is read natively by OpenCode, Codex, and Cursor; symlinks at .claude/skills/ and .pi/skills/ make Claude Code and Pi find them too. Edit canonical, all five agents follow.
Skills converted (body preserved verbatim, name+description frontmatter added): add-frontmatter, daily-review, de-ai-ify, download-attachment, inbox-processor, install-claudesidian-command, pragmatic-review, pull-request, research-assistant, thinking-partner, weekly-synthesis. Plus init-bootstrap and release with their existing frontmatter cleaned up.
Pre-existing skills (git-worktrees, json-canvas, obsidian-bases, obsidian-markdown, skill-creator, systematic-debugging) moved from .claude/skills/ to the new canonical location.
Frontmatter cleanup so all 20 skills pass strict validation:
argument-hintfield (init-bootstrap, release, upgrade)versionfield (systematic-debugging) — not in skill schemaContent fixes:
/alias|function/,/^end$/dwould delete from a bash alias (which has noend) all the way to the next^end$keyword anywhere in the file, potentially nuking unrelated shell config. Split into a single-line delete for the alias case and a range delete for the fish function case.Removed:
Note: avoided
npx skills addfrom vercel-labs/skills because its installer rm -rf's the canonical when source path == canonical path (verified by reading src/installer.ts). Did the move + symlink layout manually instead.Closes
Related
.agents/skills/layout