https://github.com/fioenix/huly-skill
CLI tool & agent skill for Huly project management — zero-install, works with Claude Code, Cursor, and 40+ AI agents
https://github.com/fioenix/huly-skill
agent-skill ai-agent claude-code cli cursor huly project-management skills task-management
Last synced: about 1 month ago
JSON representation
CLI tool & agent skill for Huly project management — zero-install, works with Claude Code, Cursor, and 40+ AI agents
- Host: GitHub
- URL: https://github.com/fioenix/huly-skill
- Owner: fioenix
- License: mit
- Created: 2026-03-17T11:23:00.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-15T06:00:37.000Z (2 months ago)
- Last Synced: 2026-04-15T06:11:26.965Z (2 months ago)
- Topics: agent-skill, ai-agent, claude-code, cli, cursor, huly, project-management, skills, task-management
- Language: JavaScript
- Homepage: https://skills.sh/fioenix/huly-skill
- Size: 4.6 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Huly Assist
A CLI tool and [agent skill](https://agentskills.io) for managing tasks, projects, labels, documents, and milestones in [Huly](https://huly.io) — built on the official [`@hcengineering/api-client`](https://github.com/hcengineering/huly-examples).
Works with Claude Code, Cursor, OpenCode, and any agent supporting the [Agent Skills](https://github.com/vercel-labs/skills) ecosystem.
## Install as Agent Skill
```bash
npx skills add fioenix/huly-skill
```
Or manually (zero-install — no `npm install` needed):
```bash
git clone https://github.com/fioenix/huly-skill.git
cd huly-skill
```
## Setup
Set these environment variables before using any command:
```bash
export HULY_HOST="https://huly.app"
export HULY_WORKSPACE_ID="your-workspace-uuid"
export HULY_API_KEY="your-api-token"
```
- **HULY_HOST**: Your Huly instance URL
- **HULY_WORKSPACE_ID**: Found in Huly Settings > Workspace
- **HULY_API_KEY**: Create at Huly Settings > API Tokens
### Verify
```bash
./bin/huly.cjs whoami
```
## Usage
### Tasks
```bash
huly tasks --assignee me # My tasks
huly tasks --project DELTA --overdue # Overdue in project
huly task DELTA-123 # Task details
huly create task "Title" --project DELTA --priority HIGH --due tomorrow
huly update task DELTA-123 --status "Done" --add-comment "Completed"
huly delete task DELTA-123 --yes # Requires confirmation
```
### Reports
```bash
huly report daily --assignee me # Today's summary
huly report weekly # Week summary
```
### Labels
```bash
huly labels list # All labels
huly labels create "bug" --color 3 # Create label
huly labels assign DELTA-123 # Assign to task
huly labels show DELTA-123 # Show task labels
```
### Documents
```bash
huly docs teamspaces # List teamspaces
huly docs list "My Documents" # List docs
huly docs read "My Documents" "Notes" # Read as markdown
huly docs create "Title" -t "My Documents" --file ./content.md
huly docs create-teamspace "Engineering"
```
### Milestones
```bash
huly milestones list --project DELTA
huly milestones create "Sprint 1" --project DELTA --target 2026-04-15
huly milestones complete --project DELTA
```
### JSON Mode
Append `--json` to any command for structured output:
```bash
huly tasks --assignee me --json
```
## MCP Server
Besides the CLI skill, the same Huly operations are exposed as an **MCP server** — a better fit for Claude Cowork and any MCP-capable client. It is published to npm as [`@fioenix/huly-mcp`](https://www.npmjs.com/package/@fioenix/huly-mcp) and runs via `npx` with no install step.
A single entry point picks its transport from `HULY_MCP_TRANSPORT` (`stdio` default, or `http`). The server is **single-workspace**: one set of Huly credentials, shared by all callers.
### stdio (local — Claude Code / Desktop)
```json
{
"mcpServers": {
"huly": {
"command": "npx",
"args": ["-y", "@fioenix/huly-mcp@latest"],
"env": {
"HULY_MCP_TRANSPORT": "stdio",
"HULY_HOST": "https://huly.app",
"HULY_WORKSPACE_ID": "your-workspace-uuid",
"HULY_API_KEY": "your-api-token"
}
}
}
}
```
### HTTP (remote — Claude Cowork)
```bash
HULY_MCP_TRANSPORT=http \
HULY_HOST=https://huly.app \
HULY_WORKSPACE_ID=your-workspace-uuid \
HULY_API_KEY=your-api-token \
HULY_MCP_AUTH_TOKEN=your-shared-secret \
npx -y @fioenix/huly-mcp@latest
```
Serves `POST /mcp` (default port 3000, override with `PORT`) and `GET /health`. When `HULY_MCP_AUTH_TOKEN` is set, callers must send `Authorization: Bearer ` — because the server holds Huly credentials, always set it for any non-local deployment.
Building from source instead of npm: `pnpm build` produces `bin/mcp.cjs` (run with `node bin/mcp.cjs`). See [`npm-package/`](./npm-package) for the published package.
## For AI Agents
See [AGENTS.md](./AGENTS.md) for the full agent integration guide, or [skills/huly-skill/SKILL.md](./skills/huly-skill/SKILL.md) for the skill definition.
## Technical Notes
All dependencies are bundled into a single `dist/bundle.cjs` via esbuild — no `npm install` or GitHub PAT required. The `@hcengineering/api-client` expects browser APIs (`indexedDB`, `window`), which are polyfilled automatically.
## License
MIT