Ccf Skill Forger

CCF Skill Forger

Invocation Controls

CCFA Handoff Mode: PARTIAL (Recommended). Follow metadata.ccf_skill_controls.handoff_question_mode and ../ccf-common/references/handoff-modes.md when maintaining the CCFA skill family.

When maintaining the CCFA skill family, preserve metadata.ccf_skill_controls in each SKILL.md. Do not add sibling-skill transitions without checking ../ccf-common/references/routing.md, ../ccf-common/references/task-modes.md, ../ccf-common/references/handoff-modes.md, and the denylist-respecting fallback.

If the user disables a skill or asks for writing-only behavior, encode that boundary directly in the edited skill instructions. Do not weaken idea-scope protection in writing skills unless the user explicitly requests that policy change.

When adding sources, update ../ccf-common/references/source-registry.yaml instead of duplicating URL lists in sibling skills. When adding browsing or evidence rules, keep them aligned with ../ccf-common/references/privacy-and-evidence.md.

Never commit machine-specific absolute paths, usernames, expanded home directories, or private local directory names into skills, README files, source registries, diagrams, examples, scripts, or command snippets. Use $CODEX_HOME, $HOME, repo-relative paths, or placeholders that do not identify the user or machine.

Core Rule

Build skills as compact operational guidance for another Codex session. Keep SKILL.md focused on trigger-relevant workflow, decisions, and resource navigation. Put detailed examples, checklists, schemas, policy text, or long instructions in references/ and load them only when needed. This skill also owns CCFA documentation SVG diagrams; do not create a separate runtime drawing skill for repository architecture or workflow diagrams.

Workflow

1. Clarify the goal with concrete examples. If the user's intent is clear, proceed with reasonable assumptions. Ask only for missing information that changes the skill's scope, location, or required assets. 2. Choose a skill name and destination. Use lowercase letters, digits, and hyphens only; keep names under 64 characters; check for conflicts in the target skills directory. Default to $CODEX_HOME/skills; if unset, use ~/.codex/skills. 3. Decide the resource shape:

• Use only SKILL.md for short, stable procedural guidance.
• Add references/ for detailed documentation that Codex should read selectively.
• Add scripts/ only for repeatable deterministic operations or fragile command sequences.
• Add assets/ only for templates, images, boilerplate, or other files used in final outputs.

4. Initialize the skill when creating from scratch. Prefer the local skill-creator initializer if available:

python '<skill-creator-dir>/scripts/init_skill.py' <skill-name> --path '<skills-dir>' --resources references,scripts

5. Write SKILL.md before filling optional resources. Put all "when to use" trigger wording in the YAML description; the body is loaded only after trigger selection. Use imperative instructions and avoid user-facing tutorial prose. 6. Add resources that directly support the skill. Remove placeholder files and unused directories. Test any script by running it on a small representative example. 7. Validate and iterate. Run the available validator, then inspect manually for trigger quality, resource links, naming, and excessive context. Use realistic future prompts to decide whether the skill actually helps. 8. Run ccf-common/scripts/check_path_privacy.py before finishing CCFA-family maintenance. Replace any committed local absolute path or username with $CODEX_HOME, $HOME, a repo-relative path, or a non-identifying placeholder. 9. For CCFA documentation diagrams, update ../tools/build_ccfa_diagrams.py, regenerate all language variants, and screenshot-check rendered SVG output. Use references/svg-style-guide.md; do not hand-edit generated SVGs unless the same change is backported to the generator.

Reference Files

Load these files only when the task calls for them:

• references/design-checklist.md: Use when planning a new skill, reviewing structure, or deciding whether content belongs in SKILL.md, references/, scripts/, or assets/.
• references/patterns.md: Use when drafting a concrete SKILL.md shape, frontmatter description, or example-driven workflow.
• references/local-commands.md: Use when scaffolding or validating skills on this machine, especially in PowerShell or Windows paths.
• references/svg-style-guide.md: Use when maintaining CCFA architecture, workflow, routing, installation, artifact, catalog, or demo SVG diagrams.

Output Style

When creating a skill, give the user a concise scheme before editing, then create the files. After creation, report the skill name, location, key files, and validation result. If validation cannot run because a local dependency is missing, say exactly what failed and perform the manual checks from references/design-checklist.md.

Design Checklist

Intake

Collect only the details that affect the skill:

• Goal: What task should future Codex sessions become better at?
• Triggers: What would the user naturally say that should activate this skill?
• Examples: What are 2-3 realistic requests the skill should handle?
• Inputs: Which files, APIs, tools, credentials, or domain facts are involved?
• Output: What should the completed work look like?
• Risk: What mistakes would be costly, destructive, or hard to notice?

