skill-forge

name	skill-forge
description	Validate, fix, and publish skills as GitHub repos. Structures workflow skills for execution fidelity. Registers skills across platforms via symlinks and guides first-use onboarding. Use when the user says "create a skill", "forge a skill", "review this skill repo", "audit this skill", "audit all my skills", "audit this project", "clean up my skills", "check my skill", "publish this skill", "push this to GitHub", "structure my workflow skill", "extract a skill from this folder", "turn my prototype into a skill", or points to a project directory with mixed skills and rules, or to an engineering folder where a skill was being prototyped. Forge: triage → discover → classify → validate → fix → local ready. Workshop input → triage extracts skill before audit. Nothing found → onboard user, scaffold, then same pipeline. Publish to GitHub when requested (Step 4).
license	MIT
metadata	{"author":"motiful","version":"9.1"}

Skill Forge

Skill engineering methodology and publishing pipeline. Defines what "well-engineered skill" means, validates skills against that standard, and produces publishable GitHub repos.

Three-Dimension Mental Model

Skill engineering decisions split along three orthogonal dimensions. Keep them separate — mixing causes self-contradictory choices.

Dimension	Question	Decides
A. Entry	Should this be its own skill?	New capability skill / new rule-skill / just a reference file
B. Dependency	How do skills relate to each other?	Runtime (setup.sh, cross-repo OK) vs Maintenance (must ship together)
C. Publishing	How to package for distribution?	Single Skill repo / Collection repo / In-repo

Each reference below covers ONE dimension (mostly):

• references/publishing-strategy.md — Dimension C
• references/rule-skill-pattern.md — Dimension A (for rule-skills specifically)
• references/skill-composition.md — Dimension B
• references/anti-graceful-skip.md — orthogonal quality check (applies to all dimensions)

When a decision seems to conflict, check which dimension you're reasoning about. A/B/C answers do not constrain each other.

Engagement Principles

These rules always apply. Read them before acting.

1. Assess before acting — first step is always understanding the situation (scan, inventory, read)
2. Report before modifying — show findings, get user approval, then act
3. Security > Structure > Quality > Polish — when multiple issues exist, fix in this priority
4. Default to local-ready — forge runs through validation and fixes until local-ready. User can stop at any point
5. One skill at a time for changes — diagnose in batch, modify one by one with user confirmation
6. Local-ready = publish-ready — publishing only sends to remote, never re-validates
7. Understand context — a skill may belong to a tool, or relate to other skills. Don't treat each in isolation
8. Follow module interfaces — when the procedure calls a reference file, read the file and follow its EP. The module's own EP is the authority, not any inline summary in the parent
9. Report what you can't resolve — severity follows the check's own criteria, not assumed user preference. A finding explained by another explicit rule is resolved, not a discrepancy — dismiss it with the reason
10. Triage before validate — read the project's directory semantics first. Never grade a workshop against gold-standard skill criteria. If the target is mixed engineering content, run Triage to extract the skill before any audit work. See references/triage.md

Execution Procedure

Follow the pseudocode step by step. At STEP 2, write a plan file with per-item checklists — this IS your execution checklist. Re-read the plan before each item to stay on track.

Forge

Trigger: "review", "check", "audit", "audit this project", "audit all my skills", "clean up my skills", "create a skill", "forge a skill", "build a skill for X", "extract a skill from this folder", "turn my prototype into a skill", "publish this skill", "push this to GitHub", "put this on GitHub"

