SKILL.md

name	claude-code-skillforge
description	Generates highly optimized Agent Skills for both native Claude Code and the Antigravity system, according to official best practices and the "Progressive Disclosure" strategy. Use when the user wants to build a new skill, turn a workflow into a skill, upgrade an existing skill to latest best practices, audit a skill for compliance, or structure agent instructions for either ecosystem.
argument-hint	skill-idea or workflow

Claude Code Skillforge SOP

Execution Rules

• Fetch all URLs and search all marketplaces in parallel using concurrent tool calls.
• read_url_content, search_web, view_content_chunk are non-destructive — execute without user approval.
• Only pause at steps marked (CHECKPOINT).

Step 0: Update Check

Fetch https://raw.githubusercontent.com/lijinnair/claude-code-skillforge/main/VERSION silently. Compare the remote version with the local version (5.10.0). If remote is newer, display: "Claude Code Skillforge v[remote] is available (you have v[local]). Run git -C [skill-path] pull to update." where [skill-path] is the detected install location. Then proceed normally — do not block execution.

Step 1: Sync Live Best Practices (CHECKPOINT)

Fetch live documentation before any user interaction.

1. Fetch ALL 5 URLs in parallel:
   • https://code.claude.com/docs/en/
   • https://code.claude.com/docs/en/skills
   • https://code.claude.com/docs/en/hooks
   • https://antigravity.google/docs/home
   • https://antigravity.google/docs/skills
2. All succeed: Synthesize best practices, present summary. Say: "Here are the latest best practices. Proceed?" Wait for confirmation.
3. Any fail: State which URLs failed. Display cached knowledge version and date. Say: "I can proceed using built-in knowledge (Version: [X], Last Updated: [Date]). Continue or retry?" Do not proceed until the user chooses.

Step 1.5: Mode Detection

Determine the user's intent:

• Build Mode — User provides a new skill idea, workflow, or says "build", "create", "new". → Proceed to Step 2.
• Upgrade Mode — User provides an existing SKILL.md, pastes skill content, or says "upgrade", "audit", "fix", "optimize", "review". → Proceed to Step U1.
• Scan Mode — User says "scan", "check my skills", "health check", "audit my skills". → Proceed to Step S1.

If ambiguous, ask: "Are you building a new skill, upgrading an existing one, or scanning your installed skills?"

Step 2: Intake & Scoping

Collect from the user:

• Name: kebab-case, preferring gerund form (e.g., analyzing-seo-pages, formatting-commits). Noun form acceptable if gerund is awkward. Constraints: max 64 characters, lowercase letters/numbers/hyphens only, no XML tags, cannot contain reserved words ("anthropic", "claude").
• Category: dev | marketing | seo | document | data | ops
• Ecosystem: Claude Code (~/.claude/skills) or Antigravity (~/.gemini/antigravity/skills)
• Triggers: Activation words or phrases
• Inputs: Context, files, or arguments needed at runtime
• Output: Expected deliverable
• Tools: Bash, URL fetch, file read, MCP servers (use ServerName:tool_name format), or context: fork?

Step 2.5: Discovery Check

Search ALL 10 sources in parallel before building from scratch:

1. Smithery — https://smithery.ai/skills?q=[skill-name]
2. SkillsMP — https://skillsmp.com/search?q=[skill-name]
3. SkillsLLM — https://skillsllm.com/search?q=[skill-name]
4. SkillHub — https://skill-marketplace.com/search?q=[skill-name]
5. Antigravity Skill Vault — https://github.com/search?q=[skill-name]+topic:antigravity-skill
6. Awesome Skills — https://github.com/sickn33/antigravity-awesome-skills CATALOG.md
7. GitHub Topics — https://github.com/search?q=[skill-name]+topic:claude-code-skill
8. Composio — https://composio.dev/search?q=[skill-name]
9. AI Templates — https://www.aitmpl.com/skills?q=[skill-name]
10. Awesome Claude Skills — https://github.com/ComposioHQ/awesome-claude-skills/search?q=[skill-name]

Results:

• No match: Proceed to Step 3.
• Match found (CHECKPOINT): Present Discovery Report (name, source, stars, description). Ask: (A) Customise existing, or (B) Build new? Wait for choice.
• Sources failed: Note unreachable sources in the report. Use whatever succeeded. If ALL 10 fail, proceed to Step 3.

Step 3: Front Matter Engineering

Design front matter (< 1024 chars) using ONLY officially recognized fields: name, description, disable-model-invocation, user-invocable, allowed-tools, model, context, agent, argument-hint, hooks. Do NOT add custom fields like license, metadata, category, version, or generated-by.

• Name: Must pass all constraints from Step 2 (≤64 chars, lowercase+hyphens, no XML tags, no reserved words).
• Description: Start with 3rd-person verb ("Analyzes...", "Generates..."). Include both what the skill does AND when to use it, with 3–5 trigger phrases. Max 1024 chars. No XML tags.
• Invocation: disable-model-invocation: true for destructive actions. user-invocable: true for explicit-only. Omit both for auto-discover.
• Argument hint: Add argument-hint: [hint] if the skill accepts arguments (e.g., argument-hint: [url]).
• Advanced: Add context: fork and allowed-tools only if required.

Step 4: SOP Translation

Convert the workflow into numbered imperative steps.

• Each step starts with a command verb ("Extract...", "Analyze...", "Compile...").
• Use $ARGUMENTS and backtick substitution (e.g., !\gh pr diff``) for runtime context.

Authoring patterns — apply where appropriate:

