skill-factory

name	skill-factory
description	Build, update, evaluate, and optimize Agent Skills / SKILL.md packages from web research, authoritative sources, private documents, or user-provided methodology. Use when the user wants to create a standard skill package, convert niche methods or practices into skills, design eval tasks, run a SkillOpt-style improvement loop, or produce best_skill.md.

Skill Factory

This skill builds and optimizes standard Agent Skill packages.

Use it when the user wants to create, update, validate, evaluate, or optimize a SKILL.md-based skill, especially when the source material comes from one or more of these inputs:

• latest or authoritative public information from web research
• private documents, notes, procedures, or business logic
• a niche methodology, emerging practice, internal workflow, or expert mental model
• an existing skill that needs refactoring, evaluation, or SkillOpt-style improvement

Operating principle

Treat a skill as a reusable operational knowledge package, not as a long prompt. Keep the main SKILL.md compact and put detailed knowledge, examples, source notes, and evaluation material in separate files.

Default package shape:

skill-name/
|-- SKILL.md
|-- agents/
|   `-- openai.yaml
|-- references/
|-- scripts/
|-- assets/
|   `-- templates/
|-- evals/
|-- examples/
|-- README.md
|-- CHANGELOG.md
`-- LICENSE.txt

Only include optional folders when they add value. Instruction-only skills can be just SKILL.md plus small references.

First decision: build, update, or optimize

Classify the user request into one of these modes:

1. Build new skill: create a complete new skill package from a topic, method, workflow, or documents.
2. Update existing skill: revise an existing SKILL.md or package while preserving useful behavior.
3. Optimize skill: improve a skill based on observed failures, eval cases, traces, or benchmark results.
4. Evaluate only: produce eval cases, rubrics, validation reports, or a quality review without changing the skill.

If the user has not specified a package name, derive one using lowercase letters, numbers, and hyphens only. The directory name and name frontmatter must match.

Build workflow

For a new skill, follow this sequence:

1. Clarify only blocking requirements. Otherwise infer reasonable defaults and proceed.
2. Assess skill value and source needs:
   • Identify whether the skill's value comes from current information, private knowledge, a methodology, niche techniques, structured organization of known knowledge, or a mix of these.
   • Treat model-known material as a possible input for organization, not a reason to reject the skill.
   • Freshness is optional; require external freshness checks only for time-sensitive, post-training, implementation-specific, or fuzzy details.
   • If the boundary is unclear and the detail affects behavior, classify it as fuzzy or fresh-needed instead of trusting memory.
   • For freshness gaps, actively collect external resources by searching from the current date backward, prioritizing the newest authoritative primary sources.
   • Ask the user for resource types the agent cannot reliably infer or access, such as private procedures, proprietary examples, internal policies, product-specific workflows, failure traces, benchmark data, local conventions, or tacit techniques.
3. Select source mode:
   • web: use when the user asks for latest, current, authoritative, official, or emerging information.
   • private: use when the user provides files, notes, procedures, or private logic.
   • hybrid: use when both public sources and private logic matter.
   • manual: use when the user already gives enough process detail and no research is needed.
4. Create a source ledger that records the value/source assessment, each source, why it is trusted, date accessed, and which claims it supports.
5. Extract only operational knowledge: trigger conditions, required inputs, workflow steps, decision points, tools, outputs, edge cases, and failure modes.
6. Design the skill package using progressive disclosure:
   • SKILL.md: activation, compact workflow, output contract, when to read references.
   • references/: detailed source synthesis, checklists, domain rules, examples, and edge cases.
   • scripts/: deterministic helpers only when code is more reliable than instructions.
   • assets/: reusable templates, schemas, forms, icons, or static resources.
   • evals/: representative test tasks and scoring rubrics.
7. Validate the package for naming, frontmatter, focus, trigger specificity, source/value fit, source traceability, and safety.
8. Produce a release note explaining what was built, what value assumptions were made, what sources were used, and how to install it.

Read references/build-protocol.md for the full build process.

Optimization workflow

For optimization, use a two-track approach.

Manual optimization works anywhere:

1. Establish a baseline by running representative tasks without changing the skill.
2. Capture failures as structured cases: input, expected behavior, actual behavior, failure type, likely cause.
3. Propose bounded edits to the skill using add, delete, or replace operations.
4. Accept an edit only if it improves the validation set without breaking previously passing cases.
5. Export the improved version as best_skill.md or update the package SKILL.md.

SkillOpt-assisted optimization is optional:

1. Create train, validation, and test splits.
2. Prepare the current skill as the initial skill document.
3. Scaffold a benchmark environment or adapter for the target harness.
4. Run SkillOpt if installed and available.
5. Review the resulting best_skill.md before replacing the production skill.

Read references/optimization-protocol.md and references/skillopt-integration.md before running automated optimization.

Source policy

When using public web information, prioritize official documentation, standards, primary papers, reputable project repositories, and authoritative maintainers. Capture the date accessed and avoid relying on SEO summaries when primary sources exist.

When using private documents, preserve the user's intent and vocabulary. Do not overwrite private logic with public best practices unless the user asks for external normalization. If public sources conflict with private logic, report the conflict and propose a resolution.

Read references/source-policy.md for authority scoring and conflict handling.

Output contract

When asked to create a skill package, return either:

• a directory/zip containing the generated package, or
• a complete file tree plus the full content of each file when file creation is unavailable.

Always include:

• package name and purpose
• build mode used: web, private, hybrid, or manual
• value/source assessment and user-supplied resource needs
• generated file tree
• validation summary
• known assumptions and limitations
• next optimization step, if applicable

Quality gates

A generated skill is not complete until it passes these gates:

• SKILL.md exists and has valid YAML frontmatter.
• name is lowercase hyphenated and matches the folder name.
• description clearly says what the skill does and when to use it.
• The skill focuses on one job or one coherent workflow family.
• Instructions are imperative, concise, and operational.
• Detailed background is moved into references/.
• Scripts are optional, deterministic, and safe to inspect before running.
• Eval cases exist for any skill intended for repeated use.
• Stable known background is organized into operational workflow when that is the skill's value, and not over-expanded as generic explanation.
• Web-derived or private-derived claims are traceable in a source ledger.
• Optimization changes are validated before being accepted.

Use scripts/validate_skill_package.py for a lightweight local check. Use scripts/validate_skill_package.py --strict before treating a package as ready to publish or reuse heavily.

Bundled references

• references/build-protocol.md: complete source-to-skill build method.
• references/source-policy.md: source selection, authority scoring, and conflict handling.
• references/evaluation-design.md: eval case and rubric design.
• references/optimization-protocol.md: manual skill optimization loop.
• references/skillopt-integration.md: optional SkillOpt integration pattern.
• references/safety-and-governance.md: security, privacy, and release gates.
• references/source-basis.md: public standard and framework notes used to design this package.