If examples are missing, invent likely examples and proceed unless the domain is high-stakes or the wrong scope would create unwanted files, network calls, credentials, or destructive actions.

Naming And Location

• Normalize names to lowercase hyphen-case, such as pdf-redline or gh-pr-review.
• Prefer short verb-led names when natural, such as draft-contracts, query-metrics, or build-plugins.
• Check the target directory before creating the skill.
• Avoid names that collide with system skills or are too broad, such as helper, coding, or skill-creator.
• Place personal skills in $CODEX_HOME/skills when set, otherwise ~/.codex/skills.
• Do not write expanded home directories, usernames, drive-specific local paths, or machine-specific skill roots into committed files. Use $CODEX_HOME, $HOME, repo-relative paths, or non-identifying placeholders.

Resource Decision

Choose the smallest structure that solves repeated work:

Avoid README.md, changelogs, installation guides, or broad explanatory documents unless the runtime explicitly requires them. A skill is for agent execution, not general documentation.

Frontmatter

For Codex skills, keep YAML frontmatter to:

---
name: skill-name
description: "What the skill does and exactly when to use it."
---

For CCFA family skills, also preserve this metadata block unless the user explicitly requests a family-policy change:

metadata:
  ccf_skill_controls:
    handoff_question_mode: partial
    respect_session_denylists: true
    protect_idea_scope_in_writing: true
    private_material_safety: moderate
    shared_controls: ../ccf-common/references/

Make the description do all trigger work:

• Include task verbs and user phrases.
• Mention important file types, tools, platforms, or domains.
• Include update/review/validate triggers if the skill supports them.
• Do not rely on a "When to use" body section, because the body loads only after the skill is selected.

Body

Keep the body actionable:

• Start with the operating principle or quick workflow.
• Use imperative instructions.
• Reference bundled resources with relative paths.
• Keep the main file under 500 lines.
• Move variant-specific details into one-level-deep files under references/.
• Include command snippets only when they are reusable and safe.

Validation

Check these before finishing:

• Folder name equals frontmatter name.
• name uses only lowercase letters, digits, and hyphens.
• description is non-empty, specific, and trigger-rich.
• SKILL.md has no unfinished placeholders.
• Referenced files exist.
• CCFA family skills preserve the shared ccf_skill_controls keys and use ccf-common for routing, handoff, privacy, and source-registry policy.
• No committed file contains personal absolute paths, usernames, expanded local skill roots, or machine-specific command examples.
• ccf-common/scripts/check_path_privacy.py passes when run at the repository root.
• Optional directories contain only useful files.
• Scripts, if any, were executed on a representative example.
• agents/openai.yaml, if present, matches the skill and uses a correct $skill-name default prompt.

Local Commands

No Personal Absolute Paths

Do not write machine-specific absolute paths, usernames, home directories, or expanded local skill paths into committed skills, README files, source registries, SVGs, scripts, or examples. Use $CODEX_HOME, $HOME, repo-relative paths, or variables such as $SkillsRoot and $SkillCreatorScripts.

Before finishing a skill-family maintenance task, search for path leaks:

python 'ccf-common/scripts/check_path_privacy.py' .

Any match should be replaced with a variable, repo-relative path, or non-identifying local reference.

Locate Skill Tools

Locate the system skill-creator scripts without expanding a personal home path:

$SkillsRoot = if ($env:CODEX_HOME) { Join-Path $env:CODEX_HOME 'skills' } else { Join-Path $HOME '.codex/skills' }
$SkillCreatorScripts = Join-Path $SkillsRoot '.system/skill-creator/scripts'

If the path changes, locate them with:

Get-ChildItem -Force -Recurse -Filter init_skill.py $SkillsRoot
Get-ChildItem -Force -Recurse -Filter quick_validate.py $SkillsRoot

Initialize A Skill

Use the initializer for new skills:

python (Join-Path $SkillCreatorScripts 'init_skill.py') my-skill --path $SkillsRoot --resources references

Add only resource directories that are needed:

python (Join-Path $SkillCreatorScripts 'init_skill.py') my-skill --path $SkillsRoot --resources scripts,references,assets

PowerShell Quoting

In PowerShell, $skill-name inside double quotes can be treated as a variable expression. Use single quotes for interface values that contain $:

python (Join-Path $SkillCreatorScripts 'init_skill.py') my-skill --path $SkillsRoot --interface display_name='My Skill' --interface short_description='Create a focused skill' --interface default_prompt='Use $my-skill to create a focused skill.'

