forge-optimize-skills

name	forge-optimize-skills
description	Audit existing skills in .agents/skills/ against agentskills.io best practices. Scores each skill on context economy, gotchas coverage, procedural clarity, progressive disclosure, calibration, and validation. Produces a reviewable audit report and can optionally apply targeted improvements.

Skill: Optimize Existing Skills Against Best Practices

You are auditing existing skills against the agentskills.io best practices. Your job is to read each skill, score it against a structured rubric, produce a reviewable audit report, and - only when the user explicitly approves - apply targeted improvements.

---

Process

Step 1: Discover Skills

List all skills in .agents/skills/. Exclude the forge meta-skills themselves (forge-* prefixed skills) unless the user explicitly asks to audit them. Focus on project-specific skills generated by forge-build-agent-team.

Skip any skill directory that has no SKILL.md.

Step 2: Audit Each Skill

For each skill, read SKILL.md and any references/, scripts/, or assets/ files. Score each axis on a 1–3 scale (1 = missing, 2 = partial, 3 = strong):

Axis	What to check	Score 3 (strong)	Score 1 (missing)
Context economy	Does the skill trim what the agent already knows? Are there generic explanations that waste tokens?	Specific, project-focused instructions. No "what is a PDF" explanations.	Long generic passages, explanations of fundamentals the agent knows.
Gotchas coverage	Are environment-specific edge cases, API inconsistencies, and naming mismatches documented?	Concrete gotchas that correct mistakes agents make without being told.	No gotchas section, or only generic advice like "handle errors appropriately."
Procedural clarity	Does the skill teach how to approach a problem (procedure) rather than what to produce (declaration)?	Step-by-step process with decision criteria.	Just declares what output should look like without teaching the process.
Progressive disclosure	Is content over ~50 lines of template/reference material moved to references/ or assets/ with load triggers?	references/ and assets/ used with explicit load triggers. SKILL.md under 500 lines.	Everything in one SKILL.md. No subdirectories.
Calibration	Is prescriptiveness matched to task fragility? Rigid for fragile ops, flexible for variable ops.	Clear defaults with escape hatches. Exact commands for destructive operations.	Uniform prescriptiveness, or important steps left too vague.
Validation	Are there concrete validation steps the agent can run to self-check its work?	Checklist, validator script, or self-check loop with fix-and-retry.	No verification step, or only generic "make sure it works."

Also check:

• name matches parent directory name
• description is specific and includes keywords for activation
• YAML frontmatter is valid
• File references use relative paths from skill root
• No more than one level of reference chain depth

Step 3: Produce docs/SKILL-AUDIT.md

Write the audit report with this structure:

# Skill Audit Report

**Generated:** YYYY-MM-DD
**Audited by:** `forge-optimize-skills`
**Skills audited:** {count}

---

## Summary Scores

| Skill | Context | Gotchas | Procedure | Progressive | Calibration | Validation | Overall |
|-------|---------|---------|-----------|-------------|-------------|------------|---------|
| `{name}` | 2 | 1 | 3 | 1 | 2 | 2 | 1.8 |

**Score interpretation:**
- 2.5–3.0: Strong - follows best practices well
- 1.5–2.4: Adequate - works but has improvement opportunities
- 1.0–1.4: Needs work - significant gaps against best practices

---

## Per-Skill Findings

### `{skill-name}`

**Overall score:** {score}

**Strengths:**
- {What the skill does well}

**Improvement opportunities:**
- {Specific, actionable suggestion}
- {Another suggestion}

**Suggested changes (requires approval):**
1. Add `## Gotchas` section with: {specific gotchas to add}
2. Move {content} to `references/{file}.md` with load trigger: "Load when {condition}"
3. Add validation loop: "{concrete check}"
4. Trim {specific verbose section}: "{what to cut}"

---

### `{skill-name}`
{Repeat for each skill}

---

## Next Steps

Review the suggested changes above. To apply them, run:
`/forge-optimize-skills Apply the approved changes from docs/SKILL-AUDIT.md`

Step 4: Present and Wait

Present a summary of the audit scores and highlight the top 3 improvement opportunities. Ask the user whether to apply changes. Never apply changes without explicit user confirmation.

If the user approves specific changes, proceed to Step 5.

Step 5: Apply Approved Changes (opt-in only)

For each approved change:

1. Add gotchas: Insert a ## Gotchas section with the suggested content. Place it after ## Process or before ## Reference - consistent with the forge's own skill conventions.

2. Move to progressive disclosure: Create the references/ or assets/ directory under the skill. Extract the identified content into the new file. Replace with a load trigger in SKILL.md (e.g., "Load references/schema.md for the full output format structure.")

3. Add validation: Insert a ## Validation section with checkboxes or a validation script invocation.

4. Trim verbose content: Remove generic explanations the agent already knows. Replace with a concise instruction.

5. Add calibration markers: For fragile operations, add explicit commands. For flexible operations, add "if that doesn't work, try X" escape hatches.

After applying changes, regenerate the audit report with updated scores. Show the user what changed.

---

Gotchas

• Never modify forge meta-skills (any skill with forge- prefix) unless explicitly asked. These follow their own conventions and are version-controlled separately.
• Don't move content that's essential for activation. The first ~100 lines of SKILL.md define the skill's purpose and trigger conditions. Keep that inline even if it's verbose.
• Load triggers must be specific. "Load references/api-errors.md if the API returns a non-200 status code" is good. "See references/ for details" is useless.
• Generated skills may reference old paths. If a skill still references .github/agents/ or .github/skills/, flag it as a path migration issue (legacy from pre-.agents/ migration).
• Validation scripts in scripts/ must be self-contained. Don't recommend scripts the user can't run without missing dependencies.

---

Guidelines

• Audit generated skills, not forge skills. The forge's own skills are maintained separately and follow their own optimization cycle.
• Score honestly. A low score isn't a failure - it's actionable data. Every skill can improve.
• Be specific in suggestions. "Add gotchas" is not helpful. "Add gotcha: 'The users table uses soft deletes - queries must include WHERE deleted_at IS NULL'" is.
• One pass at a time. Apply changes, regenerate the audit, and stop. Don't loop until perfect - real-world execution feedback (per the best practices) drives the next iteration.