---
name: akijain2000/authoring
source: https://app.decimal.ai/s/akijain2000-authoring@1/SKILL.md
source_sha256: 08af09ae7315
---

# Skill Authoring

A meta-skill that queries the Skill Factory wiki to help you write better SKILL.md files.

## When to use

- Writing a new skill from scratch (idea or rough draft)
- Reviewing an existing skill for quality
- Improving a skill's description (most common failure point)
- Adapting a skill for a different host (Cursor, Codex, Claude Code)
- Debugging why a skill doesn't trigger

## Workflow

### Step 1: Intake

Accept one of:
- A draft SKILL.md (read the file)
- A plain-English description of what the skill should do
- An existing skill directory to review

If no input provided, ask: "What should this skill do? Describe in 1-2 sentences."

### Step 2: Load the wiki index

Read the wiki index to understand what knowledge is available. All paths below are relative to the skill-factory root directory.

Read the file `wiki/INDEX.md`.

This is the master table of contents with one-line summaries. Use it to pick which articles to read next.

### Step 3: Targeted retrieval

Based on the task, read the most relevant wiki articles. Do NOT read all of them. Pick 3-5:

**Always read for any task:**
- `wiki/research/anatomy-of-a-good-skill.md` (the quality checklist)
- `wiki/concepts/description-writing.md` (most common failure point)

**Read if writing from scratch:**
- `wiki/concepts/progressive-disclosure.md`
- `wiki/concepts/naming-conventions.md`
- `wiki/concepts/skill-discovery.md`

**Read if reviewing:**
- `wiki/research/anti-patterns.md`
- `wiki/concepts/token-budget.md`

**Read if the skill has scripts:**
- `wiki/concepts/error-handling-in-scripts.md`
- `wiki/concepts/validation-loops.md`

**Read if multi-host:**
- `wiki/concepts/host-compatibility.md`
- `wiki/research/host-differences.md`

**Read if the skill has complex workflows:**
- `wiki/concepts/checklist-workflows.md`
- `wiki/concepts/plan-validate-execute.md`
- `wiki/concepts/template-patterns.md`

### Step 4: Gap analysis

Compare the draft against the quality spec. Read the file `SKILL_SPEC.md`.

Check each of these (in order of importance):

1. **Description quality** -- Does it have a WHAT verb and a WHEN trigger? Third person? Under 1024 chars? Specific keywords?
2. **Name quality** -- Lowercase, hyphens, matches directory, not vague?
3. **Body length** -- Under 500 lines? If over, should it use progressive disclosure?
4. **Anti-patterns** -- Read `wiki/research/anti-patterns.md` and check against each one
5. **Content necessity** -- Is everything in the body something the agent doesn't already know?
6. **Examples** -- Does it include concrete input/output examples?
7. **Consistency** -- Consistent terminology throughout?
8. **Output format** -- If the skill produces output, is the format specified?

### Step 5: Draft or rewrite

If writing from scratch:
1. Start with the frontmatter (name + description first, get those right)
2. Write a concise overview (2-4 sentences)
3. Write "When to use" triggers (bullet points)
4. Write the main workflow (numbered steps)
5. Add examples (input/output pairs)
6. Check line count -- split to reference files if over 500

If reviewing/improving:
1. List every issue found in Step 4
2. For each issue, show the current text and the proposed fix
3. Apply all fixes
4. Verify the result

### Step 6: Validate

Run the automated validator:

```
bun run scripts/validate-skill.ts <path-to-skill-directory>
```

If it fails, fix the issues and re-run until it passes.

### Step 7: Quality examples

If helpful, read exemplary skills for inspiration. List the files in `wiki/examples/good/` and read the one most similar to the skill being authored.

### Step 8: File insights back

If this session produced useful observations about skill authoring (a new anti-pattern, a useful pattern, a host-specific gotcha), create a new file at `wiki/queries/observation-YYYYMMDD-TOPIC.md` with this structure:

```markdown
# Observation: [TITLE]
Date: [today's date]
Context: [what skill was being authored]

## Finding
[what was discovered]

## Recommendation
[how to apply this in future skills]
```

### Step 9: Output

Deliver:
1. The final SKILL.md (complete, ready to use)
2. A summary of changes made (if reviewing)
3. Validation results (should be passing)

## Key principles (from the wiki)

- **Description is the #1 failure point.** Get the WHAT verb + WHEN trigger right before anything else.
- **Concise beats thorough.** Only include what the agent doesn't already know.
- **Defaults over menus.** Pick one tool/approach, mention alternatives as escape hatch.
- **Procedures over declarations.** Teach approach, not specific answers.
- **Test against real tasks.** A skill that doesn't improve on the baseline isn't needed.
- **Progressive disclosure.** Keep SKILL.md under 500 lines. Split details into reference files.
- **Gotchas are gold.** Environment-specific facts that defy assumptions are the highest-value content.