FeelFish Novel Writing Skill Building Complete Guide

Introduction
Chapter 1: Fundamentals
Chapter 2: Planning & Design
Chapter 3: Testing & Iteration
Chapter 4: Distribution & Sharing
Chapter 5: Patterns & Troubleshooting
Chapter 6: Resources & References
Appendix A: Quick Checklist
Appendix B: YAML Frontmatter Reference
Appendix C: Complete Skill Example

Introduction

A Skill is a set of writing conventions and workflow instructions — packaged into a simple folder — that teaches FeelFish's agents how to handle specific creative tasks or writing workflows. Skills are one of the most powerful ways to customize AI for your creative needs. Instead of re-explaining your character settings, writing style, and narrative logic in every conversation, skills let you teach the agent once and benefit consistently across every writing session.

Skills become extremely powerful when you have repeatable creative workflows: generating chapter drafts based on worldbuilding, advancing plots at a consistent pace, creating dialogue that fits character personalities, or orchestrating multi-step pipelines like outline breakdown → chapter expansion → polishing to remove AI-like writing. They work seamlessly with FeelFish's built-in features (agent collaboration, knowledge base, smart context).

This guide covers everything you need to know to build effective novel writing skills — from planning and structure to testing and distribution. Whether you're building skills for yourself, a team, or a community, you'll find practical patterns and real-world writing scenario examples throughout.

What You'll Learn

Technical requirements and best practices for skill structure
Common patterns for standalone skills and multi-agent collaborative workflows
Effective practices we've observed across different novel genres
How to test, iterate, and distribute your skills

Who This Is For

Independent authors who want FeelFish to consistently follow their writing style and process
Long-form novel writers who need to maintain setting consistency throughout an entire book
Web fiction studios looking to standardize AI-assisted writing approaches across a team or platform

Two Paths Through This Guide

Building a standalone creative skill? Focus on the "Fundamentals" and "Planning & Design" chapters — skills work independently without requiring multi-agent setups.

Building a multi-agent collaborative solution? The multi-agent orchestration patterns in the "Patterns" chapter are for you. Both paths share the same technical requirements; pick out what's relevant to your workflow.

Expected time investment: By the end, you'll be able to build a fully functional novel writing skill. Plan on approximately 15–30 minutes to build and test your first one.

Let's get started.

Chapter 1: Fundamentals

What Is a Skill?

In FeelFish, a skill is a folder stored at .feelfish/skills/<skill-name>/ in your project, containing:

File/Directory	Required	Purpose
`SKILL.md`	Required	Main Markdown instruction file with YAML frontmatter
`references/`	Optional	On-demand reference documents, e.g. style guides, character card templates
`assets/`	Optional	Supporting materials like writing templates, character relationship charts
`scripts/`	Optional	Executable helper scripts (advanced use)

Core Design Principles

Progressive Disclosure

FeelFish skills use a three-level information loading mechanism:

Level 1 (YAML frontmatter): Always injected into the agent's context. Provide just enough information for the agent to know when to use the skill, without stuffing everything into context.
Level 2 (SKILL.md body): Loaded when the agent determines the skill is relevant to the current task. Contains complete writing instructions and creative guidance.
Level 3 (linked files): Supplementary files bundled within the skill directory that the agent can selectively read on demand — for example, detailed character setting documents or chapter pacing references.

This progressive disclosure minimizes token consumption while preserving specialized creative settings, making long-form writing more cost-efficient.

Composability

FeelFish supports activating multiple skills simultaneously. Your skill should work well alongside others — for example, an "outline skill" and a "character skill" can both be active at once, jointly guiding a chapter-writing agent's behavior.

Portability

Skills are stored as standard file formats under the project directory. They can be easily exported, shared, or imported into other FeelFish projects without reconfiguration.

The Relationship Between Skills, Agents, and Solutions

Understanding how these three relate is essential for building efficient creative workflows:

Concept	Analogy	Description
Solution	Writing room	Determines which agents are used in the current project, who leads, who assists
Agent	Writer in the room	An AI role that executes specific tasks with its own responsibilities and style
Skill	Writer's handbook	A writing specification and process document that can be reused by multiple agents

Agents without skills:

Writing style requirements must be re-explained in every conversation
Character personalities and worldbuilding details often contradict across chapters
Dialogue and scene description styles drift randomly, lacking consistency
Authors frequently need to correct and rewrite

Agents equipped with skills:

Preset writing conventions activate automatically when needed
Writing style, character personalities, and worldbuilding settings stay consistent throughout the book
Best creative practices are embedded in every interaction
Significantly reduces learning overhead and back-and-forth revisions

💡 Kitchen analogy: The agent is the head chef — equipped with cooking tools and skills. The skill is the recipe — telling the chef how to prepare this dish, what ingredients to use, and how long to cook it. Neither works without the other.

Chapter 2: Planning & Design

Start With Your Creative Scenarios

