agent-skills

The shareable half of the skill estate: skills delivered per-run into AI coding agents by axskills. Personal skills live in j4k/setup-atlas instead, and a skill that only makes sense inside one project belongs in that project.

axskills clones this repository (j4k-oss/agent-skills on code.j4k.dev, main) with git, caches it, and delivers the skills you select per agent launch. As of axskills v0.6.0 its built-in default source still names the pre-transfer j4k/agent-skills.git, which the forge 301-redirects here. For Claude, axskills sync copies every skill here into ~/.claude/skills as axskills-managed directories (tagged with an .axskills-managed marker, toggled per run, pruned or updated by later syncs), skipping any name that collides with one of your own skills. For Codex, the selection is reconciled into the leased config home that axrun -i codex launches against. Claude and Codex are the only wired interactive lanes; every agent is also served by axexec's headless delivery, except Cursor, which resolves skills only from the workspace, so a selection for it is dropped.

Layout

skills/
  <skill-name>/
    SKILL.md            # YAML frontmatter with `name` + `description`, then the skill body
    <supporting files>  # optional references, scripts, assets — copied verbatim

The directory name under skills/ is the selectable skill name. description from the frontmatter is what the picker shows.

A source can also serve rules: axskills reads a rules/ tree recursively and concatenates the selection into the agent's global or user rule file for the run — appended to Claude's system prompt, reconciled into Codex's leased AGENTS.md. It never overrides a repository's committed AGENTS.md; that file stays owned by j4k-align. This repository ships skills only and has no rules/ directory; the layout for a source that serves rules is documented in the axskills README.

Usage

# List what this source provides
axskills list

# Pick the skills to remember for the current repo, then launch an agent
# (axskills selects and delivers; axrun launches)
axskills select
axrun -i claude --profile <id>   # or --vault-credential <name>; exactly one is required

# Author against a local checkout instead of the published source
axskills list --source .

Adding a skill

Create skills/<name>/SKILL.md with name and description frontmatter, commit, and push. The next axskills fetch picks it up — it always re-fetches — as does any select, list, show, or sync run passed --refresh, or axrun passed --refresh-skills. Run axskills sync after to update Claude's managed copies.