
fx-meta
- GitHub stars
- 10
Install
/plugin install fx-meta@fx-ccRun it inside Claude Code after adding the marketplace with /plugin marketplace add fx/cc.
Contents
Discovered from sourceSkills 3
Learn
This skill updates fx-cc marketplace plugins based on learnings from the current conversation. It modifies skill definitions to prevent future mistakes or improve behavior.
Step 0: Find the tree that ACTUALLY provides the skill (MANDATORY)
⛔ Do not assume the fx-cc marketplace owns the skill you are correcting. It often does not, and editing the wrong copy produces a change that is committed, reviewed, and completely inert — the skill keeps misbehaving because the file that runs was never touched.
Skills reach a session from several independent trees, and they drift:
| Tree | Typical origin |
|---|---|
~/.claude/skills/<name>/ | Usually symlinks into another checkout — follow them |
~/.agents/skills/<name>/ | Installed from a separate skills repo; upstream is in ~/.agents/.skill-lock.json |
<marketplace>/plugins/<plugin>/skills/<name>/ | The fx-cc marketplace source |
~/.claude/plugins/cache/fx-cc/<plugin>/<version>/skills/<name>/ | The cache Claude loads plugin skills from — never edit; resolve it back to its marketplace checkout |
The invocation's own base directory is the strongest evidence. A skill's prompt states the directory it was loaded from; that path, resolved through any symlink, is the copy that ran. Prefer it over every inference. Otherwise:
find ~/.claude ~/.agents -name SKILL.md -path "*<skill-name>*" 2>/dev/null \
| while read -r f; do echo "$(md5sum "$f" | cut -c1-8) $f -> $(readlink -f "$f")"; done
jq -r '.skills["<skill-name>"].sourceUrl' ~/.agents/.skill-lock.json 2>/dev/null
Write down the resolved path. [TREE] below is a literal placeholder for it —
substitute the absolute path into every command, keeping the quotes shown so a path
containing whitespace survives. It is not a shell variable: the
shell does not persist between tool calls, so an assignment in one command is gone
by the next, and every later cd would land somewhere unintended.
- If the authoritative tree is a different repository, that repo is where the fix belongs. Clone it (SSH — HTTPS may have no credential helper), edit there, and leave the change uncommitted for review exactly as Step 6 requires. Do not silently redirect the fix into fx-cc because fx-cc is the repo this skill knows.
- If several trees carry the same defect, fix the authoritative one first, then apply the same fix to the others — a stale divergent copy will be loaded by some session eventually.
⛔ If the copy that ran is under ~/.claude/plugins/cache/, do NOT edit it.
The cache is a build artifact — a versioned snapshot Claude Code copies out of a
marketplace checkout — so an edit there is overwritten on the next sync and never
reaches the repo. Map it back to its source before going further: a cache path
~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/skills/<skill>/ comes
from <marketplace checkout>/plugins/<plugin>/skills/<skill>/. Find that checkout
(~/.claude/plugins/marketplaces/<marketplace> is the usual location, but confirm
it — this repo is also cloned elsewhere), and use it as [TREE]. Step 4 then syncs
your change back into the cache.
Record which layout [TREE] has — the rest of this skill branches on it:
| Layout | Shape | Which steps apply |
|---|---|---|
| Marketplace (fx-cc) | plugins/<plugin>/skills/<skill>/SKILL.md, with .claude-plugin/ manifests and .githooks | Everything below, as written |
Flat catalog (e.g. a fx/skills-style repo) | skills/<skill>/SKILL.md, no plugin manifests | Prerequisites' hook/manifest steps, Step 4 (plugin-cache sync) and the version bumps do not apply — that repo has no plugin versions to bump and no fx-cc cache to sync. Follow that repo's own AGENTS.md/CONTRIBUTING, then go straight to Step 5 |
Substitute plugins/<plugin>/skills/<skill>/ for skills/<skill>/ throughout when
the tree is a flat catalog. Never apply the marketplace paths to a tree that does
not have that layout — the search finds nothing and the workflow stalls before it
reaches the file it came to fix.
Always tell the user which tree you edited and why. A learning applied to the wrong copy is worse than none: it reports success and changes nothing.
Prerequisites (marketplace layout only)
Skip this whole section when Step 0 resolved to a flat catalog; use that repo's own setup instructions instead. Otherwise, verify the marketplace is accessible:
cd "[TREE]" && git remote -v && git status
Verify the remote is accessible and the working directory is clean. If not accessible, inform the user and abort.
Read AGENTS.md and respect it
CRITICAL: Read AGENTS.md at the root of the marketplace repo ([TREE]/AGENTS.md) and follow every instruction it contains, especially the Required First-Time Setup section. AGENTS.md is authoritative — its rules apply to every operation this skill performs in the repo. (CLAUDE.md is just a @AGENTS.md import; REVIEW.md holds the review conventions.)
Wire up the pre-commit hook (idempotent)
Before any modification, ensure the version-bump pre-commit hook is active in this clone of the marketplace. Git does not let a repo configure its own hooks path, so each clone must opt in once:
cd "[TREE]"
# Check whether hooks are wired up; if not, wire them.
if [ "$(git config --get core.hooksPath || true)" != ".githooks" ]; then
git config core.hooksPath .githooks
echo "✓ Wired core.hooksPath → .githooks"
else
echo "✓ Hooks already wired"
fi
Run this at the very start of any learn invocation, not only when committing. It is idempotent and safe.
Never bypass the hook with --no-verify. If the hook rejects a future commit, read its message and bump the indicated plugin.json / marketplace.json versions per the rules in AGENTS.md.
Workflow
Step 1: Analyze the Learning Request
Examine the current conversation to understand:
- What went wrong - Identify the specific behavior that needs correction
- Root cause - Determine which skill caused the issue
- Desired behavior - Understand what should happen instead
Common scenarios:
- Explicitly invoked skill did not load → Verify its namespaced name, registration, and explicit-use description without adding semantic auto-trigger phrases
- Skill auto-loaded without being named → Add or repair the explicit-use boundary in its description and instructions
- Skill produced incorrect behavior → Add explicit prohibition to skill instructions
- Skill missed a step → Add the step to the skill's workflow
- Instruction was ambiguous → Clarify the wording
Step 2: Locate Relevant Files
Search the tree Step 0 resolved:
# Marketplace layout
find "[TREE]"/plugins -name "SKILL.md" -type f
# Flat catalog layout
find "[TREE]"/skills -name "SKILL.md" -type f
# Either: search for specific content
grep -rn "keyword" "[TREE]"
Key locations:
- Skills:
plugins/<plugin>/skills/<skill>/SKILL.md(marketplace) orskills/<skill>/SKILL.md(flat catalog)
Step 3: Make Targeted Modifications
Edit the relevant files to address the learning. Follow these principles:
- Be specific - Add concrete instructions, not vague guidance
- Use imperative form - Write "Do X" or "Never do Y", not "You should..."
- Add context - Explain why the rule exists if non-obvious
- Preserve structure - Maintain existing formatting and organization
For prohibitions, use clear language:
**CRITICAL:** Never do X because Y.
For required actions:
**IMPORTANT:** Always do X before Y.
Step 4: Sync to Plugin Cache (marketplace layout only)
Skip this step entirely for a flat catalog — it has no plugin versions and no fx-cc cache entry, so there is nothing to sync.
CRITICAL: Claude Code caches plugins separately from the marketplace source. After modifying files in the marketplace, sync changes to the cache so they take effect immediately.
Cache mapping:
- Source:
[TREE]/plugins/<plugin>/ - Cache:
~/.claude/plugins/cache/fx-cc/<plugin>/<version>/
To sync a modified plugin:
# Get the plugin version from its manifest
PLUGIN=fx-dev # or fx-meta, fx-research, etc.
VERSION=$(cat "[TREE]"/plugins/$PLUGIN/.claude-plugin/plugin.json | grep '"version"' | sed 's/.*: *"\([^"]*\)".*/\1/')
# Sync marketplace source to cache
rsync -av --delete \
"[TREE]"/plugins/$PLUGIN/ \
~/.claude/plugins/cache/fx-cc/$PLUGIN/$VERSION/
Sync every plugin that was modified. This ensures Claude loads the updated definitions immediately without requiring a restart.
Step 5: Verify Changes
After editing and syncing, show the diff to the user:
cd "[TREE]" && git diff
Step 6: Leave for Manual Review
CRITICAL: Do NOT commit the changes. Inform the user:
Changes have been made to the following files:
path/to/file1.mdpath/to/file2.mdReview the changes with
git diffin[TREE]. Commit manually when satisfied.
Examples
Example 1: Skill Skipped a Step
User says: "use /learn to update our sdlc skills - they should update PROJECT.md when creating PRs"
- Locate
plugins/fx-dev/skills/pr-preparer/SKILL.md - Add instruction to check PROJECT.md and update completed tasks
- Sync fx-dev plugin to cache
- Show diff, leave uncommitted
Example 2: Explicit Skill Invocation Failed
User says: "I explicitly ran /github, but the skill did not load"
- Locate
plugins/fx-dev/skills/github/SKILL.mdand its plugin registration - Verify the namespaced/slash name and explicit-use description are correct
- Do not add generic GitHub phrases as auto-trigger conditions
- Sync fx-dev plugin to cache
- Show diff, leave uncommitted
Example 3: Explicit Prohibition
User says: "/learn to never leave comments on PRs"
- Locate relevant skills (pr-preparer, resolve-pr-feedback, etc.)
- Add explicit prohibition with rationale
- Sync all modified plugins to cache
- Show diff, leave uncommitted
Plugin Creator
This skill provides guidance for creating high-quality plugins for the fx/cc Claude Code marketplace.
About fx/cc Plugins
Plugins are structured packages that extend Claude Code's capabilities by bundling related components:
- Skills - Explicitly invoked specialized knowledge and workflows; an active workflow may call internal skills by name
- Commands - Slash commands for specific operations
- Hooks - Event-driven workflow automation
Default Working Directory
All plugin development work defaults to: ~/.claude/plugins/marketplaces/fx-cc/
This is the local clone of the fx/cc marketplace repository where all plugins reside.
Plugin Creation Process
Step 1: Understanding the Plugin with Concrete Examples
To create an effective plugin, gather concrete examples of how it will be used:
Example questions to ask:
- "What functionality should this plugin provide?"
- "Can you give examples of tasks users would perform with this plugin?"
- "How will users explicitly invoke each skill or command, and which active workflows may call internal skills by name?"
- "Are these components typically used together or separately?"
Example for fx-git plugin:
- User: "Help me write better commit messages following our conventions"
- User: "Review this PR for code quality issues"
- User: "Resolve these merge conflicts"
Conclude when there's a clear understanding of:
- Plugin's domain and purpose
- Required components (skills, commands)
- Typical usage patterns
Step 2: Planning Plugin Structure
Analyze examples to determine:
1. Plugin Name
Follow fx/cc naming conventions (see references/fx-cc-guidelines.md):
- Use
fx-prefix - Kebab-case format
- Concise and descriptive
- Examples:
fx-git,fx-aws,fx-docs
2. Component Grouping
Decide whether to:
- Combine related components in one plugin (typically used together)
- Separate into multiple plugins (different domains or install preferences)
3. Required Components
Skills - When to include:
- Specialized knowledge users explicitly select
- Procedural workflows for specific tasks
- Internal roles an active, explicitly invoked workflow calls by name
- Complex multi-step operations that need bundled references or scripts
Commands - When to include:
- Explicit user-invoked operations
- Shortcuts for common workflows
- Integration with external tools/APIs
Hooks - When to include:
- Event-driven automation needs
- Pre/post-processing requirements
- Workflow customization
Step 3: Initialize Plugin Structure
Navigate to the fx/cc marketplace and create plugin directory:
cd ~/.claude/plugins/marketplaces/fx-cc/plugins
# Create plugin directory structure
mkdir -p fx-plugin-name/.claude-plugin
# Create plugin.json manifest
cat > fx-plugin-name/.claude-plugin/plugin.json <<'EOF'
{
"name": "fx-plugin-name",
"version": "0.1.0",
"description": "Clear description of what this plugin does"
}
EOF
# Create component directories as needed
cd fx-plugin-name
mkdir -p skills commands hooks
Directory structure:
~/.claude/plugins/marketplaces/fx-cc/plugins/fx-plugin-name/
├── .claude-plugin/
│ └── plugin.json
├── skills/ (if needed)
├── commands/ (if needed)
├── hooks/ (if needed)
└── README.md
Step 4: Implement Components
Skills
Create skill directories with SKILL.md:
mkdir -p skills/skill-name
cat > skills/skill-name/SKILL.md <<'EOF'
---
name: skill-name
description: When this skill should be used (third-person, specific)
---
# Skill Name
Instructions using imperative/infinitive form.
## Usage
How to use this skill and reference bundled resources.
EOF
See skill-creator skill for detailed skill development guidance.
Commands
Create command files (markdown or shell):
# Markdown command
cat > commands/command-name.md <<'EOF'
---
name: command-name
description: What this command does
---
Command implementation and documentation.
EOF
# Or shell script
cat > commands/command-name.sh <<'EOF'
#!/bin/bash
# Command implementation
EOF
chmod +x commands/command-name.sh
Hooks
Create hooks configuration:
cat > hooks/hooks.json <<'EOF'
{
"PreToolUse": {
"command": "bash -c 'echo \"Pre-tool hook\"'",
"timeout": 5000
}
}
EOF
Step 5: Documentation
Create comprehensive README.md:
# Plugin Name
Brief description of plugin purpose.
## Installation
\`/plugin install fx-plugin-name\`
## Components
### Skills (if applicable)
- **skill-name** - Explicitly invoke with `/skill-name`; may be called internally by [named workflow]
### Commands (if applicable)
- \`/command-name\` - [What it does]
## Usage Examples
[Concrete examples of using each component]
## Configuration
[Any settings or environment variables]
## Contributing
[Development and testing instructions]
Step 6: Register Plugin in Marketplace
Update ~/.claude/plugins/marketplaces/fx-cc/.claude-plugin/marketplace.json:
cd ~/.claude/plugins/marketplaces/fx-cc
# Edit marketplace.json to add new plugin entry
# Add to "plugins" array:
{
"name": "fx-plugin-name",
"source": "./plugins/fx-plugin-name"
}
Example using jq:
jq '.plugins += [{"name": "fx-plugin-name", "source": "./plugins/fx-plugin-name"}]' \
.claude-plugin/marketplace.json > /tmp/marketplace.json && \
mv /tmp/marketplace.json .claude-plugin/marketplace.json
Step 7: Validate and Test
Validate structure:
cd ~/.claude/plugins/marketplaces/fx-cc/plugins/fx-plugin-name
# Validate JSON
jq empty .claude-plugin/plugin.json
# Check frontmatter in components
grep -r "^---$" skills/ commands/ || echo "No frontmatter found"
Test functionality:
- Reload Claude Code to pick up changes
- Skills: Invoke each skill explicitly by name
- Commands: Execute slash commands
- Integration: Verify an active workflow can call only its named internal skills
Git workflow:
cd ~/.claude/plugins/marketplaces/fx-cc
# Create feature branch
git checkout -b feat/fx-plugin-name
# Stage changes
git add plugins/fx-plugin-name .claude-plugin/marketplace.json
# Commit with semantic message
git commit -m "feat(fx-plugin-name): add plugin for [purpose]"
# Push for review
git push -u origin feat/fx-plugin-name
Step 8: Iterate
After testing:
- Gather feedback on usability and effectiveness
- Identify improvements to components
- Update documentation with discovered use cases
- Refine component interactions
- Add examples from real usage
Quality Standards
Code Quality
- Valid JSON in all .json files
- Required frontmatter in all markdown components
- Clear, specific descriptions
- No dead file references
Documentation Quality
- README.md with installation and usage examples
- Expected behavior for each component
- Troubleshooting common issues
- Component interaction documentation
Testing Requirements
- Manual test all components
- Verify skills load only by explicit invocation or a named internal workflow call
- Confirm ordinary semantically similar requests do not auto-load a lifecycle
- Confirm command execution
- Validate JSON with jq
Component Guidelines
Skills
- Begin descriptions with the explicit-use boundary; describe purpose, not semantic auto-trigger phrases
- Name any active workflow that may call the skill internally
- Write using imperative/infinitive form
- Keep SKILL.md under 5k words
- Use progressive disclosure (references/ for details)
Commands
- Clear, action-oriented naming
- Descriptive command descriptions
- Document expected arguments
- Provide usage examples
Hooks
- Document hook events and purposes
- Set appropriate timeouts
- Handle errors gracefully
- Avoid blocking operations
Common Patterns
Domain-Specific Plugins
Pattern: fx-{domain}
- Single domain focus (git, aws, docker)
- Related components bundled together
- Clear scope and boundaries
Utility Plugins
Pattern: fx-{utility-type}
- General-purpose tools
- Cross-domain applicability
- Modular, reusable components
Meta Plugins
Pattern: fx-{meta-purpose}
- Tools for building other tools
- Development workflow helpers
- Marketplace management
Troubleshooting
Plugin Not Appearing
- Verify marketplace.json syntax and entry
- Check plugin.json exists and is valid
- Reload Claude Code
- Verify plugin name matches exactly
Components Not Loading
- Check frontmatter exists and is valid
- Verify file naming and locations
- Ensure proper directory structure
- Reload after changes
Explicit Invocation Not Working
- Verify the skill appears under its exact namespaced name
- Invoke it directly by name or slash command
- Check for frontmatter typos
- Verify skill path in plugin
Working Directory
Critical: All operations default to ~/.claude/plugins/marketplaces/fx-cc/
When creating, editing, or managing plugins, always work from this directory unless explicitly specified otherwise.
Skill Creator
This skill provides guidance for creating effective skills.
About Skills
Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.
What Skills Provide
- Specialized workflows - Multi-step procedures for specific domains
- Tool integrations - Instructions for working with specific file formats or APIs
- Domain expertise - Company-specific knowledge, schemas, business logic
- Bundled resources - Scripts, references, and assets for complex and repetitive tasks
Anatomy of a Skill
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ └── description: (required)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (TypeScript/Bash/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
SKILL.md (required)
Metadata Quality: The name and description in YAML frontmatter tell Claude what an explicitly invoked skill does. fx/cc skills are explicit-use only: begin descriptions with that boundary and do not list generic phrases that should auto-trigger the skill. State whether an active explicitly invoked workflow may call it internally by name.
Bundled Resources (optional)
Scripts (scripts/)
Executable code (TypeScript/JavaScript/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
- When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
- Example:
scripts/rotate-pdf.tsfor PDF rotation tasks - Benefits: Token efficient, deterministic, may be executed without loading into context
- Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments
References (references/)
Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
- When to include: For documentation that Claude should reference while working
- Examples:
references/finance.mdfor financial schemas,references/mnda.mdfor company NDA template,references/policies.mdfor company policies,references/api_docs.mdfor API specifications - Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
- Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
- Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
Assets (assets/)
Files not intended to be loaded into context, but rather used within the output Claude produces.
- When to include: When the skill needs files that will be used in the final output
- Examples:
assets/logo.pngfor brand assets,assets/slides.pptxfor PowerPoint templates,assets/frontend-template/for HTML/React boilerplate,assets/font.ttffor typography - Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context
Progressive Disclosure Design Principle
Skills use a three-level loading system to manage context efficiently:
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md body - When the user explicitly invokes it or an active workflow calls it by name (<5k words)
- Bundled resources - As needed by Claude (Unlimited*)
*Unlimited because scripts can be executed without reading into context window.
Skill Creation Process
To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.
Step 1: Understanding the Skill with Concrete Examples
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
- "Can you give some examples of how this skill would be used?"
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
- "What explicit name or slash invocation should users use, and may an active workflow call this skill internally by name?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
Step 2: Planning the Reusable Skill Contents
To turn concrete examples into an effective skill, analyze each example by:
- Considering how to execute on the example from scratch
- Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:
- Rotating a PDF requires re-writing the same code each time
- A
scripts/rotate-pdf.tsscript would be helpful to store in the skill
Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
- Writing a frontend webapp requires the same boilerplate HTML/React each time
- An
assets/hello-world/template containing the boilerplate HTML/React project files would be helpful to store in the skill
Example: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:
- Querying BigQuery requires re-discovering the table schemas and relationships each time
- A
references/schema.mdfile documenting the table schemas would be helpful to store in the skill
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
Step 2.5: Select Target Plugin
Before creating the skill, determine which plugin should contain it. Skills are organized into plugins based on their domain and purpose.
Available Plugins:
- fx-dev - Development workflows (PR management, code review, GitHub operations, CI/CD)
- fx-meta - Meta skills for Claude Code itself (skill creation, plugin creation)
- fx-mcp - MCP server development and integration
- fx-research - Research and technology scouting
Plugin Selection Process:
-
Check for obvious fit - Does the skill clearly belong to an existing plugin?
- GitHub CLI operations →
fx-dev - Skill creation →
fx-meta - MCP server development →
fx-mcp - Technology research →
fx-research
- GitHub CLI operations →
-
If uncertain or creating a new domain - Use AskUserQuestion to confirm plugin selection:
AskUserQuestion with options: - fx-dev (existing) - fx-meta (existing) - fx-mcp (existing) - fx-research (existing) - Create new plugin (requires plugin name) -
Set plugin path - Store the target plugin path for use in Step 3:
PLUGIN_PATH=~/.claude/plugins/marketplaces/fx-cc/plugins/<plugin-name>
Example: For a github skill about GitHub CLI operations:
- Clear fit:
fx-dev(development workflows) - Plugin path:
~/.claude/plugins/marketplaces/fx-cc/plugins/fx-dev
Step 3: Initializing the Skill
At this point, it is time to actually create the skill.
Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
When creating a new skill from scratch, initialize the skill directory structure within the selected plugin:
# Using the plugin path from Step 2.5
PLUGIN_PATH=~/.claude/plugins/marketplaces/fx-cc/plugins/<plugin-name>
# Create skill directory structure within the plugin
mkdir -p $PLUGIN_PATH/skills/<skill-name>/{scripts,references,assets}
# Create SKILL.md template
cat > $PLUGIN_PATH/skills/<skill-name>/SKILL.md <<'EOF'
---
name: skill-name
description: TODO - Describe when this skill should be used
---
# Skill Name
TODO - Add skill instructions here using imperative/infinitive form.
## Usage
TODO - Explain how to use this skill and reference any bundled resources.
EOF
The structure should include:
- A root directory named after the skill
SKILL.mdwith proper YAML frontmatter- Optional resource directories:
scripts/,references/, andassets/
After initialization, customize the SKILL.md and add necessary resources.
Step 4: Edit the Skill
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
Start with Reusable Skill Contents
To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.
Update SKILL.md
Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.
To complete SKILL.md, answer the following questions:
- What is the purpose of the skill, in a few sentences?
- When should the skill be used?
- In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.
Step 5: Packaging a Skill
Once the skill is ready, package it for distribution. For skills in Claude Code plugin marketplaces:
-
Validate the skill structure:
- Verify YAML frontmatter has required
nameanddescriptionfields - Check that the description states the explicit-use boundary and the skill's purpose
- Ensure SKILL.md uses imperative/infinitive language
- Verify all referenced resources exist
- Verify YAML frontmatter has required
-
Package the skill:
- For plugin-based skills, ensure the skill directory is in the correct location within the plugin
- For standalone skills, create a zip file maintaining the directory structure
- Test the skill by installing it and invoking it explicitly by name; also test any named internal call from an active workflow
Step 6: Iterate
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
Iteration workflow:
- Use the skill on real tasks
- Notice struggles or inefficiencies
- Identify how SKILL.md or bundled resources should be updated
- Implement changes and test again
Sponsors
Details
- Marketplace
- fx/cc
- Source
- plugins/fx-meta
- Category
- Community