Company Skill Creator#

Create company-internal skills through an interactive interview process. This skill helps users turn their domain knowledge into reusable skills — even when they don't have formal documentation ready.

Core philosophy#

Company skills are different from general-purpose skills. They typically involve:

• Internal APIs that Claude can't know about from training data
• Business processes specific to the company
• Domain schemas (database tables, data models, config formats)
• Proprietary tools or internal services
• Team conventions and unwritten rules

The key insight: users often have this knowledge in their heads but haven't formalized it. The skill creator's job is to extract that knowledge interactively, fill in the gaps, and produce a well-structured skill.

---

The creation workflow#

At a high level, the process goes like this:

1. Interview — Understand what the skill needs to do, gather materials
2. Scaffold — Create the skill directory structure
3. Fill gaps — Auto-generate missing scripts, references, or templates
4. Write the skill — Compose SKILL.md based on everything gathered
5. Validate & package — Make sure it's correct, package the .skill file

Your job is to guide the user through each phase, being flexible about the order and knowing when to generate vs. when to ask.

---

Phase 1: Interactive interview#

Step 1.1: Understand the core task#

Start by asking the user a few essential questions. Don't bombard them all at once — ask, listen, then follow up naturally.

Must-ask questions:

1. What should this skill do? — Get a concrete example. "I want Claude to query our user database" is better than "data access skill."

2. When should it trigger? — What would a user say to invoke it? Collect 3-5 example phrases. Include both formal ("query the user database for...") and casual ("can you look up...") phrasings.

3. What's the output? — Code? A report? A file? An API call result? A Slack message?

4. Who will use this? — Is this for engineers, PMs, data analysts? This affects the tone and level of detail.

Step 1.2: Ask the user what materials they can provide#

This is the critical step that makes company skills different. Tell the user something like:

"To build a solid skill, I'll need a few things. You don't need all of these — just share whatever you have, and I'll generate the rest. Here's what helps most:"

Then ask about each category. Do not ask all at once — let the user respond to each before moving on.

Required materials (must have at least a verbal description):

CategoryWhat to ask forIf they don't have itRequirementsUser stories, spec docs, workflow diagrams, or just describe what the skill should do step by stepExtract from conversation and write up as structured requirementsAPI / InterfaceSwagger/OpenAPI specs, API docs URLs, curl examples, SDK documentation, or just endpoint names and parametersGenerate a stub reference doc based on their verbal description; mark guessed parts with ⚠️ 待确认 (to be confirmed)Data / SchemaDatabase schemas, table descriptions, field lists, sample queries, example data filesGenerate a schema reference from their description; note any guessed fieldsScriptsExisting scripts, utilities, helper tools the team already usesWrite the scripts from scratch based on requirementsReferencesLinks to internal docs, coding standards, business logic rules, known edge casesGenerate reference docs from the interview; flag sections that need SME reviewTemplatesReport templates, code scaffolds, configuration files, message formatsCreate templates from examples the user describes

How to phrase this to the user:

Frame it as a collaborative process. The user is the domain expert; Claude is the skill architect. The user provides the raw knowledge in whatever form they have it; Claude organizes and fills gaps.

Step 1.3: Collect materials#

For each category the user says they have materials for:

1. Ask them to share the content (paste text, provide file paths, share URLs)
2. Read any files they point to
3. If they give a URL to internal docs, try fetching it; if authentication fails, ask them to paste the relevant content
4. Take notes on what's provided

For each category they don't have materials for:

1. Ask clarifying questions to extract enough detail
2. Note what they said — you'll auto-generate this later
3. Confirm: "I'll generate a draft based on what you've described. You can review and correct it later."

Step 1.4: Confirm scope#

Before writing anything, summarize what you've gathered:

"Here's what I understand so far:

• Skill name: [proposed kebab-case name]
• Purpose: [one-line summary]
• Inputs: [what the user provides]
• Outputs: [what the skill produces]
• Materials provided: [list what the user gave you]
• To be generated: [list what you'll create from scratch]

Does this look right? Anything to add or change?"

---

Phase 2: Scaffold the skill#

Step 2.1: Create the directory structure#

Use the scripts/init_skill.py script to create the directory structure:

bash

python <path-to-company-skill-creator>/scripts/init_skill.py <skill-name> --path <output-directory>

This creates:

text

skill-name/
├── SKILL.md              (with frontmatter template)
├── scripts/
│   └── __init__.py
├── references/
└── assets/

Step 2.2: Generate missing components#

Based on what the user couldn't provide, generate the necessary files. Work in this priority order:

1. Scripts first — If the skill needs to interact with an API, format data, or automate a repetitive task, write the scripts now. Put them in scripts/. These should be:

• Well-tested with happy path and basic error handling
• Documented with brief usage comments
• Written in a language the user's team uses (ask if unsure)

2. References next — Create reference documents in references/:

• API reference docs (endpoints, parameters, auth, examples)
• Schema/docs references (tables, fields, relationships)
• Business logic rules
• Each file should have a table of contents if over 100 lines
• Mark unverified information with ⚠️ 待确认 so the user can review

3. Assets last — Templates, config files, boilerplate. Put in assets/.

Step 2.3: Flag what needs review#

For every generated file, decide the confidence level:

ConfidenceMarkingMeaningHighNo markBased on concrete user input, likely correctMedium⚠️ 待确认 on specific linesReasonable guess but user should verifyLow⚠️ 待确认 in file headerMostly inferred, user must review before use

Tell the user clearly which files need their review and which are ready to go.

---

Phase 3: Write SKILL.md#

Now compose the SKILL.md. This is the heart of the skill — follow the same patterns as skill-creator but tuned for company skills.

Frontmatter#

yaml

---
name: <kebab-case-name>
description: <what it does AND when to trigger. Include 3-5 concrete trigger examples. Make it slightly pushy — err on the side of triggering. Max 1024 chars.>
---

Description writing rules:

• Be specific about when to trigger — include phrases users would actually say
• For company skills, include context clues: team names, system names, jargon
• Keep it under 1024 characters
• No angle brackets
• Make it "pushy" — if in doubt, the skill should trigger

Body structure#

markdown

# <Skill Title>

## Overview
<1-2 sentences about what this skill does and why it exists.>

## Quick start
<The most common use case, with a concrete example.>

## Workflow
<Step-by-step instructions. Use imperative mood. Explain WHY, not just WHAT.>

## API / Tool reference
<Pointer to references/ files. Don't duplicate — just link.>

## Output format
<What the skill should produce. Use templates where helpful.>

## Edge cases & known issues
<Things the user mentioned during the interview.>

Key rules for company skills#

1. Explain the "why" — Company processes often have historical reasons. The skill should capture these so Claude understands context, not just rules.

2. Progressive disclosure is critical — Company skills often have large reference files (API docs, schemas). Keep SKILL.md lean; put details in references/ with clear pointers.

3. Don't duplicate information — If a schema is in references/schema.md, don't summarize it in SKILL.md. Just link to it.

4. Use the company's language — If the team says "workspace" not "project", use "workspace" throughout.

5. Scripts over instructions — If a task requires deterministic behavior (API calls, data transforms), provide a script rather than text instructions. Scripts don't consume context window when executed.

6. Mark uncertainty — If you're unsure about a business rule or API behavior, note it with ⚠️ 待确认.

---

Phase 4: Review with the user#

Step 4.1: Present the complete skill#

Walk the user through what was created:

1. SKILL.md — Read through the key sections together
2. Scripts — Explain what each script does and when it runs
3. References — Point out files that need SME review
4. Assets — Show any templates or scaffolds

Step 4.2: Collect feedback#

Ask targeted questions:

• "Does the trigger description match how you'd actually ask for this?"
• "Looking at the API reference, are there any endpoints or parameters I got wrong?"
• "Try describing a task to me — let's see if I'd invoke the right skill."

Step 4.3: Iterate#

Apply feedback immediately. If the user has substantial changes, make them and present again. If the changes are minor, note them and move on.

---

Phase 5: Validate & package#

Step 5.1: Validate#

Run the validation script:

bash

python <path-to-company-skill-creator>/scripts/quick_validate.py <path-to-skill>

Fix any issues it reports.

Step 5.2: Package#

bash

python <path-to-company-skill-creator>/scripts/package_skill.py <path-to-skill>

This produces a .skill file. Tell the user where it is and how to install it.

Step 5.3: Final checklist#

Present a summary to the user:

text

✅ Skill created: <skill-name>
📁 Location: <path>
📦 Package: <skill-name>.skill
⚠️  Needs review: <list of files with unconfirmed content>
📋 Next steps:
   1. Review files marked with ⚠️ 待确认
   2. Install the .skill file
   3. Test with a real task
   4. Come back to iterate if needed

---

Quick mode#

If the user is in a hurry or the skill is simple, you can compress the workflow:

1. Ask: "What should this skill do? Got any docs or scripts I should know about?"
2. Generate everything from their answer
3. Present for quick review
4. Package

Skip the formal interview steps. Trust your judgment on when to use quick mode vs. full interview.

---

Communication style#

Company skill creators work with people who may not be technical writers. Adjust your communication:

• Engineers: Use technical terms freely. Focus on correctness and efficiency.
• PMs / Analysts: Explain what you're doing in plain language. "I'm going to create a reference file that documents your API" rather than "I'll generate an OpenAPI stub."
• Mixed audiences: Default to the less technical audience's level.

Always be encouraging. Users often feel their materials aren't "good enough" — reassure them that verbal descriptions and rough notes are perfectly fine starting points.

---

Special cases#

The user has a complete spec#

If the user has a well-written specification document, API docs, and sample code:

1. Read everything they provide
2. Scaffold the skill
3. Generate SKILL.md from the spec (don't make them re-explain)
4. Present for confirmation — "Here's what I built based on your docs. Did I get it right?"
5. Minimal interview needed

The user has nothing but an idea#

If the user says "I want a skill for X" but has no materials:

1. Ask for a concrete example of what they'd want to do
2. Walk through what the skill would need step by step
3. Generate everything: scripts, references, templates
4. Be explicit about uncertainty — "I wrote this API client based on what you described. You'll need to fill in the actual endpoint URLs and auth method."
5. Iterate more — expect more rounds of feedback

The user wants to convert existing documentation#

If the user has internal wiki pages, READMEs, or runbooks they want turned into a skill:

1. Read all the docs
2. Identify the procedural knowledge (the "how to") vs. reference material (the "what is")
3. Structure the procedural knowledge as SKILL.md workflow instructions
4. Structure the reference material as references/ files
5. Remove anything Claude already knows (don't explain what REST is, etc.)

---

Reference files#

• agents/interviewer.md — Detailed interview prompts and question templates for different skill types (API skills, data skills, workflow skills, template skills)
• references/company-context.md — Template for capturing company-specific context (tech stack, team structure, common workflows)

---

Bundled scripts#

• scripts/init_skill.py — Scaffold a new skill directory with the standard structure
• scripts/quick_validate.py — Validate SKILL.md frontmatter format
• scripts/package_skill.py — Package a skill folder into a .skill file

---

That's it. The most important thing: extract what the user knows, generate what they don't have, and always flag what needs review. A company skill with a few ⚠️ 待确认 marks is far more useful than no skill at all.