Before writing any skill files, identify 2–3 specific creative scenarios your skill should support.

Example of a well-defined creative scenario:

Scenario: Xianxia novel chapter expansion
Trigger: User says "help me expand this plot" or "write this chapter based on the outline"
Steps:
  1. Read worldbuilding settings and character cards from the project knowledge base
  2. Analyze the plot direction and foreshadowing from the previous chapter
  3. Develop this chapter's content using a "setup-development-turn-resolution" rhythm
  4. Control word count, perspective, and the proportion of character psychology writing
Result: A chapter draft with consistent style, internally consistent settings, and smooth pacing

Ask yourself:

What requirements will readers/editors have for this chapter?
What multi-step workflows does this creative task require?
What reference materials are needed (character cards, worldbuilding, outlines)?
What writing techniques or genre conventions should be embedded?

Common Skill Use Case Categories

Based on real-world usage observations, novel writing skills generally fall into three categories:

Category 1: Content Generation Standards

Purpose: Help agents generate novel content with consistent style and stable quality — including chapter body text, character dialogue, scene descriptions, battle sequences, etc.

Real example: Xianxia chapter expansion skill

"Expand chapter body text following Eastern xianxia genre conventions. Use when users upload an outline fragment and request 'expand this section,' 'write this chapter,' or 'continue writing.'"

Key techniques:

Embedded genre-specific writing conventions (e.g., power-leveling progression, hot-blooded action pacing)
Character personality and voice consistency constraints
Word count control and paragraph pacing guidance
No external tools needed — uses FeelFish's built-in knowledge base reading

Category 2: Creative Workflow Automation

Purpose: For multi-step creative workflows that benefit from a consistent methodology, such as a complete writing pipeline from worldbuilding → outline → chapter → polishing.

Real example: Outline breakdown and chapter planning skill

"Break down a master outline into chapter-level sub-outlines and plan the core conflict and pacing for each chapter. Use when users say 'help me break down the outline,' 'plan the chapters for this arc,' or 'I need detailed sub-outlines.'"

Key techniques:

