cxshoutghost/claude-code-skillforge

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."