{"id":"14b10305-9962-4080-9901-64ccf9663ecb","entityType":"agent","slug":"clawhub-wbavon-skill-creator-flagos","name":"Skill Creator Flagos","canonicalUrl":"https://www.xpersona.co/agent/clawhub-wbavon-skill-creator-flagos","canonicalPath":"/agent/clawhub-wbavon-skill-creator-flagos","generatedAt":"2026-10-11T17:43:26.826Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T15:25:12.898Z","emptyReason":null},"description":"Create new skills, modify existing skills, and validate skill quality for the FlagOS skills repository. Use this skill whenever someone wants to create a ski... Skill: Skill Creator Flagos Owner: wbavon Summary: Create new skills, modify existing skills, and validate skill quality for the FlagOS skills repository. Use this skill whenever someone wants to create a ski... Tags: latest:1.1.0 Version history: v1.1.0 | 2026-05-19T07:04:37.931Z | user Sync from flagos-ai/skills latest v1.0.0 | 2026-03-23T04:33:27.581Z | auto skill-creator-flagos v1.0.0 - Initial release providing","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s179mcxns07mhashdtzg4tbf6584wt8v:skill-creator-flagos","sourceUrl":"https://clawhub.ai/wbavon/skill-creator-flagos","homepage":"https://clawhub.ai/wbavon/skills/skill-creator-flagos","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/wbavon/skill-creator-flagos","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/wbavon/skills/skill-creator-flagos","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Create new skills, modify existing skills, and validate skill quality for the FlagOS skills repository. Use this skill whenever someone wants to create a ski..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T15:25:12.898Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T15:25:12.898Z","emptyReason":null},"stars":null,"forks":null,"downloads":1040,"packageName":null,"latestVersion":"1.1.0","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T15:25:12.828Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T15:25:12.898Z","lastCrawledAt":"2026-10-11T15:25:12.828Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T15:25:12.828Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.0","createdAt":"2026-05-19T07:04:37.931Z","changelog":"Sync from flagos-ai/skills latest","fileCount":9,"zipByteSize":27554},{"version":"1.0.0","createdAt":"2026-03-23T04:33:27.581Z","changelog":"skill-creator-flagos v1.0.0 - Initial release providing a meta-skill for the FlagOS skills ecosystem. - Enables users to create, scaffold, improve, and validate skills in the FlagOS repository. - Interactive workflow to capture skill intent, scaffold directories/files, and guide SKILL.md writing. - Includes automated validation for structure, frontmatter, and usage conventions. - Supports drafting test cases and iterative skill improvement. - Documentation and troubleshooting guidance included for developers and non-developers.","fileCount":8,"zipByteSize":26450}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s179mcxns07mhashdtzg4tbf6584wt8v:skill-creator-flagos","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T17:43:26.822Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wbavon-skill-creator-flagos/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T15:25:12.898Z","emptyReason":null},"readme":"Skill: Skill Creator Flagos\n\nOwner: wbavon\n\nSummary: Create new skills, modify existing skills, and validate skill quality for the FlagOS skills repository. Use this skill whenever someone wants to create a ski...\n\nTags: latest:1.1.0\n\nVersion history:\n\nv1.1.0 | 2026-05-19T07:04:37.931Z | user\n\nSync from flagos-ai/skills latest\n\nv1.0.0 | 2026-03-23T04:33:27.581Z | auto\n\nskill-creator-flagos v1.0.0\n\n- Initial release providing a meta-skill for the FlagOS skills ecosystem.\n- Enables users to create, scaffold, improve, and validate skills in the FlagOS repository.\n- Interactive workflow to capture skill intent, scaffold directories/files, and guide SKILL.md writing.\n- Includes automated validation for structure, frontmatter, and usage conventions.\n- Supports drafting test cases and iterative skill improvement.\n- Documentation and troubleshooting guidance included for developers and non-developers.\n\nArchive index:\n\nArchive v1.1.0: 9 files, 27554 bytes\n\nFiles: LICENSE.txt (11262b), README_zh.md (11050b), README.md (11951b), references/schemas.md (3102b), references/writing-guide.md (9745b), scripts/init_skill.py (6476b), skill-card.md (1967b), SKILL.md (11481b), _meta.json (139b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: skill-creator-flagos\ndescription: >\n  Create new skills, modify existing skills, and validate skill quality for the FlagOS skills\n  repository. Use this skill whenever someone wants to create a skill from scratch, improve or\n  edit an existing skill, scaffold a new skill directory, validate skill structure, or run test\n  cases against a skill. Trigger when the user says things like \"create a skill\", \"make a new\n  skill for X\", \"scaffold a skill\", \"improve this skill\", \"validate my skill\", or simply\n  \"/skill-creator-flagos\". Also trigger when users mention turning a workflow into a reusable skill,\n  or want to package a repeated process as a skill.\nargument-hint: \"[skill-name] [--init | --validate | --eval]\"\nuser-invokable: true\ncompatibility: \"Python 3.8+, works with any AI coding assistant that supports the Agent Skills standard\"\nmetadata:\n  version: \"1.0.0\"\n  author: flagos-ai\n  category: workflow-automation\n  tags: [skill-creation, scaffolding, validation, meta-skill, developer-tooling]\nallowed-tools: \"Bash(python3:*) Bash(python:*) Bash(chmod:*) Bash(mkdir:*) Bash(cp:*) Bash(ls:*) Bash(cat:*) Read Edit Write Glob Grep AskUserQuestion TaskCreate TaskUpdate TaskList TaskGet Agent\"\n---\n\n# Skill Creator\n\nA meta-skill for creating, improving, and validating skills in the FlagOS skills repository.\n\n## Overview\n\nThis skill guides you through the full lifecycle of skill development:\n1. **Create** — scaffold a new skill from template, interview the user, write SKILL.md\n2. **Improve** — analyze an existing skill, identify weaknesses, iterate with test cases\n3. **Validate** — check structure, frontmatter, references, and conventions compliance\n\n## Usage\n\n```\n/skill-creator-flagos                       # Interactive — asks what you want to do\n/skill-creator-flagosmy-new-skill --init    # Scaffold a new skill\n/skill-creator-flagosmy-skill --validate    # Validate an existing skill\n/skill-creator-flagosmy-skill --eval        # Run test prompts against a skill\n```\n\n## Execution\n\n### Step 0: Parse arguments and determine mode\n\nExtract from user input:\n- `{{skill_name}}` — optional skill name (hyphen-case)\n- `{{mode}}` — one of: `create`, `improve`, `validate`, `eval`, or `interactive` (default)\n\nIf no mode is specified, ask the user:\n\n> What would you like to do?\n> 1. Create a new skill from scratch\n> 2. Improve an existing skill\n> 3. Validate a skill's structure and conventions\n> 4. Run test cases against a skill\n\n**-> Tell user**: Confirm the mode and skill name.\n\n---\n\n## Mode 1: Create a New Skill\n\n### Step 1: Capture intent\n\nStart by understanding what the user wants to build. If the current conversation already contains a workflow the user wants to capture (e.g., \"turn this into a skill\"), extract answers from the conversation history first.\n\nKey questions to clarify:\n1. What should this skill enable the agent to do?\n2. When should this skill trigger? (user phrases, contexts, file types)\n3. What's the expected output or end state?\n4. Does the skill need scripts, reference docs, or asset files?\n5. What tools does the skill need access to?\n\nAdapt your communication style to the user — don't assume coding jargon familiarity. Pay attention to context cues.\n\n**-> Tell user**: Summarize the captured intent and confirm before proceeding.\n\n### Step 2: Initialize the skill directory\n\nRun the init script to scaffold the skill:\n\n```bash\npython3 {{skill_root}}/scripts/init_skill.py {{skill_name}} --path {{skills_dir}} [--resources scripts,references,assets]\n```\n\nWhere:\n- `{{skill_root}}` = absolute path to this skill-creator-flagos's directory\n- `{{skills_dir}}` = path to the `skills/` directory (usually the parent of `{{skill_root}}`)\n\nThe script creates the directory with SKILL.md template, LICENSE.txt, and optional subdirectories.\n\n**-> Tell user**: Show the created directory structure.\n\n### Step 3: Write the SKILL.md\n\nBased on the user interview, fill in these components:\n\n#### Frontmatter (YAML)\n\n| Field | Required | Guidelines |\n|-------|----------|------------|\n| `name` | Yes | Lowercase + hyphens, must match directory name, max 64 chars |\n| `description` | Yes | 1-2 sentences: what it does AND when to trigger. Be specific and slightly \"pushy\" — err on the side of triggering too often rather than too rarely |\n| `argument-hint` | Recommended | Show expected arguments |\n| `user-invokable` | Recommended | `true` if invokable via `/skill-name` |\n| `compatibility` | Optional | Environment requirements |\n| `metadata` | Recommended | version, author, category, tags |\n| `allowed-tools` | Recommended | Space-separated tool list with patterns |\n\n#### Body (Markdown)\n\nFollow the structure documented in `references/writing-guide.md`. At minimum include:\n- **Overview** — what problem this solves, when to activate\n- **Prerequisites** — environment requirements\n- **Execution steps** — numbered steps with `**-> Tell user**` progress markers\n- **Examples** — at least 2-3 realistic usage examples\n- **Troubleshooting** — common problems and fixes\n\nRead `references/writing-guide.md` for detailed patterns on progressive disclosure, output formats, domain organization, and writing style.\n\n### Step 4: Add supporting resources\n\nBased on the skill's needs, create:\n- **`scripts/`** — executable code for deterministic/repetitive tasks\n- **`references/`** — detailed docs loaded into context as needed\n- **`assets/`** — files used in output (templates, icons, etc.)\n\nRules:\n- Every script/reference must be documented in SKILL.md with usage instructions\n- Scripts should have execute permissions (`chmod +x`)\n- Keep SKILL.md under 500 lines; move detailed content to `references/`\n- For reference files >300 lines, include a table of contents\n\n### Step 5: Validate\n\nRun validation to check conventions compliance:\n\n```bash\npython3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}\n```\n\nFix any reported issues. See Troubleshooting section below.\n\n**-> Tell user**: Report validation results. On failure, diagnose and fix.\n\n### Step 6: Write README files\n\nCreate `README.md` (English) and optionally `README_zh.md` (Chinese) following the pattern in existing skills. The README should cover:\n- Overview / problem statement\n- Usage instructions\n- Directory structure\n- File descriptions\n- Examples\n- Installation instructions\n\n**-> Tell user**: Skill creation complete. Present the final directory tree and summary.\n\n---\n\n## Mode 2: Improve an Existing Skill\n\n### Step 1: Analyze the current skill\n\nRead the existing SKILL.md and all supporting files. Identify:\n- Unclear or missing trigger conditions in the description\n- Missing examples or edge cases\n- Steps that lack progress reporting (`**-> Tell user**`)\n- Overly long SKILL.md that should be split into references\n- Missing troubleshooting entries\n- Scripts without documentation\n\n**-> Tell user**: Present findings and proposed improvements.\n\n### Step 2: Draft test prompts\n\nCreate 2-3 realistic test prompts — things a real user would say. Share them with the user for confirmation.\n\nSave to `evals/evals.json`:\n\n```json\n{\n  \"skill_name\": \"{{skill_name}}\",\n  \"evals\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's task prompt\",\n      \"expected_output\": \"Description of expected result\",\n      \"assertions\": [\"The output includes X\", \"Step Y was executed\"]\n    }\n  ]\n}\n```\n\nSee `references/schemas.md` for the full schema.\n\n### Step 3: Iterate\n\nFor each round:\n1. Apply improvements to SKILL.md and supporting files\n2. Re-run validation\n3. Review against test prompts (mentally or by spawning test runs)\n4. Collect user feedback\n5. Repeat until satisfied\n\n**-> Tell user**: Report changes made in each iteration.\n\n---\n\n## Mode 3: Validate\n\nRun the validation script:\n\n```bash\npython3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}\n```\n\nThe script checks:\n- SKILL.md exists and has valid YAML frontmatter\n- Required fields (`name`, `description`) are present\n- `name` matches directory name, follows naming conventions\n- `description` length within limits\n- Body has sufficient content (>100 chars)\n- Referenced files in `scripts/` and `references/` actually exist\n- Scripts have execute permissions\n- No hardcoded paths or credentials\n\n**-> Tell user**: Report all findings with severity (error/warning).\n\n---\n\n## Mode 4: Run Evals\n\nIf `evals/evals.json` exists, run the test prompts against the skill:\n\n```bash\npython3 {{skill_root}}/scripts/run_eval.py {{skills_dir}}/{{skill_name}}\n```\n\nThis generates a report showing which assertions passed/failed for each test case.\n\n**-> Tell user**: Present results and suggest improvements.\n\n---\n\n## Placeholders\n\n| Placeholder | How to derive |\n|---|---|\n| `{{skill_name}}` | From user input, normalized to hyphen-case |\n| `{{skill_root}}` | Absolute path to this skill-creator-flagos's directory |\n| `{{repo_root}}` | Absolute path to the repository root (parent of `skills/`) |\n| `{{skills_dir}}` | Path to the `skills/` directory containing all skills |\n\n## Examples\n\n**Example 1: Create a new skill from scratch**\n```\nUser says: \"/skill-creator-flagospreflight-check --init\"\nActions:\n  1. Parse → skill_name=preflight-check, mode=create\n  2. Interview user about what preflight-check should do\n  3. Run init_skill.py to scaffold directory\n  4. Write SKILL.md with deployment verification workflow\n  5. Add scripts/check_gpu.sh, scripts/check_env.py\n  6. Validate and fix any issues\n  7. Write README.md\nResult: Complete preflight-check skill ready for use\n```\n\n**Example 2: Improve an existing skill**\n```\nUser says: \"improve model-migrate-flagos, the description could be better\"\nActions:\n  1. Read existing SKILL.md and all references\n  2. Analyze description — find it's too long and not trigger-friendly\n  3. Propose a more concise, trigger-optimized description\n  4. Create test prompts to verify triggering\n  5. Apply changes, validate\nResult: Improved skill with better triggering accuracy\n```\n\n**Example 3: Validate all skills**\n```\nUser says: \"/skill-creator-flagos--validate\"\nActions:\n  1. No skill_name provided → validate all skills in skills/\n  2. Run validate_skill.py on each skill directory\n  3. Report consolidated results\nResult: Validation report for all skills\n```\n\n**Example 4: Turn a conversation workflow into a skill**\n```\nUser says: \"turn what we just did into a skill\"\nActions:\n  1. Analyze conversation history for the workflow performed\n  2. Extract: tools used, sequence of steps, corrections made\n  3. Interview user to fill gaps\n  4. Scaffold and write the skill\nResult: New skill capturing the conversation workflow\n```\n\n## Troubleshooting\n\n| Problem | Cause | Fix |\n|---|---|---|\n| `name does not match directory name` | Frontmatter `name` differs from folder name | Ensure they are identical |\n| `description exceeds 1024 chars` | Description too long | Move details to the body; keep description to 1-2 sentences |\n| `SKILL.md body is too short` | Insufficient instructions | Add overview, steps, examples, troubleshooting |\n| `Missing required field` | `name` or `description` absent in frontmatter | Add the missing field |\n| `name must be lowercase+hyphens` | Invalid characters in name | Use only `a-z`, `0-9`, `-` |\n| Skill doesn't trigger | Description too narrow or vague | Make description more specific and slightly aggressive about triggering |\n| Referenced file not found | Script or reference listed in SKILL.md but not on disk | Create the file or remove the reference |\n\nFile v1.1.0:README.md\n\n# skill-creator-flagos: Skill Development Toolkit\n\n[中文版](README_zh.md)\n\n## Overview\n\n`skill-creator-flagos` is a meta-skill for creating, improving, and validating skills in the FlagOS skills repository.\n\n### Problem Statement\n\nWriting a high-quality skill involves many details: YAML frontmatter conventions, trigger-optimized descriptions, progressive disclosure structure, proper file organization, bilingual documentation, and more. Manually checking all these requirements is tedious and error-prone, and new contributors often miss conventions that only become apparent after review.\n\nThis skill automates the entire skill development lifecycle: **scaffold from template -> write with guided patterns -> validate conventions -> iterate with test cases**, spanning 4 operational modes with built-in tooling for each stage.\n\n### Usage\n\n```bash\n# Interactive — asks what you want to do\n/skill-creator-flagos\n\n# Scaffold a new skill\n/skill-creator-flagos preflight-check --init\n\n# Scaffold with specific resource directories\n/skill-creator-flagos preflight-check --init --resources scripts,references\n\n# Validate a single skill\n/skill-creator-flagos model-migrate-flagos --validate\n\n# Validate all skills\n/skill-creator-flagos --validate\n\n# Improve an existing skill\n/skill-creator-flagos model-migrate-flagos\n\n# Run test cases against a skill\n/skill-creator-flagos model-migrate-flagos --eval\n```\n\n| Argument | Required | Default | Description |\n|---|---|---|---|\n| `skill-name` | No | — | Skill name in hyphen-case (e.g. `preflight-check`) |\n| `--init` | No | — | Scaffold a new skill directory |\n| `--validate` | No | — | Validate skill structure and conventions |\n| `--eval` | No | — | Run test cases against the skill |\n| `--resources` | No | — | Comma-separated resource dirs: `scripts,references,assets` |\n\nWhen no flag is provided, the skill enters interactive mode and asks what you'd like to do.\n\n---\n\n## Four Operational Modes\n\n### Mode 1: Create — Build a New Skill from Scratch\n\n```\nIntent capture → Interview → Scaffold → Write SKILL.md → Add resources → Validate → Write README\n```\n\n**What happens:**\n\n1. **Intent capture** — The agent interviews you about what the skill should do, when it should trigger, what tools it needs, and what outputs it produces. If the current conversation already contains a workflow you want to capture, the agent extracts answers from context first.\n\n2. **Scaffold** — Runs `init_skill.py` to generate the directory structure:\n   ```\n   my-skill/\n   ├── SKILL.md        # Template with [TODO] placeholders\n   ├── LICENSE.txt      # Apache 2.0\n   ├── scripts/         # (if requested)\n   ├── references/      # (if requested)\n   └── assets/          # (if requested)\n   ```\n\n3. **Write SKILL.md** — Fills in the frontmatter and body following the patterns in `references/writing-guide.md`. The agent ensures:\n   - Description is trigger-optimized (specific phrases, slightly \"pushy\")\n   - Body includes all required sections (Overview, Steps, Examples, Troubleshooting)\n   - Progressive disclosure is applied (details in `references/`, not bloating SKILL.md)\n\n4. **Add resources** — Creates scripts, reference docs, and assets as needed, with each file documented in SKILL.md.\n\n5. **Validate & README** — Runs the validator, fixes issues, and writes bilingual READMEs.\n\n**Example session:**\n\n```\nYou:   /skill-creator-flagos preflight-check --init\nAgent: What should preflight-check do? When should it trigger?\nYou:   It checks GPU availability, driver versions, and Python env before running vLLM\nAgent: Got it. I'll scaffold the skill and include a scripts/ directory for the check scripts...\n       [creates directory, writes SKILL.md, adds scripts/check_gpu.sh, validates]\n       Skill 'preflight-check' created. Here's the final structure: ...\n```\n\n### Mode 2: Improve — Iterate on an Existing Skill\n\n**What happens:**\n\n1. **Analyze** — Reads the existing SKILL.md and all supporting files. Identifies issues:\n   - Vague or missing trigger conditions in description\n   - Missing examples or edge cases\n   - Steps without progress reporting\n   - Overly long SKILL.md that should be split\n   - Missing troubleshooting entries\n\n2. **Draft test prompts** — Creates 2-3 realistic test cases and saves them to `evals/evals.json` for verification.\n\n3. **Iterate** — Applies improvements, re-validates, reviews against test prompts, collects your feedback, and repeats.\n\n**Example session:**\n\n```\nYou:   /skill-creator-flagos model-migrate-flagos\nAgent: I've analyzed model-migrate-flagos. Found 3 potential improvements:\n       1. Description could be more trigger-friendly\n       2. Missing example for multimodal model migration\n       3. Troubleshooting table doesn't cover network timeout\n       Which should I address first?\n```\n\n### Mode 3: Validate — Check Conventions Compliance\n\n**What happens:**\n\nRuns the repository-level `scripts/validate_skills.py` which checks:\n\n| Check | Severity | Description |\n|---|---|---|\n| SKILL.md exists | Error | Entry point file must be present |\n| Valid YAML frontmatter | Error | Must start and end with `---` |\n| `name` field present | Error | Required field |\n| `description` field present | Error | Required field |\n| Name matches directory | Error | `name` field must equal folder name |\n| Name format | Error | Lowercase + hyphens only, max 64 chars |\n| Description length | Error | Must not exceed 1024 chars |\n| Body content | Error | Must be at least 100 chars |\n| Referenced files exist | Error | All linked files must be on disk |\n| Examples section | Warning | Recommended for all skills |\n| Troubleshooting section | Warning | Recommended for all skills |\n| Script permissions | Warning | `.py` and `.sh` files should be executable |\n| LICENSE.txt present | Warning | Recommended per-skill license |\n| README.md present | Warning | Recommended documentation |\n\n**Example output:**\n\n```\n============================================================\n  model-migrate-flagos: PASS\n============================================================\n    ✓ All checks passed\n\n============================================================\n  skill-creator-flagos: PASS\n============================================================\n  Warnings (1):\n    ⚠ No README.md found (recommended)\n\n────────────────────────────────────────────────────────────\n  Summary: 2 skill(s), 0 error(s), 1 warning(s)\n────────────────────────────────────────────────────────────\n```\n\n### Mode 4: Eval — Run Test Cases\n\n**What happens:**\n\nIf `evals/evals.json` exists in the skill directory, the agent runs each test prompt and checks assertions against the expected output. Generates a report showing pass/fail status per assertion.\n\n---\n\n## Directory Structure\n\n```\nskills/skill-creator-flagos/\n├── SKILL.md                          # Skill definition (entry point)\n├── LICENSE.txt                       # Apache 2.0 license\n├── README.md                         # This document (English)\n├── README_zh.md                      # Chinese version\n├── references/                       # Reference documents\n│   ├── writing-guide.md              # Detailed skill writing patterns & best practices\n│   └── schemas.md                    # JSON schemas for evals and validation\n└── scripts/                          # Executable scripts\n    └── init_skill.py                 # Scaffold a new skill directory\n```\n\n---\n\n## File Descriptions\n\n### Skill Definition\n\n#### `SKILL.md`\n\nThe skill entry point. Defines trigger conditions, argument format, four operational modes (Create, Improve, Validate, Eval), placeholder resolution, examples, and troubleshooting guide. The AI coding assistant uses this file to identify and invoke the skill.\n\n### Reference Documents (`references/`)\n\n#### `writing-guide.md` — Skill Writing Patterns & Best Practices\n\nComprehensive guide covering:\n\n- **Anatomy of a Skill** — required fields, FlagOS extension fields, directory conventions\n- **Progressive Disclosure** — three-level loading system (metadata → body → references), when and how to split content\n- **Writing the Description** — how to craft trigger-optimized descriptions with specific phrases and negative triggers\n- **Structuring the Body** — required sections template (Overview, Prerequisites, Steps, Examples, Troubleshooting)\n- **Writing Style** — imperative form, explain why not what, conciseness checklist\n- **Scripts and References** — when to use each, documentation requirements\n- **FlagOS-Specific Conventions** — naming, categories, bilingual support, licensing\n\n#### `schemas.md` — JSON Schemas\n\nDefines the JSON formats used for evaluation and validation:\n\n| Schema | Location | Purpose |\n|---|---|---|\n| `evals.json` | `evals/evals.json` | Test case definitions (prompts + assertions) |\n| `eval_result.json` | `evals/results/eval_result.json` | Evaluation results with pass/fail per assertion |\n| `validation_result.json` | `evals/results/validation_result.json` | Structured validation output |\n\n### Scripts (`scripts/`)\n\n#### `init_skill.py` — Scaffold a New Skill\n\n```bash\n# Basic usage\npython3 init_skill.py my-skill --path skills/\n\n# With resource directories\npython3 init_skill.py my-skill --path skills/ --resources scripts,references,assets\n\n# Name auto-normalization\npython3 init_skill.py \"My Cool Skill\" --path skills/\n# → creates skills/my-cool-skill/\n```\n\n**What it generates:**\n\n| File | Always | Description |\n|---|---|---|\n| `SKILL.md` | Yes | Template with all frontmatter fields and `[TODO]` body placeholders |\n| `LICENSE.txt` | Yes | Apache 2.0 license |\n| `scripts/` | If requested | Empty directory with `.gitkeep` |\n| `references/` | If requested | Empty directory with `.gitkeep` |\n| `assets/` | If requested | Empty directory with `.gitkeep` |\n\n**Validations performed:**\n- Name must be 2-64 chars, lowercase + hyphens only\n- Parent directory must exist\n- Target directory must not already exist\n- Resource types must be one of: `scripts`, `references`, `assets`\n\n### Repository-Level Validation (`scripts/validate_skills.py`)\n\nValidation is handled by the repository-level script `scripts/validate_skills.py` (not bundled inside skill-creator-flagos to avoid duplication). It supports both single-skill and batch validation:\n\n```bash\n# Validate all skills (default)\npython3 scripts/validate_skills.py\n\n# Validate a single skill\npython3 scripts/validate_skills.py skills/model-migrate-flagos\n\n# Validate all skills in a specific directory\npython3 scripts/validate_skills.py skills/ --all\n```\n\nPerforms 14 checks across two severity levels (error / warning). See the Mode 3 table above for the full list. Exit code: 0 = pass, 1 = errors found.\n\n---\n\n## Usage in FlagOS Skills Repository\n\n### Quick Install (via npx)\n\n```bash\n# Install this skill only\nnpx skills add flagos-ai/skills --skill skill-creator-flagos -a claude-code\n\n# Or install all Flagos skills at once\nnpx skills add flagos-ai/skills -a claude-code\n```\n\n### Manual Install\n\n```bash\n# From your project root\nmkdir -p .claude/skills\ncp -r <path-to-this-repo>/skills/skill-creator-flagos .claude/skills/\n```\n\n### Standalone Script Usage\n\nThe scripts can be used independently without invoking the skill:\n\n```bash\n# Scaffold a new skill anywhere\npython3 skills/skill-creator-flagos/scripts/init_skill.py my-skill --path ./my-project/skills/\n\n# Validate skills (repo-level script)\npython3 scripts/validate_skills.py\npython3 scripts/validate_skills.py skills/my-skill\n```\n\n---\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See [LICENSE.txt](LICENSE.txt) for details.\n\nFile v1.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7c1yzknmhkmxasrtdbxa3fhd81z80k\",\n  \"slug\": \"skill-creator-flagos\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1779174277931\n}\n\nFile v1.1.0:references/schemas.md\n\n# JSON Schemas\n\nDefines the JSON schemas used by skill-creator for evaluation and testing.\n\n---\n\n## evals.json\n\nDefines test cases for a skill. Located at `evals/evals.json` within the skill directory.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"evals\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's example prompt\",\n      \"expected_output\": \"Description of expected result\",\n      \"files\": [\"evals/files/sample1.txt\"],\n      \"assertions\": [\n        \"The output includes X\",\n        \"Step Y was executed correctly\",\n        \"No errors were reported\"\n      ]\n    }\n  ]\n}\n```\n\n### Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `skill_name` | Yes | Must match the skill's frontmatter `name` |\n| `evals[].id` | Yes | Unique integer identifier |\n| `evals[].prompt` | Yes | The user prompt to test with |\n| `evals[].expected_output` | Yes | Human-readable description of success |\n| `evals[].files` | No | Input file paths relative to skill root |\n| `evals[].assertions` | No | List of verifiable statements to check |\n\n### Writing Good Test Prompts\n\n- Use realistic language a real user would actually say\n- Include both direct invocations (`/skill-name arg`) and natural language triggers\n- Cover happy paths, edge cases, and error scenarios\n- At least 2-3 test prompts per skill\n\n### Writing Good Assertions\n\n- Make assertions objectively verifiable (not subjective)\n- Use descriptive text that reads clearly in reports\n- Check both positive outcomes (\"file was created\") and negative (\"no error messages\")\n- Don't assert on implementation details — focus on user-visible outcomes\n\n---\n\n## eval_result.json\n\nOutput from running evaluations. Located at `evals/results/eval_result.json`.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"timestamp\": \"2026-03-15T10:30:00Z\",\n  \"results\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's example prompt\",\n      \"assertions\": [\n        {\n          \"text\": \"The output includes X\",\n          \"passed\": true,\n          \"evidence\": \"Found X in the generated output at line 15\"\n        },\n        {\n          \"text\": \"Step Y was executed correctly\",\n          \"passed\": false,\n          \"evidence\": \"Step Y was skipped due to missing dependency\"\n        }\n      ],\n      \"summary\": {\n        \"passed\": 1,\n        \"failed\": 1,\n        \"total\": 2,\n        \"pass_rate\": 0.5\n      }\n    }\n  ],\n  \"overall\": {\n    \"total_evals\": 1,\n    \"total_assertions\": 2,\n    \"total_passed\": 1,\n    \"overall_pass_rate\": 0.5\n  }\n}\n```\n\n---\n\n## validation_result.json\n\nOutput from the validation script. Located at `evals/results/validation_result.json`.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"skill_path\": \"/path/to/skills/example-skill\",\n  \"timestamp\": \"2026-03-15T10:30:00Z\",\n  \"valid\": true,\n  \"errors\": [],\n  \"warnings\": [\n    \"No README.md found (recommended)\",\n    \"Script scripts/helper.py lacks execute permission\"\n  ],\n  \"checks\": {\n    \"frontmatter\": \"pass\",\n    \"name_convention\": \"pass\",\n    \"description_quality\": \"pass\",\n    \"body_content\": \"pass\",\n    \"file_references\": \"pass\",\n    \"script_permissions\": \"warning\"\n  }\n}\n```\n\nFile v1.1.0:references/writing-guide.md\n\n# Skill Writing Guide\n\nDetailed patterns and best practices for writing effective skills in the FlagOS skills repository.\n\n## Table of Contents\n\n- [Anatomy of a Skill](#anatomy-of-a-skill)\n- [Progressive Disclosure](#progressive-disclosure)\n- [Writing the Description](#writing-the-description)\n- [Structuring the Body](#structuring-the-body)\n- [Writing Style](#writing-style)\n- [Scripts and References](#scripts-and-references)\n- [FlagOS-Specific Conventions](#flagos-specific-conventions)\n\n---\n\n## Anatomy of a Skill\n\n```\nskill-name/\n├── SKILL.md (required)\n│   ├── YAML frontmatter (name, description required)\n│   └── Markdown instructions\n├── LICENSE.txt (recommended, Apache 2.0)\n├── README.md (recommended, English)\n├── README_zh.md (optional, Chinese)\n└── Bundled Resources (optional)\n    ├── scripts/    - Executable code for deterministic/repetitive tasks\n    ├── references/ - Docs loaded into context as needed\n    └── assets/     - Files used in output (templates, icons, fonts)\n```\n\n### Required Fields\n\n| Field | Constraints | Description |\n|-------|-------------|-------------|\n| `name` | ≤64 chars, lowercase + hyphens, matches directory | Unique identifier |\n| `description` | ≤1024 chars | What the skill does AND when to trigger |\n\n### FlagOS Extension Fields\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `argument-hint` | CLI argument hint | `\"model_name [options]\"` |\n| `user-invokable` | Can be invoked via `/skill-name` | `true` |\n| `allowed-tools` | Fine-grained tool access control | `\"Bash(python3:*) Read Edit ...\"` |\n| `compatibility` | Environment requirements | `\"Python 3.8+, CUDA required\"` |\n| `metadata.version` | Skill version (semver) | `\"1.0.0\"` |\n| `metadata.author` | Author | `\"flagos-ai\"` |\n| `metadata.category` | Category | `\"workflow-automation\"` |\n| `metadata.tags` | Tag list | `[model-migration, vllm]` |\n\n---\n\n## Progressive Disclosure\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata** (name + description) — Always in context (~100 words)\n2. **SKILL.md body** — Loaded when skill triggers (<500 lines ideal)\n3. **Bundled resources** — Loaded as needed (unlimited; scripts can execute without loading)\n\n### Key Principles\n\n- **Keep SKILL.md under 500 lines.** If approaching this limit, split content into `references/` files with clear pointers about when to read them.\n- **Reference files must be documented in SKILL.md** with guidance on when to read them.\n- **For reference files >300 lines**, include a table of contents at the top.\n- **Avoid deeply nested references** — keep one level deep from SKILL.md.\n\n### Patterns\n\n**Pattern 1: Domain-specific organization**\n\nWhen a skill supports multiple domains/frameworks, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + selection)\n└── references/\n    ├── aws.md\n    ├── gcp.md\n    └── azure.md\n```\n\nThe agent reads only the relevant reference file.\n\n**Pattern 2: Workflow with reference catalog**\n\n```\nmodel-migrate-flagos/\n├── SKILL.md (overview + step index)\n└── references/\n    ├── procedure.md (detailed 13-step procedure)\n    ├── compatibility-patches.md (patch catalog)\n    └── operational-rules.md (operational constraints)\n```\n\nSKILL.md provides the overview; detailed content lives in references.\n\n**Pattern 3: Conditional details**\n\n```markdown\n## Basic usage\nSimple inline instructions here.\n\n**For advanced configuration**: See [advanced-config.md](references/advanced-config.md)\n**For troubleshooting**: See [troubleshooting.md](references/troubleshooting.md)\n```\n\n---\n\n## Writing the Description\n\nThe `description` field is the **primary triggering mechanism**. It determines when the agent activates the skill.\n\n### Rules\n\n1. **Include both WHAT and WHEN** — what the skill does and what contexts trigger it.\n2. **Be specific about triggers** — list user phrases, file types, or task patterns.\n3. **Be slightly \"pushy\"** — err on triggering too often rather than too rarely. The agent tends to under-trigger.\n4. **Include negative triggers** — explicitly say what NOT to use this skill for.\n5. **Keep under 1024 chars** — but use the full allowance if needed.\n\n### Good Example\n\n```yaml\ndescription: >\n  Migrate a model from the latest vLLM upstream repository into the vllm-plugin-FL project\n  (pinned at vLLM v0.13.0). Use this skill whenever someone wants to add support for a new\n  model to vllm-plugin-FL, port model code from upstream vLLM, or backport a newly released\n  model. Trigger when the user says things like \"migrate X model\", \"add X model support\",\n  \"port X from upstream vLLM\". Do NOT use for models already supported by vLLM 0.13.0 core.\n```\n\n### Bad Example\n\n```yaml\ndescription: Helps with model migration.\n```\n\nToo vague — the agent won't know when to trigger.\n\n---\n\n## Structuring the Body\n\n### Required Sections\n\nEvery SKILL.md body should include:\n\n1. **Overview** — what problem this solves, when to activate, expected inputs/outputs\n2. **Prerequisites** (if any) — environment requirements, tools, access\n3. **Execution steps** — numbered steps with progress reporting\n4. **Examples** — at least 2-3 realistic usage examples\n5. **Troubleshooting** — common problems and fixes\n\n### Execution Steps Pattern\n\nUse numbered steps with `**-> Tell user**` markers for progress reporting:\n\n```markdown\n### Step 1: Parse arguments\n\nExtract from user input:\n- `{{model_name}}` = first argument (required)\n- `{{options}}` = remaining arguments\n\n**-> Tell user**: Confirm parsed values.\n\n### Step 2: Execute workflow\n\nDo the actual work here.\n\n```bash\ncommand --example\n```\n\n**-> Tell user**: Report progress.\n\n### Step 3: Verify\n\n```bash\nverification_command\n```\n\n**-> Tell user**: Report results. On failure, diagnose and fix.\n```\n\n### Examples Pattern\n\n```markdown\n## Examples\n\n**Example 1: Typical usage**\n```\nUser says: \"/skill-name argument\"\nActions:\n  1. Parse input\n  2. Execute workflow\n  3. Verify result\nResult: Description of expected outcome\n```\n\n**Example 2: Edge case**\n```\nUser says: \"alternative trigger phrase\"\nActions:\n  1. Handle the edge case\n  2. Adapt workflow accordingly\nResult: Description of expected outcome\n```\n```\n\n### Troubleshooting Pattern\n\nUse a table for common issues:\n\n```markdown\n## Troubleshooting\n\n| Problem | Cause | Fix |\n|---|---|---|\n| Common error 1 | Typical cause | How to fix |\n| Common error 2 | Typical cause | How to fix |\n```\n\n---\n\n## Writing Style\n\n### General Principles\n\n- **Use imperative form** for instructions (\"Run the script\", not \"You should run the script\").\n- **Explain WHY, not just WHAT** — help the agent understand the reasoning so it can adapt.\n- **Be concise** — the context window is a shared resource. Only add information the agent doesn't already have.\n- **Prefer examples over explanations** — a concrete example communicates faster than an abstract description.\n- **Don't over-constrain** — use MUSTs sparingly. Give the agent enough freedom to adapt to unexpected situations.\n\n### What NOT to Include\n\n- Information the agent already knows (common programming patterns, standard library usage)\n- Redundant explanations of well-known tools\n- Overly detailed error messages for obvious failures\n- Commentary about the skill creation process itself\n\n### Conciseness Checklist\n\nFor each paragraph, ask:\n- Does the agent really need this explanation?\n- Does this paragraph justify its token cost?\n- Could this be replaced by a short example?\n- Is this duplicated elsewhere in the skill or references?\n\n---\n\n## Scripts and References\n\n### When to Use Scripts\n\nUse `scripts/` when:\n- The same code would be rewritten repeatedly\n- Deterministic reliability is needed (validation, data processing)\n- Complex operations need to be reproducible\n\nScripts can be executed without loading into context, saving tokens.\n\n### When to Use References\n\nUse `references/` when:\n- Detailed documentation needs to be available but not always in context\n- Multiple variants/domains need separate detailed guides\n- Content exceeds what fits comfortably in SKILL.md\n\n### Documentation Requirements\n\nEvery script and reference file must be documented in SKILL.md:\n\n```markdown\n## Scripts Reference\n\n| Script | Step | Description |\n|---|---|---|\n| `validate_migration.py` | 6 | Automated import/API/registration checks |\n| `benchmark.sh` | 9 | `vllm bench throughput` with dummy weights |\n```\n\n---\n\n## FlagOS-Specific Conventions\n\n### Naming\n\n- Directory names: lowercase + hyphens (`model-migrate-flagos`, `preflight-check`)\n- Script filenames: lowercase + underscores (`validate_migration.py`)\n- Reference docs: lowercase + hyphens (`compatibility-patches.md`)\n- FlagOS skills use functional prefixes describing the action\n\n### Categories\n\n| Category | Description | Example |\n|---|---|---|\n| `workflow-automation` | Multi-step workflows | model-migrate-flagos |\n| `deployment-verification` | Deployment & environment validation | preflight-check |\n| `build-tooling` | Build & release tools | build-vendor-image |\n| `code-standard` | Coding standards & review | — |\n| `operations` | Operational tasks | — |\n| `developer-tooling` | Developer productivity tools | skill-creator-flagos |\n\n### Bilingual Support\n\nFlagOS skills should provide:\n- `README.md` — English documentation\n- `README_zh.md` — Chinese documentation (recommended)\n\nBoth READMEs follow the same structure but are written independently (not machine-translated).\n\n### License\n\n- Default: Apache License 2.0\n- Place `LICENSE.txt` in each skill directory\n- Third-party dependencies must be noted in SKILL.md with source and license information\n\nFile v1.1.0:README_zh.md\n\n# skill-creator-flagos：技能开发工具链\n\n## 概述\n\n`skill-creator-flagos` 是一个元技能（meta-skill），用于在 FlagOS skills 仓库中创建、改进和验证其他技能。\n\n### 解决的问题\n\n编写高质量的 skill 涉及大量细节：YAML frontmatter 格式、触发优化的 description、渐进式披露结构、文件组织规范、双语文档等。手动检查这些要求既繁琐又容易遗漏，新贡献者往往要到 review 阶段才发现问题。\n\n本技能自动化了整个技能开发生命周期：**从模板脚手架 → 按规范编写 → 验证约定 → 用测试用例迭代**，提供 4 种工作模式，每个阶段都有配套工具。\n\n### 使用方式\n\n```bash\n# 交互模式 — 询问你想做什么\n/skill-creator-flagos\n\n# 创建新 skill 脚手架\n/skill-creator-flagos preflight-check --init\n\n# 创建时指定资源目录\n/skill-creator-flagos preflight-check --init --resources scripts,references\n\n# 验证单个 skill\n/skill-creator-flagos model-migrate-flagos --validate\n\n# 验证所有 skill\n/skill-creator-flagos --validate\n\n# 改进现有 skill\n/skill-creator-flagos model-migrate-flagos\n\n# 运行测试用例\n/skill-creator-flagos model-migrate-flagos --eval\n```\n\n| 参数 | 必填 | 默认值 | 说明 |\n|---|---|---|---|\n| `skill-name` | 否 | — | hyphen-case 格式的技能名（如 `preflight-check`） |\n| `--init` | 否 | — | 创建新 skill 目录脚手架 |\n| `--validate` | 否 | — | 验证 skill 结构和规范 |\n| `--eval` | 否 | — | 对 skill 运行测试用例 |\n| `--resources` | 否 | — | 逗号分隔的资源目录：`scripts,references,assets` |\n\n不带任何 flag 时进入交互模式。\n\n---\n\n## 四种工作模式\n\n### 模式一：创建 — 从零构建新 Skill\n\n```\n意图捕获 → 访谈 → 脚手架 → 编写 SKILL.md → 添加资源 → 验证 → 写 README\n```\n\n**执行过程：**\n\n1. **意图捕获** — Agent 访谈你：这个 skill 做什么、什么时候触发、需要什么工具、产出什么。如果当前对话已经包含你想封装的工作流，Agent 会先从上下文提取信息。\n\n2. **脚手架** — 运行 `init_skill.py` 生成目录结构：\n   ```\n   my-skill/\n   ├── SKILL.md        # 带 [TODO] 占位符的模板\n   ├── LICENSE.txt      # Apache 2.0\n   ├── scripts/         # （按需）\n   ├── references/      # （按需）\n   └── assets/          # （按需）\n   ```\n\n3. **编写 SKILL.md** — 按照 `references/writing-guide.md` 中的规范填充 frontmatter 和 body：\n   - Description 优化触发（具体短语、适度\"激进\"）\n   - Body 包含所有必要章节（Overview、Steps、Examples、Troubleshooting）\n   - 渐进式披露（详细内容放 `references/`，不让 SKILL.md 膨胀）\n\n4. **添加资源** — 按需创建脚本、参考文档和资源文件，每个文件都在 SKILL.md 中记录用法。\n\n5. **验证 & README** — 运行验证器修复问题，编写中英文 README。\n\n**示例会话：**\n\n```\n你：   /skill-creator-flagos preflight-check --init\nAgent: preflight-check 应该做什么？什么时候触发？\n你：   在运行 vLLM 前检查 GPU 可用性、驱动版本和 Python 环境\nAgent: 明白了。我会创建 skill 并包含 scripts/ 目录来放检查脚本……\n       [创建目录、编写 SKILL.md、添加 scripts/check_gpu.sh、验证]\n       Skill 'preflight-check' 已创建，最终结构如下：……\n```\n\n### 模式二：改进 — 迭代优化现有 Skill\n\n**执行过程：**\n\n1. **分析** — 读取现有 SKILL.md 和所有支撑文件，识别问题：\n   - Description 中触发条件模糊或缺失\n   - 缺少示例或边界情况\n   - 步骤没有进度汇报\n   - SKILL.md 过长需要拆分\n   - Troubleshooting 条目缺失\n\n2. **设计测试用例** — 创建 2-3 个真实的测试 prompt，保存到 `evals/evals.json`。\n\n3. **迭代** — 应用改进 → 重新验证 → 对照测试用例审查 → 收集反馈 → 重复。\n\n**示例会话：**\n\n```\n你：   /skill-creator-flagos model-migrate-flagos\nAgent: 分析了 model-migrate-flagos，发现 3 个可改进项：\n       1. Description 可以更有利于触发\n       2. 缺少多模态模型迁移的示例\n       3. Troubleshooting 表没有覆盖网络超时\n       先处理哪个？\n```\n\n### 模式三：验证 — 检查规范合规性\n\n**执行过程：**\n\n运行仓库级脚本 `scripts/validate_skills.py`，检查项：\n\n| 检查项 | 级别 | 说明 |\n|---|---|---|\n| SKILL.md 存在 | Error | 必须有入口文件 |\n| YAML frontmatter 合法 | Error | 必须以 `---` 开头和结尾 |\n| `name` 字段存在 | Error | 必填字段 |\n| `description` 字段存在 | Error | 必填字段 |\n| name 与目录名一致 | Error | `name` 字段必须等于文件夹名 |\n| name 格式合规 | Error | 仅小写字母 + 数字 + 连字符，最长 64 字符 |\n| description 长度 | Error | 不超过 1024 字符 |\n| body 内容充实 | Error | 至少 100 字符 |\n| 引用文件存在 | Error | 所有 markdown 链接指向的文件必须实际存在 |\n| 有 Examples 章节 | Warning | 建议所有 skill 都包含 |\n| 有 Troubleshooting 章节 | Warning | 建议所有 skill 都包含 |\n| 脚本有执行权限 | Warning | `.py` 和 `.sh` 文件应有 `+x` 权限 |\n| LICENSE.txt 存在 | Warning | 建议每个 skill 包含 |\n| README.md 存在 | Warning | 建议包含文档 |\n\n**输出示例：**\n\n```\n============================================================\n  model-migrate-flagos: PASS\n============================================================\n    ✓ All checks passed\n\n============================================================\n  skill-creator-flagos: PASS\n============================================================\n  Warnings (1):\n    ⚠ No README.md found (recommended)\n\n────────────────────────────────────────────────────────────\n  Summary: 2 skill(s), 0 error(s), 1 warning(s)\n────────────────────────────────────────────────────────────\n```\n\n### 模式四：评估 — 运行测试用例\n\n**执行过程：**\n\n如果 skill 目录中存在 `evals/evals.json`，Agent 会运行每个测试 prompt 并检查断言，生成通过/失败报告。\n\n---\n\n## 目录结构\n\n```\nskills/skill-creator-flagos/\n├── SKILL.md                          # 技能定义（入口文件）\n├── LICENSE.txt                       # Apache 2.0 许可证\n├── README.md                         # 英文文档\n├── README_zh.md                      # 本文档（中文版）\n├── references/                       # 参考文档\n│   ├── writing-guide.md              # 详细的技能编写规范和最佳实践\n│   └── schemas.md                    # 评估和验证的 JSON schema\n└── scripts/                          # 可执行脚本\n    └── init_skill.py                 # 创建新 skill 目录脚手架\n```\n\n---\n\n## 各文件说明\n\n### 技能定义\n\n#### `SKILL.md`\n\n技能的入口文件。定义了触发条件、参数格式、四种工作模式（创建、改进、验证、评估）、占位符解析、使用示例和常见问题排查。AI 编程助手根据此文件识别和调用技能。\n\n### 参考文档（`references/`）\n\n#### `writing-guide.md` — 技能编写规范\n\n全面的编写指南，涵盖：\n\n- **Skill 结构解剖** — 必填字段、FlagOS 扩展字段、目录约定\n- **渐进式披露** — 三级加载系统（metadata → body → references）、何时以及如何拆分内容\n- **Description 编写** — 如何写出触发优化的描述（具体短语 + 反向触发条件）\n- **Body 结构** — 必要章节模板（Overview、Prerequisites、Steps、Examples、Troubleshooting）\n- **写作风格** — 祈使句、解释 why 而非堆 MUST、简洁优先\n- **Scripts 和 References 用法** — 何时使用、文档化要求\n- **FlagOS 特有约定** — 命名规范、分类体系、双语支持、许可证\n\n#### `schemas.md` — JSON Schema 定义\n\n定义评估和验证使用的 JSON 格式：\n\n| Schema | 位置 | 用途 |\n|---|---|---|\n| `evals.json` | `evals/evals.json` | 测试用例定义（prompt + 断言） |\n| `eval_result.json` | `evals/results/eval_result.json` | 评估结果（每个断言的通过/失败状态） |\n| `validation_result.json` | `evals/results/validation_result.json` | 结构化验证输出 |\n\n### 脚本（`scripts/`）\n\n#### `init_skill.py` — 创建新 Skill 脚手架\n\n```bash\n# 基本用法\npython3 init_skill.py my-skill --path skills/\n\n# 带资源目录\npython3 init_skill.py my-skill --path skills/ --resources scripts,references,assets\n\n# 名称自动标准化\npython3 init_skill.py \"My Cool Skill\" --path skills/\n# → 创建 skills/my-cool-skill/\n```\n\n**生成的文件：**\n\n| 文件 | 必定生成 | 说明 |\n|---|---|---|\n| `SKILL.md` | 是 | 带所有 frontmatter 字段和 `[TODO]` body 占位符的模板 |\n| `LICENSE.txt` | 是 | Apache 2.0 许可证 |\n| `scripts/` | 按需 | 空目录 + `.gitkeep` |\n| `references/` | 按需 | 空目录 + `.gitkeep` |\n| `assets/` | 按需 | 空目录 + `.gitkeep` |\n\n**执行的校验：**\n- 名称 2-64 字符，仅允许小写字母 + 数字 + 连字符\n- 父目录必须存在\n- 目标目录不能已存在\n- 资源类型必须是 `scripts`、`references`、`assets` 之一\n\n### 仓库级验证脚本（`scripts/validate_skills.py`）\n\n验证由仓库级脚本 `scripts/validate_skills.py` 统一处理（不在 skill-creator-flagos 内部重复，避免逻辑分散）。支持单个和批量验证：\n\n```bash\n# 验证所有 skill（默认）\npython3 scripts/validate_skills.py\n\n# 验证单个 skill\npython3 scripts/validate_skills.py skills/model-migrate-flagos\n\n# 验证目录下所有 skill\npython3 scripts/validate_skills.py skills/ --all\n```\n\n执行 14 项检查，分 error 和 warning 两个级别。退出码：0 = 通过，1 = 有错误。\n\n---\n\n## 在 FlagOS Skills 仓库中使用\n\n### 快速安装（通过 npx）\n\n```bash\n# 仅安装本 skill\nnpx skills add flagos-ai/skills --skill skill-creator-flagos -a claude-code\n\n# 或一次性安装所有 Flagos skills\nnpx skills add flagos-ai/skills -a claude-code\n```\n\n### 手动安装\n\n```bash\n# 在你的项目根目录执行\nmkdir -p .claude/skills\ncp -r <本仓库路径>/skills/skill-creator-flagos .claude/skills/\n```\n\n### 独立使用脚本\n\n脚本可以脱离 skill 调用，独立使用：\n\n```bash\n# 在任意位置创建新 skill 脚手架\npython3 skills/skill-creator-flagos/scripts/init_skill.py my-skill --path ./my-project/skills/\n\n# 验证 skills（仓库级脚本）\npython3 scripts/validate_skills.py\npython3 scripts/validate_skills.py skills/my-skill\n```\n\n---\n\n## 许可证\n\nThis project is licensed under the Apache 2.0 License. See [LICENSE.txt](LICENSE.txt) for details.\n\nFile v1.1.0:skill-card.md\n\n## Description:\n\nCreate new skills, modify existing skills, and validate skill quality for the FlagOS skills repository.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[wbavon](https://clawhub.ai/user/wbavon)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and skill maintainers use this skill to scaffold, improve, validate, and evaluate reusable agent skills for the FlagOS skills repository.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can persistently create or edit agent skills in a controlled skills repository.\n\nMitigation: Install and invoke it only for intended skill-development work, and review generated changes before committing or publishing.\n\nRisk: Broad natural-language trigger guidance may activate the meta-skill during general skill-development discussions.\n\nMitigation: Prefer pinned or manually verified installation and explicit invocation when broad automatic activation is not desired.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/wbavon/skills/skill-creator-flagos)\n- [README](artifact/README.md)\n- [Skill Writing Guide](artifact/references/writing-guide.md)\n- [JSON Schemas](artifact/references/schemas.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline code, shell commands, and generated skill files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Can create or modify persistent skill files when used by an agent with filesystem access.]\n\n## Skill Version(s):\n\n1.1.0 (source: ClawHub release metadata; artifact frontmatter lists 1.0.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.1.0:LICENSE.txt\n\nApache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to the Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by the Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding any notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"[]\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. Please also get an\n      OpenPGP-compatible signature of your completed statement.\n\n   Copyright 2026 BAAI (Beijing Academy of Artificial Intelligence)\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n\nArchive v1.0.0: 8 files, 26450 bytes\n\nFiles: LICENSE.txt (11262b), README_zh.md (11050b), README.md (11951b), references/schemas.md (3102b), references/writing-guide.md (9745b), scripts/init_skill.py (6478b), SKILL.md (11481b), _meta.json (139b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: skill-creator-flagos\ndescription: >\n  Create new skills, modify existing skills, and validate skill quality for the FlagOS skills\n  repository. Use this skill whenever someone wants to create a skill from scratch, improve or\n  edit an existing skill, scaffold a new skill directory, validate skill structure, or run test\n  cases against a skill. Trigger when the user says things like \"create a skill\", \"make a new\n  skill for X\", \"scaffold a skill\", \"improve this skill\", \"validate my skill\", or simply\n  \"/skill-creator-flagos\". Also trigger when users mention turning a workflow into a reusable skill,\n  or want to package a repeated process as a skill.\nargument-hint: \"[skill-name] [--init | --validate | --eval]\"\nuser-invokable: true\ncompatibility: \"Python 3.8+, works with any AI coding assistant that supports the Agent Skills standard\"\nmetadata:\n  version: \"1.0.0\"\n  author: flagos-ai\n  category: workflow-automation\n  tags: [skill-creation, scaffolding, validation, meta-skill, developer-tooling]\nallowed-tools: \"Bash(python3:*) Bash(python:*) Bash(chmod:*) Bash(mkdir:*) Bash(cp:*) Bash(ls:*) Bash(cat:*) Read Edit Write Glob Grep AskUserQuestion TaskCreate TaskUpdate TaskList TaskGet Agent\"\n---\n\n# Skill Creator\n\nA meta-skill for creating, improving, and validating skills in the FlagOS skills repository.\n\n## Overview\n\nThis skill guides you through the full lifecycle of skill development:\n1. **Create** — scaffold a new skill from template, interview the user, write SKILL.md\n2. **Improve** — analyze an existing skill, identify weaknesses, iterate with test cases\n3. **Validate** — check structure, frontmatter, references, and conventions compliance\n\n## Usage\n\n```\n/skill-creator-flagos                       # Interactive — asks what you want to do\n/skill-creator-flagosmy-new-skill --init    # Scaffold a new skill\n/skill-creator-flagosmy-skill --validate    # Validate an existing skill\n/skill-creator-flagosmy-skill --eval        # Run test prompts against a skill\n```\n\n## Execution\n\n### Step 0: Parse arguments and determine mode\n\nExtract from user input:\n- `{{skill_name}}` — optional skill name (hyphen-case)\n- `{{mode}}` — one of: `create`, `improve`, `validate`, `eval`, or `interactive` (default)\n\nIf no mode is specified, ask the user:\n\n> What would you like to do?\n> 1. Create a new skill from scratch\n> 2. Improve an existing skill\n> 3. Validate a skill's structure and conventions\n> 4. Run test cases against a skill\n\n**-> Tell user**: Confirm the mode and skill name.\n\n---\n\n## Mode 1: Create a New Skill\n\n### Step 1: Capture intent\n\nStart by understanding what the user wants to build. If the current conversation already contains a workflow the user wants to capture (e.g., \"turn this into a skill\"), extract answers from the conversation history first.\n\nKey questions to clarify:\n1. What should this skill enable the agent to do?\n2. When should this skill trigger? (user phrases, contexts, file types)\n3. What's the expected output or end state?\n4. Does the skill need scripts, reference docs, or asset files?\n5. What tools does the skill need access to?\n\nAdapt your communication style to the user — don't assume coding jargon familiarity. Pay attention to context cues.\n\n**-> Tell user**: Summarize the captured intent and confirm before proceeding.\n\n### Step 2: Initialize the skill directory\n\nRun the init script to scaffold the skill:\n\n```bash\npython3 {{skill_root}}/scripts/init_skill.py {{skill_name}} --path {{skills_dir}} [--resources scripts,references,assets]\n```\n\nWhere:\n- `{{skill_root}}` = absolute path to this skill-creator-flagos's directory\n- `{{skills_dir}}` = path to the `skills/` directory (usually the parent of `{{skill_root}}`)\n\nThe script creates the directory with SKILL.md template, LICENSE.txt, and optional subdirectories.\n\n**-> Tell user**: Show the created directory structure.\n\n### Step 3: Write the SKILL.md\n\nBased on the user interview, fill in these components:\n\n#### Frontmatter (YAML)\n\n| Field | Required | Guidelines |\n|-------|----------|------------|\n| `name` | Yes | Lowercase + hyphens, must match directory name, max 64 chars |\n| `description` | Yes | 1-2 sentences: what it does AND when to trigger. Be specific and slightly \"pushy\" — err on the side of triggering too often rather than too rarely |\n| `argument-hint` | Recommended | Show expected arguments |\n| `user-invokable` | Recommended | `true` if invokable via `/skill-name` |\n| `compatibility` | Optional | Environment requirements |\n| `metadata` | Recommended | version, author, category, tags |\n| `allowed-tools` | Recommended | Space-separated tool list with patterns |\n\n#### Body (Markdown)\n\nFollow the structure documented in `references/writing-guide.md`. At minimum include:\n- **Overview** — what problem this solves, when to activate\n- **Prerequisites** — environment requirements\n- **Execution steps** — numbered steps with `**-> Tell user**` progress markers\n- **Examples** — at least 2-3 realistic usage examples\n- **Troubleshooting** — common problems and fixes\n\nRead `references/writing-guide.md` for detailed patterns on progressive disclosure, output formats, domain organization, and writing style.\n\n### Step 4: Add supporting resources\n\nBased on the skill's needs, create:\n- **`scripts/`** — executable code for deterministic/repetitive tasks\n- **`references/`** — detailed docs loaded into context as needed\n- **`assets/`** — files used in output (templates, icons, etc.)\n\nRules:\n- Every script/reference must be documented in SKILL.md with usage instructions\n- Scripts should have execute permissions (`chmod +x`)\n- Keep SKILL.md under 500 lines; move detailed content to `references/`\n- For reference files >300 lines, include a table of contents\n\n### Step 5: Validate\n\nRun validation to check conventions compliance:\n\n```bash\npython3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}\n```\n\nFix any reported issues. See Troubleshooting section below.\n\n**-> Tell user**: Report validation results. On failure, diagnose and fix.\n\n### Step 6: Write README files\n\nCreate `README.md` (English) and optionally `README_zh.md` (Chinese) following the pattern in existing skills. The README should cover:\n- Overview / problem statement\n- Usage instructions\n- Directory structure\n- File descriptions\n- Examples\n- Installation instructions\n\n**-> Tell user**: Skill creation complete. Present the final directory tree and summary.\n\n---\n\n## Mode 2: Improve an Existing Skill\n\n### Step 1: Analyze the current skill\n\nRead the existing SKILL.md and all supporting files. Identify:\n- Unclear or missing trigger conditions in the description\n- Missing examples or edge cases\n- Steps that lack progress reporting (`**-> Tell user**`)\n- Overly long SKILL.md that should be split into references\n- Missing troubleshooting entries\n- Scripts without documentation\n\n**-> Tell user**: Present findings and proposed improvements.\n\n### Step 2: Draft test prompts\n\nCreate 2-3 realistic test prompts — things a real user would say. Share them with the user for confirmation.\n\nSave to `evals/evals.json`:\n\n```json\n{\n  \"skill_name\": \"{{skill_name}}\",\n  \"evals\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's task prompt\",\n      \"expected_output\": \"Description of expected result\",\n      \"assertions\": [\"The output includes X\", \"Step Y was executed\"]\n    }\n  ]\n}\n```\n\nSee `references/schemas.md` for the full schema.\n\n### Step 3: Iterate\n\nFor each round:\n1. Apply improvements to SKILL.md and supporting files\n2. Re-run validation\n3. Review against test prompts (mentally or by spawning test runs)\n4. Collect user feedback\n5. Repeat until satisfied\n\n**-> Tell user**: Report changes made in each iteration.\n\n---\n\n## Mode 3: Validate\n\nRun the validation script:\n\n```bash\npython3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}\n```\n\nThe script checks:\n- SKILL.md exists and has valid YAML frontmatter\n- Required fields (`name`, `description`) are present\n- `name` matches directory name, follows naming conventions\n- `description` length within limits\n- Body has sufficient content (>100 chars)\n- Referenced files in `scripts/` and `references/` actually exist\n- Scripts have execute permissions\n- No hardcoded paths or credentials\n\n**-> Tell user**: Report all findings with severity (error/warning).\n\n---\n\n## Mode 4: Run Evals\n\nIf `evals/evals.json` exists, run the test prompts against the skill:\n\n```bash\npython3 {{skill_root}}/scripts/run_eval.py {{skills_dir}}/{{skill_name}}\n```\n\nThis generates a report showing which assertions passed/failed for each test case.\n\n**-> Tell user**: Present results and suggest improvements.\n\n---\n\n## Placeholders\n\n| Placeholder | How to derive |\n|---|---|\n| `{{skill_name}}` | From user input, normalized to hyphen-case |\n| `{{skill_root}}` | Absolute path to this skill-creator-flagos's directory |\n| `{{repo_root}}` | Absolute path to the repository root (parent of `skills/`) |\n| `{{skills_dir}}` | Path to the `skills/` directory containing all skills |\n\n## Examples\n\n**Example 1: Create a new skill from scratch**\n```\nUser says: \"/skill-creator-flagospreflight-check --init\"\nActions:\n  1. Parse → skill_name=preflight-check, mode=create\n  2. Interview user about what preflight-check should do\n  3. Run init_skill.py to scaffold directory\n  4. Write SKILL.md with deployment verification workflow\n  5. Add scripts/check_gpu.sh, scripts/check_env.py\n  6. Validate and fix any issues\n  7. Write README.md\nResult: Complete preflight-check skill ready for use\n```\n\n**Example 2: Improve an existing skill**\n```\nUser says: \"improve model-migrate-flagos, the description could be better\"\nActions:\n  1. Read existing SKILL.md and all references\n  2. Analyze description — find it's too long and not trigger-friendly\n  3. Propose a more concise, trigger-optimized description\n  4. Create test prompts to verify triggering\n  5. Apply changes, validate\nResult: Improved skill with better triggering accuracy\n```\n\n**Example 3: Validate all skills**\n```\nUser says: \"/skill-creator-flagos--validate\"\nActions:\n  1. No skill_name provided → validate all skills in skills/\n  2. Run validate_skill.py on each skill directory\n  3. Report consolidated results\nResult: Validation report for all skills\n```\n\n**Example 4: Turn a conversation workflow into a skill**\n```\nUser says: \"turn what we just did into a skill\"\nActions:\n  1. Analyze conversation history for the workflow performed\n  2. Extract: tools used, sequence of steps, corrections made\n  3. Interview user to fill gaps\n  4. Scaffold and write the skill\nResult: New skill capturing the conversation workflow\n```\n\n## Troubleshooting\n\n| Problem | Cause | Fix |\n|---|---|---|\n| `name does not match directory name` | Frontmatter `name` differs from folder name | Ensure they are identical |\n| `description exceeds 1024 chars` | Description too long | Move details to the body; keep description to 1-2 sentences |\n| `SKILL.md body is too short` | Insufficient instructions | Add overview, steps, examples, troubleshooting |\n| `Missing required field` | `name` or `description` absent in frontmatter | Add the missing field |\n| `name must be lowercase+hyphens` | Invalid characters in name | Use only `a-z`, `0-9`, `-` |\n| Skill doesn't trigger | Description too narrow or vague | Make description more specific and slightly aggressive about triggering |\n| Referenced file not found | Script or reference listed in SKILL.md but not on disk | Create the file or remove the reference |\n\nFile v1.0.0:README.md\n\n# skill-creator-flagos: Skill Development Toolkit\n\n[中文版](README_zh.md)\n\n## Overview\n\n`skill-creator-flagos` is a meta-skill for creating, improving, and validating skills in the FlagOS skills repository.\n\n### Problem Statement\n\nWriting a high-quality skill involves many details: YAML frontmatter conventions, trigger-optimized descriptions, progressive disclosure structure, proper file organization, bilingual documentation, and more. Manually checking all these requirements is tedious and error-prone, and new contributors often miss conventions that only become apparent after review.\n\nThis skill automates the entire skill development lifecycle: **scaffold from template -> write with guided patterns -> validate conventions -> iterate with test cases**, spanning 4 operational modes with built-in tooling for each stage.\n\n### Usage\n\n```bash\n# Interactive — asks what you want to do\n/skill-creator-flagos\n\n# Scaffold a new skill\n/skill-creator-flagos preflight-check --init\n\n# Scaffold with specific resource directories\n/skill-creator-flagos preflight-check --init --resources scripts,references\n\n# Validate a single skill\n/skill-creator-flagos model-migrate-flagos --validate\n\n# Validate all skills\n/skill-creator-flagos --validate\n\n# Improve an existing skill\n/skill-creator-flagos model-migrate-flagos\n\n# Run test cases against a skill\n/skill-creator-flagos model-migrate-flagos --eval\n```\n\n| Argument | Required | Default | Description |\n|---|---|---|---|\n| `skill-name` | No | — | Skill name in hyphen-case (e.g. `preflight-check`) |\n| `--init` | No | — | Scaffold a new skill directory |\n| `--validate` | No | — | Validate skill structure and conventions |\n| `--eval` | No | — | Run test cases against the skill |\n| `--resources` | No | — | Comma-separated resource dirs: `scripts,references,assets` |\n\nWhen no flag is provided, the skill enters interactive mode and asks what you'd like to do.\n\n---\n\n## Four Operational Modes\n\n### Mode 1: Create — Build a New Skill from Scratch\n\n```\nIntent capture → Interview → Scaffold → Write SKILL.md → Add resources → Validate → Write README\n```\n\n**What happens:**\n\n1. **Intent capture** — The agent interviews you about what the skill should do, when it should trigger, what tools it needs, and what outputs it produces. If the current conversation already contains a workflow you want to capture, the agent extracts answers from context first.\n\n2. **Scaffold** — Runs `init_skill.py` to generate the directory structure:\n   ```\n   my-skill/\n   ├── SKILL.md        # Template with [TODO] placeholders\n   ├── LICENSE.txt      # Apache 2.0\n   ├── scripts/         # (if requested)\n   ├── references/      # (if requested)\n   └── assets/          # (if requested)\n   ```\n\n3. **Write SKILL.md** — Fills in the frontmatter and body following the patterns in `references/writing-guide.md`. The agent ensures:\n   - Description is trigger-optimized (specific phrases, slightly \"pushy\")\n   - Body includes all required sections (Overview, Steps, Examples, Troubleshooting)\n   - Progressive disclosure is applied (details in `references/`, not bloating SKILL.md)\n\n4. **Add resources** — Creates scripts, reference docs, and assets as needed, with each file documented in SKILL.md.\n\n5. **Validate & README** — Runs the validator, fixes issues, and writes bilingual READMEs.\n\n**Example session:**\n\n```\nYou:   /skill-creator-flagos preflight-check --init\nAgent: What should preflight-check do? When should it trigger?\nYou:   It checks GPU availability, driver versions, and Python env before running vLLM\nAgent: Got it. I'll scaffold the skill and include a scripts/ directory for the check scripts...\n       [creates directory, writes SKILL.md, adds scripts/check_gpu.sh, validates]\n       Skill 'preflight-check' created. Here's the final structure: ...\n```\n\n### Mode 2: Improve — Iterate on an Existing Skill\n\n**What happens:**\n\n1. **Analyze** — Reads the existing SKILL.md and all supporting files. Identifies issues:\n   - Vague or missing trigger conditions in description\n   - Missing examples or edge cases\n   - Steps without progress reporting\n   - Overly long SKILL.md that should be split\n   - Missing troubleshooting entries\n\n2. **Draft test prompts** — Creates 2-3 realistic test cases and saves them to `evals/evals.json` for verification.\n\n3. **Iterate** — Applies improvements, re-validates, reviews against test prompts, collects your feedback, and repeats.\n\n**Example session:**\n\n```\nYou:   /skill-creator-flagos model-migrate-flagos\nAgent: I've analyzed model-migrate-flagos. Found 3 potential improvements:\n       1. Description could be more trigger-friendly\n       2. Missing example for multimodal model migration\n       3. Troubleshooting table doesn't cover network timeout\n       Which should I address first?\n```\n\n### Mode 3: Validate — Check Conventions Compliance\n\n**What happens:**\n\nRuns the repository-level `scripts/validate_skills.py` which checks:\n\n| Check | Severity | Description |\n|---|---|---|\n| SKILL.md exists | Error | Entry point file must be present |\n| Valid YAML frontmatter | Error | Must start and end with `---` |\n| `name` field present | Error | Required field |\n| `description` field present | Error | Required field |\n| Name matches directory | Error | `name` field must equal folder name |\n| Name format | Error | Lowercase + hyphens only, max 64 chars |\n| Description length | Error | Must not exceed 1024 chars |\n| Body content | Error | Must be at least 100 chars |\n| Referenced files exist | Error | All linked files must be on disk |\n| Examples section | Warning | Recommended for all skills |\n| Troubleshooting section | Warning | Recommended for all skills |\n| Script permissions | Warning | `.py` and `.sh` files should be executable |\n| LICENSE.txt present | Warning | Recommended per-skill license |\n| README.md present | Warning | Recommended documentation |\n\n**Example output:**\n\n```\n============================================================\n  model-migrate-flagos: PASS\n============================================================\n    ✓ All checks passed\n\n============================================================\n  skill-creator-flagos: PASS\n============================================================\n  Warnings (1):\n    ⚠ No README.md found (recommended)\n\n────────────────────────────────────────────────────────────\n  Summary: 2 skill(s), 0 error(s), 1 warning(s)\n────────────────────────────────────────────────────────────\n```\n\n### Mode 4: Eval — Run Test Cases\n\n**What happens:**\n\nIf `evals/evals.json` exists in the skill directory, the agent runs each test prompt and checks assertions against the expected output. Generates a report showing pass/fail status per assertion.\n\n---\n\n## Directory Structure\n\n```\nskills/skill-creator-flagos/\n├── SKILL.md                          # Skill definition (entry point)\n├── LICENSE.txt                       # Apache 2.0 license\n├── README.md                         # This document (English)\n├── README_zh.md                      # Chinese version\n├── references/                       # Reference documents\n│   ├── writing-guide.md              # Detailed skill writing patterns & best practices\n│   └── schemas.md                    # JSON schemas for evals and validation\n└── scripts/                          # Executable scripts\n    └── init_skill.py                 # Scaffold a new skill directory\n```\n\n---\n\n## File Descriptions\n\n### Skill Definition\n\n#### `SKILL.md`\n\nThe skill entry point. Defines trigger conditions, argument format, four operational modes (Create, Improve, Validate, Eval), placeholder resolution, examples, and troubleshooting guide. The AI coding assistant uses this file to identify and invoke the skill.\n\n### Reference Documents (`references/`)\n\n#### `writing-guide.md` — Skill Writing Patterns & Best Practices\n\nComprehensive guide covering:\n\n- **Anatomy of a Skill** — required fields, FlagOS extension fields, directory conventions\n- **Progressive Disclosure** — three-level loading system (metadata → body → references), when and how to split content\n- **Writing the Description** — how to craft trigger-optimized descriptions with specific phrases and negative triggers\n- **Structuring the Body** — required sections template (Overview, Prerequisites, Steps, Examples, Troubleshooting)\n- **Writing Style** — imperative form, explain why not what, conciseness checklist\n- **Scripts and References** — when to use each, documentation requirements\n- **FlagOS-Specific Conventions** — naming, categories, bilingual support, licensing\n\n#### `schemas.md` — JSON Schemas\n\nDefines the JSON formats used for evaluation and validation:\n\n| Schema | Location | Purpose |\n|---|---|---|\n| `evals.json` | `evals/evals.json` | Test case definitions (prompts + assertions) |\n| `eval_result.json` | `evals/results/eval_result.json` | Evaluation results with pass/fail per assertion |\n| `validation_result.json` | `evals/results/validation_result.json` | Structured validation output |\n\n### Scripts (`scripts/`)\n\n#### `init_skill.py` — Scaffold a New Skill\n\n```bash\n# Basic usage\npython3 init_skill.py my-skill --path skills/\n\n# With resource directories\npython3 init_skill.py my-skill --path skills/ --resources scripts,references,assets\n\n# Name auto-normalization\npython3 init_skill.py \"My Cool Skill\" --path skills/\n# → creates skills/my-cool-skill/\n```\n\n**What it generates:**\n\n| File | Always | Description |\n|---|---|---|\n| `SKILL.md` | Yes | Template with all frontmatter fields and `[TODO]` body placeholders |\n| `LICENSE.txt` | Yes | Apache 2.0 license |\n| `scripts/` | If requested | Empty directory with `.gitkeep` |\n| `references/` | If requested | Empty directory with `.gitkeep` |\n| `assets/` | If requested | Empty directory with `.gitkeep` |\n\n**Validations performed:**\n- Name must be 2-64 chars, lowercase + hyphens only\n- Parent directory must exist\n- Target directory must not already exist\n- Resource types must be one of: `scripts`, `references`, `assets`\n\n### Repository-Level Validation (`scripts/validate_skills.py`)\n\nValidation is handled by the repository-level script `scripts/validate_skills.py` (not bundled inside skill-creator-flagos to avoid duplication). It supports both single-skill and batch validation:\n\n```bash\n# Validate all skills (default)\npython3 scripts/validate_skills.py\n\n# Validate a single skill\npython3 scripts/validate_skills.py skills/model-migrate-flagos\n\n# Validate all skills in a specific directory\npython3 scripts/validate_skills.py skills/ --all\n```\n\nPerforms 14 checks across two severity levels (error / warning). See the Mode 3 table above for the full list. Exit code: 0 = pass, 1 = errors found.\n\n---\n\n## Usage in FlagOS Skills Repository\n\n### Quick Install (via npx)\n\n```bash\n# Install this skill only\nnpx skills add flagos-ai/skills --skill skill-creator-flagos -a claude-code\n\n# Or install all Flagos skills at once\nnpx skills add flagos-ai/skills -a claude-code\n```\n\n### Manual Install\n\n```bash\n# From your project root\nmkdir -p .claude/skills\ncp -r <path-to-this-repo>/skills/skill-creator-flagos .claude/skills/\n```\n\n### Standalone Script Usage\n\nThe scripts can be used independently without invoking the skill:\n\n```bash\n# Scaffold a new skill anywhere\npython3 skills/skill-creator-flagos/scripts/init_skill.py my-skill --path ./my-project/skills/\n\n# Validate skills (repo-level script)\npython3 scripts/validate_skills.py\npython3 scripts/validate_skills.py skills/my-skill\n```\n\n---\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See [LICENSE.txt](LICENSE.txt) for details.\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7c1yzknmhkmxasrtdbxa3fhd81z80k\",\n  \"slug\": \"skill-creator-flagos\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1774240407581\n}\n\nFile v1.0.0:references/schemas.md\n\n# JSON Schemas\n\nDefines the JSON schemas used by skill-creator for evaluation and testing.\n\n---\n\n## evals.json\n\nDefines test cases for a skill. Located at `evals/evals.json` within the skill directory.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"evals\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's example prompt\",\n      \"expected_output\": \"Description of expected result\",\n      \"files\": [\"evals/files/sample1.txt\"],\n      \"assertions\": [\n        \"The output includes X\",\n        \"Step Y was executed correctly\",\n        \"No errors were reported\"\n      ]\n    }\n  ]\n}\n```\n\n### Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `skill_name` | Yes | Must match the skill's frontmatter `name` |\n| `evals[].id` | Yes | Unique integer identifier |\n| `evals[].prompt` | Yes | The user prompt to test with |\n| `evals[].expected_output` | Yes | Human-readable description of success |\n| `evals[].files` | No | Input file paths relative to skill root |\n| `evals[].assertions` | No | List of verifiable statements to check |\n\n### Writing Good Test Prompts\n\n- Use realistic language a real user would actually say\n- Include both direct invocations (`/skill-name arg`) and natural language triggers\n- Cover happy paths, edge cases, and error scenarios\n- At least 2-3 test prompts per skill\n\n### Writing Good Assertions\n\n- Make assertions objectively verifiable (not subjective)\n- Use descriptive text that reads clearly in reports\n- Check both positive outcomes (\"file was created\") and negative (\"no error messages\")\n- Don't assert on implementation details — focus on user-visible outcomes\n\n---\n\n## eval_result.json\n\nOutput from running evaluations. Located at `evals/results/eval_result.json`.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"timestamp\": \"2026-03-15T10:30:00Z\",\n  \"results\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's example prompt\",\n      \"assertions\": [\n        {\n          \"text\": \"The output includes X\",\n          \"passed\": true,\n          \"evidence\": \"Found X in the generated output at line 15\"\n        },\n        {\n          \"text\": \"Step Y was executed correctly\",\n          \"passed\": false,\n          \"evidence\": \"Step Y was skipped due to missing dependency\"\n        }\n      ],\n      \"summary\": {\n        \"passed\": 1,\n        \"failed\": 1,\n        \"total\": 2,\n        \"pass_rate\": 0.5\n      }\n    }\n  ],\n  \"overall\": {\n    \"total_evals\": 1,\n    \"total_assertions\": 2,\n    \"total_passed\": 1,\n    \"overall_pass_rate\": 0.5\n  }\n}\n```\n\n---\n\n## validation_result.json\n\nOutput from the validation script. Located at `evals/results/validation_result.json`.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"skill_path\": \"/path/to/skills/example-skill\",\n  \"timestamp\": \"2026-03-15T10:30:00Z\",\n  \"valid\": true,\n  \"errors\": [],\n  \"warnings\": [\n    \"No README.md found (recommended)\",\n    \"Script scripts/helper.py lacks execute permission\"\n  ],\n  \"checks\": {\n    \"frontmatter\": \"pass\",\n    \"name_convention\": \"pass\",\n    \"description_quality\": \"pass\",\n    \"body_content\": \"pass\",\n    \"file_references\": \"pass\",\n    \"script_permissions\": \"warning\"\n  }\n}\n```\n\nFile v1.0.0:references/writing-guide.md\n\n# Skill Writing Guide\n\nDetailed patterns and best practices for writing effective skills in the FlagOS skills repository.\n\n## Table of Contents\n\n- [Anatomy of a Skill](#anatomy-of-a-skill)\n- [Progressive Disclosure](#progressive-disclosure)\n- [Writing the Description](#writing-the-description)\n- [Structuring the Body](#structuring-the-body)\n- [Writing Style](#writing-style)\n- [Scripts and References](#scripts-and-references)\n- [FlagOS-Specific Conventions](#flagos-specific-conventions)\n\n---\n\n## Anatomy of a Skill\n\n```\nskill-name/\n├── SKILL.md (required)\n│   ├── YAML frontmatter (name, description required)\n│   └── Markdown instructions\n├── LICENSE.txt (recommended, Apache 2.0)\n├── README.md (recommended, English)\n├── README_zh.md (optional, Chinese)\n└── Bundled Resources (optional)\n    ├── scripts/    - Executable code for deterministic/repetitive tasks\n    ├── references/ - Docs loaded into context as needed\n    └── assets/     - Files used in output (templates, icons, fonts)\n```\n\n### Required Fields\n\n| Field | Constraints | Description |\n|-------|-------------|-------------|\n| `name` | ≤64 chars, lowercase + hyphens, matches directory | Unique identifier |\n| `description` | ≤1024 chars | What the skill does AND when to trigger |\n\n### FlagOS Extension Fields\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `argument-hint` | CLI argument hint | `\"model_name [options]\"` |\n| `user-invokable` | Can be invoked via `/skill-name` | `true` |\n| `allowed-tools` | Fine-grained tool access control | `\"Bash(python3:*) Read Edit ...\"` |\n| `compatibility` | Environment requirements | `\"Python 3.8+, CUDA required\"` |\n| `metadata.version` | Skill version (semver) | `\"1.0.0\"` |\n| `metadata.author` | Author | `\"flagos-ai\"` |\n| `metadata.category` | Category | `\"workflow-automation\"` |\n| `metadata.tags` | Tag list | `[model-migration, vllm]` |\n\n---\n\n## Progressive Disclosure\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata** (name + description) — Always in context (~100 words)\n2. **SKILL.md body** — Loaded when skill triggers (<500 lines ideal)\n3. **Bundled resources** — Loaded as needed (unlimited; scripts can execute without loading)\n\n### Key Principles\n\n- **Keep SKILL.md under 500 lines.** If approaching this limit, split content into `references/` files with clear pointers about when to read them.\n- **Reference files must be documented in SKILL.md** with guidance on when to read them.\n- **For reference files >300 lines**, include a table of contents at the top.\n- **Avoid deeply nested references** — keep one level deep from SKILL.md.\n\n### Patterns\n\n**Pattern 1: Domain-specific organization**\n\nWhen a skill supports multiple domains/frameworks, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + selection)\n└── references/\n    ├── aws.md\n    ├── gcp.md\n    └── azure.md\n```\n\nThe agent reads only the relevant reference file.\n\n**Pattern 2: Workflow with reference catalog**\n\n```\nmodel-migrate-flagos/\n├── SKILL.md (overview + step index)\n└── references/\n    ├── procedure.md (detailed 13-step procedure)\n    ├── compatibility-patches.md (patch catalog)\n    └── operational-rules.md (operational constraints)\n```\n\nSKILL.md provides the overview; detailed content lives in references.\n\n**Pattern 3: Conditional details**\n\n```markdown\n## Basic usage\nSimple inline instructions here.\n\n**For advanced configuration**: See [advanced-config.md](references/advanced-config.md)\n**For troubleshooting**: See [troubleshooting.md](references/troubleshooting.md)\n```\n\n---\n\n## Writing the Description\n\nThe `description` field is the **primary triggering mechanism**. It determines when the agent activates the skill.\n\n### Rules\n\n1. **Include both WHAT and WHEN** — what the skill does and what contexts trigger it.\n2. **Be specific about triggers** — list user phrases, file types, or task patterns.\n3. **Be slightly \"pushy\"** — err on triggering too often rather than too rarely. The agent tends to under-trigger.\n4. **Include negative triggers** — explicitly say what NOT to use this skill for.\n5. **Keep under 1024 chars** — but use the full allowance if needed.\n\n### Good Example\n\n```yaml\ndescription: >\n  Migrate a model from the latest vLLM upstream repository into the vllm-plugin-FL project\n  (pinned at vLLM v0.13.0). Use this skill whenever someone wants to add support for a new\n  model to vllm-plugin-FL, port model code from upstream vLLM, or backport a newly released\n  model. Trigger when the user says things like \"migrate X model\", \"add X model support\",\n  \"port X from upstream vLLM\". Do NOT use for models already supported by vLLM 0.13.0 core.\n```\n\n### Bad Example\n\n```yaml\ndescription: Helps with model migration.\n```\n\nToo vague — the agent won't know when to trigger.\n\n---\n\n## Structuring the Body\n\n### Required Sections\n\nEvery SKILL.md body should include:\n\n1. **Overview** — what problem this solves, when to activate, expected inputs/outputs\n2. **Prerequisites** (if any) — environment requirements, tools, access\n3. **Execution steps** — numbered steps with progress reporting\n4. **Examples** — at least 2-3 realistic usage examples\n5. **Troubleshooting** — common problems and fixes\n\n### Execution Steps Pattern\n\nUse numbered steps with `**-> Tell user**` markers for progress reporting:\n\n```markdown\n### Step 1: Parse arguments\n\nExtract from user input:\n- `{{model_name}}` = first argument (required)\n- `{{options}}` = remaining arguments\n\n**-> Tell user**: Confirm parsed values.\n\n### Step 2: Execute workflow\n\nDo the actual work here.\n\n```bash\ncommand --example\n```\n\n**-> Tell user**: Report progress.\n\n### Step 3: Verify\n\n```bash\nverification_command\n```\n\n**-> Tell user**: Report results. On failure, diagnose and fix.\n```\n\n### Examples Pattern\n\n```markdown\n## Examples\n\n**Example 1: Typical usage**\n```\nUser says: \"/skill-name argument\"\nActions:\n  1. Parse input\n  2. Execute workflow\n  3. Verify result\nResult: Description of expected outcome\n```\n\n**Example 2: Edge case**\n```\nUser says: \"alternative trigger phrase\"\nActions:\n  1. Handle the edge case\n  2. Adapt workflow accordingly\nResult: Description of expected outcome\n```\n```\n\n### Troubleshooting Pattern\n\nUse a table for common issues:\n\n```markdown\n## Troubleshooting\n\n| Problem | Cause | Fix |\n|---|---|---|\n| Common error 1 | Typical cause | How to fix |\n| Common error 2 | Typical cause | How to fix |\n```\n\n---\n\n## Writing Style\n\n### General Principles\n\n- **Use imperative form** for instructions (\"Run the script\", not \"You should run the script\").\n- **Explain WHY, not just WHAT** — help the agent understand the reasoning so it can adapt.\n- **Be concise** — the context window is a shared resource. Only add information the agent doesn't already have.\n- **Prefer examples over explanations** — a concrete example communicates faster than an abstract description.\n- **Don't over-constrain** — use MUSTs sparingly. Give the agent enough freedom to adapt to unexpected situations.\n\n### What NOT to Include\n\n- Information the agent already knows (common programming patterns, standard library usage)\n- Redundant explanations of well-known tools\n- Overly detailed error messages for obvious failures\n- Commentary about the skill creation process itself\n\n### Conciseness Checklist\n\nFor each paragraph, ask:\n- Does the agent really need this explanation?\n- Does this paragraph justify its token cost?\n- Could this be replaced by a short example?\n- Is this duplicated elsewhere in the skill or references?\n\n---\n\n## Scripts and References\n\n### When to Use Scripts\n\nUse `scripts/` when:\n- The same code would be rewritten repeatedly\n- Deterministic reliability is needed (validation, data processing)\n- Complex operations need to be reproducible\n\nScripts can be executed without loading into context, saving tokens.\n\n### When to Use References\n\nUse `references/` when:\n- Detailed documentation needs to be available but not always in context\n- Multiple variants/domains need separate detailed guides\n- Content exceeds what fits comfortably in SKILL.md\n\n### Documentation Requirements\n\nEvery script and reference file must be documented in SKILL.md:\n\n```markdown\n## Scripts Reference\n\n| Script | Step | Description |\n|---|---|---|\n| `validate_migration.py` | 6 | Automated import/API/registration checks |\n| `benchmark.sh` | 9 | `vllm bench throughput` with dummy weights |\n```\n\n---\n\n## FlagOS-Specific Conventions\n\n### Naming\n\n- Directory names: lowercase + hyphens (`model-migrate-flagos`, `preflight-check`)\n- Script filenames: lowercase + underscores (`validate_migration.py`)\n- Reference docs: lowercase + hyphens (`compatibility-patches.md`)\n- FlagOS skills use functional prefixes describing the action\n\n### Categories\n\n| Category | Description | Example |\n|---|---|---|\n| `workflow-automation` | Multi-step workflows | model-migrate-flagos |\n| `deployment-verification` | Deployment & environment validation | preflight-check |\n| `build-tooling` | Build & release tools | build-vendor-image |\n| `code-standard` | Coding standards & review | — |\n| `operations` | Operational tasks | — |\n| `developer-tooling` | Developer productivity tools | skill-creator-flagos |\n\n### Bilingual Support\n\nFlagOS skills should provide:\n- `README.md` — English documentation\n- `README_zh.md` — Chinese documentation (recommended)\n\nBoth READMEs follow the same structure but are written independently (not machine-translated).\n\n### License\n\n- Default: Apache License 2.0\n- Place `LICENSE.txt` in each skill directory\n- Third-party dependencies must be noted in SKILL.md with source and license information\n\nFile v1.0.0:README_zh.md\n\n# skill-creator-flagos：技能开发工具链\n\n## 概述\n\n`skill-creator-flagos` 是一个元技能（meta-skill），用于在 FlagOS skills 仓库中创建、改进和验证其他技能。\n\n### 解决的问题\n\n编写高质量的 skill 涉及大量细节：YAML frontmatter 格式、触发优化的 description、渐进式披露结构、文件组织规范、双语文档等。手动检查这些要求既繁琐又容易遗漏，新贡献者往往要到 review 阶段才发现问题。\n\n本技能自动化了整个技能开发生命周期：**从模板脚手架 → 按规范编写 → 验证约定 → 用测试用例迭代**，提供 4 种工作模式，每个阶段都有配套工具。\n\n### 使用方式\n\n```bash\n# 交互模式 — 询问你想做什么\n/skill-creator-flagos\n\n# 创建新 skill 脚手架\n/skill-creator-flagos preflight-check --init\n\n# 创建时指定资源目录\n/skill-creator-flagos preflight-check --init --resources scripts,references\n\n# 验证单个 skill\n/skill-creator-flagos model-migrate-flagos --validate\n\n# 验证所有 skill\n/skill-creator-flagos --validate\n\n# 改进现有 skill\n/skill-creator-flagos model-migrate-flagos\n\n# 运行测试用例\n/skill-creator-flagos model-migrate-flagos --eval\n```\n\n| 参数 | 必填 | 默认值 | 说明 |\n|---|---|---|---|\n| `skill-name` | 否 | — | hyphen-case 格式的技能名（如 `preflight-check`） |\n| `--init` | 否 | — | 创建新 skill 目录脚手架 |\n| `--validate` | 否 | — | 验证 skill 结构和规范 |\n| `--eval` | 否 | — | 对 skill 运行测试用例 |\n| `--resources` | 否 | — | 逗号分隔的资源目录：`scripts,references,assets` |\n\n不带任何 flag 时进入交互模式。\n\n---\n\n## 四种工作模式\n\n### 模式一：创建 — 从零构建新 Skill\n\n```\n意图捕获 → 访谈 → 脚手架 → 编写 SKILL.md → 添加资源 → 验证 → 写 README\n```\n\n**执行过程：**\n\n1. **意图捕获** — Agent 访谈你：这个 skill 做什么、什么时候触发、需要什么工具、产出什么。如果当前对话已经包含你想封装的工作流，Agent 会先从上下文提取信息。\n\n2. **脚手架** — 运行 `init_skill.py` 生成目录结构：\n   ```\n   my-skill/\n   ├── SKILL.md        # 带 [TODO] 占位符的模板\n   ├── LICENSE.txt      # Apache 2.0\n   ├── scripts/         # （按需）\n   ├── references/      # （按需）\n   └── assets/          # （按需）\n   ```\n\n3. **编写 SKILL.md** — 按照 `references/writing-guide.md` 中的规范填充 frontmatter 和 body：\n   - Description 优化触发（具体短语、适度\"激进\"）\n   - Body 包含所有必要章节（Overview、Steps、Examples、Troubleshooting）\n   - 渐进式披露（详细内容放 `references/`，不让 SKILL.md 膨胀）\n\n4. **添加资源** — 按需创建脚本、参考文档和资源文件，每个文件都在 SKILL.md 中记录用法。\n\n5. **验证 & README** — 运行验证器修复问题，编写中英文 README。\n\n**示例会话：**\n\n```\n你：   /skill-creator-flagos preflight-check --init\nAgent: preflight-check 应该做什么？什么时候触发？\n你：   在运行 vLLM 前检查 GPU 可用性、驱动版本和 Python 环境\nAgent: 明白了。我会创建 skill 并包含 scripts/ 目录来放检查脚本……\n       [创建目录、编写 SKILL.md、添加 scripts/check_gpu.sh、验证]\n       Skill 'preflight-check' 已创建，最终结构如下：……\n```\n\n### 模式二：改进 — 迭代优化现有 Skill\n\n**执行过程：**\n\n1. **分析** — 读取现有 SKILL.md 和所有支撑文件，识别问题：\n   - Description 中触发条件模糊或缺失\n   - 缺少示例或边界情况\n   - 步骤没有进度汇报\n   - SKILL.md 过长需要拆分\n   - Troubleshooting 条目缺失\n\n2. **设计测试用例** — 创建 2-3 个真实的测试 prompt，保存到 `evals/evals.json`。\n\n3. **迭代** — 应用改进 → 重新验证 → 对照测试用例审查 → 收集反馈 → 重复。\n\n**示例会话：**\n\n```\n你：   /skill-creator-flagos model-migrate-flagos\nAgent: 分析了 model-migrate-flagos，发现 3 个可改进项：\n       1. Description 可以更有利于触发\n       2. 缺少多模态模型迁移的示例\n       3. Troubleshooting 表没有覆盖网络超时\n       先处理哪个？\n```\n\n### 模式三：验证 — 检查规范合规性\n\n**执行过程：**\n\n运行仓库级脚本 `scripts/validate_skills.py`，检查项：\n\n| 检查项 | 级别 | 说明 |\n|---|---|---|\n| SKILL.md 存在 | Error | 必须有入口文件 |\n| YAML frontmatter 合法 | Error | 必须以 `---` 开头和结尾 |\n| `name` 字段存在 | Error | 必填字段 |\n| `description` 字段存在 | Error | 必填字段 |\n| name 与目录名一致 | Error | `name` 字段必须等于文件夹名 |\n| name 格式合规 | Error | 仅小写字母 + 数字 + 连字符，最长 64 字符 |\n| description 长度 | Error | 不超过 1024 字符 |\n| body 内容充实 | Error | 至少 100 字符 |\n| 引用文件存在 | Error | 所有 markdown 链接指向的文件必须实际存在 |\n| 有 Examples 章节 | Warning | 建议所有 skill 都包含 |\n| 有 Troubleshooting 章节 | Warning | 建议所有 skill 都包含 |\n| 脚本有执行权限 | Warning | `.py` 和 `.sh` 文件应有 `+x` 权限 |\n| LICENSE.txt 存在 | Warning | 建议每个 skill 包含 |\n| README.md 存在 | Warning | 建议包含文档 |\n\n**输出示例：**\n\n```\n============================================================\n  model-migrate-flagos: PASS\n============================================================\n    ✓ All checks passed\n\n============================================================\n  skill-creator-flagos: PASS\n============================================================\n  Warnings (1):\n    ⚠ No README.md found (recommended)\n\n────────────────────────────────────────────────────────────\n  Summary: 2 skill(s), 0 error(s), 1 warning(s)\n────────────────────────────────────────────────────────────\n```\n\n### 模式四：评估 — 运行测试用例\n\n**执行过程：**\n\n如果 skill 目录中存在 `evals/evals.json`，Agent 会运行每个测试 prompt 并检查断言，生成通过/失败报告。\n\n---\n\n## 目录结构\n\n```\nskills/skill-creator-flagos/\n├── SKILL.md                          # 技能定义（入口文件）\n├── LICENSE.txt                       # Apache 2.0 许可证\n├── README.md                         # 英文文档\n├── README_zh.md                      # 本文档（中文版）\n├── references/                       # 参考文档\n│   ├── writing-guide.md              # 详细的技能编写规范和最佳实践\n│   └── schemas.md                    # 评估和验证的 JSON schema\n└── scripts/                          # 可执行脚本\n    └── init_skill.py                 # 创建新 skill 目录脚手架\n```\n\n---\n\n## 各文件说明\n\n### 技能定义\n\n#### `SKILL.md`\n\n技能的入口文件。定义了触发条件、参数格式、四种工作模式（创建、改进、验证、评估）、占位符解析、使用示例和常见问题排查。AI 编程助手根据此文件识别和调用技能。\n\n### 参考文档（`references/`）\n\n#### `writing-guide.md` — 技能编写规范\n\n全面的编写指南，涵盖：\n\n- **Skill 结构解剖** — 必填字段、FlagOS 扩展字段、目录约定\n- **渐进式披露** — 三级加载系统（metadata → body → references）、何时以及如何拆分内容\n- **Description 编写** — 如何写出触发优化的描述（具体短语 + 反向触发条件）\n- **Body 结构** — 必要章节模板（Overview、Prerequisites、Steps、Examples、Troubleshooting）\n- **写作风格** — 祈使句、解释 why 而非堆 MUST、简洁优先\n- **Scripts 和 References 用法** — 何时使用、文档化要求\n- **FlagOS 特有约定** — 命名规范、分类体系、双语支持、许可证\n\n#### `schemas.md` — JSON Schema 定义\n\n定义评估和验证使用的 JSON 格式：\n\n| Schema | 位置 | 用途 |\n|---|---|---|\n| `evals.json` | `evals/evals.json` | 测试用例定义（prompt + 断言） |\n| `eval_result.json` | `evals/results/eval_result.json` | 评估结果（每个断言的通过/失败状态） |\n| `validation_result.json` | `evals/results/validation_result.json` | 结构化验证输出 |\n\n### 脚本（`scripts/`）\n\n#### `init_skill.py` — 创建新 Skill 脚手架\n\n```bash\n# 基本用法\npython3 init_skill.py my-skill --path skills/\n\n# 带资源目录\npython3 init_skill.py my-skill --path skills/ --resources scripts,references,assets\n\n# 名称自动标准化\npython3 init_skill.py \"My Cool Skill\" --path skills/\n# → 创建 skills/my-cool-skill/\n```\n\n**生成的文件：**\n\n| 文件 | 必定生成 | 说明 |\n|---|---|---|\n| `SKILL.md` | 是 | 带所有 frontmatter 字段和 `[TODO]` body 占位符的模板 |\n| `LICENSE.txt` | 是 | Apache 2.0 许可证 |\n| `scripts/` | 按需 | 空目录 + `.gitkeep` |\n| `references/` | 按需 | 空目录 + `.gitkeep` |\n| `assets/` | 按需 | 空目录 + `.gitkeep` |\n\n**执行的校验：**\n- 名称 2-64 字符，仅允许小写字母 + 数字 + 连字符\n- 父目录必须存在\n- 目标目录不能已存在\n- 资源类型必须是 `scripts`、`references`、`assets` 之一\n\n### 仓库级验证脚本（`scripts/validate_skills.py`）\n\n验证由仓库级脚本 `scripts/validate_skills.py` 统一处理（不在 skill-creator-flagos 内部重复，避免逻辑分散）。支持单个和批量验证：\n\n```bash\n# 验证所有 skill（默认）\npython3 scripts/validate_skills.py\n\n# 验证单个 skill\npython3 scripts/validate_skills.py skills/model-migrate-flagos\n\n# 验证目录下所有 skill\npython3 scripts/validate_skills.py skills/ --all\n```\n\n执行 14 项检查，分 error 和 warning 两个级别。退出码：0 = 通过，1 = 有错误。\n\n---\n\n## 在 FlagOS Skills 仓库中使用\n\n### 快速安装（通过 npx）\n\n```bash\n# 仅安装本 skill\nnpx skills add flagos-ai/skills --skill skill-creator-flagos -a claude-code\n\n# 或一次性安装所有 Flagos skills\nnpx skills add flagos-ai/skills -a claude-code\n```\n\n### 手动安装\n\n```bash\n# 在你的项目根目录执行\nmkdir -p .claude/skills\ncp -r <本仓库路径>/skills/skill-creator-flagos .claude/skills/\n```\n\n### 独立使用脚本\n\n脚本可以脱离 skill 调用，独立使用：\n\n```bash\n# 在任意位置创建新 skill 脚手架\npython3 skills/skill-creator-flagos/scripts/init_skill.py my-skill --path ./my-project/skills/\n\n# 验证 skills（仓库级脚本）\npython3 scripts/validate_skills.py\npython3 scripts/validate_skills.py skills/my-skill\n```\n\n---\n\n## 许可证\n\nThis project is licensed under the Apache 2.0 License. See [LICENSE.txt](LICENSE.txt) for details.\n\nFile v1.0.0:LICENSE.txt\n\nApache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to the Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by the Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding any notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"[]\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. Please also get an\n      OpenPGP-compatible signature of your completed statement.\n\n   Copyright 2026 BAAI (Beijing Academy of Artificial Intelligence)\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.","readmeExcerpt":"Skill: Skill Creator Flagos Owner: wbavon Summary: Create new skills, modify existing skills, and validate skill quality for the FlagOS skills repository. Use this skill whenever someone wants to create a ski... Tags: latest:1.1.0 Version history: v1.1.0 | 2026-05-19T07:04:37.931Z | user Sync from flagos-ai/skills latest v1.0.0 | 2026-03-23T04:33:27.581Z | auto skill-creator-flagos v1.0.0 - Initial release providing ","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"/skill-creator-flagos                       # Interactive — asks what you want to do\n/skill-creator-flagosmy-new-skill --init    # Scaffold a new skill\n/skill-creator-flagosmy-skill --validate    # Validate an existing skill\n/skill-creator-flagosmy-skill --eval        # Run test prompts against a skill"},{"language":"bash","snippet":"python3 {{skill_root}}/scripts/init_skill.py {{skill_name}} --path {{skills_dir}} [--resources scripts,references,assets]"},{"language":"bash","snippet":"python3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}"},{"language":"json","snippet":"{\n  \"skill_name\": \"{{skill_name}}\",\n  \"evals\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's task prompt\",\n      \"expected_output\": \"Description of expected result\",\n      \"assertions\": [\"The output includes X\", \"Step Y was executed\"]\n    }\n  ]\n}"},{"language":"bash","snippet":"python3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}"},{"language":"bash","snippet":"python3 {{skill_root}}/scripts/run_eval.py {{skills_dir}}/{{skill_name}}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: skill-creator-flagos\ndescription: >\n  Create new skills, modify existing skills, and validate skill quality for the FlagOS skills\n  repository. Use this skill whenever someone wants to create a skill from scratch, improve or\n  edit an existing skill, scaffold a new skill directory, validate skill structure, or run test\n  cases against a skill. Trigger when the user says things like \"create a skill\", \"make a new\n  skill for X\", \"scaffold a skill\", \"improve this skill\", \"validate my skill\", or simply\n  \"/skill-creator-flagos\". Also trigger when users mention turning a workflow into a reusable skill,\n  or want to package a repeated process as a skill.\nargument-hint: \"[skill-name] [--init | --validate | --eval]\"\nuser-invokable: true\ncompatibility: \"Python 3.8+, works with any AI coding assistant that supports the Agent Skills standard\"\nmetadata:\n  version: \"1.0.0\"\n  author: flagos-ai\n  category: workflow-automation\n  tags: [skill-creation, scaffolding, validation, meta-skill, developer-tooling]\nallowed-tools: \"Bash(python3:*) Bash(python:*) Bash(chmod:*) Bash(mkdir:*) Bash(cp:*) Bash(ls:*) Bash(cat:*) Read Edit Write Glob Grep AskUserQuestion TaskCreate TaskUpdate TaskList TaskGet Agent\"\n---\n\n# Skill Creator\n\nA meta-skill for creating, improving, and validating skills in the FlagOS skills repository.\n\n## Overview\n\nThis skill guides you through the full lifecycle of skill development:\n1. **Create** — scaffold a new skill from template, interview the user, write SKILL.md\n2. **Improve** — analyze an existing skill, identify weaknesses, iterate with test cases\n3. **Validate** — check structure, frontmatter, references, and conventions compliance\n\n## Usage\n\n```\n/skill-creator-flagos                       # Interactive — asks what you want to do\n/skill-creator-flagosmy-new-skill --init    # Scaffold a new skill\n/skill-creator-flagosmy-skill --validate    # Validate an existing skill\n/skill-creator-flagosmy-skill --eval        # Run test prompts against a skill\n```\n\n## Execution\n\n### Step 0: Parse arguments and determine mode\n\nExtract from user input:\n- `{{skill_name}}` — optional skill name (hyphen-case)\n- `{{mode}}` — one of: `create`, `improve`, `validate`, `eval`, or `interactive` (default)\n\nIf no mode is specified, ask the user:\n\n> What would you like to do?\n> 1. Create a new skill from scratch\n> 2. Improve an existing skill\n> 3. Validate a skill's structure and conventions\n> 4. Run test cases against a skill\n\n**-> Tell user**: Confirm the mode and skill name.\n\n---\n\n## Mode 1: Create a New Skill\n\n### Step 1: Capture intent\n\nStart by understanding what the user wants to build. If the current conversation already contains a workflow the user wants to capture (e.g., \"turn this into a skill\"), extract answers from the conversation history first.\n\nKey questions to clarify:\n1. What should this skill enable the agent to do?\n2. When should this skill trigger? (user phrases, contexts, file types)\n3. What's the expected output or end state?\n4. Does the"},{"path":"README.md","content":"# skill-creator-flagos: Skill Development Toolkit\n\n[中文版](README_zh.md)\n\n## Overview\n\n`skill-creator-flagos` is a meta-skill for creating, improving, and validating skills in the FlagOS skills repository.\n\n### Problem Statement\n\nWriting a high-quality skill involves many details: YAML frontmatter conventions, trigger-optimized descriptions, progressive disclosure structure, proper file organization, bilingual documentation, and more. Manually checking all these requirements is tedious and error-prone, and new contributors often miss conventions that only become apparent after review.\n\nThis skill automates the entire skill development lifecycle: **scaffold from template -> write with guided patterns -> validate conventions -> iterate with test cases**, spanning 4 operational modes with built-in tooling for each stage.\n\n### Usage\n\n```bash\n# Interactive — asks what you want to do\n/skill-creator-flagos\n\n# Scaffold a new skill\n/skill-creator-flagos preflight-check --init\n\n# Scaffold with specific resource directories\n/skill-creator-flagos preflight-check --init --resources scripts,references\n\n# Validate a single skill\n/skill-creator-flagos model-migrate-flagos --validate\n\n# Validate all skills\n/skill-creator-flagos --validate\n\n# Improve an existing skill\n/skill-creator-flagos model-migrate-flagos\n\n# Run test cases against a skill\n/skill-creator-flagos model-migrate-flagos --eval\n```\n\n| Argument | Required | Default | Description |\n|---|---|---|---|\n| `skill-name` | No | — | Skill name in hyphen-case (e.g. `preflight-check`) |\n| `--init` | No | — | Scaffold a new skill directory |\n| `--validate` | No | — | Validate skill structure and conventions |\n| `--eval` | No | — | Run test cases against the skill |\n| `--resources` | No | — | Comma-separated resource dirs: `scripts,references,assets` |\n\nWhen no flag is provided, the skill enters interactive mode and asks what you'd like to do.\n\n---\n\n## Four Operational Modes\n\n### Mode 1: Create — Build a New Skill from Scratch\n\n```\nIntent capture → Interview → Scaffold → Write SKILL.md → Add resources → Validate → Write README\n```\n\n**What happens:**\n\n1. **Intent capture** — The agent interviews you about what the skill should do, when it should trigger, what tools it needs, and what outputs it produces. If the current conversation already contains a workflow you want to capture, the agent extracts answers from context first.\n\n2. **Scaffold** — Runs `init_skill.py` to generate the directory structure:\n   ```\n   my-skill/\n   ├── SKILL.md        # Template with [TODO] placeholders\n   ├── LICENSE.txt      # Apache 2.0\n   ├── scripts/         # (if requested)\n   ├── references/      # (if requested)\n   └── assets/          # (if requested)\n   ```\n\n3. **Write SKILL.md** — Fills in the frontmatter and body following the patterns in `references/writing-guide.md`. The agent ensures:\n   - Description is trigger-optimized (specific phrases, slightly \"pushy\")\n   - Body includes all required sections (Overview, Steps, Examples,"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7c1yzknmhkmxasrtdbxa3fhd81z80k\",\n  \"slug\": \"skill-creator-flagos\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1779174277931\n}"},{"path":"references/schemas.md","content":"# JSON Schemas\n\nDefines the JSON schemas used by skill-creator for evaluation and testing.\n\n---\n\n## evals.json\n\nDefines test cases for a skill. Located at `evals/evals.json` within the skill directory.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"evals\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's example prompt\",\n      \"expected_output\": \"Description of expected result\",\n      \"files\": [\"evals/files/sample1.txt\"],\n      \"assertions\": [\n        \"The output includes X\",\n        \"Step Y was executed correctly\",\n        \"No errors were reported\"\n      ]\n    }\n  ]\n}\n```\n\n### Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `skill_name` | Yes | Must match the skill's frontmatter `name` |\n| `evals[].id` | Yes | Unique integer identifier |\n| `evals[].prompt` | Yes | The user prompt to test with |\n| `evals[].expected_output` | Yes | Human-readable description of success |\n| `evals[].files` | No | Input file paths relative to skill root |\n| `evals[].assertions` | No | List of verifiable statements to check |\n\n### Writing Good Test Prompts\n\n- Use realistic language a real user would actually say\n- Include both direct invocations (`/skill-name arg`) and natural language triggers\n- Cover happy paths, edge cases, and error scenarios\n- At least 2-3 test prompts per skill\n\n### Writing Good Assertions\n\n- Make assertions objectively verifiable (not subjective)\n- Use descriptive text that reads clearly in reports\n- Check both positive outcomes (\"file was created\") and negative (\"no error messages\")\n- Don't assert on implementation details — focus on user-visible outcomes\n\n---\n\n## eval_result.json\n\nOutput from running evaluations. Located at `evals/results/eval_result.json`.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"timestamp\": \"2026-03-15T10:30:00Z\",\n  \"results\": [\n    {\n      \"id\": 1,\n      \"prompt\": \"User's example prompt\",\n      \"assertions\": [\n        {\n          \"text\": \"The output includes X\",\n          \"passed\": true,\n          \"evidence\": \"Found X in the generated output at line 15\"\n        },\n        {\n          \"text\": \"Step Y was executed correctly\",\n          \"passed\": false,\n          \"evidence\": \"Step Y was skipped due to missing dependency\"\n        }\n      ],\n      \"summary\": {\n        \"passed\": 1,\n        \"failed\": 1,\n        \"total\": 2,\n        \"pass_rate\": 0.5\n      }\n    }\n  ],\n  \"overall\": {\n    \"total_evals\": 1,\n    \"total_assertions\": 2,\n    \"total_passed\": 1,\n    \"overall_pass_rate\": 0.5\n  }\n}\n```\n\n---\n\n## validation_result.json\n\nOutput from the validation script. Located at `evals/results/validation_result.json`.\n\n```json\n{\n  \"skill_name\": \"example-skill\",\n  \"skill_path\": \"/path/to/skills/example-skill\",\n  \"timestamp\": \"2026-03-15T10:30:00Z\",\n  \"valid\": true,\n  \"errors\": [],\n  \"warnings\": [\n    \"No README.md found (recommended)\",\n    \"Script scripts/helper.py lacks execute permission\"\n  ],\n  \"checks\": {\n    \"frontmatter\": \"pass\",\n    \"name_convention\": \"pass\",\n    \"description_quality\": \"pass\",\n    \""},{"path":"references/writing-guide.md","content":"# Skill Writing Guide\n\nDetailed patterns and best practices for writing effective skills in the FlagOS skills repository.\n\n## Table of Contents\n\n- [Anatomy of a Skill](#anatomy-of-a-skill)\n- [Progressive Disclosure](#progressive-disclosure)\n- [Writing the Description](#writing-the-description)\n- [Structuring the Body](#structuring-the-body)\n- [Writing Style](#writing-style)\n- [Scripts and References](#scripts-and-references)\n- [FlagOS-Specific Conventions](#flagos-specific-conventions)\n\n---\n\n## Anatomy of a Skill\n\n```\nskill-name/\n├── SKILL.md (required)\n│   ├── YAML frontmatter (name, description required)\n│   └── Markdown instructions\n├── LICENSE.txt (recommended, Apache 2.0)\n├── README.md (recommended, English)\n├── README_zh.md (optional, Chinese)\n└── Bundled Resources (optional)\n    ├── scripts/    - Executable code for deterministic/repetitive tasks\n    ├── references/ - Docs loaded into context as needed\n    └── assets/     - Files used in output (templates, icons, fonts)\n```\n\n### Required Fields\n\n| Field | Constraints | Description |\n|-------|-------------|-------------|\n| `name` | ≤64 chars, lowercase + hyphens, matches directory | Unique identifier |\n| `description` | ≤1024 chars | What the skill does AND when to trigger |\n\n### FlagOS Extension Fields\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `argument-hint` | CLI argument hint | `\"model_name [options]\"` |\n| `user-invokable` | Can be invoked via `/skill-name` | `true` |\n| `allowed-tools` | Fine-grained tool access control | `\"Bash(python3:*) Read Edit ...\"` |\n| `compatibility` | Environment requirements | `\"Python 3.8+, CUDA required\"` |\n| `metadata.version` | Skill version (semver) | `\"1.0.0\"` |\n| `metadata.author` | Author | `\"flagos-ai\"` |\n| `metadata.category` | Category | `\"workflow-automation\"` |\n| `metadata.tags` | Tag list | `[model-migration, vllm]` |\n\n---\n\n## Progressive Disclosure\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata** (name + description) — Always in context (~100 words)\n2. **SKILL.md body** — Loaded when skill triggers (<500 lines ideal)\n3. **Bundled resources** — Loaded as needed (unlimited; scripts can execute without loading)\n\n### Key Principles\n\n- **Keep SKILL.md under 500 lines.** If approaching this limit, split content into `references/` files with clear pointers about when to read them.\n- **Reference files must be documented in SKILL.md** with guidance on when to read them.\n- **For reference files >300 lines**, include a table of contents at the top.\n- **Avoid deeply nested references** — keep one level deep from SKILL.md.\n\n### Patterns\n\n**Pattern 1: Domain-specific organization**\n\nWhen a skill supports multiple domains/frameworks, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + selection)\n└── references/\n    ├── aws.md\n    ├── gcp.md\n    └── azure.md\n```\n\nThe agent reads only the relevant reference file.\n\n**Pattern 2: Workflow with reference catalog**\n\n```\nmodel-migrate-fl"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Create new skills, modify existing skills, and validate skill quality for the FlagOS skills repository. Use this skill whenever someone wants to create a ski... Skill: Skill Creator Flagos Owner: wbavon Summary: Create new skills, modify existing skills, and validate skill quality for the FlagOS skills repository. Use this skill whenever someone wants to create a ski... Tags: latest:1.1.0 Version history: v1.1.0 | 2026-05-19T07:04:37.931Z | user Sync from flagos-ai/skills latest v1.0.0 | 2026-03-23T04:33:27.581Z | auto skill-creator-flagos v1.0.0 - Initial release providing","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1369,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T15:25:12.898Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T15:25:12.898Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T17:43:26.826Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}