# Building Skills

> |

- **Type:** Skill
- **Install:** `agentstack add skill-changeflowhq-skills-building-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [changeflowhq](https://agentstack.voostack.com/s/changeflowhq)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [changeflowhq](https://github.com/changeflowhq)
- **Source:** https://github.com/changeflowhq/skills/tree/master/skills/building-skills

## Install

```sh
agentstack add skill-changeflowhq-skills-building-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Building Skills

Read [LEARNED.md](LEARNED.md) before building or reviewing any skill.

## Core Principles

### 1. Context Window is Sacred

Skills share context with system prompt, conversation history, other skills, and the user's request. Only add what Claude doesn't already know.

**For every line ask:** Does this justify its token cost? If Claude knows it, cut it.

### 2. Progressive Disclosure

Skills load in three stages. Design for this.

| Stage | What loads | Budget | Contains |
|-------|-----------|--------|----------|
| Discovery | `name` + `description` | ~100 tokens | Trigger keywords, when to use |
| Activation | SKILL.md body | 100 lines.]

## Workflows
[Checklists for multi-step tasks. Conditional routing for different paths.]

## Error Reference
[Common errors and fixes. Keep actionable, not exhaustive.]

## Self-Learning
[LEARNED.md link + what to record + consolidation rules]
```

**Stay under 500 lines.** If approaching 300, start splitting to references/.

### 5. Add self-learning

Create LEARNED.md:

```markdown
# skill-name - Learned

## [Category]

- (YYYY-MM-DD) Observation here
```

Add Self-Learning section to SKILL.md (see [template below](#self-learning-template)).

### 6. Add scripts with dependency checking

Scripts must detect missing deps and guide setup, not fail silently:

```python
import os, sys
required = ['MY_API_KEY']
missing = [v for v in required if not os.environ.get(v)]
if missing:
    print(f"Missing: {', '.join(missing)}")
    print("Add to ~/.claude/settings.json under \"env\"")
    sys.exit(1)
```

### 7. Validate

```bash
python3 ~/.claude/skills/building-skills/scripts/validate_skill.py ~/.claude/skills/my-skill
```

Fix errors, address warnings, re-run until clean.

## Restructuring an Existing Skill

1. **Audit**: SKILL.md line count (500 lines | Split to references/ |
| Nested references (A→B→C) | One level deep from SKILL.md |
| No LEARNED.md | Every skill must self-learn |
| Unbounded LEARNED.md | Cap 50 lines, consolidate |
| README.md, CHANGELOG.md etc | Skills are for AI, not human docs |
| "You can use..." in description | Third person: "Processes..." |
| Assume deps installed | Check and guide setup on failure |
| Large docs in references/ | Put in assets/ if not needed in context |

## Self-Learning Template

```markdown
## Self-Learning

Read [LEARNED.md](LEARNED.md) before using this skill.

**Update LEARNED.md when you discover:** [list skill-specific things to record]

**Consolidation (keep under 50 lines):**
Before adding a new entry, check file length. If over 50 lines:
1. Merge duplicate/overlapping entries into single proven patterns
2. Remove entries older than 3 months that haven't been reinforced
3. Drop one-off observations that never recurred
4. Move detailed context to `LEARNED-archive.md` if worth preserving
5. Keep only entries that would change behavior - if obvious, cut it
```

## Self-Learning

Read [LEARNED.md](LEARNED.md) before building or reviewing any skill.

**Update LEARNED.md when you discover:**
- Patterns that worked well in production skills
- Description wording that improved or hurt triggering
- Common mistakes when building skills
- Validation gaps (things the validator should catch)
- Structure decisions that helped or hurt

**Consolidation (keep under 50 lines):**
Before adding, check length. If over 50: merge duplicates, prune stale (>3mo unreinforced), drop one-offs, archive to LEARNED-archive.md.

## References

- [Patterns Reference](references/patterns.md) - Workflow, output, credential, hook, and testing patterns
- [Anthropic Skill Spec](https://github.com/anthropics/skills) - Official skill specification and examples

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [changeflowhq](https://github.com/changeflowhq)
- **Source:** [changeflowhq/skills](https://github.com/changeflowhq/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-changeflowhq-skills-building-skills
- Seller: https://agentstack.voostack.com/s/changeflowhq
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.