# Skill Forge > 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… - **Type:** Skill - **Install:** `agentstack add skill-motiful-skill-forge-skill-forge` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [motiful](https://agentstack.voostack.com/s/motiful) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [motiful](https://github.com/motiful) - **Source:** https://github.com/motiful/skill-forge ## Install ```sh agentstack add skill-motiful-skill-forge-skill-forge ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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" ```python 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 # since last review" shortcuts. Prior results do not reduce current scope. # Content reading and validation happen in STEP 3, driven by the plan. # If you finish STEP 1 having already validated content → you collapsed the loop. if classified: # --- Existing items --- else: # --- Nothing found --- context = detect_existing() # scan skills dirs + conversation if len(context) > 1: context = ask_user("Which existing skill?") elif not context: ask_user("What does this skill do? When should it trigger?") search_ecosystem(target) # npx skills find / skills.sh # Workspace: standalone + design-heavy → full workspace with backstage # Signals: public/publishable, 3+ expected references, multi-session, # user mentioned design docs. Rule-skill/in-repo/prototype → skip. if assess_workspace_need(name, context): # HITL — user confirms Skill("repo-scaffold", f"scaffold {name}, git init but skip push") path = f"{config.skill_workspace}/{name}-project/{name}/" else: path = f"{config.skill_workspace}/{name}/" source_docs = detect_source_documents(context) # backstage, research, outputs scaffold_skill_md(path, context) # follows references/skill-format.md standards ep_contract = extract_ep_signatures(path) # function calls in SKILL.md EP if source_docs: transform_references(source_docs, ep_contract) else: write_references(path, ep_contract) assert all_ep_calls_have_matching_defs(path) # GATE readme = Skill("readme-craft", f"create {path}") # references/templates.md assert readme.delivered # README required for local ready write_artifacts(path) # LICENSE, .gitignore — skip if exist items = [SkillItem(path)] # From here: all items — new or existing — go through the same pipeline. # Capability detection is NOT a separate step. Each reference module defines # its own applicability criteria. The validation tables cover every reference. # No explicit caps.X enumeration — all references are checked uniformly. # STEP 2: Plan — GATE: file must exist AND be per-item structured before Step 3 plan_path = f"/tmp/skill-forge-{name}.md" delete_if_exists(plan_path) # always fresh, no resume between runs # Plan MUST be organized per-item, NOT per-check-type. # Each discovered item gets its own top-level checklist entry with sub-steps. # Step 3 iterates this plan item by item — no plan means no loop. # # Plan structure (every plan follows this, no exceptions): # # ## Steps # - [ ] 1. Validate # - [ ] Security scan # - [ ] Validate (all table rows) # - [ ] 2. Validate # - [ ] ... # ## Findings # appended by STEP 3b # ### # - [ ] must-fix | check | file | description # - [ ] suggestion | check | file | description # ## Progress # Completed: 0 / N # # STEP 3a checks off validation steps. STEP 3b appends ## Findings. # STEP 3c reads ## Findings, fixes [ ] rows, marks [x]. # STEP 3d runs readme-craft + self-review on TARGET root (not per-item). write_plan(plan_path, items) # use Bash if Write tool requires Read assert file_exists(plan_path) assert plan.is_per_item_structured # GATE: each item = top-level entry + sub-steps assert plan.top_level_step_count >= len(items) # GATE: count top-level entries ≥ discovered items # ↑ If the plan batched N items into fewer entries, this fails. Rewrite: one entry per item. # review_and_update_plan between major steps: references/execution-procedure.md # STEP 3a: Validate — in batches of up to 5, one agent per item plan.items.sort(priority="security > in-repo > personal > product > rules") findings_dir = f"/tmp/skill-forge-findings-{name}/" rm_rf(findings_dir) # clean stale results from prior runs mkdir(findings_dir) for batch in chunk(plan.items, 5): # at most 5 at a time agents = [] for item in batch: findings_path = f"{findings_dir}/{item.name}.md" agents.append(Agent( f"Validate ONE skill: {item.path}. " f"Read the Security/Structure/Quality/Publishing validation tables " f"in {skill_forge_skill_md}, then read {item.skill_md} and EVERY " f"file under {item.path}/references/. " f"Check every row in the validation tables against SKILL.md and each reference file. " f"For each reference file, the EP function declared in its frontmatter " f"pseudocode block (e.g. validate_format(), review_reference()) IS the " f"dispatch entry — invoke it when evaluating rows that point to that reference. " f"Write one row per check to {findings_path}: " f"'- PASS | check | file | description' or " f"'- [ ] must-fix/suggestion | check | file | description'. " f"Do NOT skip rows. Do NOT fix. Write to file only." )) run_parallel(agents) # launch this batch # WAIT for batch to complete. Do NOT launch next batch until all findings # files in this batch exist and pass the coverage assert. for item in batch: # collect before next batch findings_path = f"{findings_dir}/{item.name}.md" assert file_exists(findings_path) # agent must have written findings findings = read(findings_path) assert row_count(findings) >= len(VALIDATION_TABLE_ROWS) review_and_update_plan(plan_path, item, "validated") # STEP 3b: Aggregate + report (Observe-Then-Act Phase B — references/execution-procedure.md §10) # 1. Extract [ ] rows from {findings_dir}/*.md, append as ## Findings to {plan_path} # 2. Cross-item analysis: identify systemic patterns across finding files # 3. Report plan path + patterns to user aggregate_and_append(findings_dir, plan_path) # [ ] rows → ## Findings in plan patterns = cross_item_analysis(findings_dir) # §10 Phase B: full-picture patterns report_to_user(plan_path, patterns) # STEP 3c: Fix — ## Findings in plan file is the todo list. # Each [ ] row = one fix. Mark [x] when done. fix_findings(plan_path) assert no_unchecked_must_fix(plan_path) # STEP 3d: Target-level quality gates — run on TARGET root, not per-item # These apply whether target is a standalone skill or a collection. rc_result = Skill("readme-craft", f"review {target}") # REQUIRED — use Skill tool assert rc_result.delivered sr_result = Skill("self-review", target) # REQUIRED — use Skill tool assert sr_result.no_broken_dimensions # Registration + git conflicts = audit_registrations(target, config) # references/registration-audit.md if conflicts.critical: resolve_or_block() # HITL detect_and_register(target) # references/platform-registry.md if not target.has_git: git_init(target) assert local_ready(target) # see Local Ready Definition # STEP 4: Publish (optional — only when trigger includes publish intent) # Triggers: "publish this skill", "push this to GitHub", "put this on GitHub" if publish_requested: confirm_with_user(org=config.github_org, name=skill_name, visibility="public") run(f"gh repo create {org}/{name} --public --source=. --push") # Non-GitHub: git remote add origin && git push -u origin main # GitHub metadata (description + topics) already applied by readme-craft Step 7 update_forge_config(skill_name) # add to Published Skills assess_cc_market(config) # references/platform-registry.md print(f"Install with: npx skills add {org}/{name}") ``` ### 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, /` 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 … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [motiful](https://github.com/motiful) - **Source:** [motiful/skill-forge](https://github.com/motiful/skill-forge) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-motiful-skill-forge-skill-forge - Seller: https://agentstack.voostack.com/s/motiful - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.