def forge(target):
    # STEP 0: Environment
    run("scripts/setup.sh")                            # exit non-zero → STOP
    config = assess_config_needs()                     # references/skill-configuration.md
    if not config: assess_and_guide(target)            # references/onboarding.md

    # STEP 0.5: Triage — what is the target, before validating it?
    state, skill_path = triage(target)                 # references/triage.md
    # state ∈ {skill_shaped, workshop, empty}
    # workshop  → triage ran HITL dialogue, extracted skill into a clean dir, returned new path
    # empty     → no skill artifacts; falls into Nothing Found branch in STEP 1
    # skill_shaped → target unchanged
    if state == "workshop": target = skill_path        # re-target to extracted skill
    # AI judgment, not hardcoded thresholds. Read folder names + file types first;
    # do not open file bodies until intent is locked. See references/triage.md §Signals.

    # STEP 1: Discover — paths and classification ONLY
    classified = discover_and_classify(target)         # references/project-audit.md
    # Find: SKILL.md (any depth), rules files, project instructions, setup scripts
    #
    # BOUNDARY: Discovery reads file PATHS and FRONTMATTER (for classification).
    # Discovery also reads project standards (CLAUDE.md, AGENTS.md) — shared context.
    # Discovery does NOT read: SKILL.md body, reference file content.
    # Discovery does NOT validate: quality, structure, reference integrity.
    # Discovery does NOT check git log, git diff, or previous review reports.
    # Every review is a FULL review — no incremental/delta mode, no "nothing changed
    
    
    

     classified:                                     

    :                                              
        context = detect_existing()                    
         (context) > : context = ask_user()
          context: ask_user()
        search_ecosystem(target)                       

        
        
        
         assess_workspace_need(name, context):       
            path = 
            mkdir_p(path); git_init(path)               
        :
            path = 

        source_docs = detect_source_documents(context) 
        scaffold_skill_md(path, context)                
        ep_contract = extract_ep_signatures(path)      

         source_docs:
            transform_references(source_docs, ep_contract)
        :
            write_references(path, ep_contract)

         all_ep_calls_have_matching_defs(path)   

        readme = Skill(, )  
         readme.delivered                        
        write_artifacts(path)                          
        items = [SkillItem(path)]

    
    
    
    

    
    plan_path = 
    delete_if_exists(plan_path)                        

    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

    write_plan(plan_path, items)                       
     file_exists(plan_path)
     plan.is_per_item_structured                 
     plan.top_level_step_count >= (items)     
    
    

    
    plan.items.sort(priority=)
    findings_dir = 
    rm_rf(findings_dir)                                
    mkdir(findings_dir)

     batch  chunk(plan.items, ):                 
        agents = []
         item  batch:
            findings_path = 
            agents.append(Agent(
                
                
                
                
                
                
                
                
                
                
                
                
            ))
        run_parallel(agents)                           
        
        
         item  batch:                             
            findings_path = 
             file_exists(findings_path)          
            findings = read(findings_path)
             row_count(findings) >= (VALIDATION_TABLE_ROWS)
            review_and_update_plan(plan_path, item, )

    
    
    
    
    aggregate_and_append(findings_dir, plan_path)      
    patterns = cross_item_analysis(findings_dir)       
    report_to_user(plan_path, patterns)

    
    
    fix_findings(plan_path)
     no_unchecked_must_fix(plan_path)

    
    
    rc_result = Skill(, )  
     rc_result.delivered
    sr_result = Skill(, target)               
     sr_result.no_broken_dimensions

    
    conflicts = audit_registrations(target, config)    
     conflicts.critical: resolve_or_block()          
    detect_and_register(target)                        
      target.has_git: git_init(target)
     local_ready(target)                         

    
    
     publish_requested:
        confirm_with_user(org=config.github_org, name=skill_name, visibility=)
        run()
        
        
        update_forge_config(skill_name)                
        assess_cc_market(config)                       
        ()

Parallel Execution

If your platform supports sub-agents (e.g., Claude Code Agent tool): setup.sh and discovery can run in parallel; independent items can validate in parallel; readme-craft then self-review are sequential.

One agent per item. Each Step 3 validation agent handles exactly one discovered item — do not batch multiple items into a single agent. This ensures each item gets isolated context and full validation depth. Launch all item agents in parallel.

Security

Pre-flight gate. If must-fix findings → block push, stop validation.

Check	Criteria
Leaked secrets	Scan for: API keys (sk-, ghp_, AKIA, xox[bpas]-), tokens, passwords, private keys (-----BEGIN.*PRIVATE KEY-----). Fix — block push
Credential files	.env, credentials.json, *.pem, *.key tracked → Fix
.gitignore coverage	.env*, node_modules/, .DS_Store, IDE configs, OS files

Validation

One pass, read every file, check everything. Each finding tagged by category. Before running, scan the project for its own quality standards (CLAUDE.md, AGENTS.md, .editorconfig, rules directories) — these add to the checks below. Break per-file review into plan sub-tasks; use sub-agents for parallelism.

Result types — every validation table row produces exactly one result:

• PASS: Meets the standard. Brief note on what was checked. Required for coverage proof.
• Must fix: Deviates from standard with concrete risk. State what the standard says, what was found, and what goes wrong for users.
• Suggestion: A better mechanism exists that would unlock higher capability. Describe the upgrade path and benefit. User decides.

No other result types. If it's not PASS, must-fix, or suggestion — it's PASS.

For each finding, explain the user impact — not which rule was violated. Standards are defined in the reference files; the validation tables below point to them. Each table row referencing a file constitutes the EP dispatch — the agent reads the reference's EP when evaluating that check (per batch principle, references/execution-procedure.md §7).

Structure

Organization, layout, file existence, dependencies.

