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.

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
All succeed: Synthesize best practices, present summary. Say: "Here are the latest best practices. Proceed?" Wait for confirmation.
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:

Smithery — https://smithery.ai/skills?q=[skill-name]
SkillsMP — https://skillsmp.com/search?q=[skill-name]
SkillsLLM — https://skillsllm.com/search?q=[skill-name]
SkillHub — https://skill-marketplace.com/search?q=[skill-name]
Antigravity Skill Vault — https://github.com/search?q=[skill-name]+topic:antigravity-skill
Awesome Skills — https://github.com/sickn33/antigravity-awesome-skills CATALOG.md
GitHub Topics — https://github.com/search?q=[skill-name]+topic:claude-code-skill
Composio — https://composio.dev/search?q=[skill-name]
AI Templates — https://www.aitmpl.com/skills?q=[skill-name]
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.

claude-code-skillforge