From local experiment to installable, trustworthy skill — in one command.
Skills are code. Engineer them like it.
The Agent Skills ecosystem has grown to 88K+ published skills (SkillsMP, skills.sh). Community audits estimate ~26% have security vulnerabilities. Most have descriptions that don't cover their actual trigger scenarios. There is no standard for what a "well-engineered skill" looks like.
If you haven't published yet — your skill is trapped in one project, can't be shared, and doesn't meet any platform's install standard. No README, no LICENSE, no proper structure, no discoverability.
If you already published — your repo might have issues you haven't noticed: leaked API keys in config files, missing .gitignore entries, structure that doesn't match the Agent Skills standard, or claims in the README that don't match what the skill actually does.
The gap is not in authoring — AI agents can already help write skill content. The gap is in engineering: validating structure, scanning for security issues, checking description coverage, enforcing claim discipline, and publishing correctly.
Skill Forge is a skill engineering methodology, publishing pipeline, and project skills architect. The methodology defines what "well-engineered skill" means. The pipeline automates validation and publishing. Both are valuable independently.
- Audits entire projects — point forge at any project directory and it organizes scattered skills, rules, and agent instructions into clean, maintainable structures — graduating personal tools to standalone repos and converting trigger-based rules to rule-skills
- Makes workflow skills actually get followed — detects multi-step skills and adds structure so agents follow your procedure step-by-step, instead of absorbing it as background knowledge. Creates the structure when forging new skills; flags missing structure when reviewing existing ones
- Scans for security issues — detects leaked API keys (
sk-,ghp_,AKIA), private keys, credential files, and missing .gitignore entries before they reach GitHub. Critical issues block push - Reviews every file, not just SKILL.md — a skill is a codebase. Forge reads every reference, script, and doc — checking that content is actionable for agents, references follow the three-layer format, scripts actually work, and docs match what SKILL.md claims
- Validates structure and discoverability — checks frontmatter, description coverage, body length, terminology, and cross-file consistency so agents can find and correctly trigger your skill
- Keeps your README honest — flags claims that exceed what your skill actually does, catches hardcoded paths, and verifies install commands and LICENSE
- Publishes and registers across platforms — pushes to GitHub with optimized About description and discoverable topics (3-tier selection), then detects Claude Code, Codex, Cursor, Windsurf, and GitHub Copilot skill roots and symlinks to one source of truth
- Generates community-ready artifacts — README (with readme-craft integration), LICENSE, .gitignore following the Agent Skills standard
Pipeline stages
def forge(target):
- Environment — run
setup.sh, load config, onboard if first use - Assess — discover existing skills (review path) or gather context for new skill (create path)
- Plan — create
/tmp/skill-forge-<name>.mdwith per-item checklists; fresh each run (plan = checklist) - Per item: Validate & Fix — Core Validation + Content Review (read every file) + Repo Hygiene → fix →
Skill("readme-craft")→Skill("self-review")→ local ready - Publish (optional) — confirm target,
gh repo create+ push, set About/Topics for discoverability
What Users Get
| Capability | What it means for you | How forge delivers it |
|---|---|---|
| Security assurance | Your skill won't leak API keys or credentials to GitHub | Repo hygiene scan: regex pattern matching for common secret formats |
| Description quality | Agents will actually find and trigger your skill | Coverage check: does the description mention key scenarios from the body? |
| Cross-platform compatibility | Works on Claude Code, Codex, Cursor, Windsurf, Copilot — not just one | Standard frontmatter validation + platform-agnostic structure |
| Efficient context usage | Your skill doesn't waste the agent's context window | Body under 500 lines, instruction density check, progressive disclosure via references/ |
| Claim discipline | README says what the skill actually does, no inflated promises | README ↔ SKILL.md consistency check |
| Configuration pattern | Your skill can have user preferences, done properly | Reference pattern for declaring and reading config |
| Dependency installation | Required tools and skills are installed automatically | scripts/setup.sh standard — install or block, no graceful skip |
| One-command publishing | Local files → installable GitHub repo | Push: gh repo create + push (everything else done at local ready) |
| Workflow execution fidelity | Your multi-step workflow skill actually gets followed, not just read | Create: generates step-by-step structure agents treat as procedure. Review: warns if workflow skill lacks this structure |
| Ongoing maintenance | Catch regressions when you update | Re-run forge on existing repos to catch regressions |
Token cost: Review ~5-15K | Create ~10-20K | Push ~1-2K. No subagents, no Python, no surprise costs.
| You're doing... | Need skill-forge? |
|---|---|
| Writing a skill's content | No — focus on the domain, not formatting |
| Ready to validate or publish | Yes — "publish this skill" or "forge a skill" |
| Reviewing an existing repo | Yes — "review this skill repo" |
| Cleaning up a project with mixed skills, rules, and agent instructions | Yes — "audit this project" or point forge at the directory |
skill-forge is a post-authoring tool. Load it when you're done writing, not while writing.
npx skills add motiful/skill-forge -gThen tell your AI coding assistant:
"Review this skill" — validate, scan, fix → local ready
"Create a skill for X" — build from scratch → local ready
"Publish this skill" — forge + publish to GitHub
Say any of:
- "Review this skill repo" — discover, validate, fix → local ready
- "Audit my skill" — same as review
- "Create a skill for X" — build from scratch → local ready
- "Forge a skill from my notes" — same as create
- "Publish this skill" — forge + publish to GitHub
- "Push this skill to GitHub" — same as publish
Example: Forge + Publish self-review
This is a sample flow, not a transcript from one specific machine.
$ "Publish self-review to GitHub"
Step 0: Config
✓ ~/.config/skill-forge/config.md found
✓ skill_workspace: ~/skills/, github_org: motiful
Step 3: Validate (review path — skill already exists)
✓ name: self-review (kebab-case, 11 chars)
✓ description: single-line, 133 chars
✓ body: 226 lines (< 500)
✓ references/dimensions.md exists and is linked
✓ README audited by readme-craft — passed
✓ no junk files, no leaked secrets
Fix → Local Ready
✓ git init + initial commit
✓ linked ~/.claude/skills/self-review → ~/skills/self-review/
✓ all local ready criteria met
Push
✓ confirmed: motiful/self-review, public
✓ gh repo create motiful/self-review --public --source=. --push
✓ Published — install with: npx skills add motiful/self-review
npx skills add motiful/skill-forge -gWorks with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and other Agent Skills adopters.
Manual registration (clone + symlink)
git clone https://github.com/motiful/skill-forge ~/skills/skill-forge
# Register only in roots you actually use.
# Claude Code
ln -sfn ~/skills/skill-forge ~/.claude/skills/skill-forge
# Codex
ln -sfn ~/skills/skill-forge ~/.agents/skills/skill-forge
# VS Code / GitHub Copilot
ln -sfn ~/skills/skill-forge ~/.copilot/skills/skill-forge
# Cursor
ln -sfn ~/skills/skill-forge ~/.cursor/skills/skill-forge
# Windsurf
ln -sfn ~/skills/skill-forge ~/.codeium/windsurf/skills/skill-forge- Git (required)
- Node.js (required for
npx skills add) - GitHub CLI (
gh) — required for publishing. Forge works without it for local validation
Installed automatically by scripts/setup.sh on first run:
| Dependency | Purpose |
|---|---|
motiful/readme-craft |
3-tier layout, badge selection, dark/light logo for README generation |
motiful/rules-as-skills |
Rule-skill methodology: three-layer model, format, in-repo patterns |
motiful/self-review |
4-pillar, 6-dimension alignment audit for skill quality validation |
Positioning
Skill Forge is a skill engineering methodology and publishing pipeline. The methodology defines what "well-engineered skill" means — referenced while writing or improving skills. The pipeline automates validation and publishing — run when ready to share.
It helps you create skills that are installable, publishable, maintainable, and honestly described.
It does not claim to prove that a generated skill's domain outputs are objectively excellent, production-safe, or aesthetically strong. Those judgments still depend on the author, the domain, and real usage.
What's Inside
SKILL.md — Full creation + publishing pipeline
.claude/skills/
└── maintenance-rules/
└── SKILL.md — In-repo maintenance rules (not independently published)
docs/
└── quality-principles.md — Maintainer governance: decision test, quality dimensions, boundaries
scripts/
└── setup.sh — Dependency installation (readme-craft, rules-as-skills, self-review)
references/
├── installation.md — setup.sh standard: dependency detection and installation
├── skill-invocation.md — Runtime invocation reliability for skill-to-skill calls
├── onboarding.md — Interactive first-use guidance pattern
├── skill-configuration.md — User preferences, config location, stateless principle
├── skill-format.md — SKILL.md + reference file format specification
├── skill-composition.md — Composition philosophy and context budget
├── rule-skill-pattern.md — Forge integration: detection, auto-creation, packaging of rule-skills
├── publishing-strategy.md — Skill or Collection decisions
├── platform-registry.md — Where each platform looks for skills
├── readme-quality.md — README writing and claim discipline
├── script-quality.md — Script file structure guidelines
├── maintenance-guide.md — In-repo maintenance-rules: when to create, what to include
├── anti-graceful-skip.md — Default-execute principle, no implicit skip paths
├── execution-procedure.md — Pseudocode + plan-as-checklist + GATE pattern for workflow skills
├── templates.md — README, LICENSE, .gitignore skeletons
├── project-audit.md — Discovery, Classification, Plan File, Rules Conversion for project-level forge
└── github-metadata.md — GitHub repo About, Topics, and metadata workflow
Bug reports, validation rule ideas, and reference doc improvements are welcome. Open an issue or pull request on GitHub.
Forged with Skill Forge · Crafted with Readme Craft