Check	Standard
Frontmatter fields	references/skill-format.md §Standard Frontmatter
name	references/skill-format.md §Standard Frontmatter — kebab-case, matches directory
description format	references/skill-format.md §Standard Frontmatter — single-line, < 1024 chars, non-empty, no angle brackets
description quality	MUST — references/skill-format.md §Description Quality (validate_description_quality()). Both halves (what + when), explicit "Use when…" triggers + concrete keywords, third person only, no vague filler, no body leak (no restating own MUST/NEVER rules, no concept-teaching). Any missing gate = must-fix
Body size	references/skill-format.md §Body — under 500 lines
Body opening	MUST — references/skill-format.md §Body Opening (validate_body_opening()). Opener (first lines / blockquote after H1) must be actionable (model / Execution Procedure / procedure), NOT meta-commentary — epistemic self-description, authority declaration, cross-skill navigation as opener, or maintenance citation = must-fix
Why-discipline (IRB)	MUST — references/skill-format.md §Why-Discipline (IRB) (validate_why_discipline()). Adopted from the ctx collection. INTENT (a one-clause so-that scoping a rule) stays inline; RATIONALE ("chose X over Y") and BACKGROUND (model-known / history) must NOT leak into the body — they belong in the skill's backstage decision record; an example / note / figure stated as a binding requirement = must-fix
References exist	All SKILL.md references resolve, no orphans
Reference file frontmatter	Each .md in references/ must have --- name + description --- per references/skill-format.md §Reference Frontmatter
Reference file size	Each reference file under 300 lines per references/reference-extraction.md; over 300 = must split
Dependencies	references/installation.md — setup.sh handles each declared dependency

Quality

SKILL.md + references + scripts + assets reviewed as one unit. Read SKILL.md first, follow module references, check coherence across all files.

Shared checks (SKILL.md and every reference file):

• Three-layer format + Positional Test + EP-Content alignment → validate_format() + review_reference() — references/skill-format.md
• EP comment discipline — references/execution-procedure.md §5
• Terminology consistency across all files

Check	Standard
Description coverage	Description covers key trigger scenarios from body — see references/skill-format.md §Description Quality gate 2 (explicit "Use when…" triggers + concrete keywords)
Description clarity	Comprehensible to a stranger without project context — see references/skill-format.md §Description Quality gates 4–5 (specific not vague, no body leak / rule-restatement)
Invocation reliability	references/skill-invocation.md
Graceful skip	references/anti-graceful-skip.md
Execution Procedure	references/execution-procedure.md — workflow skill + no EP = must fix
Entry complexity	Multiple modes must produce different deliverables
Script quality	references/script-quality.md
In-repo skills	Full validation recursively; cross-vendor symlinks use relative paths
Standard enforcement	Every reference must have an EP function call from SKILL.md — no call = 100% skip (references/execution-procedure.md §4)
EP contract integrity	Bidirectional: (1) every ref.function() call in SKILL.md EP has a matching def function() in the reference; (2) every reference def is called from SKILL.md. Parameter names must match. Reference with data but no def = must fix
EP field resolvability	Every data field referenced in EP pseudocode (answers.X, context.Y, brief.Z) must have a documented inference source. See references/anti-graceful-skip.md §Principle 5 + references/execution-procedure.md §4 Field-level resolvability
Assets referenced	Every asset file referenced by SKILL.md or references
Maintenance-rules need	references/maintenance-guide.md
Onboarding need	references/onboarding.md — zero-config → PASS; first-use decisions or credentials needed → must fix
Configuration need

Publishing

External-facing presentation and packaging.

Check	Standard
README quality	references/readme-quality.md — deferred to readme-craft in Fix Phase
Dependency mirroring	SKILL.md dependencies mirrored in README
Install command	npx skills add <org>/<repo> as primary
No hardcoded paths	No personal paths (~/, /Users/) in published files
LICENSE, .gitignore	references/templates.md — existence + content
Script documentation	Document what scripts do and permissions needed
GitHub metadata	Covered by readme-craft — do not duplicate
docs/ accuracy	No stale content vs SKILL.md claims
Unnecessary files	No lock files, > 1MB media, build artifacts
Platform-specific instruction files	Skill repo MUST NOT contain CLAUDE.md / AGENTS.md / .cursor/rules/ / .github/copilot-instructions.md or other single-platform agent instruction files — must-fix. See references/project-audit.md §Skill Repo: Platform Instruction Files Are Must-Fix and rules-as-skills/SKILL.md §In-Repo Rule-Skills §Cross-Platform Constraint

Fix Phase