• Degrees of freedom: Match specificity to task fragility. High freedom → text instructions. Medium → pseudocode. Low → exact scripts.
• Feedback loops: Add validation steps (e.g., "Run validator → fix errors → repeat").
• Template pattern: Define output format explicitly. Strict templates for data/API outputs; flexible templates when adaptation is useful.
• Examples pattern: Provide input/output pairs where output quality depends on demonstrated style or format.
• Conditional workflow: For decision points, branch explicitly: "Creating new? → Creation workflow. Editing existing? → Editing workflow."
• Checklist pattern: For complex multi-step workflows, provide a copyable checklist Claude can track progress against.
• Verifiable intermediates: For batch/destructive operations, use plan-validate-execute: create plan file → validate with script → execute after validation passes.
• Defaults over options: Provide one recommended approach with an escape hatch, not multiple equivalent choices.
• MCP tools: Reference with fully qualified names: ServerName:tool_name.
• Progressive Disclosure: Do not embed data only needed for one path — link to it or load it conditionally.
• No time-sensitive info: Do not include information that will become outdated.

Step 5: Scaffold Generation

Output the mkdir command for the chosen ecosystem:

• Claude: mkdir -p ~/.claude/skills/[skill-name]
• Antigravity: mkdir -p ~/.gemini/antigravity/skills/[skill-name]

Scripts (if applicable):

• Offload deterministic logic to scripts/. Scripts must handle errors explicitly — do not punt errors to Claude. Document all configuration constants with justification (no "voodoo constants").
• List required packages with install commands (e.g., pip install pypdf). Do not assume packages are pre-installed.

References:

• Keep references one level deep from SKILL.md — avoid chains like SKILL.md → advanced.md → details.md.
• Add a table of contents to reference files longer than 100 lines.
• Use forward slashes only in all file paths (reference/guide.md, not reference\guide.md).

Follow with the complete SKILL.md code block.

Step 6: Validate & Deliver

Run this checklist internally — fix any failures before delivering output.

Core quality

• Front matter < 1024 characters
• Only standard front matter fields used
• Name passes all constraints (≤64 chars, lowercase+hyphens, no XML, no reserved words)
• No XML tags in description
• Body < 500 lines
• Description starts with 3rd-person verb
• Description has 3+ trigger phrases and includes "Use when..."
• Invocation flags set correctly
• All steps begin with imperative verb
• Correct mkdir path for chosen ecosystem
• No time-sensitive information
• Consistent terminology throughout
• Examples are concrete, not abstract
• Progressive disclosure used appropriately
• Workflows have clear steps
• References are one level deep from SKILL.md

Code & scripts (if applicable)

• Scripts handle errors explicitly (no punting to Claude)
• No voodoo constants (all values justified)
• Required packages listed with install commands
• Scripts have clear documentation
• No Windows-style paths (forward slashes only)
• Validation/verification steps for critical operations
• Feedback loops for quality-critical tasks
• MCP tools use fully qualified ServerName:tool_name format

Post-delivery recommendations

After delivering the skill, recommend the user:

• Test with Haiku, Sonnet, and Opus
• Create 3+ evaluation scenarios with expected behaviors
• Test with real usage scenarios before sharing

Deliver: Sync status → checklist results → mkdir command → full SKILL.md code block → post-delivery testing recommendations.

Then say: "Tip: Have other skills? Say 'Upgrade this skill' with any SKILL.md, or 'Scan my skills' for a full health check."

Consult examples/ for reference outputs and evaluations/ for test prompt templates.

Upgrade Path

Step U1: Ingest Existing Skill

Read the provided SKILL.md. Parse front matter fields and body sections. Identify the target ecosystem (Claude Code or Antigravity) from the file path or content.

Step U2: Diagnostic Audit (CHECKPOINT)

Run the full 27-item validation checklist (from Step 6) against the existing skill. For each item, report:

• Pass — Meets current best practices
• Warning — Works but could be improved
• Fail — Violates current best practices

Present the diagnostic report. Say: "Here's the audit. Shall I upgrade this skill?" Wait for confirmation.

Step U3: Upgrade & Fix

Apply all fixes:

• Rewrite non-standard front matter to use only recognized fields.
• Restructure body into imperative steps if needed.
• Apply relevant authoring patterns from Step 4.
• Enforce progressive disclosure (move embedded data to references).
• Fix naming conventions, description format, and invocation flags.

Preserve the skill's original intent and domain logic — only change structure and compliance.

Step U4: Deliver Upgraded Skill

Output:

1. Change summary — Bulleted list of what was fixed and why.
2. Upgraded SKILL.md — Full code block ready to replace the original.
3. Post-upgrade recommendations — Same as Step 6 post-delivery.

Then say: "Tip: Want to check your other skills? Say 'Scan my skills' for a full health report."

Scan Path

Step S1: Discover Skills

Scan the user's skill directories:

• Claude Code: ~/.claude/skills/*/SKILL.md
• Antigravity: ~/.gemini/antigravity/skills/*/SKILL.md

If both directories exist, scan both. List all discovered skills. If no skills found, say: "No skills found in the default directories. Provide a path to scan."

Step S2: Quick Audit

For each discovered skill, run these key checks:

• Front matter present and < 1024 characters
• Only standard front matter fields used
• Name passes constraints (≤64 chars, lowercase+hyphens)
• Description starts with 3rd-person verb
• Body < 500 lines
• Steps begin with imperative verbs

Step S3: Health Report

Output a summary table:

Skill	Ecosystem	Checks Passed	Issues	Top Issue

Sort by most issues first. Then say: "Run 'Upgrade [skill-name]' on any skill to fix its issues."