Agent Skill Foundry

A local-first toolkit for turning repeatable AI-agent workflows into validated, publishable skills.

Agent Skill Foundry is for developers who use Codex, Claude Code, Cursor, Copilot, or other coding agents and want reusable workflow skills that feel engineered, not improvised.

Problem

Agent skills are becoming a practical way to package repeatable workflows, but many skills ship as vague prompt files: broad triggers, unclear inputs, missing validation, no examples, and unsafe edge cases. That makes agents harder to route, harder to trust, and harder to reuse.

Features

• init command for scaffolding a professional SKILL.md folder.
• validate command for scoring trigger clarity, structure, examples, validation, and safety boundaries.
• Markdown and JSON reports for human review or CI.
• Good and bad example skills for quick comparison.
• Codex-focused operating instructions in AGENTS.md.
• No network calls, no API key, no runtime dependencies.

Quick Start

npm install
npm test
node src/cli.mjs validate examples/good-skill --out validation/good-skill-report.md

Create a new skill:

node src/cli.mjs init examples/generated/release-notes --name release-notes
node src/cli.mjs validate examples/generated/release-notes

Example Workflow

1. Draft or scaffold a skill with node src/cli.mjs init.
2. Fill in the workflow, inputs, outputs, validation, and safety boundaries.
3. Add examples and references when they reduce ambiguity.
4. Run node src/cli.mjs validate <skill-dir> --out validation/report.md.
5. Ask Codex to fix the highest-severity findings and rerun the validator.

Use With Codex

Tell Codex:

Read AGENTS.md and docs/USAGE.md first. Validate examples/good-skill, then improve a new skill scaffold until the score is publishable. Do not broaden the trigger or add destructive commands.

Codex should read first:

• AGENTS.md
• docs/USAGE.md
• src/core.mjs
• examples/good-skill/SKILL.md

Commands Codex should run:

npm test
node src/cli.mjs validate examples/good-skill --out validation/good-skill-report.md

Expected outputs:

• A quality score.
• A Markdown report.
• Targeted fixes to SKILL.md, examples, or references.

Codex should not:

• Add network services or dependencies without a clear reason.
• Claim a skill is publishable without running validation.
• Add destructive git, secret handling, or platform-submission behavior.

Example Prompts

Use Agent Skill Foundry to audit this SKILL.md and make it publishable without changing the workflow's scope.

Create a new skill for repo onboarding, include examples and validation, then run the quality gate.

Review this skill for trigger specificity, output quality, and safety boundaries. Produce a report and a patch.

Folder Structure

agent-skill-foundry/
  src/                  CLI and validation engine
  tests/                Node test suite
  docs/                 Setup, usage, architecture, roadmap
  examples/             Good, bad, and generated skills
  validation/           Generated reports
  screenshots/          Mock report screenshot

Configuration

The MVP is convention-driven and does not require a config file. The validator reads a skill directory containing SKILL.md and optional references/, examples/, and scripts/ folders.

Future versions may support skill-foundry.config.json for custom section requirements, scoring weights, and organization policies.

Output Example

publishable: 91/100 (2 findings)

Markdown reports include:

• Score and grade.
• Findings with severity, evidence, and recommendation.
• Codex remediation guidance.

Roadmap

• Configurable scoring rules.
• Compatibility export checks for Codex, Claude Code, Cursor, and Copilot.
• CI-friendly GitHub Action example.
• Skill marketplace readiness checklist.
• Optional JSON schema validation for richer frontmatter.

License

MIT. See LICENSE.