Plan-driven. STEP 3b appends ## Findings to the plan file (extracted from per-skill finding files). STEP 3c reads [ ] rows and fixes them, marking [x]. One file, entire lifecycle.

1. Fix (STEP 3c) — read ## Findings in plan file. Each [ ] row = one fix action. Execute, then [ ] → [x]. Assert: zero unchecked must-fix rows.

2. User decides — must-fix is mandatory. Suggestion is optional (user approves/skips).

3. README — REQUIRED skill invocation:

   Run: Skill("readme-craft", "review <path>") Do not substitute with manual README review. readme-craft owns universal README quality. skill-forge owns skill-specific standards (references/readme-quality.md). Both apply, domain wins.

   If README does not exist, readme-craft will create it. After readme-craft completes, check skill-specific standards from references/readme-quality.md and fix any gaps.

4. Create missing repo artifacts (LICENSE, .gitignore) if they don't exist

5. Update remaining artifacts to pass validation

6. Local registration — detect platform roots, create symlinks:

   See references/platform-registry.md for the full path matrix. Paths found → symlink all. No paths → skip. User names undetected platform → create + link. Never link one vendor path to another. Every consumer path points to the skill's source directory. In-repo skills: cross-vendor symlinks like .agents/skills/X → ../../.claude/skills/X must use relative paths.

7. Git init (if not already a git repo) + initial commit

8. Final quality review — REQUIRED skill invocation:

   Run: Skill("self-review", "<skill-path>") Do not substitute with manual quality check. Do not declare local ready if self-review reports Broken dimensions.

9. Verify all Local Ready criteria are met

Local Ready Definition

A skill is "local ready" when ALL of the following are true:

<skill-name>/
├── SKILL.md                           # validated (Step 3 passed)
├── references/                        # if needed, all links resolve
├── scripts/                           # if needed, setup.sh works
├── README.md                          # audited by readme-craft
├── LICENSE                            # exists
└── .gitignore                         # matches template

• git init done, initial commit made
• Local registration (symlinks) done for all detected platform roots
• All must-fix issues resolved, suggestions addressed or acknowledged
• README audited by readme-craft (not just manually checked)

Local ready = publish-ready. The only remaining action is Step 4 (publish to remote).

Publish to Remote

Step 4 of forge. Only runs when the trigger includes publish intent. Requires local ready.

1. Confirm — remote target (<org>/<skill-name>, visibility), local ready status

2. Execute:

   # Push to GitHub (default)
   gh repo create <org>/<skill-name> --public --source=. --push
   
   # Non-GitHub: ask for remote URL
   git remote add origin <url> && git push -u origin main
   

3. Update config — add to ~/.config/skill-forge/config.md "Published Skills"

4. Report: "Your skill is on GitHub. Install with npx skills add <org>/<skill-name>."

CC Market: assess_cc_market(config) — references/platform-registry.md.

References

• references/triage.md — Pre-validation triage: workshop vs skill-shaped detection, semantic map, author intent dialogue, skill extraction (STEP 0.5)
• references/installation.md — setup.sh standard: dependency detection, installation, two outcomes
• references/skill-invocation.md — Runtime invocation reliability: explicit Skill(...) call + output gate pattern
• references/onboarding.md — Interactive first-use guidance pattern
• references/skill-configuration.md — User preferences, config location, litmus test, stateless principle
• references/skill-format.md — Format specification for SKILL.md and reference files (frontmatter, Execution Procedure, content alignment, positional test)
• references/skill-composition.md — Composition philosophy: context budget, dependency tiers
• references/rule-skill-pattern.md — Forge integration: detection, auto-creation, and packaging of rule-skills
• references/publishing-strategy.md — Skill vs Collection publishing models (called by project-audit.md Classification)
• references/platform-registry.md — Platform skill paths, detection logic, community directories
• references/templates.md — README, LICENSE, and .gitignore skeletons
• references/readme-quality.md — README writing, claim discipline, example rules
• references/script-quality.md — Script size limits, module split triggers, dependency policy
• references/maintenance-guide.md — In-repo maintenance-rules skill: when to create, required content, template, reference dimension classification (D1/D2/D3)
• references/anti-graceful-skip.md — Default-execute principle, skip conditions, no-downside enhancements, Step 3 audit criteria
• references/execution-procedure.md — Pseudocode + plan-as-checklist + GATE pattern + attention model + non-overlapping ownership for workflow skills
• references/project-audit.md — Discovery, Classification, Plan File, Rules Conversion, Execution Order for project-level forge
• references/reference-extraction.md — When to extract sections into references, index quality, line count thresholds
• references/registration-audit.md — Pre-registration conflict detection: workspace shadows global, broken links, copy vs symlink