semantu-agents

Reusable Claude Code and agent skills for Semantu projects.

Recommended: Global Install

npx semantu-agents global

Syncs the npm-packaged public skills to:

• ~/.claude/skills
• ~/.agents/skills

This is the default recommended setup. It keeps application repos clean and makes the shared skills available across projects. Project repos can still define app-specific skills separately.

Updating Global Skills

For normal users, rerun:

npx semantu-agents global

For contributors with an editable checkout at ~/.agents-src, run this from anywhere:

npx semantu-agents update

This updates ~/.agents-src/main, syncs it to ~/.claude/skills and ~/.agents/skills, then restores your previous branch when possible. If ~/.agents-src has uncommitted changes, commit or stash them first.

Contributing Skill Changes

Install an editable source checkout:

npx semantu-agents dev

This clones or pulls github.com:Semantu/agents into ~/.agents-src, installs a post-merge hook, and syncs that checkout globally.

Dev mode requires repo access. If cloning fails, ask for access to the Semantu agents repo.

Make changes in the source checkout only:

cd ~/.agents-src
git checkout -b my-change
# edit skills/public/... or skills/private/...
npm run sync
git add .
git commit -m "improve workflow skill"
git push -u origin my-change
gh pr create

Do not edit these generated folders directly:

• ~/.claude/skills
• ~/.agents/skills

They are overwritten by semantu-agents global, semantu-agents sync, and semantu-agents update.

The dev post-merge hook runs node cli.mjs sync after pulls, so merged changes are synced globally automatically.

Project Setup

Project-local setup is still available for repos that intentionally want checked-out helper files:

npx semantu-agents

Most projects should prefer the global install instead.

Docs index

Print a markdown or JSON index of docs that use YAML frontmatter.

npx semantu-agents docs
npx semantu-agents docs backlog
npx semantu-agents docs architecture
npx semantu-agents docs --all
npx semantu-agents docs --format markdown
npx semantu-agents docs --all --format json

Supported scopes:

• root (default) -> docs/*.md
• architecture -> docs/architecture/*.md
• backlog -> docs/backlog/*.md
• plans -> docs/plans/*.md
• reports -> docs/reports/*.md

Notes:

• default output is text
• supported formats: text, markdown, json
• JSON uses short keys: f = file, s = summary, d = folder
• --all adds a folder column in markdown, or d in JSON
• --fix adds an empty summary field when frontmatter is missing it
• missing summaries stay blank; the command does not warn

Skill layout

skills/
  public/     # shipped on npm, always available
  private/    # git-clone only, requires repo access

Both are merged into the same flat .claude/skills/ directory at sync time.

Public skills

| Skill | Purpose | |---|---| | workflow | Enforces the mode cadence: ideation → plan → tasks → implementation → review → wrapup | | ideation | Interactively explore implementation options one decision at a time | | plan | Convert decisions into a concrete architecture plan | | tasks | Break a plan into phased tasks with validation criteria | | implementation | Execute tasks phase-by-phase with commits and validation | | review | Review work against intent, readiness, and gaps; triage iterate vs defer | | wrapup | Cleanup, changesets, and PR preparation | | todo | Capture user-deferred follow-up work in docs/backlog | | automatic | Run the full workflow without manual mode transitions |