agent-skills

Reusable skills and user-level rules for engineering, design, and writing, delivered to AI coding agents by axskills. Add skills and user-level rules here when they are useful across projects. Personal or private content lives in j4k/setup-atlas. Project rules remain managed by j4k-align, with repository-specific additions in .agents/rules/.

Quick start

With axskills installed, inspect this repository's catalog:

git clone https://code.j4k.dev/j4k-oss/agent-skills.git
axskills list --source ./agent-skills

Usage

Run these commands from the project where you want to use skills:

# Inspect the configured sources and their combined catalog
axskills source list
axskills list

# Save a selection for this directory and inspect its resolved dependencies.
# A changed save syncs shared Skills; see "How it works" before using it.
axskills select
axskills show --agent claude --explain

# Launch through a configured Profile and Account Portfolio
axrun -i --profile <profile-id> --portfolio <portfolio-id> --required-harness claude

Use axskills --help for commands and the axrun README for launch configuration.

How it works

The default source is https://code.j4k.dev/j4k-oss/agent-skills.git on main. Axskills caches remote sources and reads local sources directly. Configured sources replace the default and merge into one catalog; duplicate skill names are errors. --source <path> replaces the configured sources for that invocation.

Selections combine global and directory layers, per-agent overrides, invocation options, and transitive skill dependencies. Axrun uses axexec to deliver the selection into a private home directory for each session, kept so the session can resume. Delivery supports Claude, Codex, Cursor, Gemini, OpenCode, and Grok; modes and discovery limits vary by agent. See the axskills delivery documentation for those boundaries.

Axrun delivery does not need axskills sync. Saving a changed selection with axskills select also syncs shared Skills, but native Rules require an explicit axskills sync. For agents started outside axrun, sync copies the entire source skill catalog into ~/.claude/skills and ~/.agents/skills. It owns both directories: it overwrites installed copies and deletes every skill no configured source provides, including skills you created there by hand. Make edits in source files rather than installed copies, and move any skill you want to keep into a registered source before you sync or select. A saved selection does not filter these shared installations.

Explicit sync also writes the selected Global Rules and agent overrides into managed blocks in the default Claude, Codex, Gemini, OpenCode, and Grok user instruction files. Directory Rules remain per-session. Edit the source rules, then sync; do not edit managed blocks or run another writer concurrently.

Layout

skills/
  <skill-name>/
    SKILL.md            # YAML frontmatter with `name` + `description`, then the skill body
    <supporting files>  # optional references, scripts, assets — copied verbatim
rules/
  general/              # reusable user-level engineering guidance
    <rule-name>.md
  macos/                # guidance specific to macOS
    <rule-name>.md
  claude/               # Claude Code-specific guidance, selected by an agent override
    <rule-name>.md
  codex/                # Codex-specific guidance, selected by an agent override
    <rule-name>.md

The directory name under skills/ is the selectable skill name. A capability skill's frontmatter description is a persistent Use when … routing instruction included in the client's initial skill catalog when it fits the client's catalog budget; the picker also displays it. The body remains absent until the agent loads the skill. A workflow skill is human-invoked only and may instead use a one-line picker summary.

Rules are selectable by their path relative to rules/, including the .md extension, such as general/conventional-commits.md. Registering this source makes its rules available; it does not select them. Selection order matters. Rule paths must be unique across all configured sources.

Axrun delivers selected user rules into agent-specific session targets; explicit sync delivers Global Rules into native user files. Neither changes a repository's committed AGENTS.md. Cursor has no supported user-rule target and warns when selected rules are skipped. A source can also supply settings fragments under settings/<name>.json; axexec merges selected fragments into native settings in the session home before launch, including resume. This repository supplies skills and rules. See the axskills README for the full source and delivery contracts.

Agent instructions

Choose the task by its outcome:

Skill	Outcome
write-agent-instructions	New instructions or a scoped edit.
reengineer-agent-instructions	An existing instruction set redesigned around justified requirements.
review-agent-instructions	Evidence of whether an agent following the instructions meets the intended outcomes.

writing-for-agents supplies writing and packaging guidance. reengineering supplies the shared reasoning discipline for instruction redesign and reengineer-program; grilling supplies the interview method. These are capabilities that other skills can call, not mandatory user-only sessions. Supporting references remain inside the skill that owns them.

Adding a skill

Create skills/<name>/SKILL.md with name and description frontmatter. From this checkout, inspect it with axskills list --source ., then commit and push. For remote sources, axskills fetch refreshes the caches; --refresh on select, list, show, or sync does the same, as does axrun's --refresh-skills. Local sources use the checkout's current files; fetching does not pull their Git branches.

If you also start agents outside axrun, run axskills sync --refresh to refresh remote sources and update both shared installations from the configured catalog. Don't run axskills sync --source . unless this checkout should be your only installed source: that sync deletes every other source's skills from both shared installations.

Declare hard delivery dependencies with a quoted, space-separated metadata.axskills.requires string, for example axskills.requires: "project-docs human-facing-writing-style". List only skills provided by configured axskills sources; client-bundled skills are external prerequisites and do not belong in this field. Automatic dependency delivery requires a compatible axskills release; older releases ignore this metadata.

Adding and selecting user rules

Create rules/<category>/<name>.md with a # Rule: <Title> heading and no frontmatter. Keep each rule self-contained; personal hosts, account choices, private workflows, and machine-specific paths belong in a private source. Project-wide instructions belong to the project rule system.

Use axskills 0.27.0 or newer for ordered user-rule selection and native delivery:

# Inspect this checkout without changing configuration or installed files
axskills list --source . --rules-only

# Register the public source if your configured source list does not include it
axskills source add https://code.j4k.dev/j4k-oss/agent-skills.git

# Choose rules for the user baseline, then deliver native instructions
axskills select --scope global --refresh
axskills sync --refresh

These commands use the selected axskills config, which owns sources and selections. Use axskills show --agent codex --explain to inspect the result. Shared Skills are synced on a changed selection save; review their ownership above before running the picker.

Vendored skills

Some skills began as copies of third-party skills, and each records its origin in metadata.upstream. The copies are committed here so this repository controls their contents. Nothing syncs them with upstream: they diverge deliberately, and picking up an upstream change is a manual, reviewed edit.

• skills/agent-browser/ began as the discovery stub the agent-browser CLI ships (agent-browser skills path prints where the installed original lives).

• add-dark-mode, brand-kit, canonicalize-tailwind, componentize, dark-mode-image, design, ideas, make-responsive, and markup-from-image come from ui.sh. Commit 1ce3e31 holds them as installed; every later change is local. To compare with the current upstream, run the installer with a ui.sh license token in a scratch directory. It writes the skills to .claude/skills/:

  npx -y @uidotsh/install@latest --token='<token>' --scope=local --agent=claude --all-skills