If a generated agents/openai.yaml loses the skill name, edit it so the prompt explicitly includes $my-skill.

Validate

Run the validator when available:

python (Join-Path $SkillCreatorScripts 'quick_validate.py') (Join-Path $SkillsRoot 'my-skill')

If validation fails because Python package yaml is missing, report the dependency issue and perform the manual validation checklist in references/design-checklist.md. Install dependencies only when the user has asked for a fully automated local validator or the environment policy allows it.

Inspect Created Files

Use these commands to review a skill without noisy output:

$SkillPath = Join-Path $SkillsRoot 'my-skill'
Get-ChildItem -Force -Recurse -Name -LiteralPath $SkillPath
Get-Content -Raw -LiteralPath (Join-Path $SkillPath 'SKILL.md')
Get-Content -Raw -LiteralPath (Join-Path $SkillPath 'agents/openai.yaml')

Skill Patterns

Minimal Workflow Skill

Use this when the skill mainly guides a repeated process.

---
name: review-contracts
description: "Review contract drafts for risk, missing terms, inconsistent definitions, and negotiation notes. Use when the user asks Codex to inspect, summarize, revise, or compare contract text or contract files."
---

# Review Contracts

## Workflow

1. Identify contract type, parties, governing law, and user objective.
2. Read the full document before suggesting edits.
3. Separate legal-risk findings from style or clarity suggestions.
4. Cite exact clauses or section names when possible.
5. Ask for jurisdiction-specific confirmation before giving high-stakes advice.

Reference-Backed Skill

Use this when domain details are too long for SKILL.md.

skill-name/
  SKILL.md
  references/
    schema.md
    metrics.md
    examples.md

In SKILL.md, state when to read each file:

## References

- `references/schema.md`: Read before writing SQL or interpreting table relationships.
- `references/metrics.md`: Read when the user asks for revenue, retention, or activation metrics.
- `references/examples.md`: Read when writing a query similar to prior reports.

Script-Backed Skill

Use this when repeated code would otherwise be rewritten.

skill-name/
  SKILL.md
  scripts/
    transform_input.py

In SKILL.md, include:

• What the script does.
• Required inputs and outputs.
• A small command example.
• A requirement to run the script on a representative sample after editing it.

Avoid scripts for simple one-off shell commands. Prefer scripts for fragile parsing, file format manipulation, validation, or repeatable conversions.

Asset-Backed Skill

Use this when the skill should copy or modify reusable files.

skill-name/
  SKILL.md
  assets/
    template.pptx
    frontend-starter/

In SKILL.md, explain which assets to use and how to adapt them. Do not paste the asset contents into SKILL.md.

Description Formula

Use this shape for strong trigger descriptions:

<Primary capability>. Use when the user asks to <verbs>, <verbs>, or <verbs> for <domain/files/tools>, including <specific scenarios>.

Examples:

• Create and maintain project release notes. Use when the user asks to draft, update, summarize, or standardize changelogs from git history, PR descriptions, issue lists, or milestone notes.
• Build reusable Codex skills. Use when the user asks to create, update, validate, or refactor a SKILL.md package with scripts, references, assets, or trigger descriptions.

Common Anti-Patterns

• Hiding trigger conditions in the body instead of the description.
• Writing a tutorial for humans rather than operational instructions for Codex.
• Adding all optional directories by default.
• Duplicating the same information in SKILL.md and references/.
• Creating long nested reference chains that require multiple hops to discover.
• Including broad advice that any strong model already knows.

CCFA SVG Style Guide

Diagram Types

• Architecture: show groups and ownership, not every sentence of behavior.
• Workflow: show stage order, gates, and side branches.
• Routing: show ambiguous prompts and their owning skills.
• Artifact: show project state and read/write surfaces.
• Installation: show required, recommended, partial, and forbidden installs.
• Demo: show the end-to-end example journey and verified result callouts.

Visual Rules

• Prefer swimlanes, timelines, hubs, and decision splits over large card grids.
• Use short labels: one skill name plus a three-to-six-word role line.
• Use Markdown for long descriptions.
• Use a restrained palette with strong contrast and no decorative blobs.
• Avoid diagonal text and tiny labels.
• Use arrows only when they encode real direction.

Screenshot Checklist

After generating SVG files:

1. Render representative English and Chinese SVGs to PNG with a browser. 2. Inspect for overflow, clipped descenders, accidental mixed-language labels, and unclear arrows. 3. Check that the README preview does not become a tall wall of nearly empty whitespace. 4. Re-run python ccf-common/scripts/check_v04.py.