Step-by-step workflow with validation gates (outline → conflict points → foreshadowing → chapter boundaries)
Common story structure templates (three-act structure, hero's journey, setup-development-turn-resolution)
Built-in review mechanisms (check whether foreshadowing across chapters corresponds)
Iterative refinement loops (adjust pacing based on author feedback)

Category 3: Style & Polishing

Purpose: Polish AI-generated content to remove AI-like writing artifacts, strengthen style, and correct character voice — while preserving the original author's style.

Real example: AI de-styling polish skill

"Polish AI-generated novel content to eliminate overly uniform sentence structures, hollow psychological descriptions, and redundant adjective stacking. Use when users say 'help me polish this,' 'remove the AI feel,' or 'make this section more natural.'"

Key techniques:

Embedded samples of the author's own language style (can be placed in the references/ directory)
Explicit list of AI writing clichés to avoid (e.g., "a warm feeling surged in his heart" type sentences)
Character dialogue voice consistency verification
Identification and replacement patterns for common AI writing artifacts

Defining Success Criteria

How do you know your skill is working? Here are useful evaluation dimensions:

Quantitative metrics:

Skill trigger rate: In 10–20 relevant creative requests, the skill auto-activates more than 90% of the time
Setting consistency: Across 5 consecutive chapters, no contradictions in the same character's personality descriptions, catchphrases, or ability system
Manual revision volume: Compared to without the skill, human edits needed per thousand words decrease by more than 50%

Qualitative metrics:

Authors don't need to re-state writing requirements at the start of each chapter
The agent doesn't spontaneously break established worldbuilding rules or character settings
Writing style and narrative perspective remain stable across multiple conversations

Technical Requirements

File Structure

.feelfish/skills/
└── your-skill-name/
    ├── SKILL.md              # Required — main skill file
    ├── references/           # Optional — reference documents
    │   ├── style-guide.md    # Example: writing style guide
    │   ├── character-cards/  # Example: character card directory
    │   └── world-settings.md # Example: worldbuilding settings
    └── assets/               # Optional — template materials
        └── chapter-template.md  # Example: chapter template

Key Rules

SKILL.md naming:

Must exactly match SKILL.md (case-sensitive)
No variants accepted (SKILL.MD, skill.md, etc.)

Skill folder naming:

✅ Use kebab-case: outline-helper
❌ No spaces: Outline Helper
❌ No underscores: outline_helper
❌ No capital letters: OutlineHelper

No README.md:

Do not include a README.md in the skill folder
All documentation should go in SKILL.md or references/

YAML Frontmatter: The Most Important Part

The YAML frontmatter is what the agent uses to decide whether to load your skill. This is the core of whether the skill gets triggered correctly — write it carefully.

Minimum required format:

---
name: your-skill-name
description: What this skill does. Use when the user requests [specific trigger phrases].
---

Field requirements:

name (required):

Kebab-case only
No spaces or capital letters
Must match the folder name

description (required):

Must include both: what the skill does + when to use it (trigger conditions)
Fewer than 1024 characters
No XML tags (< or >)
Include specific trigger phrases users might actually say (the closer to real writing requests, the better)

skills (optional, for associating with an agent's frontmatter):

List the skill names to associate with that agent

metadata (optional):

metadata:
  author: Your pen name or team name
  version: 1.0.0
  genre: Xianxia/Urban/Romance  # Applicable novel genres
  tags: [outline, chapter expansion, worldbuilding]

Writing Effective Skills

The Description Field

The description field is the sole basis for the agent to decide whether to use your skill for the current task. Too vague and the skill won't trigger; too broad and it'll trigger when it shouldn't.

Structure:

[What this skill does] + [When to use it] + [Main capabilities]

✅ Good description examples:

# Good — specific with trigger phrases
description: >
  Expand chapter body text following Eastern xianxia genre conventions,
  maintaining consistent character personalities and internally consistent worldbuilding.
  Use when users say "help me expand," "write this chapter," "write the body from the outline," or "continue."

# Good — for workflow automation skills
description: >
  Break down a novel's master outline into chapter-level detailed sub-outlines,
  planning the core conflict, pacing, and foreshadowing for each chapter.
  Use when users say "break down the outline," "help me plan the chapters," or "how should I write this arc."

# Good — for polishing skills
description: >
  Polish AI-generated novel text to remove AI artifacts, eliminate cliché sentence patterns,
  and strengthen character voice and author style.
  Use when users say "polish this," "remove the AI feel," "make this more natural," or "rewrite this section."

❌ Poor description examples:

# Too vague
description: Helps write novels.

# Missing trigger phrases
description: Creates high-quality xianxia novel chapter content.

# Too technical, no user language
description: Implements hierarchical recursive decomposition of narrative structure with character behavior constraints.

Writing the Main Instructions

After the frontmatter, write the actual writing instructions in Markdown.

Recommended structure (using a chapter expansion skill as an example):

---
name: chapter-writer
description: >
  Expand chapter body text following Eastern xianxia genre conventions,
  maintaining consistent character personalities and internally consistent worldbuilding.
  Use when users say "help me expand," "write this chapter," "write body from outline," or "continue."
---

# Chapter Expansion Skill

## Read Before Expanding

Before starting, confirm the following via the knowledge base:
- Main character personality tags and catchphrases
- This chapter's position in the master outline (its narrative function bridging before and after)
- Current worldbuilding rules (cultivation system, geographic settings, etc.)

## Expansion Steps

### Step 1: Confirm Chapter Positioning
- What is the core conflict of this chapter?
- Which story thread does this chapter need to advance?
- What foreshadowing does this chapter plant or resolve?

### Step 2: Build the Scene Framework
1. Opening (approx. 10%): Quickly establish time/location/character state
2. Escalating conflict (approx. 40%): Gradually intensify the core tension
3. Climax (approx. 30%): Conflict eruption or key turning point
4. Resolution (approx. 20%): Emotional settling, setup for the next chapter

### Step 3: Execute Expansion
- Target word count: 3,000–5,000 words per chapter (adjustable per user request)
- Perspective: Third-person limited (protagonist's POV), unless user specifies otherwise
- Psychology proportion: No more than 20% of total word count

## Style Guidelines

- **Dialogue:** Reflects each character's identity and personality; avoid everyone sounding the same
- **Action writing:** Verbs first, minimize adverb stacking
- **Banned cliché phrases:**
  - "A warm feeling surged in his heart"
  - "Without realizing it, time had passed"
  - "At this moment, he finally understood…" type reflective endings

## Quality Checklist

After completing the expansion, self-review:
- [ ] Are character personalities consistent with their settings?
- [ ] Are there any worldbuilding contradictions?
- [ ] Does the chapter ending have sufficient suspense or a hook?
- [ ] Are there any obvious AI cliché phrases?

## Reference Materials

For detailed character cards and worldbuilding, read:
`references/character-cards/` and `references/world-settings.md`

Instruction Best Practices

Be specific and actionable:

✅ Good example:
When expanding a character's inner thoughts, follow these principles:
- Internal monologue: no more than 3 consecutive sentences
- Use indirect psychological description (imply emotions through behavior and expression)
- Avoid directly stating "he felt sad/angry/happy"

❌ Poor example:
Pay attention to describing characters' inner worlds.

Include error handling:

## Common Issue Handling

### Insufficient outline information
If the user's outline is too brief (fewer than 50 words), first confirm:
- Main characters appearing in this chapter
- The narrative tasks this chapter needs to complete
- Any foreshadowing that needs special attention

### Setting conflicts
If a worldbuilding contradiction is discovered during expansion (e.g., a character appears
but the outline shows they have already left), notify the user rather than modifying the settings yourself.

Clearly reference bundled resources:

Before writing battle scenes, read `references/combat-rules.md` for:
- Power level descriptions corresponding to cultivation ranks
- Attack methods and visual manifestations for different techniques
- Pacing recommendations for combat scene writing

Chapter 3: Testing & Iteration

Depending on your needs, skills can be tested at different levels of rigor:

Manual testing in FeelFish: Submit creative requests directly and observe agent behavior. Fast iteration, no additional setup.
Multi-scenario coverage testing: Prepare multiple different types of test requests to verify skill performance across different writing scenarios.
Cross-chapter continuity testing: Complete 3–5 chapters consecutively and check setting consistency and stylistic stability.

💡 Pro tip: Iterate on one difficult scenario first. Find a typical task prone to problems (like a climax scene with complex multi-character dialogue), refine until satisfied, then expand to broader scenario coverage.

Recommended Testing Approaches

1. Trigger Testing

Goal: Ensure the skill is loaded by the agent at the right times.

Test case design:

Requests that should trigger:
✅ "Help me expand this outline section into body text"
✅ "Write this chapter based on the sub-outline below"
✅ "Continue from the last chapter, write the chase scene"
✅ "This plot section is too short, help me flesh it out"

Requests that should NOT trigger:
❌ "Help me fix the grammar in this paragraph" (should trigger polishing skill)
❌ "Analyze the themes of this novel" (analysis, not expansion)
❌ "Recommend some xianxia novels for me" (lookup, unrelated to writing)

Debugging method: Ask the agent directly: "When would you use the [skill name] skill?" The agent will respond based on the description field, letting you judge whether the description is accurate.

2. Functional Testing

Goal: Verify the skill produces expected creative output.

Test: Expand a conflict scene with dual-character dialogue

Preconditions:
- Character A: Arrogant, terse sect elder
- Character B: Stubborn, outspoken protagonist
- Scene: A makes B's entrance test difficult; B angrily fights back

Expected results:
- A's dialogue is brief with a condescending tone
- B's dialogue is direct with emotional fluctuation
- The two characters have clearly distinct speaking styles
- No "a surge of hot blood in his heart" type cliché ending
- Chapter ends with a suspense hook (e.g., B activates an unexpected hidden talent)

3. Setting Consistency Testing

Goal: Verify the skill maintains worldbuilding and character setting coherence across multiple chapters.

Baseline comparison:

Without skill:
- Chapter 3: Protagonist uses "Sword Flight" technique to fly
- Chapter 7: Protagonist hikes over mountains on foot (forgotten the flying ability)
- Every chapter ends with "he took a deep breath"

With skill:
- Protagonist's abilities remain consistent with established settings
- Different characters' speaking styles are stably distinguished
- The author's style tags (e.g., "concise action-focused") are evident in every chapter

Iterating Based on Feedback

Skills are living documents. Plan to update them continuously based on these signals:

Under-triggering signals:

Skill is never auto-loaded (must manually specify requirements in conversation)
Agent frequently forgets key writing conventions
Need to repeatedly remind agent of character personalities or voices

Fix: Add more natural-language trigger phrases to the description; move key conventions to the very top of the SKILL.md body.

Over-triggering signals:

Skill loads during unrelated conversations (e.g., a simple question triggers the full expansion workflow)
Agent launches the entire expansion process when the user only wants to fix a typo

Fix: Add negative trigger notes to the description that clearly distinguish applicable from non-applicable scenarios.

description: >
  Expand chapter body content. Use when users request "expand," "write this chapter."
  [NOT applicable for]: grammar/typo fixes only, brief polish (3 sentences or fewer),
  questions or lookup-type requests.

Execution quality issues:

Style conventions are followed, but chapter structure is still disorganized
Character dialogue matches the voice, but plot progression is too slow

Fix: Add structured self-review checklists to SKILL.md; replace vague style descriptions with quantifiable execution standards (e.g., "in dialogue scenes, each line of dialogue stays under 30 characters, paired with 1–2 sentences of action description").

Skills make your creative workflows reusable, shareable, and standardized. A FeelFish creative solution equipped with skills delivers faster value than pure prompt adjustments alone, and serves as an effective vehicle for knowledge transfer within web fiction studios and creative communities.

Current Distribution Model

How individual users get and install skills:

Download the skill folder (or ZIP archive)
Click "Import from Local" in FeelFish's "Skills" tab
Select the skill folder (must contain SKILL.md)
Associate the skill with the appropriate agent in the "Agent" editing interface

Team/studio skill sharing:

Commit the skill folder to a shared team Git repository
Team members pull and install via "Import from Local"
When updating skills, notify members to re-import the latest version

Marketplace distribution:

Publish via "Share to Marketplace" in the FeelFish resource marketplace
Other users can download and apply with one click, no manual import needed

An Open Creative Standard

FeelFish's skills follow an open Skill standard design, compatible with mainstream AI writing protocols. This means your carefully crafted writing skills don't belong to just one tool — the writing conventions and workflow knowledge you accumulate in FeelFish can be migrated and reused in the future.

Authors can note applicable platforms or genres in the metadata field of their skills for other users' reference.

Recommended Publishing Approach

Publish to the FeelFish resource marketplace. Once you've created a skill in FeelFish, you can publish it to the marketplace for convenient reuse across other projects.

Positioning Your Skill

How you describe your skill determines whether other authors understand its value and actually try using it.

Focus on creative outcomes, not technical features:

✅ Good example:
"With this skill, your xianxia chapter expansions will automatically follow
the cultivation rank system, character voice conventions, and action-pacing rhythm —
no need to repeat the settings each time. The AI remembers everything for you."

❌ Poor example:
"This skill contains YAML frontmatter and Markdown instructions,
implementing writing constraints through agent context injection."

Highlight the value of the "skill + agent" combination:

"FeelFish's agents give AI the ability to write.
Our skills teach it your way of writing.
Combined, they enable a truly personalized AI creative workflow."

Chapter 5: Patterns & Troubleshooting

The following patterns are drawn from observations in real novel writing scenarios. They represent common approaches validated across different genres and writing stages — not rigid templates.

Choosing Your Approach: Problem-First vs. Tool-First

Think of it like working with an editor. You might come with a specific problem — "the climax scene in this chapter feels flat, help me fix it" — and the editor devises a revision strategy based on the problem. Or you proactively tell the editor you want to practice "psychological description in battle scenes," and they apply that direction wherever it's needed.

Skills work the same way:

Problem-first: "The pacing in this chapter is too fast; the characters' emotions haven't been developed" → Your skill guides the agent to handle pacing and emotional layering in the right order. The author describes the problem; the skill provides the solution.
Tool-first: "I've already configured character cards and worldbuilding" → Your skill teaches the agent how to fully leverage these settings to write the most fitting content. The author provides the materials; the skill provides the expertise.

Pattern 1: Linear Creative Workflow Orchestration

Use case: When you need to complete multi-step creative tasks in a fixed order, e.g., a complete writing chain of "outline → sub-outline → body text → polish."

Example structure:

# Complete Chapter Writing Workflow

## Step 1: Confirm the Outline
- Read this chapter's position in the master outline
- Confirm: core conflict, characters appearing, narrative tasks to complete

## Step 2: Expand the Sub-outline
- Break the chapter's tasks into 5–8 scene nodes
- Each node includes: location, characters involved, narrative function

## Step 3: Expand the Body Text
- Expand each scene from the sub-outline
- Word count control: 400–800 words per scene

## Step 4: Quality Review
- Check character voice consistency
- Check that foreshadowing has proper setup and payoff
- Check that the chapter's closing hook is effective

Key techniques:

Explicit step ordering to prevent the agent from skipping steps
Dependencies between steps (each step relies on the previous step's output)
Validation checklists for each phase
Failure fallback instructions (e.g., "if outline information is insufficient, first confirm with user")

Pattern 2: Multi-Agent Collaborative Writing

Use case: When creative tasks span multiple specialized roles — e.g., a "planning agent" handles the outline, a "writing agent" handles body text, a "polishing agent" handles AI-artifact removal.

Example: Multi-agent workflow from zero to finished chapter

# Phase 1: Planning Agent (Outline & Structure)
1. Analyze the chapter requirements provided by the user
2. Generate the chapter sub-outline (list of scene nodes)
3. Mark key narrative functions (setup/payoff/character arc progression)

# Phase 2: Writing Agent (Body Text Expansion)
1. Receive the sub-outline output from the planning agent
2. Expand each scene following style conventions
3. Output the draft with a self-review note

# Phase 3: Polishing Agent (Style Optimization)
1. Receive the draft from the writing agent
2. Perform AI-artifact removal polish
3. Verify character voice and author style tags
4. Output the final version

Key techniques:

Clear phase boundaries (each agent focuses on one role)
Data handoff specifications between agents (input/output format agreements)
Validation before proceeding to the next phase (e.g., "if draft is under 2,000 words, return to phase 2 to supplement")

Pattern 3: Iterative Refinement Writing

Use case: Output quality improves through multiple rounds of feedback — suitable for authors with extremely high stylistic standards or scenes requiring repeated polishing.

Example: Iterative writing of a key battle scene

# Round 1: Framework Draft
1. Generate the basic framework of the battle scene (cause, process, result)
2. Save as draft

# Quality Assessment
Check for:
- Is the battle pacing tense enough (sufficient verb density)?
- Is the power balance between the two sides reasonable?
- Is the protagonist's sense of crisis sufficiently conveyed?

# Round 2: Targeted Expansion
1. Supplement the weak points identified in the assessment
2. Strengthen the sense of speed in action descriptions
3. Add psychological depth when the protagonist faces a desperate situation

# Round 3: Polish and Finish
1. Remove redundant adverbs and adjective stacking
2. Check battle logic consistency
3. Confirm the visual impact of the climax node

Key techniques:

Clear quality assessment criteria
Targeted (not wholesale) revisions each round
Knowing when to stop (avoid over-polishing until the original spark is lost)

Pattern 4: Genre-Aware Content Generation

Use case: Automatically switch to the corresponding writing conventions based on novel genre — xianxia, urban, romance, and mystery each have different pacing and descriptive preferences.

Example: Genre-adaptive writing

# Genre Detection and Convention Switching

## Decision Process
1. Confirm the current novel genre (from project knowledge base or user clarification)
2. Load the corresponding genre writing conventions:
   - Xianxia: power-leveling satisfaction, battle pacing, cultivation system descriptions
   - Urban: realistic texture, human relationships, workplace/business logic
   - Romance: emotional pacing, character interaction details, psychological description weight
   - Mystery: information control, clue planting, narrative tension

## Genre Convention Execution
- Apply the chapter pacing template for the corresponding genre
- Adjust the ratio of psychological to action description
- Match the expected moments for the corresponding genre's readership

Key techniques:

Clear genre identification criteria
Differentiated writing conventions for each genre
Fallback option (universal conventions when genre is unclear)

Pattern 5: Embedded Domain Knowledge

Use case: When your skill needs to provide specialized knowledge beyond general writing ability — e.g., a specific historical background, professional workplace logic, or regional cultural details.

Example: Ancient court etiquette constraints

# Ancient Court Scene Writing Guidelines

## Character Honorifics
- Emperor: "Your Majesty," "the Emperor" (used by subjects); addressed by title by the Empress Dowager; refers to himself as "We" (朕)
- Empress: "Your Highness," "the Empress"
- Noble Consort: "Your Highness" (address); "this consort" (self-reference)

## Ceremonial Behavior Guidelines
- Audience scenes must include: entering the hall, performing obeisance (kneeling or bowing depending on rank), rising
- Imperial consorts may not sit in the Emperor's presence without being invited to
- Eunuchs must refer to themselves as "this servant"; ladies-in-waiting as "this maidservant"

## Common Errors to Avoid
- Avoid: a consort addressing the Emperor by his given name
- Avoid: subjects arguing loudly in the imperial presence (should use "remonstrating at risk of death" phrasing)
- Avoid: modern vocabulary mixed into dialogue

Key techniques:

Domain expertise presented as actionable, specific guidelines
Constraints come before content generation (conventions take priority)
Detailed checklist of common errors

Troubleshooting

Skill Cannot Be Imported

Error: "Cannot find SKILL.md"

Cause: File is not named exactly SKILL.md

Solution:

Rename to SKILL.md (case-sensitive)
Confirm the file is directly in the skill folder's root directory

Error: "Invalid frontmatter"

Cause: YAML formatting issue

# Wrong — missing delimiters
name: my-skill
description: Expand chapter

# Wrong — unclosed quote
description: "Expand chapter content

# Correct
---
name: my-skill
description: Expand chapter content. Use when user says "help me write this chapter."
---

Error: "Invalid skill name"

Cause: Name contains spaces or capital letters

# Wrong
name: Chapter Expansion Skill
name: ChapterWriter

# Correct
name: chapter-writer

Skill Doesn't Trigger

Symptom: Skill is never auto-loaded; agent doesn't know this skill exists

Fix: Modify your description field.

Quick checklist:

Does it include trigger phrases users would actually say in natural language? ("help me expand" is more effective than "execute chapter expansion task")
Is it too generic? ("helps with writing" is ineffective)
Has the skill been associated with the corresponding agent?

Debugging method: Ask the agent directly: "When would you use the [skill name] skill?" Use the response to judge whether the description needs adjustment.

Skill Triggers Too Frequently

Symptom: Agent launches the full expansion workflow when the user only wants to fix a typo

Solution:

Add negative trigger notes:

description: >
  Expand chapter body content. Use when users request "expand" or "write this chapter."
  [NOT applicable]: grammar/typo fixes only, brief polish (3 sentences or fewer),
  questions or lookup-type requests.

Be more specific about trigger scenarios
Clearly delineate the boundaries between different skills (e.g., polishing skill and expansion skill don't overlap)

Instructions Aren't Being Followed

Symptom: Skill is loaded, but agent doesn't follow writing conventions (e.g., still uses banned phrases)

Common causes:

Conventions described too vaguely

❌ Vague instruction:
Avoid AI-sounding sentences.

✅ Clear instruction:
[BANNED phrases — do not use]:
- "A warm feeling surged in his heart…"
- "At this moment, he finally understood…"
- "Without realizing it, time had passed"
- "He took a deep breath" (as a paragraph ending)
- "A flash of [emotion] crossed his eyes" (emotional externalization cliché)
- Any paragraph ending with a "reflective summary"

Key conventions buried deep in the document

Solution: Move the most important constraints to the very top of the SKILL.md body. Use headings like ## ⚠️ Important or ## Core Guidelines to highlight them.

SKILL.md content too long

Solution: Move detailed reference materials to the references/ directory and provide links. Keep SKILL.md's core instructions concise (recommended: under 2,000 words).

Large Context Issues

Symptom: In long-form writing, the skill's constraining effect gradually weakens

Causes:

The skill content itself is too large, consuming too much of the context window
Too many skills activated simultaneously, interfering with each other
All reference documents loaded at once instead of progressively

Solutions:

Optimize SKILL.md file size — move detailed character cards, worldbuilding, etc. to references/ and read them only when needed
Reasonably control the number of simultaneously active skills — for long novels, switch between different skill combinations by writing phase (drafting phase vs. polishing phase)
Leverage the progressive disclosure design — keep only core conventions in the SKILL.md body; access details on-demand via tools

Chapter 6: Resources & References

Official Documentation

FeelFish Resources:

Example Skills

Recommended starting points:

Browse solutions and skills shared by others in the resource marketplace; find templates that fit your genre
Download, import locally, and adjust to your specific project
Use the "Smart Context" feature to analyze the structure of high-quality existing novels and convert them into skill conventions

Tools & Utilities

FeelFish built-in capabilities:

Knowledge Base: Stores long-term settings like character cards, worldbuilding, and timelines for skills to access at any time
Smart Context: Can automatically summarize based on existing content
Resource Marketplace: Browse, download, and share solutions, agents, and skills

Getting support:

Join the FeelFish community to exchange skill usage tips with other authors
Search existing skills in the marketplace to avoid reinventing the wheel
Contribute your skills via "Share to Marketplace" to help more creators

Appendix A: Quick Checklist

Use this checklist to validate your work before and after skill creation.

Before You Start

Have identified 2–3 specific creative scenarios
Have confirmed what reference materials are needed (character cards, worldbuilding, style samples)
Have planned the folder structure

During Development

Folder name uses kebab-case (lowercase letters + numbers + hyphens)
SKILL.md file exists (spelling and capitalization exactly correct)
YAML frontmatter includes --- delimiters
name field: kebab-case, no spaces, no capital letters
description includes both functional description and when to trigger
No XML tags (< >)
Writing conventions are specific and actionable (not just vague style requirements)
Includes common error handling guidance
Reference material links are clear, placed in references/ directory

Before Uploading/Importing

Trigger test: send 5 relevant creative requests and confirm skill loads
Non-trigger test: send 3 unrelated requests and confirm skill is not mistakenly triggered
Functional test: complete one full creative task and review output quality
Consistency test: two consecutive chapters confirm consistent character voice and worldbuilding

After Importing

Test effectiveness in real creative conversations
Monitor for under-triggering/over-triggering signals
Collect feedback on issues from actual writing sessions
Iterate on description and instructions based on feedback
Update version number in metadata

Appendix B: YAML Frontmatter Reference

Required Fields

---
name: skill-name-in-kebab-case
description: What this skill does, and when to use it when the user says [specific trigger phrases].
---

All Optional Fields

---
name: chapter-writer
description: >
  Expand chapter body text following Eastern xianxia conventions,
  maintaining consistent character personalities and worldbuilding.
  Use when users say "help me expand," "write this chapter," or "continue."
metadata:
  author: Your pen name
  version: 1.0.0
  genre: Xianxia
  tags: [chapter expansion, Eastern xianxia, character consistency]
  documentation: https://github.com/yourname/feelfish-skills
---

Security Notes

Allowed:

Any standard YAML types (strings, numbers, booleans, lists, objects)
Custom metadata fields
Longer descriptions (up to 1024 characters; use > for multi-line format)

Not allowed:

XML angle brackets (< >) — security restriction
Skill names prefixed with "Claude" or "Anthropic" (reserved)

Appendix C: Complete Skill Example

The following is a complete, ready-to-use skill example demonstrating the core patterns discussed in this guide:

---
name: xianxia-chapter-writer
description: >
  Expand chapter body text following Eastern xianxia genre conventions,
  maintaining a self-consistent cultivation system, consistent character voices,
  and smooth action-pacing. Use when users say "help me expand," "write this chapter,"
  "write the body from the outline," "continue," or "write this section in more detail."
  NOT applicable for: typo/grammar fixes, brief polish, purely lookup-type questions.
metadata:
  author: FeelFish Example
  version: 1.0.0
  genre: Eastern Xianxia
  tags: [chapter expansion, xianxia, cultivation system]
---

# Eastern Xianxia Chapter Expansion Skill

## ⚠️ Read Before Expanding

Before starting, confirm via the knowledge base:
- Main characters' personality tags and catchphrases
- Current cultivation system (rank breakdown, external manifestations of techniques)
- This chapter's narrative function in the master outline

If no relevant settings exist in the knowledge base, briefly confirm with the user before beginning.

## Expansion Guidelines

### Structure & Pacing

| Section | Proportion | Function |
|---------|-----------|----------|
| Opening | 10% | Quickly establish time/location/character state |
| Escalating conflict | 40% | Gradually intensify core tension |
| Climax | 30% | Conflict eruption or key turning point |
| Resolution | 20% | Emotional settling, setup for next chapter's hook |

### Writing Standards

**Target word count:** 3,000–5,000 words per chapter (adjustable per user request)

**Perspective:** Third-person limited (protagonist's POV), unless user specifies otherwise

**Psychology proportion:** No more than 20% of total word count

**Dialogue guidelines:**
- Different characters must have clearly distinguishable speaking styles
- No more than 4 consecutive lines of dialogue without action/expression beats
- Prohibited: all characters sounding identical

### Banned Phrase List

The following AI cliché phrases are explicitly prohibited:

- "A warm feeling surged in his heart…"
- "At this moment, he finally understood…"
- "Without realizing it, time had passed"
- "He took a deep breath" (as a paragraph ending)
- "A flash of [emotion] crossed his eyes" (emotional externalization cliché)
- Any paragraph ending with a reflective summary

## Quality Checklist

After completing the expansion, review item by item:

- [ ] Are character personalities consistent with knowledge base settings?
- [ ] Do cultivation rank and combat power descriptions match the system rules?
- [ ] Are there any worldbuilding contradictions?
- [ ] Does the chapter ending include a suspense hook?
- [ ] Are there any banned phrases?

## Reference Materials

For detailed settings, read:
- `references/character-cards/` — character card directory
- `references/world-settings.md` — worldbuilding and cultivation system
- `references/combat-rules.md` — battle scene writing guidelines

## Common Issue Handling

### Outline too brief
If the user's outline is under 50 words, first confirm:
1. Main characters appearing in this chapter
2. Narrative tasks this chapter needs to complete
3. Any foreshadowing that needs to be planted or resolved

### Setting contradiction discovered
If a conflict with existing settings is found, **do not modify the settings yourself**.
Instead, notify the user: "I noticed [specific contradiction] — how would you like to handle it?"

The examples above are available from the FeelFish resource marketplace, where you can also find complete skill templates for various genres in the community skill sharing area, including:

Urban workplace: Business logic constraint skills
Ancient romance: Court etiquette and honorific convention skills
Mystery/thriller: Clue planting and information control skills
General polish: AI-artifact removal and style reinforcement skills

Clone or download these skills, modify them for your specific project, and use them as a starting point for your own personalized creative workflow.

This guide was compiled by the FeelFish creative community, based on the skill system of FeelFish 3.0.0+. For questions, visit the FeelFish official documentation or join the creative community.

FeelFish Novel Writing Skill Building Complete Guide

FeelFish Novel Writing Skill Building Complete Guide

Table of Contents

Introduction

What You'll Learn

Who This Is For

Two Paths Through This Guide

Chapter 1: Fundamentals

What Is a Skill?

Core Design Principles

Progressive Disclosure

Composability

Portability

The Relationship Between Skills, Agents, and Solutions

Chapter 2: Planning & Design

Start With Your Creative Scenarios

Common Skill Use Case Categories

Category 1: Content Generation Standards

Category 2: Creative Workflow Automation

Category 3: Style & Polishing

Defining Success Criteria

Technical Requirements

File Structure

Key Rules

YAML Frontmatter: The Most Important Part

Writing Effective Skills

The Description Field

Writing the Main Instructions

Instruction Best Practices

Chapter 3: Testing & Iteration

Recommended Testing Approaches

1. Trigger Testing

2. Functional Testing

3. Setting Consistency Testing

Iterating Based on Feedback

Chapter 4: Distribution & Sharing

Current Distribution Model

An Open Creative Standard

Recommended Publishing Approach

Positioning Your Skill

Chapter 5: Patterns & Troubleshooting

Choosing Your Approach: Problem-First vs. Tool-First

Pattern 1: Linear Creative Workflow Orchestration

Pattern 2: Multi-Agent Collaborative Writing

Pattern 3: Iterative Refinement Writing

Pattern 4: Genre-Aware Content Generation

Pattern 5: Embedded Domain Knowledge

Troubleshooting

Skill Cannot Be Imported

Skill Doesn't Trigger

Skill Triggers Too Frequently

Instructions Aren't Being Followed

Large Context Issues

Chapter 6: Resources & References

Official Documentation

Example Skills

Tools & Utilities

Appendix A: Quick Checklist

Before You Start

During Development

Before Uploading/Importing

After Importing

Appendix B: YAML Frontmatter Reference

Required Fields

All Optional Fields

Security Notes

Appendix C: Complete Skill Example