# Skill Forge

> Write or improve an LLM agent skill. Use when user says "create skill", "write a skill", "improve this skill", "new skill", "skill for X", or wants to build a SKILL.md file.

- **Type:** Skill
- **Install:** `agentstack add skill-alxxpersonal-forge-skill-forge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [alxxpersonal](https://agentstack.voostack.com/s/alxxpersonal)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [alxxpersonal](https://github.com/alxxpersonal)
- **Source:** https://github.com/alxxpersonal/forge/tree/main/skills/skill-forge

## Install

```sh
agentstack add skill-alxxpersonal-forge-skill-forge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Forge

Generate or improve skills for LLM agent tools (Claude Code, Cursor, Crush, and any SKILL.md-compatible system). Research-backed, based on official docs, plugin source, and real-world skill audits.

## When to Use

- Creating a new skill from scratch
- Improving an existing skill's description, structure, or settings
- Auditing a skill for common mistakes
- Deciding between rule vs skill vs CLAUDE.md for a piece of context

## Step 1: Understand the Request

If $ARGUMENTS points to an existing SKILL.md, read it first. Otherwise, ask:

1. **What does it do?** - the core capability or workflow
2. **Who triggers it?** - user only (`disable-model-invocation: true`), model auto (`default`), or background (`user-invocable: false`)
3. **Side effects?** - does it commit, deploy, send messages, modify state?
4. **Scope?** - personal (`~/./skills/`), project (`./skills/`), or plugin?

## Step 2: Choose the Right Mechanism

These paths use `.claude/` as example but apply to any agent that supports SKILL.md format (Crush, Cursor, etc.):

| Put here | When |
|----------|------|
| CLAUDE.md / agent config | Rule applies to ALL work, every session, short |
| `./rules/` | Applies only when touching specific file types (use `paths` frontmatter) |
| `./skills/` | On-demand workflow, detailed reference, or behavioral mode |

Don't make a skill when a rule or CLAUDE.md line would suffice.

## Step 3: Write the Frontmatter

### Required fields

```yaml
---
name: skill-name          # lowercase, hyphens, max 64 chars
description: ...          # THE most important field. See below.
---
```

### Optional fields

| Field | Use when |
|-------|----------|
| `disable-model-invocation: true` | Side effects (commits, deploys), behavioral modes, timing-sensitive workflows |
| `user-invocable: false` | Background knowledge Claude should absorb passively |
| `argument-hint: "[hint]"` | Skill takes input - shows in autocomplete |
| `allowed-tools: Read, Grep` | Restrict or pre-approve tools |
| `context: fork` | Run in isolated subagent (research, batch ops, analysis) |
| `agent: Explore` | Subagent type when using `context: fork` |

### Invocation matrix

| Setting | User invokes | Claude invokes | Description in context |
|---------|-------------|---------------|----------------------|
| (default) | yes | yes | yes |
| `disable-model-invocation: true` | yes | no | no |
| `user-invocable: false` | no | yes | yes |

**Key insight:** with `disable-model-invocation: true`, the description is NOT in context at all. Don't over-optimize the description - write it for your own docs reference only.

## Step 4: Write the Description

The description is what Claude pattern-matches against to decide whether to load the skill. There is NO algorithmic routing - Claude's language model reads all descriptions and semantically matches.

### Formula

1. **What it does** - one sentence, outcome-first
2. **Trigger phrases** - exact words: "Use when user says X, Y, Z"
3. **Anti-triggers** - "NOT for..." if false positives are a risk
4. **Prerequisites** - required setup if any

### Rules

- Under 60 words
- Every word costs token budget (2% of context window shared across ALL skill descriptions)
- Description handles matching only - body handles instructions
- Don't repeat body content in description
- Be slightly "pushy" - Claude undertriggers by default

### Good example

> "Translates Figma designs into production-ready code with 1:1 visual fidelity. Use when implementing UI from Figma files, when user mentions 'implement design', 'generate code', 'build Figma design', or provides Figma URLs. Requires Figma MCP server connection."

### Bad example

> "Use when user wants to plan something" - too vague, false positives everywhere.

## Step 5: Write the Body

### Structure

```markdown
# Skill Title

Brief context sentence.

## When to Use
(if not covered by description)

## Process / Steps
1. Step one
2. Step two

## Rules / Constraints
- Rule one
- Rule two

## Examples (if applicable)
Show patterns Claude should follow.

## Validation / Checklist (if applicable)
How to verify output quality.
```

### Rules

- **Under 500 lines.** Full SKILL.md loads into context when invoked. Move reference material to supporting files.
- **Use $ARGUMENTS** if the skill takes input. Without it, Claude Code appends `ARGUMENTS: ` at the end which is messier.
- **Numbered lists** for sequential steps, bullets for options/rules.
- **Bold critical constraints** with `**IMPORTANT:**`.
- **Say "do not skip steps"** explicitly when order matters.
- **H2 for major sections, H3 for sub-sections.** Max 2 heading levels.

### Supporting files

Put adjacent to SKILL.md in the skill directory:
- `examples.md` - example inputs/outputs
- `reference.md` - detailed reference docs
- `scripts/helper.sh` - executable scripts

Reference them from SKILL.md so Claude knows to load them. Files not accessed consume zero tokens.

### Dynamic content injection

Skills support shell command output injection with `!` prefix:
- `!`\`git branch --show-current\` - inject current branch
- `!`\`ls src/\` - inject file listing

Use for context that changes between invocations.

## Step 6: Validate

Run this checklist on the generated skill:

- [ ] Description under 60 words
- [ ] Description is trigger-focused (what/when), not instruction-focused (how)
- [ ] Body under 500 lines
- [ ] No duplication between description and body
- [ ] Correct invocation setting for the use case (side effects = `disable-model-invocation: true`)
- [ ] `$ARGUMENTS` used if skill takes input
- [ ] No vague trigger phrases that cause false positives
- [ ] No `context: fork` on reference-only content (subagent gets instructions with no task)
- [ ] Critical constraints are bolded
- [ ] Steps are numbered when order matters
- [ ] Supporting files referenced if body would exceed 500 lines

## Common Mistakes

1. **Vague descriptions** - "Use when user wants to plan" triggers on everything
2. **Missing `disable-model-invocation: true` on side-effect skills** - Claude will auto-commit, auto-deploy
3. **Body too long** - 500+ lines burns context. Split into supporting files.
4. **Redundant description + body** - description matches, body instructs. Don't duplicate.
5. **`context: fork` on reference content** - subagent gets instructions with no actionable task
6. **Over-explaining in description** - the description isn't the instructions
7. **Missing NOT conditions** - for behavioral modes, add explicit "NEVER activate unless..."
8. **`user-invocable: false` on things users should manually trigger** - confusing

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [alxxpersonal](https://github.com/alxxpersonal)
- **Source:** [alxxpersonal/forge](https://github.com/alxxpersonal/forge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-alxxpersonal-forge-skill-forge
- Seller: https://agentstack.voostack.com/s/alxxpersonal
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.