skills-inject

Inject skill summaries into your agent instruction files (CLAUDE.md, AGENTS.md).

A companion tool for npx skills. Skills provide full instructions that agents load on demand. skills-inject extracts short always-on summaries from INJECT.md files and writes them into your instruction files so the agent has key context without loading the full skill.

Why inject into instruction files?

Skills are great for packaging detailed, on-demand knowledge. But Vercel's research shows that always-on context in instruction files (AGENTS.md, CLAUDE.md) significantly outperforms on-demand skill loading in agent evals.

The reason: passive context removes the decision point. The agent doesn't have to decide "should I look this up?" — the key info is just there, every turn.

skills-inject bridges the gap. Skills hold the full knowledge; their INJECT.md files provide short always-on summaries that get written directly into your instruction files.

Usage

All examples use pnpx. You can also use npx skills-inject@latest.

# Auto-detect skills dirs and target files
pnpx skills-inject

# Preview without writing
pnpx skills-inject --dry-run

# Specify target file(s) explicitly
pnpx skills-inject --target CLAUDE.md
pnpx skills-inject --target CLAUDE.md --target AGENTS.md

# Specify skills directories
pnpx skills-inject --skills-dir .claude/skills --skills-dir .agents/skills

Auto-detection

Skills directories: Scans .agents/skills/ and .claude/skills/ in order. All directories that exist are used. If none exist, the CLI exits with an error and suggests installing skills first.

Target files: If exactly one of CLAUDE.md / AGENTS.md exists, it's used automatically. If both or neither exist, you're prompted to choose. Your choice is saved to .skills-inject.json automatically so you won't be prompted again.

Configuration

| Field | CLI flag | Default | Description | |---|---|---|---| | targets | --target | Auto-detected | Target file(s) to inject into. | | skillsDirs | --skills-dir | Auto-detected | Skills directories to scan for INJECT.md files. | | heading | — | "Skill Instructions" | The ## heading for the injected section. | | description | — | "The following instructions come from installed skills (autogenerated, do not edit manually) and should always be followed." | Paragraph after the heading. Set to "" to suppress. |

CLI flags always override stored config. Config can be stored in either of these locations:

.skills-inject.json

{
  "targets": ["CLAUDE.md"],
  "skillsDirs": [".agents/skills", ".claude/skills"],
  "heading": "Project Guidelines",
  "description": "These rules come from the team's shared skill library."
}

package.json

{
  "skills-inject": {
    "targets": ["CLAUDE.md", "AGENTS.md"],
    "skillsDirs": [".claude/skills"]
  }
}

For skill authors

Each skill that wants to inject always-on context includes an INJECT.md alongside its SKILL.md:

my-skill/
  SKILL.md       # Full skill (loaded on demand by agent)
  INJECT.md      # Short summary (injected into instruction files)

INJECT.md format

---
heading: My Custom Heading    # Optional, auto-derived from directory name
priority: high                # Optional, default "normal"
---

- Always-on instruction one.
- Always-on instruction two.

Frontmatter reference

| Field | Default | Description | |---|---|---| | heading | Auto-derived from directory name | Set a custom ### heading. Use false to suppress the heading and control the markup directly in the body. | | priority | normal | Ordering tier. high skills appear first, low skills appear last. Same tier sorts alphabetically. |

Example output

Given skills with INJECT.md files, running pnpx skills-inject produces:

<!-- skills-inject:start -->
## Skill Instructions

The following instructions come from installed skills (autogenerated, do not edit manually) and should always be followed.

### Changesets

- Any PR that should trigger a package release must include a changeset.
- Choose the right bump: `patch` for fixes, `minor` for features, `major` for breaking changes.

### Review Gate

- **Never** commit, push, create branches, or create PRs without explicit user approval.
- Wait for the user to approve or request changes before proceeding.

<!-- skills-inject:end -->

Content outside the markers is never touched. Re-running replaces only the injected section.